Ink et les variables : comment les utiliser dans vos récits ?

Comment comprendre les variables dans Ink ?

Dans Ink, une variable est une information nommée dont la valeur peut changer pendant la partie. Elle permet de faire réagir le récit à une décision, à une action ou à un événement extérieur, au lieu d’afficher toujours le même texte.

Le chapitre consacré aux variables dans l’ouvrage Creating Playable Stories with Ink and Inky, publié par Toronto Metropolitan University Pressbooks, présente cette logique avec des nombres, des textes et des booléens. En pratique, vous pouvez retenir une règle simple : la variable décrit l’état de l’histoire, et la condition décide comment cet état modifie la scène.

Cette approche rejoint la conception des choix et conséquences dans les jeux vidéo. Un choix intéressant ne change pas seulement une phrase immédiate, il peut aussi modifier une relation, ouvrir un lieu ou rendre une fin possible plusieurs scènes plus tard.

Quelles différences entre variables globales, temporaires et externes ?

Une variable globale est déclarée avec VAR et reste disponible dans les différents passages de l’histoire. Une variable temporaire, introduite avec temp, ne vit que dans le bloc ou la fonction où elle a été créée, ce qui évite de laisser des données de calcul contaminer toute la partie.

Une variable externe est contrôlée par le programme qui fait fonctionner Ink, par exemple Unity, Godot ou une intégration personnalisée. Le fichier Ink peut alors consulter une valeur fournie par le moteur, comme le niveau de difficulté ou le nom du joueur, sans devenir responsable de sa sauvegarde.

Comment déclarer, initialiser et modifier une variable ?

Vous déclarez une variable globale avec le mot-clé VAR, suivi de son nom, d’un signe égal et de sa valeur initiale. Cette valeur sert de point de départ lorsque l’histoire commence ou lorsqu’une nouvelle partie est créée.

Quelle syntaxe utiliser avec VAR, temp et les affectations ?

VAR courage = 2
VAR nom_joueur = "Mina"
VAR porte_ouverte = false

=== fouiller_la_piece ===
    ~ temp objets_trouves = 1
    Vous trouvez {objets_trouves} objet.
    ~ courage = courage + 1
    -> DONE

Les noms peuvent contenir des lettres, des chiffres et des caractères de soulignement, mais pas d’espace. Une affectation avec ~ modifie une variable pendant le déroulement, tandis que temp crée une donnée locale destinée à un calcul ou à un résultat intermédiaire.

Pour une fonction avancée d’Ink destinée à gérer des objets, vous pouvez isoler le calcul dans une fonction et lui transmettre une valeur. Cela rend le code plus lisible lorsque plusieurs scènes doivent appliquer la même règle, par exemple retirer une clé d’un inventaire ou calculer un prix.

Quels types de valeurs Ink prend-il en charge ?

Les nombres servent aux points de vie, aux compteurs et aux relations chiffrées. Les chaînes de caractères, écrites entre guillemets, servent aux noms ou aux textes courts, mais elles ne se comportent pas comme des nombres : ajouter "10" et "1" produit une concaténation, soit "101", et non 11.

Les booléens ne possèdent que deux états : true et false. Ils conviennent à une porte ouverte, une quête terminée ou une promesse tenue, alors qu’un nombre convient mieux à une relation qui évolue progressivement.

Comment utiliser les variables dans les conditions et les choix ?

Une condition lit la valeur d’une variable et choisit le texte ou le passage à afficher. Dans Ink, les accolades permettent d’insérer une expression dans le texte, tandis que les blocs conditionnels rendent une option disponible seulement lorsque l’état de l’histoire le permet.

Comment écrire des conditions simples et imbriquées ?

VAR cle_trouvee = false
VAR confiance = 0

=== porte ===
{ cle_trouvee:
    La serrure cède sous votre clé.
- else:
    La porte reste fermée.
}

{ confiance >= 2:
    Vous demandez de l’aide à Noa.
    { cle_trouvee:
        Noa vous suit jusqu’à la porte.
    }
- else:
    Noa refuse de vous accompagner.
}

Les opérateurs >, <, >=, <= et == permettent de comparer des valeurs. Vous pouvez combiner les tests avec and et or, mais des conditions courtes restent plus faciles à tester et à relire.

Évitez de faire dépendre une scène de nombreux tests imbriqués. Une variable comme quete_terminee peut résumer plusieurs événements et rendre le passage plus clair qu’une longue expression qui vérifie chaque étape séparément.

Comment afficher la valeur d’une variable dans le texte ?

Placez le nom de la variable entre accolades pour afficher sa valeur, comme dans Vous avez {pieces} pièces.. Ink évalue alors l’expression au moment où le texte est produit, ce qui permet d’afficher un compteur actualisé après chaque choix.

Vous pouvez aussi utiliser une condition directement dans les accolades pour adapter une formulation. Testez cependant les accords et les variantes à l’écran, car une phrase grammaticalement correcte pour une valeur peut devenir maladroite pour une autre.

Comment gérer l’aléatoire avec Ink ?

Ink propose des séquences et des listes pour choisir entre plusieurs résultats. L’aléatoire par les listes Ink convient aux descriptions variables, aux rencontres et aux récompenses, mais il doit rester contrôlé si le joueur a besoin d’un résultat prévisible pour comprendre une énigme.

Comment créer des tirages aléatoires et des choix pondérés ?

Une séquence aléatoire peut sélectionner une ligne parmi plusieurs possibilités. Les alternatives répétées donnent à chaque résultat une chance comparable, tandis que la répétition d’une entrée dans une structure adaptée permet de lui donner davantage de poids.

{~
    Un corbeau traverse le ciel.
-   Une pluie fine commence.
-   Une cloche sonne au loin.
}

Les séquences diverties, cyclées ou mélangées ne produisent pas le même comportement. Une séquence cyclée avance dans un ordre fixe, alors qu’une séquence mélangée évite généralement de reprendre immédiatement la même entrée, ce qui convient mieux à une série de descriptions.

Comment éviter les résultats répétitifs ?

Pour empêcher deux résultats identiques, stockez les éléments déjà utilisés dans une liste ou utilisez une séquence conçue pour parcourir ses entrées avant de recommencer. Pour un système complexe, retirez l’élément tiré d’une collection, puis réinitialisez cette collection lorsqu’elle est vide.

Ne confondez pas hasard et variété narrative. Un tirage fréquent peut rendre une scène confuse si le joueur ne comprend pas pourquoi le résultat change, alors qu’un événement rare, annoncé par une variable de progression, semblera davantage lié à ses actions.

Comment créer et manipuler des listes Ink ?

Une liste Ink regroupe des valeurs nommées dans une variable structurée. Elle est utile pour un inventaire, des états de relation, des étapes de quête ou un ensemble d’événements encore disponibles.

Comment déclarer une liste nommée ?

LISTE armes = couteau, arc, marteau
VAR arme_actuelle = couteau

La déclaration d’une liste nommée permet de manipuler des éléments qui ont un sens narratif plutôt que de simples nombres. Vérifiez la syntaxe prise en charge par votre version d’Inky et par le compilateur Ink utilisé par votre intégration, car les détails de certaines opérations peuvent varier entre les outils.

Comment tester, ajouter et retirer des éléments ?

Vous pouvez tester la présence d’un élément avant d’afficher une option, puis modifier la collection après une action. Une logique d’inventaire suit généralement ce modèle : vérifier l’absence de l’objet, l’ajouter après l’obtention, puis le retirer lorsqu’il est consommé.

VAR a_boussole = false

=== trouver_boussole ===
    ~ a_boussole = true
    Vous rangez la boussole dans votre sac.
    -> DONE

=== franchir_brouillard ===
{ a_boussole:
    La boussole vous indique le nord.
- else:
    Vous avancez au hasard dans le brouillard.
}

Comment utiliser les listes pour suivre une progression ?

Une liste de progression peut représenter les étapes franchies sans multiplier les variables booléennes. Pour une quête courte, trois états nommés comme indice_trouve, porte_ouverte et gardien_convaincu rendent la lecture plus directe qu’un compteur dont la signification changerait selon la scène.

Quand plusieurs valeurs doivent être conservées simultanément, une collection est plus adaptée. Pour une explication plus générale de la mémoire narrative, consultez aussi notre article sur le fonctionnement des variables dans Twine, qui permet de comparer une autre approche de la fiction interactive.

Comment modéliser des objets et des collections ?

Ink ne fournit pas un système d’objets comparable aux classes d’un langage généraliste. Vous pouvez néanmoins modéliser un objet narratif avec plusieurs variables, une liste ou une combinaison des deux.

Quelles sont les limites des objets natifs dans Ink ?

Une épée n’est pas naturellement une structure contenant un nom, une puissance, un état et une description. Si vous créez une variable pour chaque propriété, votre code devient vite difficile à maintenir lorsque l’inventaire contient de nombreux objets.

Pour quelques éléments importants, plusieurs variables explicites restent lisibles : epee_obtenue, epee_usee et epee_nom. Pour une collection plus large, le moteur du jeu peut gérer les données détaillées, tandis qu’Ink conserve seulement les informations nécessaires au récit.

Comment représenter un objet avec plusieurs variables ou une liste ?

Utilisez un groupe de variables lorsqu’un objet possède un état narratif propre. Une liste convient mieux à une série d’objets interchangeables, comme des clés, des indices ou des ingrédients.

Cette séparation évite de transformer Ink en base de données. Le texte doit décider ce que l’objet signifie dans la scène, tandis que le moteur peut gérer son icône, son poids ou son identifiant technique.

Comment échanger des variables entre Ink et le moteur du jeu ?

Une intégration charge une histoire compilée, puis expose ses variables globales au programme. Le moteur peut fournir le nom du joueur ou le niveau courant, tandis qu’Ink renvoie une conséquence narrative, comme une relation modifiée ou une mission achevée.

Comment injecter des valeurs externes dans Ink ?

Déclarez une variable externe dans Ink lorsque sa valeur doit venir du programme. Cette méthode évite de dupliquer dans le script une information déjà connue par Unity ou une autre intégration.

EXTERNAL obtenir_nom_joueur()

=== debut ===
    Bonjour, {obtenir_nom_joueur()}.

Protégez les valeurs attendues avant de lancer la scène. Un nom absent, une valeur vide ou un nombre fourni sous forme de texte peut produire une phrase incorrecte ou une erreur difficile à repérer.

Comment lire et modifier les variables depuis Unity ou une autre intégration ?

Le runtime Ink expose un état de variables globales que le moteur peut consulter et modifier. Le fichier VariablesState.cs du dépôt officiel Ink sur GitHub montre que l’état prend en charge la lecture, l’affectation, la sérialisation et la notification des changements de variables.

Dans Unity, gardez une convention claire entre les noms Ink et les noms C#. Modifiez une variable au bon moment, puis laissez Ink poursuivre son histoire afin d’éviter qu’un affichage du moteur et un texte narratif ne présentent deux états différents.

Comment sauvegarder, réinitialiser et déboguer l’état des variables ?

Une sauvegarde doit conserver l’état de l’histoire, pas seulement le passage affiché. Les choix déjà effectués, les valeurs globales et la position dans le flux doivent être restaurés ensemble pour éviter qu’un joueur ne retrouve une scène incompatible avec son inventaire.

Comment gérer la persistance et la restauration d’une partie ?

Utilisez la sérialisation proposée par le runtime Ink pour enregistrer l’état, puis restaurez-le avec la même version de l’histoire lorsque c’est possible. Le fichier de variables du runtime officiel indique que les valeurs globales peuvent être converties en données JSON et rechargées depuis cet état.

Réinitialisez explicitement les variables lorsque le joueur démarre une nouvelle partie. Une ancienne sauvegarde ou une variable conservée par erreur peut donner l’impression qu’un choix n’a pas été pris, alors que le problème vient simplement d’un état persistant.

Comment vérifier les valeurs dans Inky et le runtime ?

Testez chaque branche avec plusieurs parties courtes : une partie où le joueur obtient l’objet, une autre où il le refuse et une troisième où il revient après avoir modifié une relation. Inky permet de suivre le texte produit, mais l’intégration doit aussi être testée dans le moteur réel.

Ajoutez temporairement une ligne de diagnostic qui affiche une variable, ou utilisez les événements de changement du runtime lorsqu’ils sont disponibles. Retirez ces traces avant la diffusion, puis conservez des noms explicites afin de retrouver rapidement la source d’une valeur inattendue.

Comment construire une histoire avec inventaire, hasard et progression ?

Un exemple complet peut combiner un booléen d’inventaire, un compteur de confiance et une séquence variable. Le joueur trouve une lampe, gagne la confiance d’un personnage et traverse une scène dont la description change sans modifier la logique principale.

VAR lampe = false
VAR confiance = 0
VAR porte_franchie = false

=== debut ===
    Une porte bloque le couloir.
    + [Chercher une lampe]
        ~ lampe = true
        Vous trouvez une lampe sous une chaise.
        -> debut
    + [Parler à Sacha]
        ~ confiance = confiance + 1
        Sacha vous observe plus longtemps avant de répondre.
        -> debut
    + {lampe} [Éclairer la serrure]
        ~ porte_franchie = true
        La lumière révèle un mécanisme caché.
        -> couloir

=== couloir ===
    { confiance >= 2:
        Sacha vous indique le chemin le moins dangereux.
    - else:
        Vous avancez seul.
    }
    {~
        Une conduite gronde derrière le mur.
    -
        Une odeur de pluie entre par une fenêtre brisée.
    }
    -> DONE

Ce script sépare clairement les rôles : lampe contrôle une option, confiance mesure une progression et la séquence aléatoire renouvelle l’ambiance. Pour produire une histoire plus riche, ajoutez ensuite une liste d’objets ou une fonction de calcul, mais gardez chaque variable liée à un effet narratif identifiable.

Si votre projet devient multilingue, pensez à séparer les données de progression du texte affiché. Les principes présentés dans notre article sur la gestion de plusieurs langues dans un jeu Twine s’appliquent aussi à cette discipline générale : une variable doit décrire l’état du jeu, jamais une phrase traduite.