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

TypeMembres
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. Elle donne un accès simple aux fonctions 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 contenant un script Loreline et la transforme en AST Script.

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

méthode

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

Démarre l'exécution d'un script analysé.

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

méthode

function M.extract_translations(script)

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

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 sans erreur.

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

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 sans erreur, pour rester compatible avec les versions futures.

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

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

méthode

function M.print(script, indent, newline)

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)
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ètreTypeDescription
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é : garde l'état de l'histoire, décide de la suite et rend la main à votre code à chaque réplique 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ètreTypeDescription
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

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ètreTypeDescription
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 une fois l'état restauré.

JavaScript TypeScript C# Java PHP Python Lua Haxe

get_character

méthode

function Interpreter:get_character(name)

Renvoie les propriétés d'un personnage par son nom.

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

méthode

function Interpreter:get_character_field(character, field)

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

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

méthode

function Interpreter:set_character_field(character, field, value)

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

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

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

get_state_field

méthode

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

méthode

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

méthode

function Interpreter:get_top_level_state_field(name)

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 nil si elle n'existe pas.

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)

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

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

current_node

méthode

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

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

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

méthode

function Node:to_json(pretty)

Exporte ce nœud en chaîne JSON.

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

méthode

function Node.from_json(json_str)

Reconstruit un Node depuis une chaîne JSON.

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

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

méthode

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

méthode

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

méthode

function Node:length()

Renvoie la longueur du texte source que couvre 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 du nœud en notation pointée.

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