Containers

Containers are items that can hold other items. They can be opened, closed, locked, and unlocked. Think chests, boxes, cabinets, and bags.

Schema

"wooden_chest": {
  "name": "Wooden Chest",
  "description": "A sturdy wooden chest bound with iron bands.",
  "is_container": true,
  "locked": true,
  "unlock_item": "chest_key",
  "unlock_flag": "chest_unlocked",
  "locked_message": "The chest is locked tight.",
  "on_open_message": "The lid creaks open, revealing treasures inside!",
  "on_close_message": "You close the chest lid.",
  "open_description": "An open wooden chest.",
  "closed_description": "A closed wooden chest with iron bands.",
  "empty_message": "The chest is empty.",
  "contents": ["gold_ring", "health_potion"],
  "takeable": false
}

Container Fields

Field	Type	Default	Description
`is_container`	boolean	`false`	Marks this item as a container. required for container behavior.
`locked`	boolean	`false`	If `true`, the container must be unlocked before opening.
`unlock_item`	string	—	Item ID needed in inventory to unlock the container.
`unlock_flag`	string	—	Global flag that must be `true` to unlock the container.
`locked_message`	string	—	Message shown when trying to open a locked container.
`on_open_message`	string	—	Message shown when the container is opened.
`on_close_message`	string	—	Message shown when the container is closed.
`open_description`	string	—	Description shown when examining an open container.
`closed_description`	string	—	Description shown when examining a closed container.
`empty_message`	string	—	Message shown when examining an open but empty container.
`contents`	array	`[]`	Item IDs initially inside the container.

Container Commands

Command	Effect
`open [container]`	Opens the container (must be unlocked). Shows contents.
`close [container]`	Closes the container.
`examine [container]`	Shows open/closed description and lists contents if open.
`take [item] from [container]`	Takes an item from an open container.

Unlocking Containers

A locked container can be unlocked in two ways:

1. By item (unlock_item)

The player must have the specified item in their inventory. The item is not consumed — it just needs to be present. The container unlocks when the player tries to open it.

2. By flag (unlock_flag)

A global flag must be true. This lets you gate containers behind quests, dialogue, or other events.

If both unlock_item and unlock_flag are set, having either one satisfied will unlock the container.

Nested Containers

Containers can hold other containers, creating nested structures. The engine supports recursive searching through open containers.

// A chest containing a box containing a ring
"big_chest": {
  "name": "Big Chest",
  "is_container": true,
  "contents": ["small_box"]
}

"small_box": {
  "name": "Small Box",
  "is_container": true,
  "contents": ["gold_ring"]
}

Important:

Only open containers are searchable. If the Big Chest is open but the Small Box inside it is closed, the player can see the Small Box but can't access the Gold Ring until they also open the Small Box.

Examining Containers

When a player examines a container, they see:

Closed: The closed_description (or default description)
Open with items: The open_description + a list of contents
Open and empty: The empty_message (or a default "It's empty.")

Full Example

"ornate_cabinet": {
  "name": "Ornate Cabinet",
  "description": "A tall cabinet with glass doors and golden trim.",
  "keywords": ["cabinet", "cupboard"],
  "is_container": true,
  "takeable": false,
  "cant_take_msg": "The cabinet is bolted to the wall.",
  "locked": true,
  "unlock_item": "cabinet_key",
  "locked_message": "The glass doors are locked. You can see items inside but can't reach them.",
  "on_open_message": "The glass doors swing open with a gentle chime.",
  "on_close_message": "You carefully close the cabinet doors.",
  "open_description": "The cabinet stands open, its shelves exposed.",
  "closed_description": "Through the glass, you can make out shapes on the shelves.",
  "empty_message": "The shelves are bare.",
  "contents": ["ancient_map", "silver_dagger"]
}