Référence de l'API Python

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

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

TypeMembres
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. Exemple d'utilisation :

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 contenant un script Loreline et la transforme en AST Script.

ParamètreTypeDescription
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 doit l'être aussi. optionnel: None
handle_file Optional[ImportsFileHandler] Handler optionnel qui lit les fichiers importés. S'il est asynchrone, parse() renvoie null : utilisez alors l'argument callback. optionnel: None
callback Optional[Callable[[Script], None]] S'il est fourni, il est appelé avec le script obtenu. Utile surtout quand les imports 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 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

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 l'exécution d'un script analysé.

ParamètreTypeDescription
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] Dictionnaire qui associe un nom à function(interpreter, args), pour rendre ces fonctions disponibles dans le script. optionnel: None
strict_access bool Si True, lire ou écrire une variable non définie lève une erreur. optionnel: False
translations Any Traductions renvoyées par 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ètreTypeDescription
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 (en général, celles renvoyées par interpreter.save())
beat_name Optional[str] Nom optionnel d'un beat où reprendre, à la place du point sauvegardé optionnel: None
functions Optional[dict] Dictionnaire qui associe un nom à function(interpreter, args), pour rendre ces fonctions disponibles dans le script. optionnel: None
strict_access bool Si True, lire ou écrire une variable non définie lève une erreur. optionnel: False
translations Any Traductions renvoyées par 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ètreTypeDescription
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 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

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ètreTypeDescription
locale str Le code de langue (par exemple "fr")
script Script Le script source analysé (analysé avec un chemin de fichier, sinon fournissez filePath)
file_path Optional[str] 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: None
handle_file Optional[ImportsFileHandler] Handler de fichiers utilisé pour lire les fichiers de traduction optionnel: None
callback Optional[Callable[[Any], None]] Appelé avec les traductions fusionnées. Requis si handleFile est asynchrone. optionnel: None

Retourne Any Les traductions fusionnées (renvoyées directement quand handle_file est synchrone).

Pour chaque fichier du script (le fichier racine et tout ce qu'il importe, directement ou non), cherche 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.

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 autre format de fichier de traduction.

ParamètreTypeDescription
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 reconnus : "po" (.po), "xliff" (.xliff, .xlf), "csv" (.csv, .tsv). Les noms inconnus sont acceptés sans erreur, pour rester compatible avec les versions futures.

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 à parse() ou load_locale() s'il a échoué, ou None s'il a réussi.

Retourne Optional[Any]

En mode asynchrone (avec callback), le callback reçoit None en cas d'échec et cette méthode dit ce qui s'est mal passé. En mode synchrone, l'appel lève une exception, et cette méthode renvoie la même erreur, consultable après le except.

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ètreTypeDescription
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ètreTypeDescription
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ètreTypeDescription
_internal Any L'interpréteur du runtime, enveloppé. Créez les interpréteurs avec Loreline.play() plutôt qu'en appelant ce constructeur.

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

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

Retourne None

JavaScript TypeScript C# Java PHP Python Lua Haxe

get_character

méthode

def get_character(name: str) -> Any

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

ParamètreTypeDescription
name str Le nom du personnage à récupérer

Retourne Any Les propriétés 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

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

ParamètreTypeDescription
character str Le nom du personnage
field str Le nom de la propriété à lire

Retourne Any La valeur de la propriété, ou None si la propriété n'existe pas.

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

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

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

Retourne None

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

get_state_field

méthode

def get_state_field(name: str) -> Any

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

Retourne Any La valeur de la propriété, ou None si la propriété n'existe pas.

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

set_state_field

méthode

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

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

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

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

ParamètreTypeDescription
name str Le nom de la propriété à lire

Retourne Any La valeur de la propriété, ou None si la propriété n'existe pas.

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

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

ParamètreTypeDescription
name str Le nom de la propriété à modifier
value Any La nouvelle valeur

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 script Loreline analysé, sous forme d'AST.

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ètreTypeDescription
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ètreTypeDescription
_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 Le type du nœud, sous forme de chaîne

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ètreTypeDescription
pretty bool optionnel: False

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

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

Reconstruit un Node depuis une chaîne JSON.

ParamètreTypeDescription
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ètreTypeDescription
_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 du passage du code 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 au joueur.

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 placé dans un texte, pour la mise en forme ou tout autre usage.

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 de ce tag dans le texte.

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 de l'option choisie.

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.

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