Status Effect Configuration

Define timed buffs and debuffs — heal/damage over time and vulnerability — that entities can carry.

Status effects are timed buffs and debuffs an entity carries: they apply, tick each server frame, and expire on their own. Define them in a status-effect-config.yaml, then apply them by id from a consumable item or a Lua script (entity:apply_effect). Effects work on both players and mobs.

File Location

mods/<your-mod>/status-effect-config.yaml

Declare it in your mod manifest with the status-effect-config: key (the value is optional and defaults to status-effect-config.yaml).

Fields

Each entry under status-effects: is one effect:

Field	Required	Default	Description
`id`	yes	—	The effect’s name, referenced by consumables and Lua. Namespaced to your mod (`regeneration` becomes `YourMod:regeneration`).
`kind`	yes	—	What the effect does — one of the kinds below.
`magnitude`	yes	—	The effect’s strength. Its meaning depends on `kind` (see below).
`duration-seconds`	yes	—	How long the effect lasts once applied.
`damage-type`	no	`physical`	For `damage-over-time` only: the mitigation channel the damage uses (`physical` / `fire` / `blast` / `decay` / `radiant`). Ignored by other kinds.
`ward-capability`	no	(none)	For `damage-over-time` only: marks the effect a warded region hazard (a weather storm / ambient DoT). A target holding this capability never receives the effect — it is refused when applied — while a target without it takes it armor-bypassing as usual. Omitted → an ordinary DoT. Ignored by other kinds.

Kinds

`kind`	What `magnitude` means	Behaviour
`heal-over-time`	Health healed per second	Heals the host each tick (never above `max`, never revives a dead host).
`damage-over-time`	Damage dealt per second	Damages the host each tick, on the `damage-type` channel. Applied straight to health (armor does not reduce it).
`damage-taken-multiplier`	The multiplier itself (`2.0` = double)	While active, scales incoming damage the host takes. `>1` = more vulnerable, `<1` = more resistant. Multiple such effects multiply together.

Stacking & lifetime

Re-applying an effect refreshes its duration rather than stacking a second copy — the timer resets to full and adopts the new magnitude. (Distinct effect ids are independent and, for damage-taken-multiplier, multiply together.)
Effects are runtime-only — they are not saved with the world; a reload starts an entity with none.
A player’s active effects show on the HUD with a countdown; effect-driven health changes are visible immediately.

Applying an effect

From a consumable item — see consumable-config.md:

consumable-info:
  effects:
    - regeneration

From Lua, on any entity:

entity:apply_effect("YourMod:regeneration")           -- config duration & magnitude
entity:apply_effect("YourMod:poison", 8.0, 3.0)       -- override duration (s) and magnitude
entity:clear_effect("YourMod:poison")                 -- remove it early; returns whether one was cleared

Example

status-effects:
  - id: regeneration
    kind: heal-over-time
    magnitude: 2.0            # +2 health per second
    duration-seconds: 10.0

  - id: poison
    kind: damage-over-time
    magnitude: 1.0            # 1 damage per second
    duration-seconds: 5.0
    damage-type: decay

  - id: vulnerable
    kind: damage-taken-multiplier
    magnitude: 2.0            # takes double damage
    duration-seconds: 15.0

Last updated Aug 22, 2026