← Documentation

Référence de l'API JavaScript

L'API publique complète du runtime Loreline.

Vous débutez avec Loreline en JavaScript ? Commencez par le guide d'intégration. Cette page est la référence exhaustive.

Vue d'ensemble

TypeMembres
Loreline parse play resume extractTranslations loadLocale translationFormat lastError print
Interpreter constructor start save restore resume getCharacter getCharacterField setCharacterField getStateField setStateField getTopLevelStateField setTopLevelStateField currentNode currentNodeFilePath
Script body filePath fromJson
Node id pos type toJson fromJson each
InterpreterOptions functions strictAccess customCreateFields translations
ChoiceOption text tags enabled
TextTag closing value offset
DialogueHandler
ChoiceHandler
FinishHandler
ImportsFileHandler
ImportsErrorHandler
FunctionsMap
Translations
SaveData
Tokens
Error message pos stack toString
Position line column offset length toString
NodeId toString toInt64
Int64 high low
Fields lorelineCreate lorelineGet lorelineSet lorelineExists lorelineFields

Loreline

classe

L'API publique principale du runtime Loreline. Donne accès simplement aux fonctionnalités de base pour analyser et exécuter des scripts Loreline.

parse

méthode 

parse(input, filePath, handleFile, callback)

Analyse le texte fourni et en crée une instance Script exécutable.

ParamètreTypeDescription
input string Le contenu du script Loreline sous forme de chaîne (format .lor)
filePath string Chemin optionnel du fichier analysé. S'il est fourni, handleFile est requis également. optionnel
handleFile ImportsFileHandler Handler de fichiers optionnel pour lire les imports. Si ce handler est asynchrone, parse() renverra null et l'argument callback devra être utilisé optionnel
callback (script: Script) => void S'il est fourni, sera appelé avec le script résultant en argument. Utile surtout quand les imports de fichiers sont lus de façon asynchrone optionnel

Retourne Script | null Le script analysé, sous forme d'instance AST Script (s'il a été chargé de façon synchrone)

Lève Si le script contient des erreurs de syntaxe ou d'autres problèmes d'analyse

C'est la première étape du travail avec un script Loreline. L'objet Script renvoyé peut ensuite être passé aux méthodes play() ou resume().

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

play

méthode 

play(script, handleDialogue, handleChoice, handleFinish, beatName, options)

Démarre la lecture d'un script Loreline depuis le début ou depuis un beat précis.

ParamètreTypeDescription
script Script Le script analysé (résultat de parse())
handleDialogue DialogueHandler Fonction appelée quand un texte de dialogue doit être affiché
handleChoice ChoiceHandler Fonction appelée quand le joueur doit faire un choix
handleFinish FinishHandler Fonction appelée quand l'exécution du script se termine
beatName string Nom optionnel d'un beat précis par lequel démarrer (par défaut, le premier beat) optionnel
options InterpreterOptions Options supplémentaires optionnel

Retourne Interpreter L'instance d'interpréteur qui exécute le script

Cette fonction se charge d'initialiser l'interpréteur et de démarrer l'exécution immédiatement. Vous devrez fournir des handlers pour les dialogues, les choix et la fin du script.

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

resume

méthode 

resume(script, handleDialogue, handleChoice, handleFinish, saveData, beatName, options)

Reprend un script Loreline précédemment sauvegardé depuis son état enregistré.

ParamètreTypeDescription
script Script Le script analysé (résultat de parse())
handleDialogue DialogueHandler Fonction appelée quand un texte de dialogue doit être affiché
handleChoice ChoiceHandler Fonction appelée quand le joueur doit faire un choix
handleFinish FinishHandler Fonction appelée quand l'exécution du script se termine
saveData SaveData Les données de sauvegarde (typiquement issues de interpreter.save())
beatName string Nom de beat optionnel pour choisir où reprendre optionnel
options InterpreterOptions Options optionnelles pour configurer le comportement de l'interpréteur optionnel

Retourne Interpreter L'instance d'interpréteur qui exécute le script

Cela permet de continuer une histoire exactement là où elle a été sauvegardée, en restaurant toutes les variables d'état, les choix et la progression du joueur.

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

extractTranslations

méthode 

extractTranslations(script)

Extrait les traductions d'un script de traduction analysé.

ParamètreTypeDescription
script Script Le script de traduction analysé (résultat de parse() sur un fichier .XX.lor)

Retourne Translations Une table de traductions à passer comme InterpreterOptions.translations

À partir d'un fichier de traduction analysé avec parse(), renvoie une table de traductions qui peut être passée comme options.translations à play() ou resume().

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

loadLocale

méthode 

loadLocale(locale, script, filePath, handleFile, callback)

Charge les traductions d'une langue donnée, en parcourant tout l'arbre d'imports du script.

ParamètreTypeDescription
locale string Le code de langue (par exemple "fr")
script Script Le script source analysé (il doit avoir été analysé avec un chemin de fichier, ou filePath doit être fourni)
filePath string | null Emplacement de remplacement optionnel où chercher les fichiers de traduction (par défaut script.filePath). Peut être un chemin de fichier .lor/.lor.txt ou un dossier. optionnel
handleFile ImportsFileHandler Handler de fichiers utilisé pour lire les fichiers de traduction optionnel
callback (translations: Translations) => void Appelé avec la table de traductions fusionnée. Requis si handleFile est asynchrone. optionnel

Retourne Translations | null La table de traductions fusionnée (de façon synchrone quand handleFile est synchrone)

Pour chaque fichier concerné par le script (racine + imports transitifs), le fichier de traduction correspondant est recherché en insérant .<locale> avant l'extension (par exemple characters.lor -> characters.fr.lor). Les fichiers de traduction absents sont ignorés silencieusement. La table renvoyée peut être passée comme InterpreterOptions.translations à play() ou resume().

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

translationFormat

méthode 

translationFormat(name, enabled)

Active ou désactive la prise en charge d'un format de fichier de traduction alternatif.

ParamètreTypeDescription
name string L'identifiant de format (voir ci-dessus)
enabled boolean True pour activer le format, false pour le désactiver

Retourne void

Par défaut, loadLocale n'essaie que les fichiers .<locale>.lor. Appelez cette méthode pour activer d'autres formats :

  • "po" : GNU gettext PO (.po)
  • "xliff" : XLIFF 1.2 / 2.x (.xliff, .xlf)
  • "csv" : CSV / TSV (.csv, .tsv)

Les noms inconnus sont acceptés silencieusement (compatibilité avec de futurs formats).

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

lastError

méthode 

lastError()

Renvoie l'erreur du dernier appel échoué à parse() ou loadLocale(), ou null en cas de succès.

Retourne Error | null

En mode asynchrone (avec callback), le callback se déclenche avec null en cas d'échec et cette méthode indique ce qui n'a pas fonctionné. En mode synchrone, l'appel lève une exception, et cette valeur porte la même erreur pour pouvoir être consultée après le catch.

Pas thread-safe : à lire immédiatement après le retour de l'appel.

JavaScript TypeScript C# C++ Java PHP Python Lua Haxe

print

méthode 

print(script, indent, newline)

Régénère le code source Loreline à partir d'un script analysé.

ParamètreTypeDescription
script Script Le script analysé (résultat de parse())
indent string La chaîne d'indentation à utiliser (par défaut, deux espaces) optionnel
newline string La chaîne de saut de ligne à utiliser (par défaut "\n") optionnel

Retourne string Le code source produit, sous forme de chaîne

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

Interpreter

classe

Exécute un script analysé : détient l'état de l'histoire, décide de la suite, et rend la main à votre code à chaque ligne de dialogue et à chaque choix.

constructor

constructeur 

constructor(script, handleDialogue, handleChoice, handleFinish, options)

Crée un nouvel interpréteur de script Loreline.

ParamètreTypeDescription
script Script Le script analysé à exécuter
handleDialogue DialogueHandler Fonction à appeler pour afficher un texte de dialogue
handleChoice ChoiceHandler Fonction à appeler pour présenter des choix
handleFinish FinishHandler Fonction à appeler quand l'exécution se termine
options InterpreterOptions Options supplémentaires optionnel

JavaScript TypeScript C# Java Python Haxe

start

méthode 

start(beatName)

Démarre l'exécution du script depuis le début ou depuis un beat précis.

ParamètreTypeDescription
beatName string Nom optionnel du beat par lequel démarrer. Si null, l'exécution démarre au premier beat, ou au beat nommé "_" s'il existe. optionnel

Retourne void

Lève RuntimeError Si le beat indiqué n'existe pas, ou si aucun beat n'est trouvé dans le script

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

save

méthode 

save()

Sauvegarde l'état courant de l'interpréteur. Cela comprend toutes les variables d'état, l'état des personnages et la pile d'exécution, ce qui permet de reprendre l'exécution plus tard exactement au même point.

Retourne SaveData Un objet SaveData contenant l'état sérialisé

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

restore

méthode 

restore(saveData)

Restaure l'état de l'interpréteur depuis un objet SaveData. Cela permet de reprendre l'exécution depuis un état précédemment sauvegardé.

ParamètreTypeDescription
saveData SaveData L'objet SaveData contenant l'état sérialisé

Retourne void

Lève RuntimeError Si la version des données de sauvegarde est incompatible

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

resume

méthode 

resume()

Reprend l'exécution après la restauration de l'état. À appeler après restore() pour poursuivre l'exécution.

Retourne void

JavaScript TypeScript C# Java PHP Python Lua Haxe

getCharacter

méthode 

getCharacter(name)

Récupère un personnage par son nom.

ParamètreTypeDescription
name string Le nom du personnage à récupérer

Retourne any Les champs du personnage, ou null si le personnage n'existe pas

JavaScript TypeScript C# Java PHP Python Lua Haxe

getCharacterField

méthode 

getCharacterField(character, name)

Récupère un champ précis d'un personnage.

ParamètreTypeDescription
character string Le nom du personnage
name string Le nom du champ à lire

Retourne any La valeur du champ, ou null si le personnage ou le champ n'existe pas

Les valeurs conteneur (objets clé-valeur et tableaux) sont de simples objets et tableaux JS : les accesseurs de champs et les fonctions personnalisées échangent des valeurs JS idiomatiques dans les deux sens.

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

setCharacterField

méthode 

setCharacterField(character, name, value)

Écrit un champ précis d'un personnage.

ParamètreTypeDescription
character string Le nom du personnage
name string Le nom du champ à écrire
value any La valeur à écrire

Retourne void

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

getStateField

méthode 

getStateField(name)

Lit un champ d'état par son nom, en résolvant depuis la portée courante vers l'extérieur.

ParamètreTypeDescription
name string Le nom du champ à lire

Retourne any La valeur du champ, ou null si elle est introuvable

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

setStateField

méthode 

setStateField(name, value)

Écrit un champ d'état par son nom, en résolvant depuis la portée courante vers l'extérieur.

ParamètreTypeDescription
name string Le nom du champ à écrire
value any La valeur à écrire

Retourne void

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

getTopLevelStateField

méthode 

getTopLevelStateField(name)

Lit directement un champ de l'état de premier niveau.

ParamètreTypeDescription
name string Le nom du champ à lire

Retourne any La valeur du champ, ou null si elle est introuvable

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

setTopLevelStateField

méthode 

setTopLevelStateField(name, value)

Écrit directement un champ sur l'état de premier niveau.

ParamètreTypeDescription
name string Le nom du champ à écrire
value any La valeur à écrire

Retourne void

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

currentNode

méthode 

currentNode()

Renvoie le nœud en cours d'exécution. Pendant un callback de dialogue, renvoie le nœud de l'instruction de dialogue. Pendant un callback de choix, renvoie le nœud de l'instruction de choix.

Retourne Node | null Le nœud courant, ou null si aucun nœud n'est en cours d'exécution

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

currentNodeFilePath

méthode 

currentNodeFilePath(rootPath)

Renvoie le chemin du fichier contenant le nœud courant. Résout les chaînes d'imports relativement au chemin racine fourni.

ParamètreTypeDescription
rootPath string Le chemin du fichier du script racine

Retourne string Le chemin du fichier contenant le nœud courant, ou rootPath si l'on se trouve dans le fichier racine

JavaScript TypeScript Haxe

Script

classe

Représente le nœud racine de l'AST d'un script Loreline.

body

propriété 

body

Tableau des déclarations de premier niveau du script.

Retourne Array<Node>

JavaScript TypeScript Haxe

filePath

propriété 

filePath

Le chemin du fichier depuis lequel ce script a été analysé. Peut être null si le script a été analysé sans chemin de fichier.

Retourne string | null

JavaScript TypeScript Haxe

fromJson

méthode 

fromJson(json)

Reconstruit un Script depuis sa représentation JSON.

ParamètreTypeDescription
json any L'objet JSON (tel que renvoyé par script.toJson())

Retourne Script Le Script reconstruit

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

Node

classe

Classe de base de tous les nœuds de l'AST. Contient les informations de position et la conversion JSON de base.

id

propriété 

id

Un identifiant unique pour ce nœud au sein de l'AST, qui permet de le distinguer des autres nœuds du script.

Retourne NodeId

JavaScript TypeScript C# Java Haxe

pos

propriété 

pos

Position dans le code source où ce nœud apparaît.

Retourne Position

JavaScript TypeScript Haxe

type

méthode 

type()

Renvoie le type de ce nœud.

Retourne string Représentation textuelle du type de nœud

JavaScript TypeScript C# C++ Java PHP Python Lua Haxe

toJson

méthode 

toJson()

Convertit le nœud en représentation JSON.

Retourne any Objet contenant le type et la position du nœud

JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe

fromJson

méthode 

fromJson(json)

Reconstruit un Node depuis sa représentation JSON.

ParamètreTypeDescription
json any L'objet JSON (tel que renvoyé par node.toJson())

Retourne Node Le Node reconstruit

JavaScript TypeScript C# Java PHP Python Lua Haxe

each

méthode 

each(handleNode)

Parcourt tous les nœuds enfants de ce nœud.

ParamètreTypeDescription
handleNode (node: Node, parent: Node) => void Fonction à appeler pour chaque nœud enfant

Retourne void

JavaScript TypeScript Haxe

InterpreterOptions

interface

Options de configuration du comportement de l'interpréteur Loreline

functions

propriété 

functions

Table optionnelle de fonctions supplémentaires à rendre disponibles au script

Retourne FunctionsMap

JavaScript TypeScript C# GDScript C++ Java Haxe

strictAccess

propriété 

strictAccess

Indique si l'accès est strict ou non. Si true, lire ou écrire une variable non définie lève une erreur.

Retourne boolean

JavaScript TypeScript C# GDScript C++ Java Haxe

customCreateFields

propriété 

customCreateFields()

Un instanciateur personnalisé pour créer les objets de champs.

Retourne (interpreter: Interpreter, type: string, node: Node) => any

JavaScript TypeScript C# Java Haxe

translations

propriété 

translations

Table de traductions optionnelle pour la localisation. Construite depuis un fichier de traduction analysé avec Loreline.extractTranslations().

Retourne Translations

JavaScript TypeScript C# GDScript C++ Java Haxe

ChoiceOption

interface

Représente une option de choix présentée à l'utilisateur.

text

propriété 

text

Le texte de l'option de choix.

Retourne string

JavaScript TypeScript C# C++ Java PHP Python Haxe

tags

propriété 

tags

Les tags éventuellement associés au texte du choix.

Retourne Array<TextTag>

JavaScript TypeScript C# C++ Java PHP Python Haxe

enabled

propriété 

enabled

Indique si cette option de choix est actuellement activée.

Retourne boolean

JavaScript TypeScript C# C++ Java PHP Python Haxe

TextTag

interface

Représente un tag dans un contenu textuel, utilisable pour la mise en forme ou à d'autres fins.

closing

propriété 

closing

Indique s'il s'agit d'un tag fermant.

Retourne boolean

JavaScript TypeScript C# C++ Java PHP Python Haxe

value

propriété 

value

La valeur ou le nom du tag.

Retourne string

JavaScript TypeScript C# C++ Java PHP Python Haxe

offset

propriété 

offset

La position dans le texte où ce tag apparaît.

Retourne number

JavaScript TypeScript C# C++ Java PHP Python Haxe

DialogueHandler

alias de type

Type de handler pour la sortie de texte avec callback. Appelé quand le script doit afficher du texte à l'utilisateur.

ChoiceHandler

alias de type

Type de handler pour la présentation des choix avec callback. Appelé quand le script doit présenter des choix à l'utilisateur.

FinishHandler

alias de type

Type de handler appelé quand l'exécution se termine.

ImportsFileHandler

alias de type

Fonction de handler pour le chargement des imports de fichiers

ImportsErrorHandler

alias de type

Fonction de handler pour les erreurs d'import

FunctionsMap

alias de type

Table associant des noms de fonctions à leur implémentation

Translations

alias de type

Type opaque pour une table de traductions. Obtenu via Loreline.extractTranslations() et passé à InterpreterOptions.translations.

SaveData

alias de type

Type opaque pour les données de sauvegarde.

Tokens

alias de type

Type Tokens

Error

interface

Représente une erreur dans le système Loreline.

message

propriété 

message

Le message d'erreur qui décrit le problème.

Retourne string

JavaScript TypeScript

pos

propriété 

pos

La position dans le code source où l'erreur s'est produite.

Retourne Position

JavaScript TypeScript

stack

propriété 

stack

La pile d'appels de cette erreur

Retourne Array<any>

JavaScript TypeScript

toString

méthode 

toString()

Convertit l'erreur en chaîne lisible.

Retourne string Message d'erreur formaté, avec la position

JavaScript TypeScript

Position

interface

Représente une position dans le code source, avec le numéro de ligne, la colonne et la position absolue. Utilisée partout dans le compilateur pour situer précisément les tokens, les nœuds et les messages d'erreur.

line

propriété 

line

Le numéro de ligne dans le code source, à partir de 1.

Retourne number

JavaScript TypeScript

column

propriété 

column

Le numéro de colonne dans le code source, à partir de 1. Représente la position du caractère dans la ligne courante.

Retourne number

JavaScript TypeScript

offset

propriété 

offset

La position absolue du caractère depuis le début du code source. Sert aux calculs précis de position et d'étendue.

Retourne number

JavaScript TypeScript

length

propriété 

length

La longueur de l'étendue de texte source que représente cette position. Une valeur de 0 indique un point plutôt qu'une étendue.

Retourne number

JavaScript TypeScript

toString

méthode 

toString()

Convertit la position en chaîne lisible.

Retourne string Chaîne de position formatée

JavaScript TypeScript

NodeId

interface

Représente un identifiant unique de nœud au sein de l'AST. Utilise un système d'identifiants structuré en section, branche, bloc et nœud.

toString

méthode 

toString()

Convertit le NodeId en représentation textuelle.

Retourne string Chaîne au format "section.branch.block.node"

JavaScript TypeScript C# Haxe

toInt64

méthode 

toInt64()

Convertit le NodeId en sa représentation Int64.

Retourne Int64 La valeur Int64 de ce NodeId

JavaScript TypeScript Haxe

Int64

interface

Un objet qui stocke un Int64 à partir de deux valeurs numériques high et low.

high

propriété 

high

Partie haute de l'Int64

Retourne number

JavaScript TypeScript

low

propriété 

low

Partie basse de l'Int64

Retourne number

JavaScript TypeScript

Fields

interface

Interface de base pour contenir des valeurs loreline. Cette interface permet de relier les champs d'objets loreline à des objets propres au jeu.

lorelineCreate

méthode 

lorelineCreate(interpreter)

Appelé quand l'objet a été créé depuis un interpréteur

ParamètreTypeDescription
interpreter Interpreter

Retourne void

JavaScript TypeScript C# Haxe

lorelineGet

méthode 

lorelineGet(interpreter, key)

Lit la valeur associée à la clé de champ donnée

ParamètreTypeDescription
interpreter Interpreter
key string

Retourne any

JavaScript TypeScript C# Haxe

lorelineSet

méthode 

lorelineSet(interpreter, key, value)

Écrit la valeur associée à la clé de champ donnée

ParamètreTypeDescription
interpreter Interpreter
key string
value any

Retourne void

JavaScript TypeScript C# Haxe

lorelineExists

méthode 

lorelineExists(interpreter, key)

Vérifie si une valeur existe pour la clé donnée

ParamètreTypeDescription
interpreter Interpreter
key string

Retourne boolean

JavaScript TypeScript C# Haxe

lorelineFields

méthode 

lorelineFields(interpreter)

Récupère tous les champs de cet objet

ParamètreTypeDescription
interpreter Interpreter

Retourne string[]

JavaScript TypeScript C# Haxe

Générée depuis Loreline v0.10.0.

Voir aussi
JavaScript →
Exécuter des scripts Loreline dans Node.js ou le navigateur.
Référence de l'API →
Toutes les classes et méthodes publiques du runtime Loreline, pour chaque langage cible.