**Language / Langue :** [[fr:yaml:objets|FR]] | **EN** ====== Objects and Inventory (YAML) ====== 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''. ===== Full Example ===== - 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." ===== Available Fields ===== ^ Field ^ Effect ^ | ''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''. | | ''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. 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 ===== ''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. 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. ===== 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. 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''. ===== Object Conditions ===== In ''if:'' fields, test objects by name: if: "key" # player owns key Or: if: "-key" # player does not own key ===== Quantity conditions ===== 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. ===== Add or Remove an Object with do: ===== 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" ===== Media in Descriptions ===== ''description:'' and ''furniture_description:'' accept the same media syntax as narrative text: images ''%%[[url]]%%'', sounds ''%%<>%%'' 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 ''. ===== 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: 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:''. ===== Renaming during play ===== 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''. ===== 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. 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 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. 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 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. 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 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.