Différences

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

--- en:yaml:modeles [2026/05/03 18:29] – Add English wiki page using real engine keys cyrilfiesta
+++ en:yaml:modeles [2026/10/20 22:23] (Version actuelle) – Modèles sur_place, portée des encadrés et objets 4.17 cyrilfiesta
@@ Ligne 1: / Ligne 1: @@
-**Language:** [[fr:yaml:modeles|Français]] | **English**
+**Language / Langue :** [[fr:yaml:modeles|FR]] | **EN**
 ====== Models (YAML) ======
-Models are reusable groups of rooms. They are useful for fights, repeated mini-games, puzzles or reusable systems.
+A model contains reusable rooms. Each instance binds its variable and exit names to those of the scenario.
-===== Declare a Model =====
+===== Example: a healing room =====
+This scenario opens the model, lets the player heal, then returns to the calling room's choices.
 <code yaml>
+title: Infirmary
+vars:
+  hp: 10
 models:
-  - name: simple_fight
+  healing:
     variables:
-      enemy_hp: enemy_hp
+      health: 0
-    exits:
-      victory: victory
-      defeat: defeat
     rooms:
-      - id: attack
+      - id: sheet
-        text: "You attack!"
+        text: 'Health: v_health_v'
-        events:
+        auto_refresh: true
-          - if: "v_enemy_hp_v <= 0"
+        actions:
-            to: victory
+          - verb: heal
-          - if: ~
+            target: all
-            do: "enemy_hp.-.3"
+            button: Heal
-            to: enemy_turn
+            do: health + 5
+        choices:
+          - button: Leave
+            to: end_model
+rooms:
+  - id: start
+    text: You enter the infirmary.
+    models:
+      - model: healing
+        variables:
+          health: hp
+    choices:
+      - button: Finish
+        to: conclusion
+  - id: conclusion
+    events:
+      - end: victory
+</code>
-      - id: enemy_turn
+The ''models:'' definitions are keyed by name, here ''healing''. The ''start'' room contains a list of instances: ''model: healing'' selects the definition and ''health: hp'' binds its generic variable to ''hp'', declared in the scenario.
-        text: "The enemy retaliates."
-        events:
+Internal rooms receive a prefix to avoid ID collisions. ''end_model'' resumes after the model: here, the Finish choice becomes available. A generic exit declared in ''exits:'' can also be bound to a scenario room in the instance.
-          - if: "v_hp_v <= 0"
-            to: defeat
+===== Bound lists and collections (4.17) =====
-          - if: ~
-            to: attack
+A model can declare generic lists and collections. Bind them to scenario data in the instance, without copying:
+<code yaml>
+lists:
+  products: world.shop.bag
+collections:
+  hero: world.state
 </code>
-===== Instantiate a Model =====
+Targets must exist. Paths cross collections only, without list indices. Required properties are checked when a parent is replaced or a saved game is resumed.
+See [[en:yaml:listes-boucles|Lists and collections]], [[en:yaml:tags|Tags]] and [[en:yaml:evenements|Events]].
+===== Adding a model to the current room: inline =====
+Set ''inline: true'' in the model definition. The model must contain exactly one internal room. Its initialisations, objects, actions, events, choices, shortcuts and HUD panels are added to the calling room, without entering a virtual room. The calling room keeps its ID and text; the internal room's text is not added.
 <code yaml>
-- id: goblin_fight
+title: A model in the workshop
-  text: "A goblin appears!"
+collections:
-  models:
+  player: {}
-    - name: simple_fight
+models:
-      variables:
+  inline_healing:
-        enemy_hp: goblin_hp
+    inline: true
-      exits:
+    collections:
-        victory: after_fight
+      hero: {health: 0}
-        defeat: game_over
+    defaults:
+      hero: {health: 100}
+    rooms:
+      - id: content
+        hud:
+          position: top-right
+          scope: room
+          text: 'Health: v_hero.health_v'
+        actions:
+          - verb: heal
+            target: all
+            button: Heal
+            do: hero.health + 1
+rooms:
+  - id: workshop
+    text: You are in the workshop.
+    models:
+      - model: inline_healing
+        collections: {hero: player}
+    choices:
+      - {command: leave, to: corridor}
+  - id: corridor
+    text: The corridor.
+    choices:
+      - {command: return, to: workshop}
 </code>
-Internal rooms are automatically prefixed to avoid ID collisions. ''end_model'' is the reserved keyword used to return to the calling room flow.
+Heal acts in the workshop and Leave remains available. Returning preserves ''player.health''. The model's ''init:'' entries run on each entry, just like the room's own initialisations, so they can explicitly reset values.
+''exits:'' and their instance bindings remain available. For an inline model, ''end_model'' refers to the calling room. Simple fields supplied by the model can replace room fields: check display settings in particular. Avoid competing commands and HUD positions; the linter reports a model panel replacing a room panel.
+''inline'' controls model integration. ''scope: room'' separately controls a panel's lifetime. **Without an explicit scope, panels remain persistent, including those from inline models.** See [[en:yaml:hud|HUD panels]]. French syntax: ''sur_place: true'' and ''portee: salle''.
+===== Collection defaults =====
+The example's ''defaults:'' block fills only missing properties in bound collections, before validation. Values already supplied by the scenario are preserved, including in nested collections. The target collection must exist: ''player: {}'' is sufficient here. Defaults apply to generic collections declared by the model; they do not replace room initialisations.
+The editor exposes inline insertion and defaults for each generic collection in the model definition. The French key is ''defauts:''.
+The supplied library includes ''grille_2d'', an inline model binding map and player collections. Its demos cover movement, collisions, furniture, doors and optional combat. It uses ordinary room objects and choices, with a panel explicitly scoped to the room. Copy the model and follow its definition comments to prepare the map and bindings.