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

====== Models (YAML) ======

A model contains reusable rooms. Each instance binds its variable and exit names to those of the scenario.

===== 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:
  healing:
    variables:
      health: 0
    rooms:
      - id: sheet
        text: 'Health: v_health_v'
        auto_refresh: true
        actions:
          - verb: heal
            target: all
            button: Heal
            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>

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.

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.

===== Bound lists and collections (4.17) =====

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>

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>
title: A model in the workshop
collections:
  player: {}
models:
  inline_healing:
    inline: true
    collections:
      hero: {health: 0}
    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>

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.