ModifiersFramework

Description

ModifiersFramework lets other Valheim mods apply temporary skills, gameplay modifiers and custom YAML buffs. Built for multiplayer efficiency and integrity, it keeps effects separate per player and source while calling mods control server authority and synchronize definitions and events.

Overview

| Feature | Description |

| --- | --- |

| Shared API | Calling mods supply modifiers and identify their own sources. |

| Skills and gameplay modifiers | Temporary skills, damage/resistances, action costs and refunds, regeneration, movement, carry capacity, adrenaline, stagger and tailwind. |

| Added elemental damage | Fixed values or ranges for fire, frost, lightning, spirit and poison; added fire uses native torch burning. |

| Trinket effects | Parry bonus, armor, swimming speed, attack cost and instant health, stamina or eitr gains. |

| Food sources | Effects follow successful consumption and native food lifetimes. |

| Conditional and timed sources | Effects last until the caller removes them or their supplied duration expires. |

| Custom buffs | YAML definitions combine a name, description, matching PNG icon and complete effectsList. |

| Native effect display | Icons, timers and Wet-style colored tooltips; calling mods can disable each display option. |

| Live YAML updates | Valid edits reload and notify callers without restarting; invalid edits retain the last valid catalog. |

| Saved effects | Captured food effects restore automatically; generic sources can opt into persistence. |

| Multiplayer efficiency | Cached totals and scheduled expiry minimize work; dedicated servers skip PNGs and display. No custom framework RPCs. |

| Bounded diagnostics | Always-on logging uses background writes and overwrites output.log at 1 MiB. |

See API.md for caller integration, modifiers.md for supported values and CUSTOM-BUFFS.md for YAML examples.

Configuration and values

The framework generates no.cfg file and has no player settings. On first startup it creates BepInEx/config/ModifiersFramework/customModifiers.yaml, the adjacent icons/ folder and output.log. Existing YAML is preserved. The table lists buff-definition fields, caller API controls and fixed framework behavior; API controls are not YAML fields.

| Section / option | Default | Meaning |

| --- | --- | --- |

| customModifiers.yaml | Empty {} with a commented example | Catalog of named buffs; calling mods select buff[callingName]. |

| YAML / top-level key | — | Required, case-sensitive callingName without spaces; also determines the PNG filename. |

| YAML / buffName | — | Required title shown in orange in Active effects. |

| YAML / buffText | — | Required white description; its value may be blank. |

| YAML / effectsList | — | Required list of modifiers applied together; creates a visual-only buff. |

| icons / callingName.png | Shared fallback icon | Supply a PNG matching the buff key, such as icons/MightofNorn.png. |

| Caller API / showBuff | true | Show the source in the HUD and Active effects; hiding it preserves gameplay. |

| Caller API / showBuffTimers | true | Show remaining time and the timed buff's duration row. |

| Caller API / showModifierDescriptions | true | Show description and modifier rows. |

| Caller API / durationSeconds | 0 | Generic sources are untimed at 0; a positive duration expires automatically. |

| Caller API / persistOnSave | false | Enable saved generic sources with registered restoration metadata; food effects save automatically. |

| Diagnostics / debugging | Always enabled | Write lifecycle and failure messages to output.log. |

| Diagnostics / log limit | 1 MiB | Overwrite the log on rollover; no backup logs accumulate. |

YAML changes reload automatically after 500 ms of quiet and notify subscribed calling mods. Active titles, text and icons refresh; existing numerical effects stay captured until the caller reapplies them. Definitions and icons are local files; multiplayer synchronization remains the calling mod's responsibility.

Manual I