Référence de l'API Python

L'API publique complète du runtime Loreline.

Vous débutez avec Loreline en Python ? 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` `last_error` `print` `update`
`Interpreter`	`__init__` `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` `__init__`
`Node`	`type` `to_json` `from_json` `__init__` `line` `column` `offset` `length` `node_id_to_string`
`ChoiceOption`	`text` `tags` `enabled`
`TextTag`	`closing` `value` `offset`
`DialogueHandler`
`ChoiceHandler`
`FinishHandler`
`ImportsFileHandler`

`Loreline`

classe

API publique principale du runtime de fiction interactive Loreline.

Toutes les méthodes sont statiques. Usage typique ::

script = Loreline.parse(source) interp = Loreline.play(script, on_dialogue, on_choice, on_finish)

`parse`

méthode

def parse(source: str, file_path: Optional[str] = None, handle_file: Optional[ImportsFileHandler] = None, callback: Optional[Callable[[Script], None]] = None) -> Optional[Script]

Analyse une chaîne de script Loreline et en fait un AST Script.

Paramètre	Type	Description
`source`	`str`	Le contenu du script Loreline sous forme de chaîne (format `.lor`)
`file_path`	`Optional[str]`	Chemin optionnel du fichier analysé. S'il est fourni, `handleFile` est requis également. optionnel: `None`
`handle_file`	`Optional[ImportsFileHandler]`	Handler de fichiers optionnel pour lire les imports. Si ce handler est asynchrone, `parse()` renverra null et l'argument `callback` devra être utilisé optionnel: `None`
`callback`	`Optional[Callable[[Script], None]]`	S'il est fourni, sera appelé avec le script résultant en argument. Utile surtout quand les imports de fichiers sont lus de façon asynchrone optionnel: `None`

Retourne Optional[Script] Le Script analysé, ou None 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 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

def play(script: Script, handle_dialogue: DialogueHandler, handle_choice: ChoiceHandler, handle_finish: FinishHandler, beat_name: Optional[str] = None, functions: Optional[dict] = None, strict_access: bool = False, translations: Any = None) -> Interpreter

Démarre la lecture d'un script analysé.

Paramètre	Type	Description
`script`	`Script`	Le script analysé (résultat de `parse()`)
`handle_dialogue`	`DialogueHandler`	Fonction appelée quand un texte de dialogue doit être affiché
`handle_choice`	`ChoiceHandler`	Fonction appelée quand le joueur doit faire un choix
`handle_finish`	`FinishHandler`	Fonction appelée quand l'exécution du script se termine
`beat_name`	`Optional[str]`	Nom optionnel d'un beat précis par lequel démarrer (par défaut, le premier beat) optionnel: `None`
`functions`	`Optional[dict]`	Table associant un nom à `function(interpreter, args)`, rendue disponible au script. optionnel: `None`
`strict_access`	`bool`	Si true, lire ou écrire une variable non définie lève une erreur. optionnel: `False`
`translations`	`Any`	Table de traductions issue de `extract_translations()` ou `load_locale()`. optionnel: `None`

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

def resume(script: Script, handle_dialogue: DialogueHandler, handle_choice: ChoiceHandler, handle_finish: FinishHandler, save_data: Any, beat_name: Optional[str] = None, functions: Optional[dict] = None, strict_access: bool = False, translations: Any = None) -> Interpreter

Reprend un script depuis un état sauvegardé.

Paramètre	Type	Description
`script`	`Script`	Le script analysé (résultat de `parse()`)
`handle_dialogue`	`DialogueHandler`	Fonction appelée quand un texte de dialogue doit être affiché
`handle_choice`	`ChoiceHandler`	Fonction appelée quand le joueur doit faire un choix
`handle_finish`	`FinishHandler`	Fonction appelée quand l'exécution du script se termine
`save_data`	`Any`	Les données de sauvegarde (typiquement issues de `interpreter.save()`)
`beat_name`	`Optional[str]`	Nom de beat optionnel pour choisir où reprendre optionnel: `None`
`functions`	`Optional[dict]`	Table associant un nom à `function(interpreter, args)`, rendue disponible au script. optionnel: `None`
`strict_access`	`bool`	Si true, lire ou écrire une variable non définie lève une erreur. optionnel: `False`
`translations`	`Any`	Table de traductions issue de `extract_translations()` ou `load_locale()`. optionnel: `None`

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

def extract_translations(script: Script) -> Any

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 Any Un objet de traductions à passer comme argument translations à play() ou resume().

À 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

def load_locale(locale: str, script: Script, file_path: Optional[str] = None, handle_file: Optional[ImportsFileHandler] = None, callback: Optional[Callable[[Any], None]] = None) -> Any

Charge les traductions d'une langue donnée, en parcourant tout l'arbre d'imports du script.

Paramètre	Type	Description
`locale`	`str`	Le code de langue (par exemple `"fr"`)
`script`	`Script`	Le script source analysé (il doit avoir été analysé avec un chemin de fichier, ou `filePath` doit être fourni)
`file_path`	`Optional[str]`	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: `None`
`handle_file`	`Optional[ImportsFileHandler]`	Handler de fichiers utilisé pour lire les fichiers de traduction optionnel: `None`
`callback`	`Optional[Callable[[Any], None]]`	Appelé avec la table de traductions fusionnée. Requis si `handleFile` est asynchrone. optionnel: `None`

Retourne Any La table de traductions fusionnée (de façon synchrone, quand handle_file est synchrone).

Pour chaque fichier concerné par le script (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 silencieusement.

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

`translation_format`

méthode

def translation_format(name: str, enabled: bool) -> None

Active ou désactive la prise en charge d'un format de fichier de traduction alternatif.

Paramètre	Type	Description
`name`	`str`	L'identifiant de format (voir ci-dessus)
`enabled`	`bool`	True pour activer le format, false pour le désactiver

Retourne None

Par défaut, load_locale n'essaie que les fichiers .<locale>.lor. Appelez cette méthode pour activer d'autres formats. Noms connus : "po" (.po), "xliff" (.xliff, .xlf), "csv" (.csv, .tsv). Les noms inconnus sont acceptés silencieusement, par compatibilité ascendante.

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

`last_error`

méthode

def last_error() -> Optional[Any]

Renvoie l'erreur du dernier appel échoué à parse() ou load_locale(), ou None en cas de succès.

Retourne Optional[Any]

En mode asynchrone (avec callback), le callback se déclenche avec None 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 ce champ porte la même erreur pour pouvoir être consulté 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

def print(script: Script, indent: str = '  ', newline: str = '\n') -> str

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`	`str`	La chaîne d'indentation à utiliser (par défaut, deux espaces) optionnel: `' '`
`newline`	`str`	La chaîne de saut de ligne à utiliser (par défaut "\n") optionnel: `'\n'`

Retourne str Le code source produit.

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

`update`

méthode

def update(delta: float) -> None

Fait avancer les timers wait() en attente. À appeler depuis votre boucle de jeu à chaque frame.

Paramètre	Type	Description
`delta`	`float`	Temps écoulé depuis la frame précédente, en secondes

Retourne None

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.

C# C++ Java PHP Python Lua Haxe

`Interpreter`

classe

Un interpréteur de script Loreline en cours d'exécution.

Fournit des méthodes pour sauvegarder et restaurer l'état, et pour accéder aux données des personnages.

`init`

constructeur

def __init__(_internal: Any) -> None

Crée un nouvel interpréteur de script Loreline.

Paramètre	Type	Description
`_internal`	`Any`	L'interpréteur runtime enveloppé. Construisez les interpréteurs avec `Loreline.play()` plutôt qu'en appelant ceci directement.

Retourne None

JavaScript TypeScript C# Java Python Haxe

`start`

méthode

def start(beat_name: Optional[str] = None) -> None

Démarre ou redémarre l'exécution depuis un beat précis.

Paramètre	Type	Description
`beat_name`	`Optional[str]`	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: `None`

Retourne None

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`

méthode

def save() -> Any

Sauvegarde l'état courant de l'interpréteur.

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

Renvoie un objet de sauvegarde opaque, à passer plus tard à Loreline.resume() ou Interpreter.restore().

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

`restore`

méthode

def restore(save_data: Any) -> None

Restaure l'interpréteur dans un état précédemment sauvegardé.

Paramètre	Type	Description
`save_data`	`Any`	L'objet SaveData contenant l'état sérialisé

Retourne None

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

def resume() -> None

Reprend l'exécution après la restauration de l'état.

Retourne None

JavaScript TypeScript C# Java PHP Python Lua Haxe

`get_character`

méthode

def get_character(name: str) -> Any

Récupère les champs d'un personnage par son nom.

Paramètre	Type	Description
`name`	`str`	Le nom du personnage à récupérer

Retourne Any L'objet de champs du personnage, ou None s'il est introuvable.

JavaScript TypeScript C# Java PHP Python Lua Haxe

`get_character_field`

méthode

def get_character_field(character: str, field: str) -> Any

Récupère un champ précis d'un personnage.

Paramètre	Type	Description
`character`	`str`	Le nom du personnage
`field`	`str`	Le nom du champ à lire

Retourne Any La valeur du champ, ou None si elle est introuvable.

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

`set_character_field`

méthode

def set_character_field(character: str, field: str, value: Any) -> None

Écrit un champ précis d'un personnage.

Paramètre	Type	Description
`character`	`str`	Le nom du personnage
`field`	`str`	Le nom du champ à écrire
`value`	`Any`	La valeur à écrire

Retourne None

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

`get_state_field`

méthode

def get_state_field(name: str) -> Any

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

Paramètre	Type	Description
`name`	`str`	Le nom du champ à lire

Retourne Any La valeur du champ, ou None si elle est introuvable.

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

`set_state_field`

méthode

def set_state_field(name: str, value: Any) -> None

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

Paramètre	Type	Description
`name`	`str`	Le nom du champ à écrire
`value`	`Any`	La valeur à écrire

Retourne None

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

`get_top_level_state_field`

méthode

def get_top_level_state_field(name: str) -> Any

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

Paramètre	Type	Description
`name`	`str`	Le nom du champ à lire

Retourne Any La valeur du champ, ou None si elle est introuvable.

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

`set_top_level_state_field`

méthode

def set_top_level_state_field(name: str, value: Any) -> None

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

Paramètre	Type	Description
`name`	`str`	Le nom du champ à écrire
`value`	`Any`	La valeur à écrire

Retourne None

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

`current_node`

méthode

def current_node() -> Optional[Node]

Renvoie le nœud en cours d'exécution.

Retourne Optional[Node] Le Node courant, ou None si aucun nœud n'est en cours d'exécution.

Pendant un callback de dialogue, renvoie le nœud de l'instruction de dialogue. Pendant un callback de choix, renvoie le nœud de l'instruction de choix.

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

`Script`

classe

Un AST de script Loreline analysé.

S'obtient via Loreline.parse(). À passer à Loreline.play() ou Loreline.resume() pour l'exécuter.

`from_json`

méthode

def from_json(json_str: str) -> 'Script'

Reconstruit un Script depuis une chaîne JSON.

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

Retourne 'Script' Le Script reconstruit.

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

`init`

constructeur

def __init__(_internal: Any) -> None

Paramètre	Type	Description
`_internal`	`Any`

Retourne None

`Node`

classe

Classe de base des nœuds de l'AST Loreline.

Donne accès au type du nœud, à son identifiant unique et à son export JSON.

`type`

méthode

def type() -> str

Le type de ce nœud (par exemple "Script", "Beat", "Text").

Retourne str Représentation textuelle du type de nœud

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

`to_json`

méthode

def to_json(pretty: bool = False) -> str

Exporte ce nœud en chaîne JSON.

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

Retourne str Une représentation JSON de l'arbre du nœud, sous forme de chaîne.

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

`from_json`

méthode

def from_json(json_str: str) -> 'Node'

Reconstruit un Node depuis une chaîne JSON.

Paramètre	Type	Description
`json_str`	`str`	L'objet JSON (tel que renvoyé par `node.toJson()`)

Retourne 'Node' Le Node reconstruit.

JavaScript TypeScript C# Java PHP Python Lua Haxe

`init`

constructeur

def __init__(_internal: Any) -> None

Paramètre	Type	Description
`_internal`	`Any`

Retourne None

`line`

méthode

def line() -> int

Le numéro de ligne dans le code source où ce nœud apparaît (à partir de 1).

Retourne int

`column`

méthode

def column() -> int

Le numéro de colonne dans le code source où ce nœud apparaît (à partir de 1).

Retourne int

`offset`

méthode

def offset() -> int

La position absolue du caractère depuis le début du code source.

Retourne int

`length`

méthode

def length() -> int

La longueur de l'étendue de texte source que représente ce nœud.

Retourne int

`node_id_to_string`

méthode

def node_id_to_string() -> str

Renvoie l'identifiant de nœud lisible (par exemple '1.0.0.0').

Retourne str

`ChoiceOption`

classe

Une option de choix présentée à l'utilisateur.

`text`

propriété

text: str

Le texte de l'option de choix.

Retourne str

JavaScript TypeScript C# C++ Java PHP Python Haxe

`tags`

propriété

tags: List[TextTag]

Les tags éventuellement associés au texte du choix.

Retourne List[TextTag]

JavaScript TypeScript C# C++ Java PHP Python Haxe

`enabled`

propriété

enabled: bool

Indique si cette option de choix est actuellement activée.

Retourne bool

JavaScript TypeScript C# C++ Java PHP Python Haxe

`TextTag`

classe

Un tag intégré au contenu textuel, utilisé pour la mise en forme ou à d'autres fins.

`closing`

propriété

closing: bool

Indique s'il s'agit d'un tag fermant.

Retourne bool

JavaScript TypeScript C# C++ Java PHP Python Haxe

`value`

propriété

value: str

La valeur ou le nom du tag.

Retourne str

JavaScript TypeScript C# C++ Java PHP Python Haxe

`offset`

propriété

offset: int

La position dans le texte où ce tag apparaît.

Retourne int

JavaScript TypeScript C# C++ Java PHP Python Haxe

`DialogueHandler`

alias de type

DialogueHandler = Callable[['Interpreter', Optional[str], str, List[TextTag], Callable[[], None]], None]

Appelé quand un texte de dialogue doit être affiché. Args : interpreter : l'instance d'interpréteur. character : le personnage qui parle (None pour un texte de narration). text : le contenu textuel à afficher. tags : les tags éventuels présents dans le texte. advance : fonction à appeler une fois le texte affiché.

`ChoiceHandler`

alias de type

ChoiceHandler = Callable[['Interpreter', List[ChoiceOption], Callable[[int], None]], None]

Appelé quand le joueur doit faire un choix. Args : interpreter : l'instance d'interpréteur. options : les options de choix disponibles. select : fonction à appeler avec l'indice du choix sélectionné.

`FinishHandler`

alias de type

FinishHandler = Callable[['Interpreter'], None]

Appelé quand l'exécution du script se termine. Args : interpreter : l'instance d'interpréteur.

`ImportsFileHandler`

alias de type

ImportsFileHandler = Callable[[str, Callable[[str], None]], None]

Appelé pour charger un fichier importé. Args : path : le chemin du fichier à charger. callback : fonction à appeler avec le contenu du fichier chargé.

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

Voir aussi

Python →

Exécuter des scripts Loreline en Python 3.

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 Python

Vue d'ensemble

Loreline#

parse#

play#

resume#

extract_translations#

load_locale#

translation_format#

last_error#

print#

update#

Interpreter#

__init__#

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#

__init__#

Node#

type#

to_json#

from_json#

__init__#

line#

column#

offset#

length#

node_id_to_string#

ChoiceOption#

text#

tags#

enabled#

TextTag#

closing#

value#

offset#

DialogueHandler#

ChoiceHandler#

FinishHandler#

ImportsFileHandler#

`Loreline`

`parse`

`play`

`resume`

`extract_translations`

`load_locale`

`translation_format`

`last_error`

`print`

`update`

`Interpreter`

`init`

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

`init`

`Node`

`type`

`to_json`

`from_json`

`init`

`line`

`column`

`offset`

`length`

`node_id_to_string`

`ChoiceOption`

`text`

`tags`

`enabled`

`TextTag`

`closing`

`value`

`offset`

`DialogueHandler`

`ChoiceHandler`

`FinishHandler`

`ImportsFileHandler`