Référence de l'API TypeScript
L'API publique complète du runtime Loreline pour chaque langage supporté.
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. Elle donne un accès simple aux fonctions 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 doit l'être aussi.
optionnel
|
handleFile |
ImportsFileHandler |
Handler optionnel qui lit les fichiers importés. S'il est asynchrone, parse() renvoie null : utilisez alors l'argument callback.
optionnel
|
callback |
(script: Script) => void |
S'il est fourni, il est appelé avec le script obtenu. Utile surtout quand les imports sont lus de façon asynchrone. optionnel |
Retourne
Script | null
Le script analysé, une instance Script de l'AST (si le chargement est synchrone)
Lève Si le script contient des erreurs de syntaxe ou d'autres problèmes d'analyse
C'est la première étape pour utiliser un script Loreline. L'objet Script renvoyé se passe ensuite à 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 l'exécution 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 à partir d'une sauvegarde.
| 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 (en général, celles renvoyées par interpreter.save())
|
beatName |
string |
Nom optionnel d'un beat où reprendre, à la place du point sauvegardé optionnel |
options |
InterpreterOptions |
Options de configuration de l'interpréteur (optionnelles) 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
Les traductions, à passer dans InterpreterOptions.translations
À partir d'un fichier de traduction analysé avec parse(), renvoie les traductions, à passer dans options.translations de play() ou de 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é (analysé avec un chemin de fichier, sinon fournissez filePath)
|
filePath |
string | null |
Emplacement 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 les traductions fusionnées. Requis si handleFile est asynchrone.
optionnel
|
Retourne
Translations | null
Les traductions fusionnées (renvoyées directement si handleFile est synchrone)
Pour chaque fichier du script (le fichier racine et tous ses imports, directs ou non), le fichier de traduction correspondant est cherché en insérant .<locale> avant l'extension (par exemple characters.lor -> characters.fr.lor). Les fichiers de traduction absents sont ignorés sans erreur. Les traductions renvoyées se passent dans InterpreterOptions.translations de play() ou de 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 autre format de fichier de traduction.
| 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 sans erreur, pour rester compatible 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 reçoit 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 méthode renvoie la même erreur, consultable 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 régénéré, sous forme de chaîne
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
Interpreter
Exécute un script analysé : garde l'état de l'histoire, décide de la suite et rend la main à votre code à chaque réplique 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 appelée pour afficher un texte de dialogue |
handleChoice |
ChoiceHandler |
Fonction appelée pour présenter des choix |
handleFinish |
FinishHandler |
Fonction appelée 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 le script ne contient aucun beat
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 à partir d'un objet SaveData, pour reprendre l'exécution là où elle avait été sauvegardée.
| 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
Renvoie un personnage par son nom.
| Paramètre | Type | Description |
|---|---|---|
name |
string |
Le nom du personnage à récupérer |
Retourne
any
Les propriétés du personnage, ou null si le personnage n'existe pas
getCharacterField
getCharacterField(character: string, name: string): any
Renvoie une propriété précise d'un personnage.
| Paramètre | Type | Description |
|---|---|---|
character |
string |
Le nom du personnage |
name |
string |
Le nom de la propriété à lire |
Retourne
any
La valeur de la propriété, ou null si le personnage ou la propriété n'existe pas
Les conteneurs (dictionnaires et tableaux) sont de simples objets et tableaux JS : les accesseurs de propriétés et les fonctions personnalisées échangent des valeurs JS ordinaires dans les deux sens.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
setCharacterField
setCharacterField(character: string, name: string, value: any): void
Modifie une propriété d'un personnage.
| Paramètre | Type | Description |
|---|---|---|
character |
string |
Le nom du personnage |
name |
string |
Le nom de la propriété à modifier |
value |
any |
La nouvelle valeur |
Retourne
void
getStateField
getStateField(name: string): any
Renvoie une propriété de l'état par son nom, en cherchant d'abord dans la portée courante, puis dans les portées englobantes.
| Paramètre | Type | Description |
|---|---|---|
name |
string |
Le nom de la propriété à lire |
Retourne
any
La valeur de la propriété, ou null si la propriété est introuvable
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
setStateField
setStateField(name: string, value: any): void
Modifie une propriété de l'état par son nom, en cherchant d'abord dans la portée courante, puis dans les portées englobantes.
| Paramètre | Type | Description |
|---|---|---|
name |
string |
Le nom de la propriété à modifier |
value |
any |
La nouvelle valeur |
Retourne
void
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
getTopLevelStateField
getTopLevelStateField(name: string): any
Renvoie directement une propriété de l'état de premier niveau.
| Paramètre | Type | Description |
|---|---|---|
name |
string |
Le nom de la propriété à lire |
Retourne
any
La valeur de la propriété, ou null si la propriété est introuvable
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
setTopLevelStateField
setTopLevelStateField(name: string, value: any): void
Modifie directement une propriété de l'état de premier niveau.
| Paramètre | Type | Description |
|---|---|---|
name |
string |
Le nom de la propriété à modifier |
value |
any |
La nouvelle valeur |
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 ce nœud est 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 d'origine de ce script. 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 de ce nœud dans le code source.
Retourne
Position
JavaScript TypeScript Haxe
type
type(): string
Renvoie le type de ce nœud.
Retourne
string
Le type du nœud, sous forme de chaîne
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 appelée pour chaque nœud enfant |
Retourne
void
JavaScript TypeScript Haxe
InterpreterOptions
Options de configuration du comportement de l'interpréteur Loreline
functions
functions?: FunctionsMap
Dictionnaire optionnel de fonctions supplémentaires que le script pourra appeler
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 les objets qui contiennent les propriétés.
Retourne
(interpreter: Interpreter, type: string, node: Node) => any
JavaScript TypeScript C# Java Haxe
translations
translations?: Translations
Traductions optionnelles pour la localisation. Construites depuis un fichier de traduction analysé avec Loreline.extractTranslations().
Retourne
Translations
ChoiceOption
Représente une option de choix présentée au joueur.
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 de ce tag dans le texte.
Retourne
number
DialogueHandler
export type DialogueHandler = (interpreter: Interpreter, character: string | null, text: string, tags: Array<TextTag>, callback: () => void) => voidType de handler pour l'affichage de texte, avec callback. Appelé quand le script doit afficher du texte au joueur.
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 au joueur.
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) => voidHandler qui charge les fichiers importés
ImportsErrorHandler
export type ImportsErrorHandler = (error: Error) => voidHandler appelé en cas d'erreur d'import
FunctionsMap
export type FunctionsMap = Record<string, Function>Dictionnaire qui associe des noms de fonctions à leur implémentation
Translations
export type Translations = anyType opaque qui contient les 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 de l'erreur dans le code source.
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 Int64.
Retourne
Int64
La valeur Int64 de ce NodeId
JavaScript TypeScript Haxe
Int64
Un objet qui stocke un Int64 sous forme de deux nombres, 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 des objets qui contiennent des valeurs Loreline. Elle permet de relier les propriétés des 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
Renvoie la valeur associée à la clé de propriété 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
Modifie la valeur associée à la clé de propriété 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[]
Renvoie toutes les propriétés de cet objet
| Paramètre | Type | Description |
|---|---|---|
interpreter |
Interpreter |
Retourne
string[]
JavaScript TypeScript C# Haxe
Générée depuis Loreline v0.10.0.