Objects declared in objects: are added when the player enters the room. They use the native bot commands: take, examine and drop.

Important: YAML objects do not support if: or visible-if: directly. To make an object conditional, use another room, an event, a choice, a tag, or an object with remove: true.

- id: library
  text: |
    A cluttered table stands in the room.
    An old chest rests against the wall.
  objects:
    - name: grimoire
      location: table
      furniture_description: "An old wooden table. A dusty grimoire lies on it."
      description: "An old grimoire with yellowed pages."
      pickup_text: "You take the grimoire from the table."
      furniture_reaction: "Examine the table"
      pickup_reaction: "Take the grimoire"
      object_reaction: "Examine the grimoire"

    - name: key
      location: invisible
      description: "A small silver key."
      pickup_text: "You pick up the key."

    - name: old_potion
      remove: true
      location: invisible
      remove_text: "The old potion disappears from your bag."

location: defines visible furniture. With location: chest, the player can examine chest. furniture_description: describes the chest, while description: describes the object itself.

location: invisible means the object exists in the room but is not directly listed as a visible object to take. This is useful for internal states or event-managed objects.

Declaring the same name: several times now means several real copies, including across different furniture or rooms. Taking one no longer hides the others, and each keeps its own description in the scenery.

objects:
  - name: coin
    location: chest
    description: "A worn silver coin."
  - name: coin
    location: purse
    description: "A coin still warm from someone's hand."

The inventory groups them as coin x 2. Throwing, using or removing an object only consumes one unit, and the historical object / -object conditions keep their meaning.

inventory-limit: sets the maximum. Without it, the player holds one copy. 0 means unlimited.

objects:
  - name: torch
    location: wall
    inventory-limit: 3
    inventory-limit-message: "You already carry three torches."

Going over the limit is a normal narrative answer, not an error: the engine states how many copies are already held and what the limit is, then leaves the commands available. The two optional messages accept the usual text processing, including v_variable_v and t_variable_t.

In if: fields, test objects by name:

if: "key"      # player owns key

Or:

if: "-key"     # player does not own key

A structured condition compares the number of copies held.

events:
  - if:
      object: coin
      quantity: 3
      operator: ">="
    text: "You have enough coins to pay the ferryman."

The editor offers this setting in its condition builder.

Recommended form:

events:
  - if: ~
    do:
      - object: rusty_key
        to: inventory
        description: "An old rusty key."
      - object: fake_key
        to: inventory
        remove: true
    text: "Your keyring changes."

The legacy action-string form is still accepted:

do:
  - "rusty_key&&inventory&&An old rusty key."
  - "-fake_key&&inventory&&null"

description: and furniture_description: accept the same media syntax as narrative text: images [[url]], sounds <<url>> and videos ((url)).

objects:
  - name: map
    location: table
    description: "A map of the kingdom.\n[[https://example.com/images/map.png]]"
    pickup_text: "You take the map."

Clicking an object in the inventory automatically runs inspect <object>.

• Conditions
• Custom actions
• Sounds, images and videos

name: remains the stable identifier used by conditions, effects and saves. display_name: supplies a readable player-facing name:

objects:
  - name: workshop_key
    display_name: workshop key
    location: table
    description: A small iron key.

The player can type take workshop key, examine workshop key, or use workshop_key. Display-name matching ignores case, accents and repeated spaces. Commands, aliases, identifiers and explicit action targets keep priority; furniture and variables can still be examined even if an object shares their display name.

The inventory numbers distinct objects sharing a display name, for example drink 1 and drink 2; these labels can be typed. Copies of the same identifier remain grouped. Always use identifiers in conditions and effects. t_action_target_t also contains the resolved identifier.

In the editor, Display name expands on demand and stays open when populated. French syntax: nom_affiche:.

In an interaction's do: block:

do:
  - display_name: workshop_key
    value: identified workshop key

The effect changes the display name without changing the identifier or quantities. Saves retain it. Setting value: “” restores the identifier workshop_key, even if the original declaration supplied another display name. This effect is not allowed inside loop bodies. In the editor, use Rename an item, with the object and its new display name. French syntax: nom_affiche and valeur.

secret: true reserves an entry for its furniture description. The player can examine the furniture, but cannot take or examine the secret object itself. Its object description, display name, pickup text and object/pickup buttons are ignored; use furniture_description and optionally furniture_reaction.

objects:
  - name: workshop_key
    display_name: workshop key
    location: table
    furniture_description: A key rests on the table.
    description: A small iron key.
  - name: empty_table
    secret: true
    location: table
    furniture_description: The table is empty.
  - name: statue_scenery
    secret: true
    location: statue
    furniture_description: An old stone statue.
    furniture_reaction: Examine the statue

Place an empty-furniture entry after the ordinary objects on that furniture. The first object still present supplies its description; after taking the key, examine table shows “The table is empty.” The statue illustrates permanent scenery.

secret differs from location: invisible, which retains the object's historical uses. Do not combine secret: true and remove: true: removal takes priority and the linter reports that secret is ignored. The editor hides unused secret fields while preserving their values, and allows contradictory imports to be corrected. French syntax: secret: true, endroit, desc_meuble and reaction_meuble.