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

====== Modèles (YAML) ======

Un modèle contient des salles réutilisables. Chaque instance associe ses noms de variables et de sorties à ceux du scénario.

===== Exemple : une salle de soins =====

Ce scénario ouvre le modèle, permet de se soigner, puis revient aux choix de la salle appelante.

<code yaml>
titre: Infirmerie
vars:
  pv: 10
modeles:
  soins:
    variables:
      vie: 0
    salles:
      - id: fiche
        texte: 'Points de vie : v_vie_v'
        auto_refresh: true
        actions:
          - verbe: soigner
            cible: all
            bouton: Soigner
            faire: vie + 5
        choix:
          - bouton: Sortir
            vers: fin_modele
salles:
  - id: depart
    texte: Tu entres dans l'infirmerie.
    modeles:
      - modele: soins
        variables:
          vie: pv
    choix:
      - bouton: Terminer
        vers: conclusion
  - id: conclusion
    evenements:
      - fin: victoire
</code>

Les définitions de ''modeles:'' sont rangées par nom, ici ''soins''. La salle ''depart'' contient une liste d'instances : ''modele: soins'' choisit la définition et ''vie: pv'' relie la variable générique à ''pv'', déclarée dans le scénario.

Les salles internes reçoivent un préfixe pour éviter les collisions d'ID. ''fin_modele'' reprend après le modèle : ici, le choix Terminer devient disponible. Une sortie générique déclarée dans ''sorties:'' peut aussi être associée à une salle du scénario dans l'instance.

===== Listes et collections associées (4.17) =====

Le modèle peut déclarer des listes et collections génériques. Dans l'instance, les associer aux données du scénario, sans copie :

<code yaml>
listes:
  produits: monde.marchand.sac
collections:
  heros: monde.etat
</code>

Les cibles doivent exister. Le chemin traverse uniquement des collections, sans indice de liste. Les propriétés requises restent contrôlées si un parent est remplacé ou après une reprise de sauvegarde.

Voir [[fr:yaml:listes-boucles|Listes et collections]], [[fr:yaml:tags|Tags]] et [[fr:yaml:evenements|Événements]].

===== Ajouter un modèle dans la salle : sur_place =====

''sur_place: true'' se place dans la définition du modèle. Il doit contenir exactement une salle interne. Ses initialisations, objets, actions, événements, choix, raccourcis et encadrés sont ajoutés à la salle appelante, sans détour par une salle virtuelle. Le texte et l'identifiant de la salle appelante sont conservés ; le texte de la salle interne n'est pas ajouté.

<code yaml>
titre: Un modèle dans l'atelier
collections:
  joueur: {}
modeles:
  soins_sur_place:
    sur_place: true
    collections:
      heros: {vie: 0}
    defauts:
      heros: {vie: 100}
    salles:
      - id: contenu
        encadre:
          position: haut-droite
          portee: salle
          texte: 'Vie : v_heros.vie_v'
        actions:
          - verbe: soigner
            cible: all
            bouton: Soigner
            faire: heros.vie + 1
salles:
  - id: atelier
    texte: Vous êtes dans l'atelier.
    modeles:
      - modele: soins_sur_place
        collections: {heros: joueur}
    choix:
      - {commande: sortir, vers: couloir}
  - id: couloir
    texte: Le couloir.
    choix:
      - {commande: revenir, vers: atelier}
</code>

Ici, Soigner agit dans l'atelier et Sortir reste disponible. En revenant, la valeur de ''joueur.vie'' est conservée. Les ''init:'' du modèle sont exécutés à chaque entrée comme ceux de la salle : ils peuvent donc réinitialiser explicitement des valeurs.

Les ''sorties:'' et leurs associations dans l'instance restent utilisables. ''fin_modele'' désigne la salle appelante pour un modèle sur place. Les champs simples fournis par le modèle peuvent remplacer ceux de la salle : vérifier notamment les réglages d'affichage. Éviter aussi les commandes et positions d'encadrés concurrentes ; le linter signale un encadré de modèle qui remplace celui de la salle.

''sur_place'' règle l'intégration du modèle. ''portee: salle'' règle séparément la durée de vie d'un encadré. **Sans portée explicite, un encadré reste persistant, même dans un modèle sur place.** Voir [[fr:yaml:hud|Encadrés HUD]]. En anglais : ''inline: true'' et ''scope: room''.

===== Valeurs par défaut des collections =====

Le bloc ''defauts:'' de l'exemple complète uniquement les propriétés absentes des collections associées, avant leur validation. Une valeur déjà fournie par le scénario reste conservée, y compris dans les collections imbriquées. La collection cible doit exister : ''joueur: {}'' suffit ici. Les valeurs par défaut s'appliquent aux collections génériques déclarées par le modèle ; elles ne remplacent pas une initialisation de salle.

Dans l'éditeur, la définition du modèle propose l'insertion dans la salle appelante et les valeurs par défaut de chaque collection. En anglais, le bloc s'appelle ''defaults:''.

La bibliothèque fournie comprend ''grille_2d'', un modèle sur place associant une carte et un joueur à des collections. Ses démonstrations montrent déplacements, collisions, meubles, portes et combat facultatif. Il utilise les objets et choix ordinaires de la salle, ainsi qu'un encadré explicitement limité à cette salle. Copier le modèle et suivre les commentaires de sa définition pour préparer la carte et les associations.