====== Règle « remplacer » ======

Une **règle remplacer** **écrase intégralement** une action existante : description, phases (''prérequis'', ''exécution'', ''épilogue''), balises d’aide… Tout le bloc d’origine est remplacé par le vôtre. C’est l’outil à utiliser quand on veut **réécrire** une action (souvent une [[reference:routines:actions_predefinies:start|action de base]] héritée du moteur) plutôt que de simplement la conditionner ([[reference:routines:regle:avant|règle avant]]) ou y ajouter une réaction ([[reference:routines:regle:apres|règle après]]).

===== Syntaxe =====

<code donjon>
règle remplacer <action>:
  -- phases qui remplacent intégralement l’action d’origine
fin règle
</code>

Le bloc se ferme par ''fin règle'' — c’est bien une règle qui s’applique sur une action.

Le mot ''action'' après ''remplacer'' est **facultatif**. Les deux formes sont équivalentes :

<code donjon>
règle remplacer sauter:        -- forme courte
règle remplacer action sauter: -- forme explicite
</code>

===== Correspondance par signature =====

Une règle remplacer ne touche **que** l’action dont la **signature** correspond exactement. La signature combine :

  * **l’infinitif** (''sauter'', ''examiner'', ''ouvrir''…)
  * **l’arité** : sans complément / avec ''ceci'' / avec ''ceci'' et ''cela''
  * **les prépositions** (''sauter sur ceci'', ''mettre ceci dans cela''…)
  * **le type** de ''ceci'' et ''cela'' donné dans ''définitions:'' (''objet'', ''lieu'', ''direction'', ''personne'', ''vivant''…)

Si une seule de ces dimensions diffère, l’action **n’est pas remplacée**.

<WRAP info>Les **épithètes** (''visible'', ''vu'', ''accessible'') et la **priorité** (''prioritairement…'') ne participent **pas** à l’identification. Recopiez-les tout de même dans votre bloc remplaçant : comme le remplacement est total, ces critères sont aussi remplacés ; si vous les omettez, le résolveur de commandes peut ne plus sélectionner votre version au profit d’une autre action concurrente.</WRAP>

==== Exemple 1 — signature simple (sans complément) ====

<file donjon wiki_regles_remplacer_sauter>
Le belvédère est un lieu.
Le joueur se trouve dans le belvédère.

règle remplacer sauter:
  phase épilogue:
    dire "Vous bondissez sur place. Quelle vue !".
fin règle
</file>

[[djnc>wiki_regles_remplacer_sauter|tester cet exemple]] — testez avec la commande ''sauter''.

==== Exemple 2 — l’arité compte (sauter ≠ sauter sur ceci) ====

''sauter'' et ''sauter sur ceci'' sont deux signatures distinctes. Une règle qui cible l’une **ne touche pas** l’autre.

<file donjon wiki_regles_remplacer_sauter_sur>
Le belvédère est un lieu.
Le joueur se trouve dans le belvédère.
Le banc est un support ici.

règle remplacer sauter:
  phase épilogue:
    dire "Vous bondissez sur place.".
fin règle

règle remplacer sauter sur ceci:
  phase épilogue:
    dire "Vous voilà perché sur [le ceci].".
fin règle
</file>

[[djnc>wiki_regles_remplacer_sauter_sur|tester cet exemple]] — essayez ''sauter'' puis ''sauter sur le banc''.

==== Exemple 3 — désambiguïsation par ''définitions'' ====

Plusieurs actions du moteur partagent le même infinitif et la même arité, mais ciblent des **types** différents. Le fichier ''actions.djn'' définit par exemple quatre ''examiner ceci'' (direction, lieu, objet, spécial). Pour cibler la bonne version, reproduisez le bloc ''définitions'' de la version visée :

<code donjon>
règle remplacer examiner ceci:
  définitions:
    ceci est un objet prioritairement visible et mentionné.
  phase épilogue:
    dire "Rien d’intéressant à signaler sur [le ceci].".
fin règle
</code>

Si plusieurs actions correspondent sans pouvoir être désambiguïsées → erreur de compilation. Si aucune n’est trouvée → avertissement non bloquant dans l’éditeur et création d’une nouvelle action.

==== Exemple 4 — deux compléments hétérogènes ====

<file donjon wiki_regles_remplacer_montrer>
Le salon est un lieu.
Le joueur se trouve dans le salon.
La gemme est un objet ici.
L’elfe est un vivant ici.

règle remplacer montrer ceci à cela:
  définitions:
    ceci est un objet.
    cela est un vivant.
  phase épilogue:
    dire "[Intitulé cela] examine [le ceci] avec curiosité.".
fin règle
</file>

[[djnc>wiki_regles_remplacer_montrer|tester cet exemple]] — essayez ''montrer la gemme à l’elfe''.

===== Une seule règle remplacer par action =====

Deux blocs ''règle remplacer'' qui ciblent la **même** signature sont refusés par le compilateur — une seule règle de remplacement est autorisée par action. De même, deux blocs ''action <signature>:'' identiques sont refusés ; le compilateur invite alors à utiliser ''règle remplacer''.

===== Voir aussi =====

  * [[reference:routines:regle:start|Règles (avant / après / remplacer) — index]]
  * [[reference:routines:regle:avant|Règle avant]] — pour conditionner ou bloquer
  * [[reference:routines:regle:apres|Règle après]] — pour ajouter une réaction
  * [[reference:routines:action:start|Actions personnalisées]] — créer un nouveau verbe (à distinguer)
  * [[reference:routines:actions_predefinies:start|Actions de base]] — la liste des actions du moteur