Référence de l'API GDScript

L'API publique complète du runtime Loreline.

Vous débutez avec Loreline en GDScript ? 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` `print_script` `shared`
`LorelineInterpreter`	`start` `save_state` `restore_state` `get_character_field` `set_character_field` `get_state_field` `set_state_field` `get_top_level_state_field` `set_top_level_state_field` `current_node` `dialogue` `choice` `finished` `advance` `select`
`LorelineScript`	`from_json` `play` `resume`
`Node`	`to_json`
`LorelineOptions`	`set_function` `set_strict_access` `set_translations` `get_strict_access` `set_async_function` `remove_function`
`LorelineTranslations`
`LorelineParseResult`	`completed`
`LorelineLoadLocaleResult`	`completed`
`LorelineResourceLoader`

`Loreline`

classe

Point d'entrée public du runtime Loreline en GDScript pur. Reproduit exactement l'API de la GDExtension native, ce qui permet de passer d'un backend à l'autre sans modifier le code (un seul addon peut être installé à la fois, les deux enregistrant les mêmes noms de classes).

On accède au runtime par Loreline.shared(), qui crée le nœud au premier usage et l'ajoute à la racine de l'arbre de scène. Ce n'est pas un autoload Godot : il n'y a rien à déclarer dans les réglages du projet.

`parse`

méthode

func parse(source: String, file_path: String = "", file_handler: Callable = Callable()) -> Signal

Analyse une source Loreline (ou un chemin res:// / user://) et en fait un script. Renvoie un Signal : var script = await loreline.parse(...). file_handler, s'il est fourni, est appelé sous la forme (path, provide) et doit appeler provide.call(contenu_ou_null).

Paramètre	Type	Description
`source`	`String`	Le contenu du script Loreline sous forme de chaîne (format `.lor`)
`file_path`	`String`	Chemin optionnel du fichier analysé. S'il est fourni, `handleFile` est requis également. optionnel: `""`
`file_handler`	`Callable`	Handler de fichiers optionnel pour lire les imports. Si ce handler est asynchrone, `parse()` renverra null et l'argument `callback` devra être utilisé optionnel: `Callable()`

Retourne Signal Le script analysé, sous forme d'instance AST Script (s'il a été chargé de façon synchrone)

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

func play(script: LorelineScript, on_dialogue: Callable = Callable(), on_choice: Callable = Callable(), on_finished: Callable = Callable(), beat_name: String = "", options: LorelineOptions = null) -> LorelineInterpreter

Exécute un script, en connectant les Callables fournis aux signaux dialogue/choice/finished de l'interpréteur.

Paramètre	Type	Description
`script`	`LorelineScript`	Le script analysé (résultat de `parse()`)
`on_dialogue`	`Callable`	Fonction appelée quand un texte de dialogue doit être affiché optionnel: `Callable()`
`on_choice`	`Callable`	Fonction appelée quand le joueur doit faire un choix optionnel: `Callable()`
`on_finished`	`Callable`	Fonction appelée quand l'exécution du script se termine optionnel: `Callable()`
`beat_name`	`String`	Nom optionnel d'un beat précis par lequel démarrer (par défaut, le premier beat) optionnel: `""`
`options`	`LorelineOptions`	Options supplémentaires optionnel: `null`

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

func resume(script: LorelineScript, on_dialogue: Callable, on_choice: Callable, on_finished: Callable, save_data: String = "", beat_name: String = "", options: LorelineOptions = null) -> LorelineInterpreter

Reprend un script depuis des données de sauvegarde, en connectant les Callables fournis.

Paramètre	Type	Description
`script`	`LorelineScript`	Le script analysé (résultat de `parse()`)
`on_dialogue`	`Callable`	Fonction appelée quand un texte de dialogue doit être affiché
`on_choice`	`Callable`	Fonction appelée quand le joueur doit faire un choix
`on_finished`	`Callable`	Fonction appelée quand l'exécution du script se termine
`save_data`	`String`	Les données de sauvegarde (typiquement issues de `interpreter.save()`) optionnel: `""`
`beat_name`	`String`	Nom de beat optionnel pour choisir où reprendre optionnel: `""`
`options`	`LorelineOptions`	Options optionnelles pour configurer le comportement de l'interpréteur optionnel: `null`

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

`extract_translations`

méthode

func extract_translations() -> LorelineTranslations

Extrait les traductions d'un script de traduction analysé.

Retourne LorelineTranslations Une table de traductions à passer comme InterpreterOptions.translations

À 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

func load_locale(locale: String, script: LorelineScript, file_path: String = "", file_handler: Callable = Callable()) -> Signal

Charge les traductions d'une langue (par exemple "fr") relativement au script. Renvoie un Signal qui se résout en LorelineTranslations (ou null).

Paramètre	Type	Description
`locale`	`String`	Le code de langue (par exemple `"fr"`)
`script`	`LorelineScript`	Le script source analysé (il doit avoir été analysé avec un chemin de fichier, ou `filePath` doit être fourni)
`file_path`	`String`	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. optionnel: `""`
`file_handler`	`Callable`	Handler de fichiers utilisé pour lire les fichiers de traduction optionnel: `Callable()`

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

func translation_format(name: String, enabled: bool) -> void

Active ou désactive un format de fichier de traduction ("po", "xliff", "csv").

Paramètre	Type	Description
`name`	`String`	L'identifiant de format (voir ci-dessus)
`enabled`	`bool`	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 silencieusement (compatibilité avec de futurs formats).

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

`print_script`

méthode

func print_script() -> String

Régénère le script sous sa forme source Loreline.

Retourne String Le code source produit, sous forme de chaîne

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

`shared`

méthode

static func shared() -> Loreline

Renvoie le nœud Loreline partagé, en le créant et en l'ajoutant à l'arbre de scène au premier usage.

Retourne Loreline

C'est le point d'entrée de tout le reste : Loreline.shared().parse(...).

`LorelineInterpreter`

classe

Enveloppe un interpréteur Loreline en cours d'exécution (runtime GDScript pur). Reproduit l'API de la GDExtension native : mêmes signaux, mêmes méthodes et mêmes conventions de Callable, les deux backends sont donc interchangeables.

`start`

méthode

func start(beat_name: String = "") -> void

Démarre (ou redémarre) l'exécution depuis le beat indiqué.

Paramètre	Type	Description
`beat_name`	`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 aucun beat n'est trouvé dans le script

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

`save_state`

méthode

func save_state() -> String

Renvoie l'état complet de l'interpréteur, sérialisé en chaîne JSON.

Retourne String Un objet SaveData contenant l'état sérialisé

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

`restore_state`

méthode

func restore_state(data: String) -> void

Restaure l'état de l'interpréteur depuis une chaîne JSON produite par save_state().

Paramètre	Type	Description
`data`	`String`	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

`get_character_field`

méthode

func get_character_field(character: String, field: String)

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 La valeur du champ, ou null si le personnage ou le champ n'existe pas

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

`set_character_field`

méthode

func set_character_field(character: String, field: String, value) -> void

É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`		La valeur à écrire

Retourne void

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

`get_state_field`

méthode

func get_state_field(field: String)

Lit un champ d'état par son nom, en résolvant depuis la portée courante vers l'extérieur.

Paramètre	Type	Description
`field`	`String`	Le nom du champ à lire

Retourne La valeur du champ, ou null si elle est introuvable

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

`set_state_field`

méthode

func set_state_field(field: String, value) -> void

Écrit un champ d'état par son nom, en résolvant depuis la portée courante vers l'extérieur.

Paramètre	Type	Description
`field`	`String`	Le nom du champ à écrire
`value`		La valeur à écrire

Retourne void

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

`get_top_level_state_field`

méthode

func get_top_level_state_field(field: String)

Lit directement un champ de l'état de premier niveau.

Paramètre	Type	Description
`field`	`String`	Le nom du champ à lire

Retourne La valeur du champ, ou null si elle est introuvable

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

`set_top_level_state_field`

méthode

func set_top_level_state_field(field: String, value) -> void

Écrit directement un champ sur l'état de premier niveau.

Paramètre	Type	Description
`field`	`String`	Le nom du champ à écrire
`value`		La valeur à écrire

Retourne void

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

`current_node`

méthode

func current_node() -> Dictionary

Informations sur le nœud en cours d'évaluation.

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

`dialogue`

signal

signal dialogue(interpreter, character: String, text: String, tags: Array, advance: Callable)

Émis quand une ligne de dialogue doit être affichée.

Paramètre	Type	Description
`interpreter`
`character`	`String`
`text`	`String`
`tags`	`Array`
`advance`	`Callable`

Appelez advance.call() une fois que le joueur l'a lue, pour laisser l'histoire continuer. character est vide pour la narration.

`choice`

signal

signal choice(interpreter, options: Array, select: Callable)

Émis quand le joueur doit choisir entre plusieurs options.

Paramètre	Type	Description
`interpreter`
`options`	`Array`
`select`	`Callable`

Appelez select.call(index) avec l'indice de l'option choisie. Chaque entrée de options est un dictionnaire avec text, tags et enabled.

`finished`

signal

signal finished(interpreter)

Émis quand le script est arrivé à son terme.

Paramètre	Type	Description
`interpreter`

`advance`

méthode

func advance() -> void

Passe au-delà du dialogue courant (équivalent à appeler le Callable advance reçu avec le signal dialogue).

Retourne void

`select`

méthode

func select(index: int) -> void

Sélectionne une option de choix par son indice (équivalent à appeler le Callable select reçu avec le signal choice).

Paramètre	Type	Description
`index`	`int`

Retourne void

`LorelineScript`

classe

Un script Loreline analysé. Reproduit l'API de la GDExtension native.

`from_json`

méthode

static func from_json(json: String) -> LorelineScript

Recrée un script à partir de la sortie de to_json().

Paramètre	Type	Description
`json`	`String`	L'objet JSON (tel que renvoyé par `script.toJson()`)

Retourne LorelineScript Le Script reconstruit

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

`play`

méthode

func play(beat_name: String = "", options: LorelineOptions = null) -> LorelineInterpreter

Exécute le script. Préférez Loreline.play(), qui connecte aussi les Callables.

Paramètre	Type	Description
`beat_name`	`String`	optionnel: `""`
`options`	`LorelineOptions`	optionnel: `null`

Retourne LorelineInterpreter

`resume`

méthode

func resume(save_data: String, beat_name: String = "", options: LorelineOptions = null) -> LorelineInterpreter

Reprend le script depuis un état sauvegardé. Préférez Loreline.resume().

Paramètre	Type	Description
`save_data`	`String`
`beat_name`	`String`	optionnel: `""`
`options`	`LorelineOptions`	optionnel: `null`

Retourne LorelineInterpreter

`Node`

Classe de base de tous les nœuds de l'AST. Contient les informations de position et la conversion JSON de base.

Godot n'a pas de type de nœud distinct. Les opérations regroupées ici vivent sur LorelineScript, ce que renvoie Loreline.parse().

`to_json`

méthode

func to_json(pretty: bool = false) -> String

Sérialise l'AST du script en JSON.

Paramètre	Type	Description
`pretty`	`bool`	optionnel: `false`

Retourne String Objet contenant le type et la position du nœud

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

`LorelineOptions`

classe

Options pour Loreline.play() / Loreline.resume(). Reproduit l'API de la GDExtension native.

Conventions des fonctions personnalisées :

synchrone : func(interp: LorelineInterpreter, args: Array) -> Variant
asynchrone : func(interp: LorelineInterpreter, args: Array, resolve: Callable) Appelez resolve.call() pour reprendre l'exécution. Appeler resolve deux fois n'a aucun effet ; l'abandonner sans l'appeler laisse l'interpréteur en pause.

Godot configure les options via des setters sur un objet LorelineOptions plutôt que par des champs. Créez-en un avec LorelineOptions.new() et passez-le à play() ou resume().

`set_function`

méthode

func set_function(name: String, callable: Callable) -> void

Table optionnelle de fonctions supplémentaires à rendre disponibles au script

Paramètre	Type	Description
`name`	`String`
`callable`	`Callable`

Retourne void

JavaScript TypeScript C# GDScript C++ Java Haxe

`set_strict_access`

méthode

func set_strict_access(strict: bool) -> void

Active ou désactive l'accès strict.

Paramètre	Type	Description
`strict`	`bool`

Retourne void

Avec l'accès strict activé, lire ou écrire une variable non définie lève une erreur au lieu de passer silencieusement.

JavaScript TypeScript C# GDScript C++ Java Haxe

`set_translations`

méthode

func set_translations(translations: LorelineTranslations) -> void

Table de traductions optionnelle pour la localisation. Construite depuis un fichier de traduction analysé avec Loreline.extractTranslations().

Paramètre	Type	Description
`translations`	`LorelineTranslations`

Retourne void

JavaScript TypeScript C# GDScript C++ Java Haxe

`get_strict_access`

méthode

func get_strict_access() -> bool

Indique si l'accès strict est activé.

Retourne bool

`set_async_function`

méthode

func set_async_function(name: String, callable: Callable) -> void

Enregistre une fonction personnalisée qui se termine plus tard.

Paramètre	Type	Description
`name`	`String`
`callable`	`Callable`

Retourne void

Le Callable reçoit (interp, args, resolve) et l'interpréteur reste en pause jusqu'à l'appel de resolve.call(). Appeler resolve deux fois n'a aucun effet ; l'abandonner sans l'appeler laisse l'interpréteur en pause.

`remove_function`

méthode

func remove_function(name: String) -> void

Retire une fonction personnalisée précédemment enregistrée.

Paramètre	Type	Description
`name`	`String`

Retourne void

`LorelineTranslations`

classe

Conteneur opaque pour une table de traductions, obtenu via LorelineScript.extract_translations() ou Loreline.load_locale(), et passé à LorelineOptions.set_translations().

`LorelineParseResult`

classe

Cible d'await à usage unique renvoyée par Loreline.parse(). L'émission est différée à la frame de traitement suivante pour que les awaiters soient connectés d'abord.

`completed`

signal

signal completed(script)

Émis avec le LorelineScript analysé, ou null si l'analyse a échoué.

Paramètre	Type	Description
`script`

`LorelineLoadLocaleResult`

classe

Cible d'await à usage unique renvoyée par Loreline.load_locale(). L'émission est différée à la frame de traitement suivante pour que les awaiters soient connectés d'abord.

`completed`

signal

signal completed(translations)

Émis avec les LorelineTranslations chargées, ou null si rien n'a été trouvé.

Paramètre	Type	Description
`translations`

`LorelineResourceLoader`

classe

Fait reconnaître les fichiers .lor comme des ressources, à l'image du LorelineResourceLoader de la GDExtension native.

Au-delà de permettre load("res://story.lor"), c'est ce qui rend les fichiers .lor visibles au système d'export : un preset qui exporte « toutes les ressources » ne prend que les fichiers revendiqués par un ResourceFormatLoader. Sans cela, les fichiers d'histoire sont absents de tous les exports en silence, et le jeu fonctionne dans l'éditeur mais n'affiche rien une fois exporté.

Le class_name ci-dessus est fonctionnel, pas cosmétique : Godot récupère les chargeurs de formats de ressources personnalisés dans le registre global des classes de scripts, ce qui fait fonctionner tout ceci sans plugin activé ni configuration du projet. Le retirer empêche silencieusement l'export des fichiers .lor.

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

Voir aussi

Godot →

Intégrer Loreline dans un projet Godot avec GDScript.

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 GDScript

Vue d'ensemble

Loreline#

parse#

play#

resume#

extract_translations#

load_locale#

translation_format#

print_script#

shared#

LorelineInterpreter#

start#

save_state#

restore_state#

get_character_field#

set_character_field#

get_state_field#

set_state_field#

get_top_level_state_field#

set_top_level_state_field#

current_node#

dialogue#

choice#

finished#

advance#

select#

LorelineScript#

from_json#

play#

resume#

Node#

to_json#

LorelineOptions#

set_function#

set_strict_access#

set_translations#

get_strict_access#

set_async_function#

remove_function#

LorelineTranslations#

LorelineParseResult#

completed#

LorelineLoadLocaleResult#

completed#

LorelineResourceLoader#

`Loreline`

`parse`

`play`

`resume`

`extract_translations`

`load_locale`

`translation_format`

`print_script`

`shared`

`LorelineInterpreter`

`start`

`save_state`

`restore_state`

`get_character_field`

`set_character_field`

`get_state_field`

`set_state_field`

`get_top_level_state_field`

`set_top_level_state_field`

`current_node`

`dialogue`

`choice`

`finished`

`advance`

`select`

`LorelineScript`

`from_json`

`play`

`resume`

`Node`

`to_json`

`LorelineOptions`

`set_function`

`set_strict_access`

`set_translations`

`get_strict_access`

`set_async_function`

`remove_function`

`LorelineTranslations`

`LorelineParseResult`

`completed`

`LorelineLoadLocaleResult`

`completed`

`LorelineResourceLoader`