Référence de l'API TypeScript
L'API publique complète du runtime Loreline.
Vous débutez avec Loreline en TypeScript ? Commencez par le guide d'intégration. Cette page est la référence exhaustive.
Vue d'ensemble
Loreline
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
static parse(input: string, filePath?: string, handleFile?: ImportsFileHandler, callback?: (script: Script) => void): Script | null
Analyse le texte fourni et en crée une instance Script exécutable.
| Paramètre | Type | Description |
|---|---|---|
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
static play( script: Script, handleDialogue: DialogueHandler, handleChoice: ChoiceHandler, handleFinish: FinishHandler, beatName?: string, options?: InterpreterOptions ): Interpreter
Démarre la lecture d'un script Loreline depuis le début ou depuis un beat précis.
| Paramètre | Type | Description |
|---|---|---|
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
static resume( script: Script, handleDialogue: DialogueHandler, handleChoice: ChoiceHandler, handleFinish: FinishHandler, saveData: SaveData, beatName?: string, options?: InterpreterOptions ): Interpreter
Reprend un script Loreline précédemment sauvegardé depuis son état enregistré.
| Paramètre | Type | Description |
|---|---|---|
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
static extractTranslations(script: Script): Translations
Extrait les traductions d'un script de traduction analysé.
| Paramètre | Type | Description |
|---|---|---|
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
static loadLocale( locale: string, script: Script, filePath?: string | null, handleFile?: ImportsFileHandler, callback?: (translations: Translations) => void ): Translations | null
Charge les traductions d'une langue donnée, en parcourant tout l'arbre d'imports du script.
| Paramètre | Type | Description |
|---|---|---|
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
static translationFormat(name: string, enabled: boolean): void
Active ou désactive la prise en charge d'un format de fichier de traduction alternatif.
| Paramètre | Type | Description |
|---|---|---|
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
static lastError(): Error | null
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.
print
static print(script: Script, indent?: string, newline?: string): string
Régénère le code source Loreline à partir d'un script analysé.
| Paramètre | Type | Description |
|---|---|---|
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
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
constructor( script: Script, handleDialogue: DialogueHandler, handleChoice: ChoiceHandler, handleFinish: FinishHandler, options?: InterpreterOptions )
Crée un nouvel interpréteur de script Loreline.
| Paramètre | Type | Description |
|---|---|---|
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
start(beatName?: string): void
Démarre l'exécution du script depuis le début ou depuis un beat précis.
| Paramètre | Type | Description |
|---|---|---|
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
save(): SaveData
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
restore(saveData: SaveData): void
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ètre | Type | Description |
|---|---|---|
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
resume(): void
Reprend l'exécution après la restauration de l'état. À appeler après restore() pour poursuivre l'exécution.
Retourne
void
getCharacter
getCharacter(name: string): any
Récupère un personnage par son nom.
| Paramètre | Type | Description |
|---|---|---|
name |
string |
Le nom du personnage à récupérer |
Retourne
any
Les champs du personnage, ou null si le personnage n'existe pas
getCharacterField
getCharacterField(character: string, name: string): any
Récupère un champ précis d'un personnage.
| Paramètre | Type | Description |
|---|---|---|
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
setCharacterField(character: string, name: string, value: any): void
Écrit un champ précis d'un personnage.
| Paramètre | Type | Description |
|---|---|---|
character |
string |
Le nom du personnage |
name |
string |
Le nom du champ à écrire |
value |
any |
La valeur à écrire |
Retourne
void
getStateField
getStateField(name: string): any
Lit un champ d'état par son nom, en résolvant depuis la portée courante vers l'extérieur.
| Paramètre | Type | Description |
|---|---|---|
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
setStateField(name: string, value: any): void
Écrit un champ d'état par son nom, en résolvant depuis la portée courante vers l'extérieur.
| Paramètre | Type | Description |
|---|---|---|
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
getTopLevelStateField(name: string): any
Lit directement un champ de l'état de premier niveau.
| Paramètre | Type | Description |
|---|---|---|
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
setTopLevelStateField(name: string, value: any): void
Écrit directement un champ sur l'état de premier niveau.
| Paramètre | Type | Description |
|---|---|---|
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
currentNode(): Node | null
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
currentNodeFilePath(rootPath: string): string
Renvoie le chemin du fichier contenant le nœud courant. Résout les chaînes d'imports relativement au chemin racine fourni.
| Paramètre | Type | Description |
|---|---|---|
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
Représente le nœud racine de l'AST d'un script Loreline.
body
body:Array<Node>
Tableau des déclarations de premier niveau du script.
Retourne
Array<Node>
JavaScript TypeScript Haxe
filePath
filePath: string | null
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
static fromJson(json: any): Script
Reconstruit un Script depuis sa représentation JSON.
| Paramètre | Type | Description |
|---|---|---|
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 de base de tous les nœuds de l'AST. Contient les informations de position et la conversion JSON de base.
id
id: NodeId
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
pos: Position
Position dans le code source où ce nœud apparaît.
Retourne
Position
JavaScript TypeScript Haxe
type
type(): string
Renvoie le type de ce nœud.
Retourne
string
Représentation textuelle du type de nœud
toJson
toJson(): any
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
static fromJson(json: any): Node
Reconstruit un Node depuis sa représentation JSON.
| Paramètre | Type | Description |
|---|---|---|
json |
any |
L'objet JSON (tel que renvoyé par node.toJson())
|
Retourne
Node
Le Node reconstruit
each
each(handleNode: (node: Node, parent: Node) => void): void
Parcourt tous les nœuds enfants de ce nœud.
| Paramètre | Type | Description |
|---|---|---|
handleNode |
(node: Node, parent: Node) => void |
Fonction à appeler pour chaque nœud enfant |
Retourne
void
JavaScript TypeScript Haxe
InterpreterOptions
Options de configuration du comportement de l'interpréteur Loreline
functions
functions?: FunctionsMap
Table optionnelle de fonctions supplémentaires à rendre disponibles au script
Retourne
FunctionsMap
strictAccess
strictAccess?: boolean
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
customCreateFields
customCreateFields?: (interpreter: Interpreter, type: string, node: Node) => any
Un instanciateur personnalisé pour créer les objets de champs.
Retourne
(interpreter: Interpreter, type: string, node: Node) => any
JavaScript TypeScript C# Java Haxe
translations
translations?: Translations
Table de traductions optionnelle pour la localisation. Construite depuis un fichier de traduction analysé avec Loreline.extractTranslations().
Retourne
Translations
ChoiceOption
Représente une option de choix présentée à l'utilisateur.
text
text: string
Le texte de l'option de choix.
Retourne
string
tags
tags: Array<TextTag>
Les tags éventuellement associés au texte du choix.
Retourne
Array<TextTag>
enabled
enabled: boolean
Indique si cette option de choix est actuellement activée.
Retourne
boolean
TextTag
Représente un tag dans un contenu textuel, utilisable pour la mise en forme ou à d'autres fins.
closing
closing: boolean
Indique s'il s'agit d'un tag fermant.
Retourne
boolean
value
value: string
La valeur ou le nom du tag.
Retourne
string
offset
offset: number
La position dans le texte où ce tag apparaît.
Retourne
number
DialogueHandler
export type DialogueHandler = (interpreter: Interpreter, character: string | null, text: string, tags: Array<TextTag>, callback: () => void) => voidType de handler pour la sortie de texte avec callback. Appelé quand le script doit afficher du texte à l'utilisateur.
ChoiceHandler
export type ChoiceHandler = (interpreter: Interpreter, options: Array<ChoiceOption>, callback: (index: number) => void) => voidType de handler pour la présentation des choix avec callback. Appelé quand le script doit présenter des choix à l'utilisateur.
FinishHandler
export type FinishHandler = (interpreter: Interpreter) => voidType de handler appelé quand l'exécution se termine.
ImportsFileHandler
export type ImportsFileHandler = (path: string, callback: (data: string) => void) => voidFonction de handler pour le chargement des imports de fichiers
ImportsErrorHandler
export type ImportsErrorHandler = (error: Error) => voidFonction de handler pour les erreurs d'import
FunctionsMap
export type FunctionsMap = Record<string, Function>Table associant des noms de fonctions à leur implémentation
Translations
export type Translations = anyType opaque pour une table de traductions. Obtenu via Loreline.extractTranslations() et passé à InterpreterOptions.translations.
SaveData
export type SaveData = anyType opaque pour les données de sauvegarde.
Tokens
export type Tokens = Array<any>Type Tokens
Error
Représente une erreur dans le système Loreline.
message
message: string
Le message d'erreur qui décrit le problème.
Retourne
string
JavaScript TypeScript
pos
pos: Position
La position dans le code source où l'erreur s'est produite.
Retourne
Position
JavaScript TypeScript
stack
stack: Array<any>
La pile d'appels de cette erreur
Retourne
Array<any>
JavaScript TypeScript
toString
toString(): string
Convertit l'erreur en chaîne lisible.
Retourne
string
Message d'erreur formaté, avec la position
JavaScript TypeScript
Position
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
line: number
Le numéro de ligne dans le code source, à partir de 1.
Retourne
number
JavaScript TypeScript
column
column: number
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
offset: number
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
length: number
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
toString(): string
Convertit la position en chaîne lisible.
Retourne
string
Chaîne de position formatée
JavaScript TypeScript
NodeId
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
toString(): string
Convertit le NodeId en représentation textuelle.
Retourne
string
Chaîne au format "section.branch.block.node"
JavaScript TypeScript C# Haxe
toInt64
toInt64(): Int64
Convertit le NodeId en sa représentation Int64.
Retourne
Int64
La valeur Int64 de ce NodeId
JavaScript TypeScript Haxe
Int64
Un objet qui stocke un Int64 à partir de deux valeurs numériques high et low.
high
high: number
Partie haute de l'Int64
Retourne
number
JavaScript TypeScript
low
low: number
Partie basse de l'Int64
Retourne
number
JavaScript TypeScript
Fields
Interface de base pour contenir des valeurs loreline. Cette interface permet de relier les champs d'objets loreline à des objets propres au jeu.
lorelineCreate
lorelineCreate(interpreter: Interpreter): void
Appelé quand l'objet a été créé depuis un interpréteur
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
Retourne
void
JavaScript TypeScript C# Haxe
lorelineGet
lorelineGet(interpreter: Interpreter, key: string): any
Lit la valeur associée à la clé de champ donnée
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
|
key |
string |
Retourne
any
JavaScript TypeScript C# Haxe
lorelineSet
lorelineSet(interpreter: Interpreter, key: string, value: any): void
Écrit la valeur associée à la clé de champ donnée
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
|
key |
string |
|
value |
any |
Retourne
void
JavaScript TypeScript C# Haxe
lorelineExists
lorelineExists(interpreter: Interpreter, key: string): boolean
Vérifie si une valeur existe pour la clé donnée
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
|
key |
string |
Retourne
boolean
JavaScript TypeScript C# Haxe
lorelineFields
lorelineFields(interpreter: Interpreter): string[]
Récupère tous les champs de cet objet
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
Retourne
string[]
JavaScript TypeScript C# Haxe
Générée depuis Loreline v0.10.0.