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
Loreline
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
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è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 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
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
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 (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
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
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é (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
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 sans erreur, pour rester compatible avec de futurs formats.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
print_script
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
LorelineInterpreter
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
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 le script ne contient aucun beat
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
save_state
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
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
func get_character_field(character: String, field: String)
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 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
func set_character_field(character: String, field: String, value) -> void
Modifie une propriété d'un personnage.
| Paramètre | Type | Description |
|---|---|---|
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
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ètre | Type | Description |
|---|---|---|
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
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ètre | Type | Description |
|---|---|---|
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
func get_top_level_state_field(field: String)
Renvoie directement une propriété de l'état de premier niveau.
| Paramètre | Type | Description |
|---|---|---|
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
func set_top_level_state_field(field: String, value) -> void
Modifie directement une propriété de l'état de premier niveau.
| Paramètre | Type | Description |
|---|---|---|
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
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 dialogue(interpreter, character: String, text: String, tags: Array, advance: Callable)
Émis quand une réplique 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 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 finished(interpreter)
Émis quand le script est terminé.
| Paramètre | Type | Description |
|---|---|---|
interpreter |
advance
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
func select(index: int) -> void
Sélectionne une option par son indice (revient à appeler le Callable select reçu avec le signal choice).
| Paramètre | Type | Description |
|---|---|---|
index |
int |
Retourne
void
LorelineScript
Un script Loreline analysé, avec la même API que la GDExtension native.
from_json
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
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
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 à part. Les opérations regroupées ici se trouvent sur
LorelineScript, l'objet que renvoieLoreline.parse().
to_json
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
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)Appelezresolve.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 avecLorelineOptions.new()et passez-le àplay()ouresume().
set_function
func set_function(name: String, callable: Callable) -> void
Dictionnaire optionnel de fonctions supplémentaires que le script pourra appeler
| Paramètre | Type | Description |
|---|---|---|
name |
String |
|
callable |
Callable |
Retourne
void
JavaScript TypeScript C# GDScript C++ Java Haxe
set_strict_access
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, 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
func set_translations(translations: LorelineTranslations) -> void
Traductions optionnelles pour la localisation. Construites 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
func get_strict_access() -> bool
Indique si l'accès strict est activé.
Retourne
bool
set_async_function
func set_async_function(name: String, callable: Callable) -> void
Enregistre une fonction personnalisée asynchrone, 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(). Un second appel à resolve est ignoré ; si resolve n'est jamais appelé, l'interpréteur reste en pause.
remove_function
func remove_function(name: String) -> void
Retire une fonction personnalisée déjà enregistrée.
| Paramètre | Type | Description |
|---|---|---|
name |
String |
Retourne
void
LorelineTranslations
Conteneur opaque de traductions, obtenu avec LorelineScript.extract_translations() ou Loreline.load_locale(), à passer à LorelineOptions.set_translations().
LorelineParseResult
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 completed(script)
Émis avec le LorelineScript analysé, ou null si l'analyse a échoué.
| Paramètre | Type | Description |
|---|---|---|
script |
LorelineLoadLocaleResult
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 completed(translations)
Émis avec l'objet LorelineTranslations chargé, ou null si aucune traduction n'a été trouvée.
| Paramètre | Type | Description |
|---|---|---|
translations |
LorelineResourceLoader
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.