Référence de l'API GDScript

L'API publique complète du runtime Loreline pour chaque langage supporté.

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

TypeMembres
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 à la première utilisation 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 Paramètres 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(...). S'il est fourni, file_handler est appelé avec (path, provide) et doit appeler provide.call(content_or_null).

ParamètreTypeDescription
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 doit l'être aussi. optionnel: ""
file_handler Callable Handler optionnel qui lit les fichiers importés. S'il est asynchrone, parse() renvoie null : utilisez alors l'argument callback. optionnel: Callable()

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

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ètreTypeDescription
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ètreTypeDescription
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 (en général, celles renvoyées par interpreter.save()) optionnel: ""
beat_name String Nom optionnel d'un beat où reprendre, à la place du point sauvegardé optionnel: ""
options LorelineOptions Options de configuration de l'interpréteur (optionnelles) 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 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

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ètreTypeDescription
locale String Le code de langue (par exemple "fr")
script LorelineScript Le script source analysé (analysé avec un chemin de fichier, sinon fournissez filePath)
file_path String 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: ""
file_handler Callable Handler de fichiers utilisé pour lire les fichiers de traduction optionnel: Callable()

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

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ètreTypeDescription
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 sans erreur, pour rester compatible 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 code source Loreline du script.

Retourne String Le code source régénéré, 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é. Au premier appel, il est créé et ajouté à l'arbre de scène.

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). Même API que la GDExtension native (mêmes signaux, méthodes et conventions de Callable) : les deux backends sont interchangeables.

start

méthode

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

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

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

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

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 La valeur de la propriété, ou null si le personnage ou la propriété 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

Modifie une propriété d'un personnage.

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

Retourne void

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

get_state_field

méthode

func get_state_field(field: String)

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
field String Le nom de la propriété à lire

Retourne La valeur de la propriété, ou null si la propriété 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

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
field String Le nom de la propriété à modifier
value La nouvelle valeur

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)

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

ParamètreTypeDescription
field String Le nom de la propriété à lire

Retourne La valeur de la propriété, ou null si la propriété 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

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

ParamètreTypeDescription
field String Le nom de la propriété à modifier
value La nouvelle valeur

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 réplique doit être affichée.

ParamètreTypeDescription
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ètreTypeDescription
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 terminé.

ParamètreTypeDescription
interpreter

advance

méthode

func advance() -> void

Fait avancer l'histoire après la réplique courante (comme appeler le Callable advance reçu avec le signal dialogue).

Retourne void

select

méthode

func select(index: int) -> void

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

ParamètreTypeDescription
index int

Retourne void

LorelineScript

classe

Un script Loreline analysé, avec la même API que 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ètreTypeDescription
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ètreTypeDescription
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ètreTypeDescription
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 à part. Les opérations regroupées ici se trouvent sur LorelineScript, l'objet que renvoie Loreline.parse().

to_json

méthode

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

Sérialise l'AST du script en JSON.

ParamètreTypeDescription
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 passées à Loreline.play() ou Loreline.resume(). Même API que 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. Un second appel à resolve est ignoré ; si resolve n'est jamais appelé, l'interpréteur reste en pause.

Sous Godot, les options se règlent par des setters sur un objet LorelineOptions, et non 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

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

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

Retourne void

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

JavaScript TypeScript C# GDScript C++ Java Haxe

set_translations

méthode

func set_translations(translations: LorelineTranslations) -> void

Traductions optionnelles pour la localisation. Construites depuis un fichier de traduction analysé avec Loreline.extractTranslations().

ParamètreTypeDescription
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 asynchrone, qui se termine plus tard.

ParamètreTypeDescription
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(). Un second appel à resolve est ignoré ; si resolve n'est jamais appelé, l'interpréteur reste en pause.

remove_function

méthode

func remove_function(name: String) -> void

Retire une fonction personnalisée déjà enregistrée.

ParamètreTypeDescription
name String

Retourne void

LorelineTranslations

classe

Conteneur opaque de traductions, obtenu avec LorelineScript.extract_translations() ou Loreline.load_locale(), à passer à LorelineOptions.set_translations().

LorelineParseResult

classe

Objet à attendre avec await, une seule fois, renvoyé par Loreline.parse(). Le signal est émis à la frame suivante, pour laisser à await le temps de s'y connecter.

completed

signal

signal completed(script)

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

ParamètreTypeDescription
script

LorelineLoadLocaleResult

classe

Objet à attendre avec await, une seule fois, renvoyé par Loreline.load_locale(). Le signal est émis à la frame suivante, pour laisser à await le temps de s'y connecter.

completed

signal

signal completed(translations)

Émis avec l'objet LorelineTranslations chargé, ou null si aucune traduction n'a été trouvée.

ParamètreTypeDescription
translations

LorelineResourceLoader

classe

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

En plus de permettre load("res://story.lor"), c'est ce qui rend les fichiers .lor visibles pour l'export : un preset qui exporte "toutes les ressources" ne prend que les fichiers reconnus par un ResourceFormatLoader. Sans lui, les fichiers d'histoire manquent dans chaque export sans aucun avertissement : le jeu marche dans l'éditeur mais n'affiche rien une fois exporté.

Le class_name ci-dessus est indispensable, pas décoratif : Godot trouve les chargeurs de formats de ressources personnalisés dans le registre global des classes de scripts, et c'est ce qui permet à tout ceci de marcher sans plugin activé ni réglage du projet. Le retirer bloque l'export des fichiers .lor sans aucun avertissement.

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