Item

An item is metadata about a thing the player can carry: its name, description, stacking behavior, and tags. The actual inventory is not stored on the Item entity itself; it’s a list-typed Variable that holds item ids. You create items in the editor’s Items panel, then reference them in expressions with Has(var_inventory, "item_<id>") and in events that grant or consume them.

For conventions shared by all entity types, see Entities.

Fields

Custom fields

Author-defined key-value bag for host-specific data. Free-form; the engine treats it opaquely so studios can add their own integration metadata such as sprite ids, rarity tiers, gameplay flags, or vendor pricing. The editor exposes it as a key-value editor in the item inspector. Has no runtime effect on the story engine.

Description

Optional author-typed prose explaining the item. Shown in the editor’s item inspector and can be read by the host UI for tooltip or inventory-detail views. No runtime effect.

Display name

The human-readable label shown in the editor’s items table, in inventory listings, and in any host UI that displays the item’s name. Free-form string, author-typed.

Translator notes

Display name can carry a translator note: see Entities for more information.

ID

The item’s expression-namespace identifier. You’ll use this in expressions that check inventory membership (Has(var_inventory, "item_<id>")) and as the key the engine looks up when resolving an item reference in events that grant or consume items. Pick from the editor’s item picker. Renaming the ID updates expressions that mention the old name.

Convention: item ids are prefixed item_. Existing items aren’t renamed when the prefix convention shifts; consistency is enforced at create-time only.

Stackable

When true, multiple copies of the same item type are treated as a single stacked entry in the inventory list. When false, each copy is a distinct list element. Use this for consumables and other quantitative items (stackable) versus unique single-instance items (not stackable). Default is false.

When to reach for items

Items are the right shape when the same thing can change hands. A photograph the player picks up, hides in a drawer, and later gives to a witness is an item; inventory tracking lives in a list-typed variable that the host game reads, and events grant or consume by appending or removing the item id. If the answer to “does the player still have it?” matters across scenes, it is probably an item; if the answer is always “yes” once collected, a variable or a tag fits better.

Items also double as world-layer encounter triggers. When the host UI surfaces an item somewhere in the game world (a poster on a wall, a letter on a desk), clicking it starts whichever encounter is currently available at the player’s location. The runtime tracks the available set and tells the host which encounter the click starts.