Référence de l'API Lua
L'API publique complète du runtime Loreline pour chaque langage supporté.
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
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
function M.parse(source, file_path, handle_file, callback)
Analyse une chaîne contenant un script Loreline et la transforme en 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 doit l'être aussi.
|
handle_file |
function|nil |
Handler optionnel qui lit les fichiers importés. S'il est asynchrone, parse() renvoie null : utilisez alors l'argument callback.
|
callback |
function|nil |
S'il est fourni, il est appelé avec le script obtenu. Utile surtout quand les imports 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 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
function M.play(script, handle_dialogue, handle_choice, handle_finish, beat_name, options)
Démarre l'exécution 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
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 (en général, celles renvoyées par interpreter.save())
|
beat_name |
string|nil |
Nom optionnel d'un beat où reprendre, à la place du point sauvegardé |
options |
table|nil |
Options de configuration de l'interpréteur (optionnelles) |
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
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 les traductions, à passer dans options.translations de play() ou de resume().
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
load_locale
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 sans erreur.
| 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)
|
file_path |
string|nil |
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.
|
handle_file |
function |
Handler de fichiers utilisé pour lire les fichiers de traduction |
callback |
function|nil |
Appelé avec les traductions fusionnées. Requis si handleFile est asynchrone.
|
Retourne
table
Les traductions fusionnées (renvoyées directement quand handle_file 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
translation_format
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 sans erreur, pour rester compatible avec les versions futures.
| 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 sans erreur, pour rester compatible avec de futurs formats.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
last_error
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 fonction renvoie la même erreur, que l'on peut consulter après le catch. Pas thread-safe : à lire immédiatement après le retour de l'appel.
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
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
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 |
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.
start
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 le script ne contient aucun beat
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
save
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
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
function Interpreter:resume()
Reprend l'exécution une fois l'état restauré.
JavaScript TypeScript C# Java PHP Python Lua Haxe
get_character
function Interpreter:get_character(name)
Renvoie les propriétés d'un personnage par son nom.
| Paramètre | Type | Description |
|---|---|---|
name |
string |
Le nom du personnage à récupérer |
Retourne
table|nil
Les propriétés du personnage, ou nil s'il est introuvable.
JavaScript TypeScript C# Java PHP Python Lua Haxe
get_character_field
function Interpreter:get_character_field(character, field)
Renvoie une propriété précise d'un personnage.
| Paramètre | Type | Description |
|---|---|---|
character |
string |
Le nom du personnage |
field |
string |
Le nom de la propriété à lire |
Retourne
any
La valeur de la propriété, ou nil si elle n'existe pas.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
set_character_field
function Interpreter:set_character_field(character, field, value)
Modifie une propriété précise d'un personnage.
| Paramètre | Type | Description |
|---|---|---|
character |
string |
Le nom du personnage |
field |
string |
Le nom de la propriété à modifier |
value |
any |
La nouvelle valeur |
get_state_field
function Interpreter:get_state_field(name)
Renvoie une propriété de l'état par son nom, en la cherchant de la portée courante vers l'extérieur.
| Paramètre | Type | Description |
|---|---|---|
name |
string |
Le nom de la propriété à lire |
Retourne
any
La valeur de la propriété, ou nil si elle n'existe pas.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
set_state_field
function Interpreter:set_state_field(name, value)
Modifie une propriété de l'état par son nom, en la cherchant de la portée courante vers l'extérieur.
| Paramètre | Type | Description |
|---|---|---|
name |
string |
Le nom de la propriété à modifier |
value |
any |
La nouvelle valeur |
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
get_top_level_state_field
function Interpreter:get_top_level_state_field(name)
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 nil si elle n'existe pas.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
set_top_level_state_field
function Interpreter:set_top_level_state_field(name, value)
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 |
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
current_node
function Interpreter:current_node()
Renvoie le nœud en cours d'exécution. Dans un callback de dialogue, c'est le nœud de l'instruction de dialogue ; dans un callback de choix, celui 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
Représente le nœud racine de l'AST d'un script Loreline.
from_json
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 de base de tous les nœuds de l'AST. Contient les informations de position et la conversion JSON de base.
node_type
function Node:node_type()
Renvoie 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
function Node:to_json(pretty)
Exporte ce nœud en chaîne JSON.
| Paramètre | Type | Description |
|---|---|---|
pretty |
boolean|nil |
Retourne
string
Une chaîne JSON qui représente le nœud et tout son sous-arbre.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
from_json
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
function Node:line()
Renvoie le numéro de ligne de ce nœud dans le code source (numérotation à partir de 1).
Retourne
number
Le numéro de ligne.
column
function Node:column()
Renvoie le numéro de colonne de ce nœud dans le code source (numérotation à partir de 1).
Retourne
number
Le numéro de colonne.
offset
function Node:offset()
Renvoie la position absolue de ce nœud, en caractères depuis le début du code source.
Retourne
number
La position absolue.
length
function Node:length()
Renvoie la longueur du texte source que couvre ce nœud.
Retourne
number
La longueur.
node_id_to_string
function Node:node_id_to_string()
Renvoie l'identifiant de nœud lisible (par exemple '1.0.0.0').
Retourne
string
L'identifiant du nœud en notation pointée.
Générée depuis Loreline v0.10.0.