Différences

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

--- reference:routines:simple [2022/07/30 17:37] – jonathan
+++ reference:routines:simple [2026/06/16 21:50] (Version actuelle) – modification externe 127.0.0.1
@@ Ligne 1: / Ligne 1: @@
 ====== Routine simple ======
-Une routine simple peut-être réutilisée à l’intérieur d’une autre routine (action, règle, réaction, …) afin de ne pas avoir à dupliquer certains blocs d’instructions que vous êtes amenés à utiliser à plusieurs endroits différents.
+Une **routine simple** est un bloc d’instructions qu’on peut **réutiliser** depuis n’importe quelle autre routine (action, règle, réaction, ou une autre routine simple). Elle évite la duplication de code.
-===== Exemple simple =====
+===== Définir et appeler une routine simple =====
+==== Définition ====
 <code donjon>
-routine afficherContenuSac
+routine remercier:
+  dire "« Merci et à bientôt ! »".
+fin routine
+</code>
+==== Appel ====
+Les deux formes ci-dessous sont équivalentes :
+<code donjon>
+exécuter routine remercier.
+exécuter la routine remercier.
+</code>
+==== Exemple minimal complet ====
+<file donjon wiki_routines_routine_simple_min>
+Le lieu de test est un lieu.
+routine remercier:
+  dire "« Merci ! »".
+fin routine
+action saluer:
+  exécuter la routine remercier.
+fin action
+règle avant commencer le jeu:
+  dire "Essayez : {/saluer/}".
+fin règle
+</file>
+[[djnc>wiki_routines_routine_simple_min|tester cet exemple]]
+===== Paramètres typés (''ceci'' / ''cela'') =====
+Une routine simple peut accepter jusqu’à deux paramètres typés ''ceci'' et ''cela'', déclarés dans un bloc ''définitions:'', et utilisés dans le bloc ''exécution:''. La forme courte (sans étiquette, comme plus haut) reste valide pour les routines sans paramètre.
+==== Types disponibles ====
+^ Type             ^ Sémantique                                                          ^ Ce qu’on peut passer à l’appel                                                                  ^
+| ''nombre''       | valeur entière, capturée à l’appel (lecture seule)                  | un littéral (''5''), la valeur d’un compteur, une propriété numérique                            |
+| ''texte''        | chaîne, capturée à l’appel (lecture seule)                          | une chaîne ''"…"'', l’intitulé d’un élément                                                       |
+| ''compteur''     | référence à un compteur (la routine peut le modifier)               | un compteur                                                                                       |
+| ''<classe>''     | référence à un élément du type ''<classe>'' (modifiable)            | un élément dont la classe hérite de ''<classe>'' (''objet'', ''lieu'', ''vivant'', ''dragon'', …) |
+| ''élément''      | catchall : n’importe quel élément du jeu (objet, lieu, personne, …) | un objet, un lieu, une personne… (le ''compteur'' n’en hérite pas — voir ligne « compteur »)     |
+L’article admis est ''un'' ou ''une'' (paramètre singulier). ''des'' est refusé.
+==== Définition et appel ====
+<file donjon wiki_routines_routine_param_min>
+Le salon est un lieu.
+La potion est un objet dans le salon.
+Le score est un compteur initialisé à 0.
+routine LancerObjet:
+  définitions:
+    ceci est un objet.
+    cela est un nombre.
+  exécution:
+    dire "Vous lancez [intitulé ceci] avec [c cela] points de force.".
+fin routine
+routine ajusterScore:
+  définitions:
+    ceci est un compteur.
+  exécution:
+    changer ceci augmente de 10.
+    dire "Bonus ! Score : [c ceci].".
+fin routine
+routine notifier:
+  définitions:
+    ceci est un texte.
+  exécution:
+    dire "Note : [ceci]".
+fin routine
+règle après commencer le jeu:
+  exécuter routine LancerObjet avec la potion et 5.
+  exécuter routine ajusterScore avec le score.
+  exécuter routine notifier avec "Bienvenue !".
+fin règle
+</file>
+[[djnc>wiki_routines_routine_param_min|tester cet exemple]]
+==== Sans bloc ''définitions:'' ====
+Sans bloc ''définitions:'', la routine n’attend aucun paramètre. ''exécuter routine X avec 5'' sur une telle routine remonte une erreur.
+==== Balises d’interpolation utiles ====
+Dans le corps d’une routine paramétrée :
+  * paramètre de **classe** (''objet'', ''lieu'', ''personne''…) : ''[intitulé ceci]'', ''[le ceci]'', ''[nom ceci]'', ''[description ceci]'', etc. ;
+  * paramètre ''nombre'' ou ''compteur'' : ''[c ceci]'' (valeur), ''[s ceci]'' (« s » si la valeur n’est pas 1) ;
+  * paramètre ''texte'' : ''[ceci]'' substitue la chaîne capturée.
+===== Surcharge de routines =====
+Plusieurs routines peuvent partager le même nom si leur signature diffère (arité ou types des paramètres). Le moteur choisit automatiquement la variante la **plus spécifique** à l’appel.
+<file donjon wiki_routines_routine_surcharge>
+Le salon est un lieu.
+La pomme est un objet dans le salon.
+Le chien est un vivant dans le salon.
+routine logger:
+  dire "ZERO.".
+fin routine
+routine logger:
+  définitions:
+    ceci est un objet.
+  exécution:
+    dire "OBJ : [intitulé ceci].".
+fin routine
+routine logger:
+  définitions:
+    ceci est un vivant.
+  exécution:
+    dire "VIV : [intitulé ceci].".
+fin routine
+règle après commencer le jeu:
+  exécuter routine logger.                   -- ZERO
+  exécuter routine logger avec la pomme.     -- OBJ
+  exécuter routine logger avec le chien.     -- VIV (vivant > objet)
+fin règle
+</file>
+[[djnc>wiki_routines_routine_surcharge|tester cet exemple]]
+**Règles de spécificité** :
+  * Un paramètre de type **classe** bat toujours un paramètre ''nombre'' / ''texte'' sur le même argument (« kind beats depth »). Conséquence : si on surcharge ''nombre'' et ''compteur'' pour le même nom, passer un compteur choisit la variante ''compteur''.
+  * Entre deux paramètres de classe, la classe la plus profonde gagne (''dragon'' > ''vivant'' > ''objet'' > ''élément'').
+  * Si plusieurs variantes ont la même spécificité maximale, le moteur renvoie une erreur (ambiguïté) ; il faut alors préciser un type plus spécifique.
+===== Appels différés avec arguments =====
+Les appels différés (''dans N <unité>'') acceptent eux aussi des arguments : ''exécuter la routine X avec <arguments> dans N secondes''. Les arguments sont résolus **au moment du déclenchement** (et non à la programmation), puis la surcharge est choisie comme pour un appel immédiat.
+→ Voir [[reference:temps:programmer_routine|Programmer une routine]] pour un exemple jouable.
+===== Cas typique : factoriser un affichage =====
+Une routine appelée depuis plusieurs actions affichant le même message :
+<file donjon wiki_routines_sac_inventaire>
+Le lieu de test est un lieu.
+Le sac est un contenant dans l'inventaire.
+La pomme est un objet vu ici.
+La clé est un objet vu ici.
+routine afficherContenuSac:
   dire "Votre sac [si le sac contient un objet]contient : [lister objets sac][sinon]est vide.[fin si]".
 fin routine
+action ouvrir le sac:
+  exécuter la routine afficherContenuSac.
+fin action
+action fouiller le sac:
+  exécuter la routine afficherContenuSac.
+fin action
+règle avant commencer le jeu:
+  dire "Essayez : {/prendre la pomme/} puis {/ouvrir le sac/} ou {/fouiller le sac/}.".
+fin règle
+</file>
+[[djnc>wiki_routines_sac_inventaire|tester cet exemple]]
+===== Programmer l’exécution d’une routine =====
+Une routine simple peut être déclenchée après un délai en temps réel :
+<code donjon>
+règle après commencer le jeu:
+  exécuter la routine alarme dans 30 secondes.
+fin règle
 </code>
+→ Voir [[reference:temps:programmer_routine|Programmer une routine]].
+===== Exemple plus consistant : magasin =====
+Une routine ''remercier'' appelée par deux actions distinctes ''acheter'' et ''vendre''.
+<file donjon wiki_routines_magasin_remercier>
+Le magasin est un lieu.
+L'objet à acheter est un objet vu dans le magasin.
+routine remercier:
+  dire "« Merci et à bientôt ! »".
+fin routine
+action acheter:
+  dire "Vous achetez l'objet.".
+  exécuter la routine remercier.
+fin action
+action vendre:
+  dire "Vous vendez l'objet.".
+  exécuter la routine remercier.
+fin action
+règle avant commencer le jeu:
+  dire "Essayez : {/acheter/} ou {/vendre/}.".
+fin règle
+</file>
+[[djnc>wiki_routines_magasin_remercier|tester cet exemple]]
+===== Voir aussi =====
+  * [[reference:routines:|Routines]] — vue d’ensemble des 4 types.
+  * [[reference:routines:action:|Actions]] — routines déclenchées par les commandes joueur (acceptent ''ceci'' / ''cela'').
+  * [[reference:routines:regle:|Règles]] — routines avant/après un événement.
+  * [[reference:temps:programmer_routine|Programmer une routine]] — déclencher une routine après un délai.
+{{tag>routine routines routine_simple exécuter executer appel paramètre parametre paramètres parametres ceci cela surcharge factoriser réutiliser reutiliser différé differe programmer}}