Consumable Item Configuration

Make an item that applies status effects to whoever uses it and is spent from the stack.

A consumable is an item type that, on primary use, applies one or more status effects to the user and is spent one from the stack — the basis for potions, food, and draughts. It’s an item type like any other, configured in item-config.yaml with a consumable-info block.

Where It’s Used

A catalog entry in item-config.yaml whose type is consumable:

items:
  - name: healing_draught
    type: consumable
    display-name: Healing Draught
    consumable-info:
      effects:
        - regeneration

The consumable-info block is required for a consumable-type item (as every typed item requires its matching *-info block).

Fields

consumable-info fields:

Field	Required	Default	Description
`effects`	yes	—	The status effect(s) applied to the user on use — a single effect id or a list. Each references an effect defined in status-effect-config.md, namespaced like any reference (a bare `regeneration` resolves to your own mod’s `regeneration`). At least one is required.
`cooldown-ms`	no	`0`	Minimum time between uses, in milliseconds. A use within this window of the user’s last consumable use is a no-op — nothing is applied and nothing is spent. This is what stops a held primary-use from draining the whole stack at once. `0` means no cooldown (each press consumes one). The cooldown is shared across consumables: after using any consumable, the user waits its `cooldown-ms` before the next consumable of any kind.

Behaviour

On primary use, every listed effect is applied to the user, then one is spent from the stack.
Effect ids are resolved when the item is used, not at load, so a consumable and its effects don’t depend on load order. An id that doesn’t resolve is logged and skipped; if none resolve, the item is not consumed (a misconfigured consumable can’t silently eat itself).
Server-authoritative: the effect and the health/inventory changes are applied on the server and synced to clients. A healing draught’s health gain and the effect’s HUD countdown both appear right after use.
Consumables stack like ordinary items; set stackable: false or a max-stack-size in the item entry if you want otherwise.

Example

# In status-effect-config.yaml
status-effects:
  - id: regeneration
    kind: heal-over-time
    magnitude: 2.0
    duration-seconds: 10.0

# In item-config.yaml
items:
  - name: healing_draught
    type: consumable
    display-name: Healing Draught
    tooltip: "Restores a little health over time."
    consumable-info:
      effects:
        - regeneration

Last updated Aug 17, 2026