Différences

Ci-dessous, les différences entre deux révisions de la page.

--- en:yaml:objets [2026/05/03 18:47] – Harmonize FR/EN language switch cyrilfiesta
+++ en:yaml:objets [2026/11/04 21:34] (Version actuelle) – Documentation 4.17 : objets, evenements et mise en page verifies cyrilfiesta
@@ Ligne 3: / Ligne 3: @@
 ====== 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''.
+Declarations in ''objects:'' define items and their initial locations in the room. They use the native bot commands: ''take'', ''inspect'' 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''.
@@ Ligne 38: / Ligne 38: @@
 ^ Field ^ Effect ^
-| ''name:'' | Object identifier. Required. |
+| ''name:'' | Object identifier. Optional for empty furniture, required for an item or removal. |
+| ''display_name:'' | Player-facing name, without changing the identifier. |
+| ''empty-furniture: true'' | Scenery accessible only through its furniture. |
 | ''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. |
+| ''absent: true'' | Declares an initially empty slot that can be activated. |
 | ''remove: true'' | Removes this object when entering the room, equivalent to the legacy ''-name'' prefix. |
 | ''remove_text:'' | Text used on removal when ''remove: true''. |
@@ Ligne 48: / Ligne 51: @@
 | ''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. Without a retained limit: 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 =====
@@ Ligne 55: / Ligne 61: @@
 ''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 =====
+===== Several copies of the same object =====
-Declare the same ''name:'' multiple times on the same ''location:'' to simulate a decreasing stock. Each pickup activates the next slot.
+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>
@@ Ligne 63: / Ligne 69: @@
   - name: coin
     location: chest
-    furniture_description: "The chest contains three coins."
+    description: "A worn silver coin."
-    description: "A gold coin."
-    pickup_text: "You take a coin. Two remain."
   - name: coin
-    location: chest
+    location: purse
-    furniture_description: "The chest still contains two coins."
+    description: "A coin still warm from someone's hand."
-    description: "A gold coin."
-    pickup_text: "You take a coin. One remains."
 </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 a limit retained from a previous declaration, 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 =====
@@ Ligne 79: / Ligne 97: @@
 <code yaml>
 if: "key"      # player owns key
+</code>
+Or:
+<code yaml>
 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: =====
@@ Ligne 110: / Ligne 148: @@
 ''description:'' and ''furniture_description:'' accept the same media syntax as narrative text: images ''%%[[url]]%%'', sounds ''%%<<url>>%%'' and videos ''%%((url))%%''.
+<code yaml>
+objects:
+  - name: map
+    location: table
+    description: "A map of the kingdom.\n[[https://example.com/images/map.png]]"
+    pickup_text: "You take the map."
+</code>
+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]]
+===== Display name and identifier =====
+''name:'' remains the stable identifier used by conditions, effects and saves. ''display_name:'' supplies a readable player-facing name:
+<code yaml>
+objects:
+  - name: workshop_key
+    display_name: workshop key
+    location: table
+    description: A small iron key.
+</code>
+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:''.
+===== Renaming during play =====
+In an interaction's ''do:'' block:
+<code yaml>
+do:
+  - display_name: workshop_key
+    value: identified workshop key
+</code>
+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''.
+===== Scenery and empty furniture =====
+''empty-furniture: true'' describes furniture without an item to take. Players can inspect the furniture, but cannot take or inspect this scenery as an item. Its ''name:'' is optional: the engine then creates an internal identity. Use ''furniture_description:'' and, if needed, ''furniture_reaction:''. Pickup, item inspection, display name and inventory limit fields provide no item interaction for this scenery.
+<code yaml>
+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
+    empty-furniture: true
+    location: table
+    furniture_description: The table is empty.
+  - name: statue_scenery
+    empty-furniture: true
+    location: statue
+    furniture_description: An old stone statue.
+    furniture_reaction: Examine the statue
+</code>
+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.
+''location: invisible'' keeps the historical uses of a hidden item; it is not empty furniture. With ''remove: true'', removal takes priority: an item name is required and the linter warns that ''empty-furniture'' is ignored. The editor preserves hidden field values and lets you correct contradictory settings. The linter rejects the ''secret'' key on objects; secret achievements keep their own setting. French syntax: ''meuble-vide: true'', ''endroit'', ''desc_meuble'' and ''reaction_meuble''.
+===== Reversible items and commands (4.17) =====
+Taking an item deactivates one declared instance in its furniture. ''put'' and ''place'' return it to an available declaration of the same item. These forms are equivalent: ''put piece in coffre'', ''place piece on coffre'' and ''put piece coffre''. Without furniture, ''put piece'' finds an available slot. A custom action with the same name takes priority. A refused deposit removes nothing from the inventory.
+Different items can share furniture. Inspecting furniture uses the first declaration with an item still present. Items are taken in declaration order; deposits fill free slots in reverse order.
+<code yaml>
+title: 'Wiki 4.17: stacks'
+vars:
+  capacite: 2
+rooms:
+- id: atelier
+  text: A chest and a table.
+  objects:
+  - name: piece
+    location: coffre
+    description: First coin.
+    inventory_limit: v_capacite_v
+  - name: piece
+    location: coffre
+    description: Second coin.
+  - name: cle
+    location: coffre
+    description: A key.
+  - empty-furniture: true
+    location: coffre
+    furniture_description: The chest is empty.
+  choices:
+  - command: rester
+    button: Stay
+    to: atelier
+</code>
+Here, ''piece'' can be taken twice. After putting one back in ''coffre'', the second declaration becomes present first. ''inspect_from coffre'' inspects the first item currently in that furniture; ''take_from coffre'' takes it. These commands target the slot, even if the same identifier exists elsewhere. French: ''examiner_objet_dans coffre'' and ''prendre_dans coffre''.
+===== Absent declarations, transfers and activation =====
+''absent: true'' reserves an initially empty slot. It can be filled after taking, transferring or activating an item.
+<code yaml>
+title: 'Wiki 4.17: activation'
+rooms:
+- id: atelier
+  text: A table, a chest and a box.
+  objects:
+  - name: cle
+    location: table
+  - name: cle
+    location: coffre
+    absent: true
+  - name: bille
+    location: boite
+    absent: true
+  actions:
+  - verb: ranger
+    target: all
+    button: Store the key
+    do:
+      object: cle
+      to: coffre
+  - verb: apparition
+    target: all
+    button: Reveal the marble
+    do:
+      object: bille
+      activate: boite
+  choices:
+  - command: rester
+    button: Stay
+    to: atelier
+</code>
+After ''take cle'', ''{object: cle, to: coffre}'' transfers one carried unit into the chest. ''{object: bille, activate: boite}'' activates an absent declaration without consuming inventory. A ''room:'' field can target another room. Test presence with ''if: {object: bille, in: boite, quantity: 1, operator: ">="}''.
+===== Inventory limit selection =====
+The first active declaration specifying a limit is used in the current room. If none specifies it, the last encountered limit is retained; otherwise the default is 1. A reference such as ''v_capacite_v'' is read again when adding an item. ''0'' means unlimited. Lowering the limit does not remove already carried units.