DND Engine Registry
Module Registry / consumable

consumable

Registers under Consumables · source: modules/consumable/v1

`icon_id`: filename stem of this item's art in assets/items/ — pure display data, see bot/item_icons.py. `tags`: free-text Catalog-filter labels (e.g. "pixel art") — same pure display status, see modules/ weapon/v1's own docstring for the full reasoning (DND-30, 2026-10-20). `essence_type_id`/`amount`/`stat_id`/`difficulty`/`restore_percent`: the flat, community-settable alternative to `effect_payload` — see the module-level `_PAYLOAD_BUILDERS` comment above and the `effect_kind` breakdown below for which field(s) each kind actually uses. Ignored entirely if `effect_payload` is passed directly (the trusted-Python way every existing content file already uses). `can_be_in_shop`/`shop_price` — same "tag eligibility + a price, nothing more" convention weapon/armor/accessory already use (see e.g. modules/weapon/v1) — feeds the Shop's `CanBeInShop: true` pool (see combat-engine-readme.md → Gear → Locations & Economy) exactly the same way, now that /shop actually looks at the consumable category too (see bot/cogs/shop.py). Defaults to False: a consumable with no explicit shop flag is story/quest-reward-only by default, the same as every other item category — not everything needs a price tag, and nothing here should silently become purchasable just because it's real content. If `shop_price` is left at its default (0.0, falsy), bot/item_pricing.py's resolve_shop_price falls back to content/tuning.py's shopPriceByTier, keyed by `tier` below — the same fallback weapon/armor/accessory items get. `tier` — display-only (item tile border/glow) AND the shopPriceByTier lookup key described above; validated against VALID_TIERS same as armor/accessory. `effect_kind`: statReset — clears all accumulated Stat EXP (see engine.progression.apply_stat_exp). skillTreeReset — resets one skill tree branch (see engine.skill_tree.reset_branch); WHICH branch is picked at use-time, not baked into the item (see discord-commands-ui.md's open question about `/item use` needing a follow-up for some items — resolved here as an extra command param, not a multi-step UI flow). essenceRefill — grants `effect_payload = {"essenceTypeId": ..., "amount": ...}` via engine.essence.apply_given. heal — restores `effect_payload = {"amount": ...}` HP, capped at the character's maxHp. `tabletop- design-story.md`'s "Item" combat category is framed as usable mid-fight, but `/fight` currently resolves a whole battle atomically in one command call (see bot/cogs/combat.py) — so in practice this only helps *between* fights right now, not mid-round. Wiring items into an actual in-progress round is Action-Economy territory, not solved here. soulCatch — combat-engine-readme.md → Death & Recovery's SoulCatchAttempt item: `effect_payload = {"statId": ..., "difficulty": ...}`. Belongs to a *teammate* (a fellow in-game Guild member — see bot/cogs/recovery.py), not the fallen character — the doc frames this as something the party attempts on your behalf, not something you use on yourself. Resolved via engine.hp.soul_catch_attempt using the attempting teammate's own stats. revive — combat-engine-readme.md → Death & Recovery's "in-dungeon revive" item: `effect_payload = {"restorePercent": ...}` of maxHp, no roll, bypasses SoulCatchAttempt and the recovery campaign entirely. Works two ways (see bot/cogs/recovery.py): a teammate can use one directly on a fallen ally at any point after death, or a solo player can carry one themselves for an automatic self-revive at the moment of death (nothing else can save a player with no Guild — see resolve_combat_defeat). Neither `soulCatch` nor `revive` is dispatched through `/item use` — both are consumed automatically by the Death & Recovery flow, not a direct player action, so `/item use` on either correctly falls through to its "unhandled effect kind" message.

Example Usage

resource "flask_of_vigor" {
  source: modules/consumable/v1
  id: "flask_of_vigor"
  name: "Flask of Vigor"
  effect_kind: "essenceRefill"
  essence_type_id: "stamina"
  amount: 20.0
  tier: "common"
  can_be_in_shop: true
  description: "A stamina-restoring flask. Common among melee fighters."
  icon_id: "flask_of_vigor"
  tags: ["pixel art"]
}

Arguments Reference

The following arguments are supported:

  • id - (Required) The unique id this record is registered and referenced under — what a `.resource` file's own filename-independent identity is, and what any other content's foreign-key-style field (a dungeon node's `next`, a skill node's `parent_id`, and so on) points at. community
  • name - (Required) The player-facing display label — shown everywhere a player sees this record (shop listings, inventory, character sheet, etc.); the raw id is never shown directly. community
  • effect_kind - (Required) `effect_kind`: statReset — clears all accumulated Stat EXP (see engine.progression.apply_stat_exp). skillTreeReset — resets one skill tree branch (see engine.skill_tree.reset_branch); WHICH branch is picked at use-time, not baked into the item (see discord-commands-ui.md's open question about `/item use` needing a follow-up for some items — resolved here as an extra command param, not a multi-step UI flow). essenceRefill — grants `effect_payload = {"essenceTypeId": ..., "amount": ...}` via engine.essence.apply_given. heal — restores `effect_payload = {"amount": ...}` HP, capped at the character's maxHp. Valid options are essenceRefill, heal, revive, skillTreeReset, soulCatch and statReset. community
  • effect_payload - (Optional) Defaults to None. developer
  • can_be_in_shop - (Optional) `can_be_in_shop`/`shop_price` — same "tag eligibility + a price, nothing more" convention weapon/armor/accessory already use (see e.g. modules/weapon/v1) — feeds the Shop's `CanBeInShop: true` pool (see combat-engine-readme.md → Gear → Locations & Economy) exactly the same way, now that /shop actually looks at the consumable category too (see bot/cogs/shop.py). Defaults to False. community
  • shop_price - (Optional) Defaults to 0.0. community
  • description - (Optional) Flavor text shown to players — pure display data with no effect on game mechanics. community
  • icon_id - (Optional) `icon_id`: filename stem of this item's art in assets/items/ — pure display data, see bot/item_icons.py. community
  • essence_type_id - (Optional) `essence_type_id`/`amount`/`stat_id`/`difficulty`/`restore_percent`: the flat, community-settable alternative to `effect_payload` — see the module-level `_PAYLOAD_BUILDERS` comment above and the `effect_kind` breakdown below for which field(s) each kind actually uses. Currently registered: ammo, mana and stamina. community
  • amount - (Optional) Defaults to 0.0. community
  • stat_id - (Optional) Currently registered: strength, agility, evasiveness, luck, vitality, wisdom and charisma. community
  • difficulty - (Optional) Defaults to 0.0. community
  • restore_percent - (Optional) Defaults to 0.0. community
  • tier - (Optional) `tier` — display-only (item tile border/glow) AND the shopPriceByTier lookup key described above; validated against VALID_TIERS same as armor/accessory. Valid options are common, legendary and rare. Defaults to 'common'. community
  • tags - (Optional) `tags`: free-text Catalog-filter labels (e.g. "pixel art") — same pure display status, see modules/ weapon/v1's own docstring for the full reasoning (DND-30, 2026-10-20). Defaults to None. community