Différences

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

--- reference:routines:action:start [2022/10/11 17:57] – jonathan
+++ reference:routines:action:start [2026/06/16 21:50] (Version actuelle) – modification externe 127.0.0.1
@@ Ligne 1: / Ligne 1: @@
-====== Action (personnalisées) ======
+====== Action (personnalisée) ======
 Une action est une [[reference:routines:start|routine]] qui s’exécute lorsque le joueur entre une commande durant une partie.
-💡 Si vous souhaitez consulter les //actions de base//, voir [[reference:actions:start|cette page]].
+💡 Si vous souhaitez consulter les //actions de base//, voir [[reference:routines:actions_predefinies:start|cette page]].
 ===== Exemple d’action simple =====
@@ Ligne 12: / Ligne 12: @@
 <code donjon>
 action sauter:
-  dire "Vous sautez sur place.";
+  dire "Vous sautez sur place.".
 fin action
 </code>
@@ Ligne 38: / Ligne 38: @@
 ===== Les phases d’une action =====
-Ainsi que vous pouvez le voir dans l’exemple ci-dessus, une action se compose de 3 phases : refus, exécution et épilogue.
+Ainsi que vous pouvez le voir dans l’exemple ci-dessus, une action se compose de 3 phases : prérequis, exécution et épilogue. Elles s’exécutent dans cet ordre. **Si la phase prérequis refuse l’action, les phases suivantes (exécution et épilogue) ne sont pas exécutées.**
 ==== Phase prérequis ====
@@ Ligne 52: / Ligne 52: @@
 Cette phase permet d’informer le joueur du résultat de l’action qui s’est exécutée. Par exemple on décrit au joueur le lieu dans lequel il s’est déplacé.
-===== Définition des compléments =====
+===== Refuser une action =====
+Vous pouvez interrompre une action depuis la phase prérequis (ou depuis une [[reference:routines:regle:start|règle avant]]). Deux formes :
+==== refuser "message" ====
+Affiche le message au joueur et stoppe l’action :
+<code donjon>
+si ceci n’est pas accessible, refuser "Je n’y ai pas accès.".
+</code>
+==== refuser l’action ====
+Stoppe l’action **sans** afficher de message — utile quand vous avez déjà affiché un texte contextuel avec ''dire'' juste avant :
+<code donjon>
+règle avant prendre le vase Ming:
+  dire "Le gardien lève les yeux et vous regarde fixement.".
+  refuser l’action.
+fin règle
+</code>
+<WRAP info>Un refus stoppe l’action **complètement** : les phases ''exécution'' et ''épilogue'' ne sont pas exécutées.</WRAP>
+===== Définition des compléments variables d'une action =====
+Il est possible de spécifier 1 ou 2 compléments pour une action.
+Par convention, le premier sera toujours nommé « ''ceci'' » et le second « ''cela'' ».
+Si vous n'écrivez pas de définition pour les compléments, il leur sera attribué une définition par défaut « ''ceci est un objet visible et accessible.'' »
+==== Action sans complément ====
+<code donjon>
+action sauter:
+  dire "Vous sautez.".
+fin action
+</code>
+==== Action avec 1 complément (ceci) ====
+<code donjon>
+action sauter sur ceci:
+  définition:
+    ceci est un support.
+  phase épilogue:
+    dire "vous sautez sur [intitulé ceci].".
+fin action
+</code>
+==== Action avec 2 compléments (ceci et cela) ====
+<code donjon>
+action combiner ceci avec cela:
+  définitions:
+    ceci est un objet visible et accessible.
+    cela est un objet visible et accessible.
+  phase épilogue:
+    dire "Ça n'a rien donné.".
+fin action
+</code>
+==== Types de cibles ====
+À l’intérieur de ''définition'' (ou ''définitions'' au pluriel quand il y a deux compléments), vous précisez ce que le moteur doit chercher pour identifier ''ceci'' / ''cela'' :
+<code donjon>
+ceci est un objet.                       -- n'importe quel objet
+ceci est un objet visible.               -- objet présent et visible
+ceci est un objet vu et visible.         -- objet déjà vu au moins une fois
+ceci est un support.                     -- objet sur lequel on peut poser
+ceci est un contenant.                   -- objet dans lequel on peut mettre
+ceci est une personne.                   -- élément vivant
+ceci est un lieu.                        -- pour une action de déplacement
+ceci est une direction.                  -- nord, sud, en haut, …
+ceci est un intitulé.                    -- n'importe quel élément ou direction
+</code>
+Les épithètes se combinent ; l’ordre n’a pas d’importance :
+<code donjon>
+ceci est un objet vu, visible et accessible.
+cela est une personne visible.
+</code>
+==== Priorité (prioritairement) ====
+Si vous souhaitez donner la priorité à certains objets par rapport à d’autres vous pouvez utiliser le mot clé « ''prioritairement'' ».
+__Exemple concret__
+En cours de jeu, le joueur possède une pomme dans son inventaire tandis qu’une autre pomme se trouve encore sur la table.
+Voici 2 commandes que le joueur pourrait entrer:
+) ''prendre la pomme'': l’action //prendre// donne la priorité à la pomme qui est encore //disponible// sur la table (contrairement à celle qui est déjà //possédée// par le joueur).
+<code donjon>
+action prendre ceci:
+  définitions:
+    ceci est un objet visible et accessible prioritairement disponible.
+(...)
+fin action
+</code>
+) ''lâcher la pomme'': l’action //lâcher// donne la priorité à la pomme est est //possédée// par le joueur (contrairement à celle qui est encore //disponible// sur la table).
+<code donjon>
+action lâcher ceci:
+  définitions:
+    ceci est prioritairement possédé.
+(...)
+fin action
+</code>
+Plus d’informations : [[reference:definitions:etats_personnalises|États personnalisés]] et [[reference:definitions:visibilite|Visibilité et accessibilité]].
+===== Définition d'une action qui déplace le joueur =====
+En ajoutant la phrase ''L’action déplace le joueur vers ceci.'' vous aurez accès aux variables ''source'' et ''destination'' dans vos règles.
+<code donjon>
+action aller vers ceci:
+  définitions:
+    Ceci est un lieu.
+    L’action déplace le joueur vers ceci.
+  phase prérequis:
+    si le joueur se trouve dans ceci, refuser "Vous y êtes déjà.".
+  phase exécution:
+    déplacer le joueur vers ceci.
+  phase épilogue:
+    exécuter l’action regarder.
+fin action
+-- modifier l’action « aller »
+--   remarque: avec une action qui déplace le joueur (aller), on peut utiliser les
+--   variables « origine », « destination » et « orientation ».
+règle avant aller vers un lieu:
+  -- si le joueur tente d’aller là où il se trouve déjà
+  si le joueur se trouve dans destination:
+    dire "Vous y êtes déjà !".
+  -- sinon déplacer le joueur vers la destination.
+  sinon
+    dire "{/Vous disparaissez de [intitulé origine]… et vous apparaissez dans [intitulé destination] !/}".
+    changer le joueur se trouve dans destination.
+    -- décrire le nouveau lieu où se trouve le joueur
+    dire "{p}{_{*[titre ici]*}_}".
+    dire "{n}[description ici][décrire objets ici]".
+  fin si
+  arrêter l’action.
+fin règle
+</code>
+===== Aide contextuelle =====
+Vous pouvez fournir une aide affichée quand le joueur tape ''aide nomAction'' :
+<code donjon>
+L’aide pour l’action mélanger est "{*mélanger X avec Y*}{n}Verse une potion dans une autre. Les deux potions doivent être des potions distinctes.".
+</code>
+===== Remplacer une action existante =====
+→ **Page dédiée : [[reference:routines:regle:remplacer|Règle remplacer]]** (syntaxe, correspondance par signature, exemples testables).
+Pour **écraser** une action déjà définie (par exemple une [[reference:routines:actions_predefinies:start|action de base]] héritée du moteur), utilisez un bloc ''règle remplacer <signature>:''. Le bloc remplace **intégralement** l’action d’origine : description, phases, balises d’aide, etc. Les synonymes ne sont pas hérités — recopiez-les si vous voulez les conserver. Le bloc se ferme par ''fin règle''. Le mot ''action'' est facultatif après ''remplacer'' : ''règle remplacer sauter'' et ''règle remplacer action sauter'' sont équivalents.
+<code donjon>
+règle remplacer sauter:
+  phase épilogue:
+    dire "Vous bondissez comme un cabri.".
+fin règle
+</code>
+==== Correspondance par signature ====
+La signature doit correspondre exactement à l’action ciblée : verbe, prépositions et présence de ''ceci'' / ''cela''. Un bloc ''règle remplacer sauter'' ne touche pas ''action sauter sur ceci'' et vice-versa.
+<code donjon>
+règle remplacer sauter sur ceci:
+  phase épilogue:
+    dire "Hop, vous voilà perché sur [le ceci].".
+fin règle
+</code>
+==== Désambiguïsation par définitions ====
+Plusieurs actions du moteur partagent le même infinitif et la même arité. Le fichier ''actions.djn'' définit par exemple **quatre** ''action examiner ceci'' distinctes, une pour chaque type de cible : direction, lieu, objet, spécial.
+Pour cibler la bonne version, reproduisez le bloc ''définitions'' de la version visée — seul le **type** de la cible (''objet'', ''lieu'', ''direction''…) est utilisé pour identifier l’action ; les épithètes (''visible'', ''vu'', ''prioritairement…'') n’interviennent pas dans la sélection.
+<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>
+<WRAP info>
+Recopiez tout de même les épithètes et la priorité de l’action originale (ici ''prioritairement visible et mentionné''). 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>
+Si plusieurs actions correspondent à la signature fournie sans pouvoir être désambiguïsées, une erreur de compilation est émise. Si aucune action existante ne correspond, un avertissement non bloquant est affiché dans l’éditeur Donjon FI et la règle crée une nouvelle action.
+==== Doublons d’actions ====
+Deux blocs ''action <signature>:'' avec **exactement** la même signature (même infinitif, même arité ceci/cela, mêmes prépositions, même type de cible via ''définitions:'') sont refusés. Le compilateur émet une erreur et vous invite à utiliser ''règle remplacer'' si l’intention était de modifier le comportement existant. De même, deux blocs ''règle remplacer'' qui ciblent la même action sont refusés : une seule règle de remplacement est autorisée par action.
+===== Voir aussi =====
+  * [[reference:routines:action:exemples|Exemples d’actions personnalisées]] — mini-scénarios complets à tester
+  * [[reference:routines:regle:start|Règles avant / après]] — pour intercepter une action existante sans la réécrire
+  * [[reference:routines:actions_predefinies:start|Actions de base]] — la liste des actions déjà fournies par le moteur
+  * [[reference:divers:synonymes|Synonymes d’actions]] — pour rediriger ''regarder'' vers ''examiner'', etc.
+{{tag>action actions action_personnalisée action_personnalisee verbe commande routine routines phase phases prérequis prerequis exécution execution épilogue epilogue ceci cela complément complement définition definition refuser prioritairement remplacer aide}}