Items System

Items in Dryad Engine follow the same layered philosophy as everything else. When equipped, an item applies a status to the character - adding stats, granting abilities, or changing appearance.

Items Are Status Containers

Like skills and buffs, equipped items add a status layer to the character:

Unequip the item, and its status is removed. The character loses those bonuses immediately.

The Editor Forms

Item Traits

What they are: Custom data fields for items (like Character Traits, but for items).

Go to Items > Item Traits and define fields like:

When to use: Any data you want to store on items - display info, stats, custom properties.

Fixed-option traits (rarity)

Traits with a chooseOne type give a fixed option list — rarity (common, uncommon, rare, epic, legendary, quest) ships this way for every game, and you can define your own in the item_traits file.

When to use: Filtering items in UI, driving visual styles, game logic branches.

Item Slots

What they are: Equipment positions on characters.

Items define which slots they can go into (the item's slots). Characters define which slots they have (and where they appear in the equipment UI).

accepts — sharing one item across many slots. A slot always admits items targeting its own id. The optional accepts field lists extra slot tokens it also admits, so a single item can fit many slots without listing each one. Define a shared "tag" slot (with no character instances) and have the real slots accept it:

A general trinket sets slots: ["trinket_general"] and fits every character's trinket slot; a character-specific trinket sets slots: ["trinket_ane"] and fits only Ane's. Adding a new character never touches existing items — its slot simply lists trinket_general in accepts. Leave accepts empty for an ordinary slot (it matches its own id only).

Item Categories

What they are: Player-facing inventory filter groups — the tabs (and their icons) in the inventory UI. Unrelated to Item Slots: categories never affect where an item equips; they only sort the inventory view.

Go to Items > Item Categories and define groups:

Each item template picks one category (its category field). The inventory shows a built-in All tab plus one tab per category, with a name search box; items with no category appear only under All.

Item Templates

What they are: The actual item definitions.

A traits.item_level number renders as a level badge on the item card – a purely visual indicator. Systems that scale item instances (e.g. the experience plugin's dungeon-level scaling) stamp it on creation.

Example - Iron Sword:

Inventories

What they are: Containers that hold items.

Special inventories:

Equipment Flow

Consumable Items

Items are consumable for one-time-use effects (potions, scrolls, buff foods). There is no is_consumable flag — an item is consumable when it has any consume effect: it applies a status, restores/reduces a resource, or defines a consume action script. When it does, a Consume choice appears in the inventory automatically.

What Happens on Consume

Template Fields

Equip status and consume statuses are independent

status is applied on equip; apply_statuses_on_consume on consume. An item can carry both and they can differ — e.g. a Golden Apple gives +2 luck while equipped, and +10 health when eaten.

Duration, stacking, and mutual exclusion live on the status

Because consume statuses are real templates, their duration / max_stacks / multi_stack come from the status itself. To make ranked variants replace each other (small_blessing → big_blessing), give them the same group_id on the status template — applying one removes any other in the group, regardless of how it was applied (status action, consumable, or battle effect).

Usable Items

An item with a use_scene trait gets a Use choice in the inventory. The trait's value is a scene reference (dungeon_id.room_id.scene_id, room_id.scene_id, a full #id, or an &anchor), and picking Use plays that scene with the item as the active item.

The engine does nothing else: no cost, no gating, no consumption. The scene owns all of it, which is what makes one trait enough for every kind of usable item — a key, a letter, a single-use charm.

#lockpick_use
1
%
|I| work the |item| into the lock until something inside it gives.
{remove_item: true}

book and painting are the two specialized cousins of this trait — they render their own reader / viewer instead of playing an authored scene. Reach for use_scene for everything else.

Accessing Items in Code

Common patterns:

Item Actions (scripting)

Scene actions for items (used in dungeon content). See Actions for full syntax.

Prefer equip over equip_item/unequip_item for normal scripting: it takes stable character and item ids, while equip_item/unequip_item operate on the active item's uid.

Item Events

Example - Cursed items:

Quick Reference

Next Steps

• Exchange - Trading, shops, and currencies
• Apply - Crafting and custom apply logic
• Overview - How items connect to the status system