Tutoriel : créer une histoire avec Donjon.FI

Maintenant que nous nous sommes familiarisés avec l’éditeur de Donjon.FI dans l’article Prise en main de Donjon.FI, nous allons pouvoir nous intéresser à la création d’une fiction interactive en utilisant cet outil. Pour ce faire, direction l’éditeur où l’on retrouve le jeu de présentation fourni par l’éditeur.

Pour rappel, voici les parties de l’éditeur qui vont nous intéresser ici :

On voit sur la capture ci-dessus le bouton qui permet de revenir sur le code lorsqu’on testera le jeu (1), le bouton pour lancer la compilation du jeu (2) et les premières lignes de code qui permettent de définir des informations sur le jeu et son auteur (3).

Dans ce tutoriel, nous allons créer un jeu de toutes pièces et pour cela, on ne gardera que les lignes encadrées qu’on adaptera.

Heureusement, les deux premières lignes sont assez explicites pour savoir quoi placer. Pour le titre, on mettra « La maison hantée », et pour l’auteur, notre pseudo. L’identifiant est une chaîne de caractères générée automatiquement par Donjon de manière à être unique pour chaque jeu. 

Le code devrait ressembler à cela : 

-- "Informations sur le jeu".
Le titre du jeu est "La maison hantée".
L’auteur du jeu est "Onirie".
L’identifiant du jeu est "d0f1e150-42a7-45ca-8a04-cb280dd301b4".

Dans le code, les commentaires doivent avoir leur ligne qui commence par « –« . Si un texte se trouve avant, Donjon tentera d’interpréter le commentaire.

Les lieux

Pour créer un lieu, il faut le déclarer par une phrase du type nomDuLieu est un lieu. Chaque déclaration doit se terminer par un point, sinon Donjon essayera de lire la ligne suivante pour compléter l’instruction. 

Pour créer un lieu, on va donc écrire :

L'Entrée est un lieu.

Puisqu’il s’agit du premier lieu déclaré, Donjon y placera le joueur au début de la partie. Il est également possible de forcer la position du joueur avec la commande suivante :

Le joueur se trouve dans l'Entrée.

Pour ajouter une description à cette Entrée, il existe trois méthodes.
1. L’ajouter directement après la définition du couloir :

L'Entrée est un lieu.
"Vous êtes dans l'entrée de la maison abandonnée. ".

2. Avec une phrase se situant juste après la définition du couloir :

L'Entrée est un lieu.
Sa description est "Vous êtes dans l'entrée de la maison abandonnée. ".

3. Avec une phrase complète indiquant clairement qu’il s’agit de sa description :

L'Entrée est un lieu.
La description de l'Entrée est "Vous êtes dans l'entrée de la maison abandonnée. ".

L’instruction peut être complétée avec la position d’un lieu par rapport à un autre lieu, ce que nous allons voir en ajoutant d’autres pièces :

Le Couloir est un lieu au nord de l'Entrée.
Sa description est "Un couloir dans l'axe Est-Ouest.".

Le Salon est un lieu à l'est du Couloir.
Sa description est "Un grand salon au style vieillot.".

La Bibliothèque est un lieu à l'ouest du Couloir.
Sa description est "Une bibliothèque à l'ambiance pesante.".

Cette fois, nous avons directement ajouté la position des pièces les unes par rapport aux autres, mais on aurait pu également l’ajouter a posteriori avec la phrase suivante :

Le Couloir se trouve au nord de l'Entrée, à l'est de la Bibliothèque et à l'ouest du Salon.

Dans notre cas ce n’est pas utile, mais si on veut afficher un nom de lieu différent du nom utilisé pour sa déclaration, on peut le faire avec la phrase suivante :

Le titre de l'Entrée est "L'entrée de la maison hantée.".

Pour connecter les lieux, les choix possibles sont :

• nord, sud, est et ouest
• nord-est, sud-est, sud-ouest et nord-ouest
• à l’intérieur, à l’extérieur, en haut, en bas

Les objets

Créer un objet est tout aussi simple, et il est possible de placer l’objet dans un lieu. Le type d’objet le plus général est objet. Des types d’objets plus spécifiques existent, permettant d’apporter des comportements plus adaptés, comme animal, humain, support (pour les objets sur lesquels on peut poser d’autres objets, comme les tables et étagères), contenant (pour les objets qui peuvent contenir d’autres objets, comme les boîtes), etc.

Commençons par placer quelques objets dans l’entrée.

Le portemanteau est un support dans l'Entrée.
Sa description est "Un vieux portemanteau, le poids des années ne semble pas l'avoir affecté.".
Le placard est un contenant dans l'Entrée.
Sa description est "Un vieux placard qui a perdu ses portes.".
Le chapeau est un objet portable sur le portemanteau.
Sa description est "Un chapeau melon datant d'une autre époque.".

La table est un support dans le Salon.
Le buffet est un contenant fixé dans le Salon.

La porte est une porte fermée.
Elle se trouve à l'ouest du Couloir et à l'est de la Bibliothèque.

Par défaut, Donjon ajoute la liste des objets présents sur les supports comme on le constate ci-dessus. Il est possible de ne pas avoir cet affichage en utilisant la règle suivante :

Désactiver la description des objets supportés.

Cependant, en faisant cela, la joueuse ne pourra pas manipuler les objets présents sur les supports tant qu’elle n’aura pas examiné les supports en question, ce qui peut être perçu comme illogique.

La position de la porte a été précisée par rapport au couloir et à la bibliothèque afin que la joueuse puisse interagir avec l’objet « porte » depuis les deux emplacements.

Ajouter des états

Si on tente de prendre les objets présents dans l’entrée, on retrouvera le placard dans son inventaire, mais pas le portemanteau. Pour ce dernier, on vous répondra à la place qu’ « Il est fixé. »

Par défaut, les objets de type support sont fixés et ne peuvent pas être pris par le joueur. Ce n’est pas le cas pour les contenants, ce qui permet de se promener avec le placard sous le bras. Pour ajouter l’état fixé à un objet, on peut le faire directement lors de sa déclaration :

Le placard est un contenant fixé dans l'Entrée.

Ou bien a posteriori, via :

Le placard est fixé.

Donjon propose un ensemble d’états par défaut, mais il est possible d’ajouter ses propres états pour répondre aux besoins de son histoire.

Les états gérés par Donjon sont listés sur la page suivante : Wiki – états de base.
On y trouve également les relations entre les différents états. Par exemple, si on ajoute l’état ouvert à un objet qui avait l’état fermé, Donjon va automatiquement retirer ce dernier.

On peut attribuer directement plusieurs états lors de la déclaration d’un objet, comme :

Le présentoir est un contenant fixé, fermé, ouvrable et transparent dans la Bibliothèque.
Le grimoire est un objet dans le présentoir.

Ajouter des synonymes 

Il est utile – et très important – d’ajouter des synonymes aux objets afin que la joueuse ne soit pas limitée à l’utilisation du terme exact dans ses commandes :

Interpréter le porte manteau comme le portemanteau.
Interpréter le chapeau melon et le vieux chapeau comme le chapeau.

Dans la description des objets, il faut bien penser à repérer les synonymes qui sont utilisés afin de les déclarer.
Les synonymes ne peuvent être utilisés dans le code, ils ne sont prévus que pour être utilisés par les joueurs. Dans le code, pour désigner un objet, il faudra obligatoirement utiliser le nom de la déclaration.

Les actions et les règles 

Les actions permettent de créer de nouveaux verbes qui seront utilisés par les joueurs, tandis que les règles permettent de modifier le comportement des actions déjà existantes. 

Il est également possible de déclarer des routines simples, qui correspondent à un enchainement d’actions à réaliser. Les routines ne peuvent cependant pas être appelées par les joueurs.

Les actions

La structure pour déclarer une action est la suivante :

action verbe complément:
  définition:
  phase prérequis:
  phase exécution:
  phase épilogue:
fin action

Dans Donjon, le complément correspond aux objets auxquels s’applique le verbe. S’il n’y a pas d’objet, il n’y aura pas de complément. S’il y a un objet, le complément sera le mot-clé ceci, s’il y en a deux, le premier sera le mot-clé ceci et le second sera le mot-clé cela.

La définition ainsi que les différentes phases sont facultatives. Voici à quoi correspondent ces différentes parties :

• définition : si l’action porte sur un ou plusieurs objets, cette étape permet d’indiquer si l’objet doit être d’un type particulier, ou avoir des états spéciaux.
  • exemple : Ceci est un objet visible, accessible et possédé.
• phase prérequis : permet de terminer directement l’action selon des tests.
  • exemple : si ceci n’est pas mangeable, refuser "Ça ne se mange pas voyons !".
• phase exécution : permet de mettre les actions à exécuter si l’action passe les tests réalisés dans la phase prérequis.
  • exemple : changer ceci est ouvert. (pour l’action 'ouvrir ceci')
• phase épilogue : permet d’indiquer la réponse que l’action va donner au joueur.
  • exemple : dire "Vous ouvrez [intitulé ceci].". (pour l’action 'ouvrir ceci')

Dans l’exemple utilisé pour la phase épilogue, on remarque l’utilisation de [intitulé ceci] pour que Donjon insère le nom de l’objet dans la réponse donnée aux joueuses.

Les trois phases de l’action se déroulent toujours dans cet ordre précis.

Passons à un exemple concret : ajoutons une planche qui bloque la porte. Cela se fait en ajoutant l’état bloquée à la porte.

La porte est une porte fermée et bloquée.
La planche est un objet fixé et arrachable dans le Couloir.
Sa description est "Une planche qui bloque la porte".

On vient de créer une état arrachable qui sert à faire la différence entre les objets que le joueur peut ou ne peut pas arracher.

Créons maintenant une action permettant d’arracher un objet. La définition commencera par :

action arracher ceci:
  définition:
    ceci est un objet visible et accessible.
  phase prérequis:
    si ceci n'est pas fixé, refuser "Vous n'avez pas besoin de l'arracher, il suffit de le prendre.".
    si ceci n'est pas arrachable, refuser "Vous ne pouvez pas l'arracher.".

La partie définition correspond à ce que met Donjon par défaut. C’est donc facultatif, mais toujours bien de l’avoir sous la main si on veut être plus (ou moins) restrictif par la suite.

Du côté des prérequis, on indique qu’il faut que ce soit un élément fixé pour pouvoir l’arracher. Dans le texte de refus, on indique qu’il suffit de le prendre si ce n’est pas fixé.

La phase d’exécution contient ceci :

  phase exécution:
    changer ceci n'est plus fixé.
    déplacer ceci dans l'inventaire.
    si ceci est la planche:
      changer la porte n'est pas bloquée.
    finsi

On commence par retirer l’état fixée à la planche, puis on la déplace dans l’inventaire du joueur.

Et si c’est la planche qu’on retire, on enlève l’état bloquée de la porte.

Si on avait voulu garder l’action la plus générique possible, on aurait pu ne pas inclure cette partie concernant la planche et la porte. On aurait alors effectué ceci dans une surcharge de l’action a posteriori. (On en reparlera dans la partie sur les règles)

Enfin, pour effectuer un retour à l’utilisateur, on utilise la phase épilogue :

  phase épilogue:
    dire "Vous arrachez [intitulé ceci] et [le ceci] prenez avec vous.".
fin action

Dans la réponse faite, nous avons deux blocs entre crochets qui vont permettre d’adapter automatiquement le retour au joueur en fonction de l’objet sur lequel la commande porte. Le premier utilise le mot clé « intitulé » et indique à Donjon qu’il faut replacer ce bout de texte par l’intitulé de l’objet « ceci » – dans notre cas, ce sera « la planche ». Le second utilise le mot clé « le », indiquant qu’il faut que Donjon remplace le texte par l’article associé à l’objet « ceci » – toujours dans notre cas, « la ».

À noter que, si on souhaite placer l’intitulé de l’objet en début de phrase, il suffit de mettre le i en majuscule « [Intitulé ceci] » pour que Donjon mette en majuscule la première lettre du nom de l’objet.

Voilà, notre première action est complète et presque prête à être testée. Que manque-t-il ? Des synonymes, pour ne pas que votre jeu se transforme en un « Trouve le bon verbe ». Pour ce faire, rien de plus simple, il suffit d’ajouter une ligne :

Interpréter ôter et extirper comme arracher.

Maintenant, on peut réellement considérer que l’action est prête à être testée.

Les règles après

Les règles après permettent de surcharger la phase épilogue d’une action déjà définie. Si l’action concerne un ou deux objets, la règle peut s’appliquer uniquement sur un objet ou sur tous les objets.

Par défaut, une règle après remplace le contenu de la phase épilogue, bloquant donc l’exécution des commandes présentes dans la phase épilogue de l’action. Pour que le comportement par défaut se produise, il faut utiliser la commande continuer l'action.

Par exemple, pour l’action arracher ceci, si on avait voulu qu’elle reste générique lors de sa création, on aurait du s’occuper du cas particulier de l’arrachage de la planche en surchargeant la phase exécution ainsi :

règle après arracher la planche:
  Changer la porte n'est pas bloquée.
  Continuer l'action.
fin règle

Ou :

règle après arracher ceci:
  Si ceci est la planche :
    Changer la porte n'est pas bloquée.
    Continuer l'action.
  finsi
fin règle

Les règles avant

Les règles avant permettent de définir des règles qui vont s’exécuter avant l’exécution normale d’une action. Avec la commande arrêter l'action elles peuvent même bloquer l’exécution de toutes les phases de l’action.

Comme pour les règles après, elles peuvent s’appliquer sur un objet précis ou sur les mots-clés ceci et cela.

Utilisons ce type de règle pour empêcher l’ouverture de la porte tant que la planche la bloque.

règle avant ouvrir la porte:
  si la porte est bloquée:
    dire "La porte est bloquée par la planche. Pour pouvoir ouvrir la porte, il faudrait arracher la planche.".
    arrêter l'action.
  finsi
fin règle

C’est également ce type de règle qui permet d’afficher un texte introductif à l’histoire.

règle avant commencer le jeu:
  dire "Vous venez de rentrer dans la vieille maison hantée. Votre objectif : récupérer le grimoire magique qu'elle renferme.".
fin règle

Pour ne pas mettre la joueuse devant un énorme pavé de texte, ou bien pour ajouter un délai entre le texte introductif et la description de la première pièce, il est possible d’utiliser attendre x secondes ou attendre une touche.

Terminer le jeu

Pour que l’histoire se termine, il faut utiliser la commande terminer le jeu dans une action. On va surcharger l’action prendre le grimoire dans notre exemple :

Le grimoire est un objet dans le présentoir.
Interpréter le grimoire magique comme le grimoire.

règle après prendre le grimoire:
  dire "Vous prenez le grimoire. Bientôt la magie noire n'aura plus de secret pour vous."
  terminer le jeu.
fin règle

Les routines simples

Une routine est un regroupement de consignes qui ne peut pas être appelé par le joueur. Les routines sont destinées à être appelées au sein des actions et des règles définies via la consigne exécuter la routine NomRoutine.

Contrairement aux actions, les routines ne prennent pas de paramètre et ne sont donc pas aussi génériques qu’une action.

Dans l’exemple, on aurait pu vouloir offrir aux joueurs plusieurs moyens de retirer la planche qui bloque la porte (prendre la planche si la joueuse possède un pied-de-biche, utiliser pied-de-biche sur la planche, arracher planche avec pied-de-biche…). Dans ce cas, il aurait été possible d’utiliser la routine suivante :

routine debloquerPorte:
  changer la planche n'est plus fixé.
  déplacer la planche dans l'inventaire.
  changer la porte n'est pas bloquée.
fin routine

Et pour son utilisation dans l’action « prendre la planche si la joueuse possède un pied-de-biche » :

Le pied-de-biche est un objet dans le placard.

règle avant prendre la planche:
  si la planche est fixée:
    si le joueur possède le pied-de-biche:
      exécuter la routine debloquerPorte.
      dire "À l'aide du pied-de-biche, vous retirer la planche qui bloquait la porte.".
      arrêter l'action.
    finsi
  finsi
fin règle

On vérifie ici si la planche est fixée (car après avoir retiré la planche, il n’y aura plus besoin d’utiliser le pied-de-biche pour la prendre de nouveau) et que la joueuse possède bien le pied-de-biche.

Aperçu des objets et texte conditionnel

Si on teste le jeu en l’état, la description automatique du couloir par Donjon n’est pas satisfaisante. Modifions la description du couloir et l’aperçu de la porte pour un résultat plus pertinent.

Avant :

Modifications :

Le Couloir est un lieu au nord de l'Entrée.
Sa description est "Un couloir dans l'axe Est-Ouest. À l'ouest, une porte fermée est bloquée par une planche.[# planche]".
[…]
L'aperçu de la porte est "-".

Ici le mot-clé [# planche] permet d’indiquer à Donjon que la description parle déjà de la planche, et qu’il n’est donc pas nécessaire de la lister.

Comme la porte a un type spécial, il n’est pas possible d’effectuer la même manipulation pour retirer son aperçu. C’est pour cela qu’on déclare l’aperçu de la porte avec la valeur "-" qui est une valeur spéciale indiquant à Donjon de ne pas ajouter la porte et son état après la description de la pièce.

Après :

Nouveau problème : si on arrache la planche et qu’on affiche de nouveau la description de la pièce, on aura toujours la description de la porte bloquée par la planche. Pour résoudre ce problème, on va utiliser les balises de texte [si XXX][sinonsi][sinon][finsi].

Le Couloir est un lieu.
Sa description est "Un couloir dans l'axe Est-Ouest. À l'ouest, [si la porte est bloquée]une porte fermée est bloquée par une planche[# planche][sinonsi la porte est fermée] la porte est fermée[sinon]la porte est ouverte[finsi].".

Il faut bien mettre le [# planche] entre les balises [si] et [finsi] afin de ne pas masquer la planche si le joueur décide de la poser dans le couloir après l’avoir arrachée.

Modifions également la description de la planche :

Sa description est "[Si la porte est bloquée]Une planche en bois qui bloque l'ouverture de la porte.[sinon]La planche qui bloquait le passage précédemment.[finsi]".

Le code complet

Voici à quoi ressemble le code complet réalisé dans cet article. Comme nous n’avons pas ajouté d’autre méthode pour retirer la planche, la routine debloquerPorte est absente.

-- "Informations sur le jeu".
Le titre du jeu est "La maison hantée".
L’auteur du jeu est "Onirie".
L’identifiant du jeu est "d0f1e150-42a7-45ca-8a04-cb280dd301b4".

règle avant commencer le jeu:
  dire "Vous venez de rentrer dans la vieille maison hantée. Votre objectif : récupérer le grimoire magique qu'elle renferme.".
--  attendre une touche.
fin règle

L'Entrée est un lieu.
Le titre de l'Entrée est "L'entrée de la maison hantée.".
Sa description est "Vous êtes dans l'entrée de la maison abandonnée.". 

Le portemanteau est un support dans l'Entrée.
Sa description est "Un vieux portemanteau, le poids des années ne semble pas l'avoir affecté.".
Interpréter le porte manteau comme le portemanteau.

Le placard est un contenant fixé dans l'Entrée.
Sa description est "Un vieux placard qui a perdu ses portes.".

Le chapeau est un objet portable sur le portemanteau. 
Sa description est "Un chapeau melon datant d'une autre époque.".
Interpréter le chapeau melon comme le chapeau.


Le Couloir est un lieu.
Sa description est "Un couloir dans l'axe Est-Ouest. À l'ouest, [si la porte est bloquée]une porte fermée est bloquée par une planche[# planche][sinonsi la porte est fermée] la porte est fermée[sinon]la porte est ouverte[finsi].".

Le Couloir se trouve au nord de l'Entrée, à l'est de la Bibliothèque et à l'ouest du Salon.

La porte est une porte fermée et bloquée.
Elle se trouve à l'ouest du Couloir et à l'est de la Bibliothèque.
L'aperçu de la porte est "-".

La planche est un objet fixé et arrachable dans le Couloir.
Sa description est "[Si la porte est bloquée]Une planche en bois qui bloque l'ouverture de la porte.[sinon]La planche qui bloquait le passage précédemment.[finsi]".


Le Salon est un lieu à l'est du Couloir.
Sa description est "Un grand salon au style vieillot.".

La table est un support dans le Salon.
Le buffet est un contenant fixé dans le Salon.



La Bibliothèque est un lieu à l'ouest du Couloir.
Sa description est "Une bibliothèque à l'ambiance pesante.".

Le présentoir est un contenant fixé, fermé, ouvrable et transparent dans la Bibliothèque.

Le grimoire est un objet dans le présentoir.
Interpréter le grimoire magique comme le grimoire.


action arracher ceci:
  définition:
    ceci est un objet visible et accessible.
  phase prérequis: 
    si ceci n'est pas fixé, refuser "Vous n'avez pas besoin de l'arracher, il suffit de le prendre.".
	  si ceci n'est pas arrachable, refuser "Vous ne pouvez pas l'arracher.".
  phase exécution: 
    Changer ceci n'est plus fixé. 
    Déplacer ceci dans l'inventaire.
    Si ceci est la planche:
	  Changer la porte n'est pas bloquée.
    finsi
  phase épilogue: 
    Dire "Vous arrachez [intitulé ceci] et [le ceci] prenez avec vous.".
fin action
Interpréter ôter et extirper comme arracher.

règle avant ouvrir la porte:
  si la porte est bloquée:
    dire "La porte est bloquée par la planche. Pour pouvoir ouvrir la porte, il faudrait arracher la planche.".
    arrêter l'action.
  finsi
fin règle

règle après prendre le grimoire:
  dire "Vous prenez le grimoire. Bientôt la magie noire n'aura plus de secret pour vous.".
  terminer le jeu.
fin règle

Conclusion

Vous pouvez maintenant créer vos propres FI avec Donjon. N’hésitez pas à enrichir cet exemple pour mettre en pratique les concepts abordés dans l’article, par exemple en ajoutant le pied-de-biche évoqué précédemment.

Avant de fermer l’onglet de Donjon, n’oubliez pas de sauvegarder votre travail. Donjon ne sauvegarde rien de son coté. Vous pourrez ainsi donner votre jeu à une autre personne pour qu’elle y joue.