Content-Driven Status Effects

Status effects are a YAML catalog. Content references an effect id; the sim applies mods and periodic ticks from that definition. Designers do not hard-code “frost” or “fortify” in Rust.

Two clocks (do not confuse them)

When a while_equipped binding is active and the item is worn, the entity gets the named effect (using the effect’s own duration/refresh rules while equipped). When the binding expires, the enchantment falls off the item.

Catalog (named effects)

Author once under the content files (admin → Status effects):

• id, label, polarity (buff / debuff / neutral)
• dot_color — #RRGGBB tint for world/HUD status dots
• duration_sec, clear_on_death, stacking (refresh | stack | single), max_stacks (default 10 when stacking)
• Stat mods — add / mul / override on closed keys (move_speed, damage_dealt, armor_physical, attr.strength, regen.health, …). On damage_dealt and damage_taken, optional damage_type limits the row to hits of that type (fire, frost, water, air, …). A blank type still applies to every hit.
• Periodic damage/heal ticks (interval_sec, optional damage_type)

Schema: schemas/status-effect.schema.json.

Ops (runtime)

Per modifier: Add, Mul, or Override (priority + newest on ties). Collect Muls × (base + Adds); Override wins when present.

• ActiveStatus on entities
• Apply / refresh same id / expire / clear on death
• Unequip clears template grant_effects_while_equipped and inactive instance while_equipped grants
• Combat path: damage_dealt, damage_taken (optional per-type), armor_physical, resists
• Movement: move_speed; regen/drain: regen.* / drain.*; attrs: attr.*
• Protocol: StatusEffectHud on combat HUD; gfx does not open T1/T2 solely because a buff is active

Attach points (complete picture)

┌─────────────────────────────────────────────────────────────────┐
│  Status effect catalog (id → duration, mods, periodic)          │
│  the content files*.yaml                            │
└────────────────────────────┬────────────────────────────────────┘
                             │ referenced by id
     ┌───────────────────────┼───────────────────────┐
     ▼                       ▼                       ▼
 Abilities              Item templates          Instance grants
 on_hit apply_status    (all mints of template) (one item_instance_id)
 requires_*_status

Modes for grants_item_status (not “consumable type”)

These describe how the bound effect fires on the gear, not how you drink the oil:

Fortify oil is a consumable that performs a grant; its mode must be while_equipped, not on_hit. content editor Items/Consumables use a catalog <select> for effect_id (not a free-text datalist); mode defaults to while_equipped when creating a new grant row.

Fortify oil (worked example)

Authored on the item (the content files):

grants_item_status:
  effect_id: fortify
  mode: while_equipped
  success_chance: 1.0
  copper_cost: 0
  duration_sec: 3600.0   # ← 1 hour binding TTL (inventory countdown)

Do not put fortify in apply_status_ids for this oil (that would drink-apply a 12s entity buff and skip the gear picker).

Play loop:

1. Inventory → select oil → e → pick wearable → Enter (UseGrant)
2. Binding appears on that instance (e.g. “fortify · while equipped · 50m left”)
3. Equip the piece → entity shows Fortify while worn
4. After duration_sec from step 1, binding expires off the item

Admin map

Latent marks

Set latent: true and the effect's mods and periodic ticks stay off until an ability uses on_hit: { kind: activate_latent, effect_id }.

A boon leaves consume_on_activate false. Each activating spell pulses the effect once while the mark remains.

Catalog

Gear examples that are not statuses themselves:

Player UX

• Grant picker: inventory e / Move → Apply onto gear…
• Inventory & Equip show instance bindings + remaining binding time
• Character / Equip show active entity statuses
• Combat dock status strip only when combat UI is already open (target / in combat / cast) — buffs alone do not open T1/T2

Out of scope (deferred)

Multi-stack formulas, dispel schools, CC (stun/root), enchanting-station procs beyond this substrate.

Ops / reload

Edit YAML → content publish (or restart worker).