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

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. Elle donne un accès simple aux fonctions de base pour analyser et exécuter des scripts Loreline.

parse

méthode

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è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 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

méthode

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è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

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è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 (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

méthode

static extractTranslations(script: Script): Translations

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 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

méthode

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ètreTypeDescription
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

méthode

static translationFormat(name: string, enabled: boolean): void

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

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 sans erreur, pour rester compatible avec de futurs formats.

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

lastError

méthode

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.

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

print

méthode

static print(script: Script, indent?: string, newline?: string): string

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 régénéré, sous forme de chaîne

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

Interpreter

classe

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

constructeur

constructor( script: Script, handleDialogue: DialogueHandler, handleChoice: ChoiceHandler, handleFinish: FinishHandler, options?: InterpreterOptions )

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

ParamètreTypeDescription
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

méthode

start(beatName?: string): void

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 le script ne contient aucun beat

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

save

méthode

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

méthode

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è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(): void

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: string): any

Renvoie un personnage par son nom.

ParamètreTypeDescription
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

JavaScript TypeScript C# Java PHP Python Lua Haxe

getCharacterField

méthode

getCharacterField(character: string, name: string): any

Renvoie une propriété précise d'un personnage.

ParamètreTypeDescription
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

méthode

setCharacterField(character: string, name: string, value: any): void

Modifie une propriété d'un personnage.

ParamètreTypeDescription
character string Le nom du personnage
name string Le nom de la propriété à modifier
value any La nouvelle valeur

Retourne void

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

getStateField

méthode

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ètreTypeDescription
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

méthode

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ètreTypeDescription
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

méthode

getTopLevelStateField(name: string): any

Renvoie directement une propriété de l'état de premier niveau.

ParamètreTypeDescription
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

méthode

setTopLevelStateField(name: string, value: any): void

Modifie directement une propriété de l'état de premier niveau.

ParamètreTypeDescription
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

méthode

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

méthode

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ètreTypeDescription
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

classe

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

body

propriété

body:Array<Node>

Tableau des déclarations de premier niveau du script.

Retourne Array<Node>

JavaScript TypeScript Haxe

filePath

propriété

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

méthode

static fromJson(json: any): Script

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: 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

propriété

pos: Position

Position de ce nœud dans le code source.

Retourne Position

JavaScript TypeScript Haxe

type

méthode

type(): string

Renvoie le type de ce nœud.

Retourne string Le type du nœud, sous forme de chaîne

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

toJson

méthode

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

méthode

static fromJson(json: any): Node

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: (node: Node, parent: Node) => void): void

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

ParamètreTypeDescription
handleNode (node: Node, parent: Node) => void Fonction appelée 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?: FunctionsMap

Dictionnaire optionnel de fonctions supplémentaires que le script pourra appeler

Retourne FunctionsMap

JavaScript TypeScript C# GDScript C++ Java Haxe

strictAccess

propriété

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

JavaScript TypeScript C# GDScript C++ Java Haxe

customCreateFields

propriété

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

propriété

translations?: Translations

Traductions optionnelles pour la localisation. Construites 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 au joueur.

text

propriété

text: string

Le texte de l'option de choix.

Retourne string

JavaScript TypeScript C# C++ Java PHP Python Haxe

tags

propriété

tags: Array<TextTag>

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

Retourne Array<TextTag>

JavaScript TypeScript C# C++ Java PHP Python Haxe

enabled

propriété

enabled: boolean

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: boolean

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

Retourne boolean

JavaScript TypeScript C# C++ Java PHP Python Haxe

value

propriété

value: string

La valeur ou le nom du tag.

Retourne string

JavaScript TypeScript C# C++ Java PHP Python Haxe

offset

propriété

offset: number

La position de ce tag dans le texte.

Retourne number

JavaScript TypeScript C# C++ Java PHP Python Haxe

DialogueHandler

alias de type

export type DialogueHandler = (interpreter: Interpreter, character: string | null, text: string, tags: Array<TextTag>, callback: () => void) => void

Type de handler pour l'affichage de texte, avec callback. Appelé quand le script doit afficher du texte au joueur.

ChoiceHandler

alias de type

export type ChoiceHandler = (interpreter: Interpreter, options: Array<ChoiceOption>, callback: (index: number) => void) => void

Type de handler pour la présentation des choix, avec callback. Appelé quand le script doit présenter des choix au joueur.

FinishHandler

alias de type

export type FinishHandler = (interpreter: Interpreter) => void

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

ImportsFileHandler

alias de type

export type ImportsFileHandler = (path: string, callback: (data: string) => void) => void

Handler qui charge les fichiers importés

ImportsErrorHandler

alias de type

export type ImportsErrorHandler = (error: Error) => void

Handler appelé en cas d'erreur d'import

FunctionsMap

alias de type

export type FunctionsMap = Record<string, Function>

Dictionnaire qui associe des noms de fonctions à leur implémentation

Translations

alias de type

export type Translations = any

Type opaque qui contient les traductions. Obtenu via Loreline.extractTranslations() et passé à InterpreterOptions.translations.

SaveData

alias de type

export type SaveData = any

Type opaque pour les données de sauvegarde.

Tokens

alias de type

export type Tokens = Array<any>

Type Tokens

Error

interface

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

message

propriété

message: string

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

Retourne string

JavaScript TypeScript

pos

propriété

pos: Position

La position de l'erreur dans le code source.

Retourne Position

JavaScript TypeScript

stack

propriété

stack: Array<any>

La pile d'appels de cette erreur

Retourne Array<any>

JavaScript TypeScript

toString

méthode

toString(): string

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: number

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

Retourne number

JavaScript TypeScript

column

propriété

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

propriété

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

propriété

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

méthode

toString(): string

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(): string

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(): Int64

Convertit le NodeId en Int64.

Retourne Int64 La valeur Int64 de ce NodeId

JavaScript TypeScript Haxe

Int64

interface

Un objet qui stocke un Int64 sous forme de deux nombres, high et low.

high

propriété

high: number

Partie haute de l'Int64

Retourne number

JavaScript TypeScript

low

propriété

low: number

Partie basse de l'Int64

Retourne number

JavaScript TypeScript

Fields

interface

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

méthode

lorelineCreate(interpreter: Interpreter): void

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: Interpreter, key: string): any

Renvoie la valeur associée à la clé de propriété donnée

ParamètreTypeDescription
interpreter Interpreter
key string

Retourne any

JavaScript TypeScript C# Haxe

lorelineSet

méthode

lorelineSet(interpreter: Interpreter, key: string, value: any): void

Modifie la valeur associée à la clé de propriété donnée

ParamètreTypeDescription
interpreter Interpreter
key string
value any

Retourne void

JavaScript TypeScript C# Haxe

lorelineExists

méthode

lorelineExists(interpreter: Interpreter, key: string): boolean

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: Interpreter): string[]

Renvoie toutes les propriétés de cet objet

ParamètreTypeDescription
interpreter Interpreter

Retourne string[]

JavaScript TypeScript C# Haxe

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