Items

Items are objects players can interact with — pick up, drop, use, examine, and equip. Items can also be weapons, containers, keys, healing potions, and more.

Schema

"item_id": {
  "name": "Rusty Sword",
  "description": "A dull blade, but still sharp enough to cut.",
  "keywords": ["sword", "blade", "rusty blade"],
  "takeable": true,
  "consumable": false
}

Base Fields

Field	Type	Default	Description
name	string	required	Display name shown to the player.
description	string	required	Text shown when the player examines the item.
keywords	array	[]	Alternative names for fuzzy matching. Players can refer to the item by any keyword.
takeable	boolean	true	Whether the player can pick up this item.
cant_take_msg	string	—	Custom message when trying to take a non-takeable item.
consumable	boolean	false	If true, the item is removed from inventory when used.

Weapons & Armor

Items can provide combat bonuses when in the player's inventory.

"iron_sword": {
  "name": "Iron Sword",
  "description": "A well-forged iron blade.",
  "weapon_damage": 8
}

"leather_shield": {
  "name": "Leather Shield",
  "description": "A sturdy shield made of hardened leather.",
  "defense_bonus": 3
}

Field	Type	Description
weapon_damage	number	Bonus damage added to attacks. Only the highest weapon_damage in inventory is used (not stacked).
defense_bonus	number	Bonus to defense. All defense bonuses in inventory are stacked (summed).

combat_effect

Items with combat_effect can be used during combat for special actions like healing.

"health_potion": {
  "name": "Health Potion",
  "description": "A glowing red potion.",
  "consumable": true,
  "combat_effect": {
    "type": "heal",
    "amount": 15
  }
}

Field	Type	Default	Description
type	string	—	Effect type. Currently only "heal" is supported.
amount	number	10	Amount of HP restored. Capped at player's max health.

on_use

Defines what happens when a player uses the item outside of combat.

"on_use": {
  "type": "unlock",        // or "message", "heal", "script"
  "requires_target": true,  // for "unlock": needs a target
  "sets_flag": "flag_name",
  "success_msg": "You use the item successfully."
}

type	Behavior
"unlock"	Sets a flag and shows a success message. Use with requires_target to require the player to specify what they're unlocking.
"message"	Simply displays the text field to the player.
"heal"	Restores HP by amount. Item is consumed if consumable: true.

on_use Fields

Field	Type	Description
type	string	One of: "unlock", "message", "heal"
requires_target	boolean	For "unlock" — requires player to specify a target
sets_flag	string	Flag to set when used
success_msg	string	Message shown on successful use
text	string	Message shown (for "message" type)
amount	number	HP restored (for "heal" type)

reveals_exit

Using the item reveals a hidden exit in the current room.

"magic_lens": {
  "name": "Magic Lens",
  "description": "A lens that reveals hidden things.",
  "reveals_exit": {
    "direction": "west",
    "message": "Through the lens, a hidden doorway shimmers into view!"
  }
}

on_examine

Special behavior when the item is examined. Can reveal exits or show custom text.

"suspicious_bookcase": {
  "name": "suspicious bookcase",
  "description": "A tall bookcase. One shelf seems slightly askew.",
  "takeable": false,
  "on_examine": {
    "reveals_exit": "west",
    "text": "Pulling a book triggers a mechanism. The bookcase swings open!"
  }
}

Field	Type	Description
reveals_exit	string	Direction of the exit to reveal in the current room.
text	string	Custom text shown instead of the normal description.

dice_roll

Items can trigger D&D-style dice rolls when used. See Dice Rolls for full details.

"lockpick": {
  "name": "Lockpick",
  "description": "A thin metal pick for opening locks.",
  "consumable": true,
  "dice_roll": {
    "dc": 12,
    "dice": "1d20",
    "attempt_message": "You carefully insert the lockpick...",
    "consume_on": "failure",
    "on_success": { /* ... */ },
    "on_failure": { /* ... */ }
  }
}

Non-Takeable Items

Some items are part of the environment and shouldn't be picked up. Set takeable: false and optionally provide a custom rejection message.

"fountain": {
  "name": "stone fountain",
  "description": "A beautiful fountain with crystal-clear water.",
  "takeable": false,
  "cant_take_msg": "The fountain is far too heavy to move."
}

Fuzzy Matching

The engine matches player input against items using this priority:

1. Exact ID match — e.g., take rusty_sword matches item ID rusty_sword
2. Keyword match — checks if any keyword contains the search term (or vice versa)
3. Name match — checks if the item's name contains the search term

All matching is case-insensitive. Good keywords make your items easier to interact with.