**Language / Langue :** [[fr:yaml:objets|FR]] | **EN**

====== Objects and Inventory (YAML) ======

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''.

===== Full Example =====

<code yaml>
- 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."
</code>

===== Available Fields =====

^ Field ^ Effect ^
| ''name:'' | Object identifier. Required. |
| ''location:'' | Furniture or place where the object is located. Default: ''invisible''. |
| ''description:'' | Text shown when the player examines the object. |
| ''furniture_description:'' | Text shown when the player examines the furniture/location. If missing, the engine falls back to ''description:''. |
| ''pickup_text:'' | Text shown when the object is taken. |
| ''remove: true'' | Removes this object when entering the room, equivalent to the legacy ''-name'' prefix. |
| ''remove_text:'' | Text used on removal when ''remove: true''. |
| ''furniture_reaction:'' | Button shown to examine the furniture. |
| ''pickup_reaction:'' | Button shown to take the object. |
| ''object_reaction:'' | Button shown to examine the object. |

===== Furniture, Object and Inventory =====

''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.

===== Progressive Stock =====

Declare the same ''name:'' multiple times on the same ''location:'' to simulate a decreasing stock. Each pickup activates the next slot.

<code yaml>
objects:
  - name: coin
    location: chest
    furniture_description: "The chest contains three coins."
    description: "A gold coin."
    pickup_text: "You take a coin. Two remain."
  - name: coin
    location: chest
    furniture_description: "The chest still contains two coins."
    description: "A gold coin."
    pickup_text: "You take a coin. One remains."
</code>

===== Object Conditions =====

In ''if:'' fields, test objects by name:

<code yaml>
if: "key"      # player owns key
if: "-key"     # player does not own key
</code>

===== Add or Remove an Object with do: =====

Recommended form:

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

The legacy action-string form is still accepted:

<code yaml>
do:
  - "rusty_key&&inventory&&An old rusty key."
  - "-fake_key&&inventory&&null"
</code>

===== Media in Descriptions =====

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