Référence de l'API Lua

L'API publique complète du runtime Loreline.

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

Vue d'ensemble

Type	Membres
`loreline`	`parse` `play` `resume` `extract_translations` `load_locale` `translation_format` `last_error` `print` `update`
`Interpreter`	`start` `save` `restore` `resume` `get_character` `get_character_field` `set_character_field` `get_state_field` `set_state_field` `get_top_level_state_field` `set_top_level_state_field` `current_node`
`Script`	`from_json`
`Node`	`node_type` `to_json` `from_json` `line` `column` `offset` `length` `node_id_to_string`

`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

function M.parse(source, file_path, handle_file, callback)

Analyse une chaîne de script Loreline et en fait un AST Script.

Paramètre	Type	Description
`source`	`string`	Le contenu du script Loreline sous forme de chaîne (format `.lor`)
`file_path`	`string\|nil`	Chemin optionnel du fichier analysé. S'il est fourni, `handleFile` est requis également.
`handle_file`	`function\|nil`	Handler de fichiers optionnel pour lire les imports. Si ce handler est asynchrone, `parse()` renverra null et l'argument `callback` devra être utilisé
`callback`	`function\|nil`	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

Retourne Script|nil Le Script analysé, ou nil en cas de chargement asynchrone.

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

function M.play(script, handle_dialogue, handle_choice, handle_finish, beat_name, options)

Démarre la lecture d'un script analysé.

Paramètre	Type	Description
`script`	`Script`	Le script analysé (résultat de `parse()`)
`handle_dialogue`	`function`	Fonction appelée quand un texte de dialogue doit être affiché
`handle_choice`	`function`	Fonction appelée quand le joueur doit faire un choix
`handle_finish`	`function`	Fonction appelée quand l'exécution du script se termine
`beat_name`	`string\|nil`	Nom optionnel d'un beat précis par lequel démarrer (par défaut, le premier beat)
`options`	`table\|nil`	Options supplémentaires

Retourne Interpreter L'instance d'Interpreter en cours d'exécution.

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

function M.resume(script, handle_dialogue, handle_choice, handle_finish, save_data, beat_name, options)

Reprend un script depuis un état sauvegardé.

Paramètre	Type	Description
`script`	`Script`	Le script analysé (résultat de `parse()`)
`handle_dialogue`	`function`	Fonction appelée quand un texte de dialogue doit être affiché
`handle_choice`	`function`	Fonction appelée quand le joueur doit faire un choix
`handle_finish`	`function`	Fonction appelée quand l'exécution du script se termine
`save_data`	`table`	Les données de sauvegarde (typiquement issues de `interpreter.save()`)
`beat_name`	`string\|nil`	Nom de beat optionnel pour choisir où reprendre
`options`	`table\|nil`	Options optionnelles pour configurer le comportement de l'interpréteur

Retourne Interpreter L'instance d'Interpreter en cours d'exécution.

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

`extract_translations`

méthode

function M.extract_translations(script)

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 table Un objet de traductions à passer à play() ou resume().

À 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

`load_locale`

méthode

function M.load_locale(locale, script, file_path, handle_file, callback)

Charge les traductions d'une langue donnée, en parcourant tout l'arbre d'imports du script. Pour chaque fichier concerné (racine + imports transitifs), recherche le fichier de traduction correspondant en insérant .<locale> avant l'extension (par exemple characters.lor -> characters.fr.lor). Les fichiers de traduction absents sont ignorés silencieusement.

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)
`file_path`	`string\|nil`	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.
`handle_file`	`function`	Handler de fichiers utilisé pour lire les fichiers de traduction
`callback`	`function\|nil`	Appelé avec la table de traductions fusionnée. Requis si `handleFile` est asynchrone.

Retourne table La table de traductions fusionnée (de façon synchrone, quand handle_file 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

`translation_format`

méthode

function M.translation_format(name, enabled)

Active ou désactive la prise en charge d'un format de fichier de traduction alternatif. Par défaut, load_locale n'essaie que les fichiers .<locale>.lor. Appelez cette fonction pour activer d'autres formats. Noms connus : "po" (.po), "xliff" (.xliff, .xlf), "csv" (.csv, .tsv). Les noms inconnus sont acceptés silencieusement, par compatibilité ascendante.

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

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

`last_error`

méthode

function M.last_error()

Renvoie l'erreur du dernier appel échoué à parse() ou load_locale(), ou nil en cas de succès. En mode asynchrone (avec callback), le callback se déclenche avec nil en cas d'échec et cette fonction 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.

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

function M.print(script, indent, newline)

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)
`newline`	`string`	La chaîne de saut de ligne à utiliser (par défaut "\n")

Retourne string Le code source produit.

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

`update`

méthode

function M.update(delta)

Fait avancer les timers wait() en attente. À appeler depuis votre boucle de jeu à chaque frame. Le premier appel active le mode différé non bloquant pour wait() ; avant cet appel, wait() retombe sur une attente bloquante, ce qui convient aux outils en ligne de commande.

Paramètre	Type	Description
`delta`	`number`	Temps écoulé depuis la frame précédente, en secondes

C# 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.

`start`

méthode

function Interpreter:start(beat_name)

Démarre ou redémarre l'exécution depuis un beat précis.

Paramètre	Type	Description
`beat_name`	`string\|nil`	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.

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

function Interpreter:save()

Sauvegarde l'état courant de l'interpréteur.

Retourne table Données de sauvegarde opaques, à passer plus tard à loreline.resume() ou interpreter:restore().

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

`restore`

méthode

function Interpreter:restore(save_data)

Restaure l'interpréteur dans un état précédemment sauvegardé.

Paramètre	Type	Description
`save_data`	`table`	L'objet SaveData contenant l'état sérialisé

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

function Interpreter:resume()

Reprend l'exécution après la restauration de l'état.

JavaScript TypeScript C# Java PHP Python Lua Haxe

`get_character`

méthode

function Interpreter:get_character(name)

Récupère les champs d'un personnage par son nom.

Paramètre	Type	Description
`name`	`string`	Le nom du personnage à récupérer

Retourne table|nil Les champs du personnage, ou nil s'il est introuvable.

JavaScript TypeScript C# Java PHP Python Lua Haxe

`get_character_field`

méthode

function Interpreter:get_character_field(character, field)

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

Paramètre	Type	Description
`character`	`string`	Le nom du personnage
`field`	`string`	Le nom du champ à lire

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

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

`set_character_field`

méthode

function Interpreter:set_character_field(character, field, value)

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

Paramètre	Type	Description
`character`	`string`	Le nom du personnage
`field`	`string`	Le nom du champ à écrire
`value`	`any`	La valeur à écrire

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

`get_state_field`

méthode

function Interpreter:get_state_field(name)

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 nil si elle est introuvable.

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

`set_state_field`

méthode

function Interpreter:set_state_field(name, value)

É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

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

`get_top_level_state_field`

méthode

function Interpreter:get_top_level_state_field(name)

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 nil si elle est introuvable.

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

`set_top_level_state_field`

méthode

function Interpreter:set_top_level_state_field(name, value)

É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

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

`current_node`

méthode

function Interpreter:current_node()

Récupère 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|nil Le nœud courant, ou nil si aucun nœud n'est en cours d'exécution.

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

`Script`

classe

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

`from_json`

méthode

function Script.from_json(json_str)

Reconstruit un Script depuis une chaîne JSON.

Paramètre	Type	Description
`json_str`	`string`	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.

`node_type`

méthode

function Node:node_type()

Récupère le type de ce nœud (par exemple "Script", "Beat", "Text", "Dialogue").

Retourne string Le type du nœud.

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

`to_json`

méthode

function Node:to_json(pretty)

Exporte ce nœud en chaîne JSON.

Paramètre	Type	Description
`pretty`	`boolean\|nil`

Retourne string Une représentation JSON de l'arbre du nœud, sous forme de chaîne.

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

`from_json`

méthode

function Node.from_json(json_str)

Reconstruit un Node depuis une chaîne JSON.

Paramètre	Type	Description
`json_str`	`string`	L'objet JSON (tel que renvoyé par `node.toJson()`)

Retourne Node Le Node reconstruit.

JavaScript TypeScript C# Java PHP Python Lua Haxe

`line`

méthode

function Node:line()

Récupère le numéro de ligne dans le code source où ce nœud apparaît (à partir de 1).

Retourne number Le numéro de ligne.

`column`

méthode

function Node:column()

Récupère le numéro de colonne dans le code source où ce nœud apparaît (à partir de 1).

Retourne number Le numéro de colonne.

`offset`

méthode

function Node:offset()

Récupère la position absolue du caractère depuis le début du code source.

Retourne number La position absolue.

`length`

méthode

function Node:length()

Récupère la longueur de l'étendue de texte source que représente ce nœud.

Retourne number La longueur.

`node_id_to_string`

méthode

function Node:node_id_to_string()

Renvoie l'identifiant de nœud lisible (par exemple '1.0.0.0').

Retourne string L'identifiant de nœud pointé.

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

Voir aussi

Lua →

Intégrer Loreline dans un projet Lua.

Référence de l'API →

Toutes les classes et méthodes publiques du runtime Loreline, pour chaque langage cible.

Référence de l'API Lua

Vue d'ensemble

loreline#

parse#

play#

resume#

extract_translations#

load_locale#

translation_format#

last_error#

print#

update#

Interpreter#

start#

save#

restore#

resume#

get_character#

get_character_field#

set_character_field#

get_state_field#

set_state_field#

get_top_level_state_field#

set_top_level_state_field#

current_node#

Script#

from_json#

Node#

node_type#

to_json#

from_json#

line#

column#

offset#

length#

node_id_to_string#

`loreline`

`parse`

`play`

`resume`

`extract_translations`

`load_locale`

`translation_format`

`last_error`

`print`

`update`

`Interpreter`

`start`

`save`

`restore`

`resume`

`get_character`

`get_character_field`

`set_character_field`

`get_state_field`

`set_state_field`

`get_top_level_state_field`

`set_top_level_state_field`

`current_node`

`Script`

`from_json`

`Node`

`node_type`

`to_json`

`from_json`

`line`

`column`

`offset`

`length`

`node_id_to_string`