**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. |
| ''inventory-limit:'' | How many copies the player may hold. Absent: one copy. ''0'': unlimited. |
| ''inventory-limit-message:'' | Optional text shown when the limit is reached. |
| ''throw-missing-message:'' | Optional text shown when the player throws an object they do not carry. |

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

===== Several copies of the same object =====

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.

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

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.

===== How many copies can be held =====

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

<code yaml>
objects:
  - name: torch
    location: wall
    inventory-limit: 3
    inventory-limit-message: "You already carry three torches."
</code>

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

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

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

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

===== Quantity conditions =====

A structured condition compares the number of copies held.

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

The editor offers this setting in its condition builder.

===== 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))%%''.

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

===== See also =====

  * [[en:yaml:conditions|Conditions]]
  * [[en:yaml:actions|Custom actions]]
  * [[en:yaml:medias|Sounds, images and videos]]