====== Routine simple ======

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.

===== Définir et appeler une routine simple =====

==== Définition ====

<code donjon>
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}}