Tutoriel Twine 2 variables : comment les utiliser en jeu ?

Tutoriel Twine 2 variables : qu’est-ce qu’une variable ?

Une variable dans Twine 2 est un conteneur mémoire identifié par un nom qui stocke une information évolutive durant la partie. Elle permet au moteur de jeu de se souvenir d’une décision passée, d’un objet ramassé ou d’un point de vie perdu par le joueur.

Comprendre à quoi sert une variable dans un jeu à embranchements évite de créer un passage distinct pour chaque variante d’une même scène. Selon la documentation répertoriée sur l’IFWiki, l’utilisation de variables réduit la taille des graphes d’histoires de plus de 60 % dans les projets interactifs d’envergure.

Quels sont les différents types de variables (texte, nombre, booléen) ?

Twine 2 manipule principalement trois formes de données dans ses formats d’histoire comme Harlowe ou SugarCube. Le choix du bon type dépend directement de l’usage narratif ou ludique prévu dans le jeu.

• Les chaînes de texte (String) : encadrées par des guillemets, elles conservent des mots ou phrases comme le nom d’un personnage "Jacqueline" ou un titre "Capitaine".
• Les nombres (Number / Integer) : utilisés pour les valeurs quantitatives calculables, comme la santé 100, l’or 50 ou le nombre de clés possédées.
• Les booléens (Boolean) : ils ne prennent que deux valeurs possibles, true (vrai) ou false (faux), idéaux pour vérifier si un événement a déjà eu lieu.

Quelle est la différence entre variables globales ($) et temporaires (_) ?

Dans le moteur Harlowe de Twine 2, le préfixe attribué au nom de la variable détermine sa durée de vie au sein du jeu. Il existe deux niveaux de portée à ne pas confondre lors de la rédaction de vos scénarios.

• Variables globales ($) : leur nom débute par le symbole dollar, par exemple $or. Elles restent en mémoire de passage en passage tout au long de la session de jeu.
• Variables temporaires (_) : leur nom commence par un tiré bas (underscore), par exemple _calcul. Elles sont effacées dès que le joueur quitte le passage où elles ont été créées.

Pour la majorité des données d’inventaire, de choix narratifs et de statistiques de personnage, vous utiliserez des variables globales $.

Comment définir et afficher des variables ?

L’affectation de valeurs s’effectue au moyen de macros spécifiques intégrées au format d’histoire sélectionné dans Twine 2. Dans ce tutoriel twine premieres macros, nous nous concentrons sur le format par défaut de Twine 2, Harlowe 3.

Pour les auteurs consultant l’Interactive Fiction Database (IFDB), ces instructions correspondent aux briques logiques fondamentales que l’on retrouve dans la majorité des œuvres textuelles modernes.

Comment créer et modifier une variable avec la macro (set:) ?

La macro (set:) est l’outil de base pour initialiser ou modifier le contenu d’une variable globale ou locale. On écrit le nom de la variable, le mot-clé to, puis la valeur souhaitée.

• Initialiser du texte : (set: $nom to "Alexis") enregistre le prénom dans la variable.
• Initialiser un nombre : (set: $points_vie to 100) fixe la santé de départ.
• Incrémenter une valeur : (set: $or to $or + 15) ajoute 15 pièces au total existant. Vous pouvez aussi utiliser (set: $or to it + 15) où it désigne la variable elle-même.
• Basculer un booléen : (set: $porte_ouverte to true) valide le déverrouillage d’un accès.

Comment afficher la valeur d’une variable dans un passage ?

Pour insérer le contenu d’une variable directement dans le texte lu par le joueur, vous pouvez simplement écrire son nom précédé du symbole $ dans votre passage. Le moteur Harlowe remplace automatiquement la variable par sa valeur actuelle lors de l’affichage.

Par exemple, si vous écrivez : « Bonjour $nom, vous possédez $or pièces d’or », Twine affichera : « Bonjour Alexis, vous possédez 50 pièces d’or ». Si vous souhaitez forcer l’affichage ou effectuer un traitement intermédiaire, vous pouvez employer la macro (print: $nom).

Comment demander une saisie au joueur (nom, choix) ?

L’interaction dynamique passe souvent par des formulaires ou des fenêtres de saisie où le joueur tape lui-même une information. Harlowe propose des macros clés en main pour collecter ces entrées dans une variable.

• Fenêtre modale avec (prompt:) : (set: $nom to (prompt: "Entrez votre nom :", "Aventurier")) ouvre un champ contextuel avec une valeur par défaut.
• Champ texte intégré avec (input:) : (input: bind $nom, "Tapez votre nom") place une zone de texte directement dans la page.
• Liens modificateurs (setter links) : (link: "Choisir Jacqueline")[(set: $nom to "Jacqueline")(goto: "Suite")] affecte la variable et redirige le joueur en un seul clic.

Comment utiliser les macros conditionnelles ?

Les structures conditionnelles twine permettent d’afficher du texte ou de débloquer des choix uniquement si certaines conditions liées aux variables sont remplies. Elles se composent d’une macro de test et d’un crochet [...] contenant les éléments à afficher.

Mon expérience de création sur Twine montre que l’association des tests conditionnels aux variables réduit le sentiment de répétition chez le joueur tout en densifiant l’univers narratif.

Comment utiliser la macro (if:) pour tester une variable ?

La macro (if:) évalue une expression. Si le résultat est vrai, le contenu entre crochets situés juste après s’affiche à l’écran.

• Test d’égalité textuelle : (if: $nom is "Alexis")[Vous retrouvez votre vieux manteau.]
• Test de valeur numérique : (if: $or >= 50)[Le marchand vous salue chaleureusement.]
• Test d’un booléen : (if: $cle_trouvee)[La serrure cède dans un cliquetis.] (équivalent à $cle_trouvee is true).

Comment utiliser (else-if:) et (else:) pour gérer les alternatives ?

Lorsque le premier test (if:) est faux, vous pouvez enchaîner d’autres vérifications grâce à (else-if:) ou définir un cas par défaut avec (else:).

• Aiguillage à choix multiples : (if: $or >= 100)[Vous logez dans la suite royale.]
• Alternative intermédiaire : (else-if: $or >= 20)[Vous obtenez un lit en dortoir.]
• Cas de repli ultime : (else:)[Faute d'argent, vous dormez à la belle étoile.]

Comment combiner plusieurs conditions avec les opérateurs (and, or, not) ?

Il est fréquent de devoir tester plusieurs critères simultanément avant d’accorder un choix ou une récompense au joueur. Harlowe utilise des mots-clés anglais explicites pour lier les conditions.

• L’opérateur AND : (if: $cle_trouvee and $or >= 10)[Vous achetez le coffre et l'ouvrez aussitôt.] (les deux conditions doivent être vraies).
• L’opérateur OR : (if: $classe is "Voleur" or $force >= 15)[Vous enfoncez la porte sans bruit.] (au moins une condition doit être vraie).
• L’opérateur NOT : (if: not $garde_assomme)[Le garde vous repère immédiatement.] (inverse la valeur logique).

Quels sont les exemples pratiques d’utilisation dans votre jeu ?

La théorie prend tout son sens à travers des cas d’usage concrets applicables dès vos premières créations interactives. Voici trois structures couramment implémentées par les concepteurs de jeux textuels.

Cas 1 : comment gérer un inventaire (ramasser une clé et ouvrir une porte) ?

Pour gérer des objets, on combine un booléen initialisé en début de partie avec une mise à jour lors de la fouille d’une pièce.

• Passage ‘Initialisation’ : (set: $has_key to false) défini dans le tout premier passage du jeu.
• Passage ‘Fouille de la pièce’ : Vous trouvez une clé en cuivre sur la table. (link: "Prendre la clé")[(set: $has_key to true)Vous cochez la clé dans votre sac.]
• Passage ‘Devant la porte’ : (if: $has_key)[(link: "Ouvrir le donjon")[(goto: "Salle du Trésor")]] (else:)[La porte est verrouillée à double tour.]

Cas 2 : comment concevoir un système de points et de statistiques (vie, or, score) ?

Les variables numériques permettent d’implanter des éléments légers de jeu de rôle (RPG) sans alourdir l’interface du joueur.

• Combat ou piège : Un piège à fléchettes s'active ! (set: $pv to $pv - 20) Vous perdez 20 points de vie.
• Vérification de la survie : (if: $pv <= 0)[(goto: "Game Over")] placé au début du passage suivant.
• Affichage dans une barre latérale : utilisation du passage spécial Header ou Footer pour afficher PV: $pv | OR: $or sur chaque écran.

Cas 3 : comment suivre la progression et les choix du joueur ?

Pour adapter le dialogue d'un personnage non-joueur (PNJ) en fonction du passé du héros, stockez le niveau de réputation ou l'état des discussions.

• Enregistrement de la décision : (set: $trahison to true) si le joueur choisit de révéler un secret.
• Conséquence narrative ultérieure : (if: $trahison)["Arrière, félon !" crache le capitaine.] (else:)["Bienvenue, mon ami !" sourit le capitaine.]
• Suivi automatique des visites : Harlowe propose la macro native (visited: "Nom du passage") qui renvoie true si le joueur est déjà passé par ce lieu.

Quelles sont les erreurs fréquentes et les bonnes pratiques ?

Les bogues dans une fiction interactive proviennent généralement d'une faute de frappe dans le nom d'une variable ou d'une mauvaise affectation initiale. Un suivi rigoureux dès la phase de conception évite les blocages lors des tests.

Quelles sont les erreurs de syntaxe courantes en Harlowe et SugarCube ?

Les deux principaux moteurs de Twine 2 n'utilisent pas la même syntaxe pour traiter les données. Mélanger les règles de Harlowe et SugarCube est la cause numéro 1 des dysfonctionnements.

• Casse des caractères : $MaVariable et $mavariable sont traitées comme deux variables totalement différentes par le moteur.
• Oubli des guillemets : écrire (set: $nom to Alexis) au lieu de (set: $nom to "Alexis") provoque une erreur car Twine cherche une variable nommée Alexis.
• Confusion de syntaxe SugarCube : sous SugarCube, on utilise <<set $or to 10>> et non (set: $or to 10). Respectez scrupuleusement le story-format configuré dans votre projet.
• Absence d'initialisation : tester la valeur d'une variable (if: $or > 5) sans l'avoir définie au préalable génère une alerte d'erreur à l'écran.

Comment tester et déboguer ses variables avec le mode Debug ?

Twine 2 intègre un outil de test performant accessible directement depuis le panneau d'édition de votre histoire en cliquant sur le bouton « Tester » ou « Debug ».

• Inspecteur de variables : la fenêtre inférieure affiche en temps réel la liste de toutes les variables globales $ actives et leurs valeurs modifiées.
• Modification à la volée : vous pouvez changer manuellement la valeur d'un paramètre pendant le test pour vérifier un embranchement sans rejouer tout le jeu.
• Console d'erreurs : les erreurs de syntaxe ou les macros mal fermées apparaissent surlignées en rouge directement sur le passage concerné.