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
Loreline
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
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è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 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
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è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] |
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
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 (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
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 les traductions, à passer dans options.translations de play() ou de resume().
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
load_locale
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é (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
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è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 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
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
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
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.
Interpreter
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__
def __init__(_internal: Any) -> None
Crée un nouvel interpréteur de script Loreline.
| Paramètre | Type | Description |
|---|---|---|
_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
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 le script ne contient aucun beat
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
save
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
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
def resume() -> None
Reprend l'exécution une fois l'état restauré.
Retourne
None
JavaScript TypeScript C# Java PHP Python Lua Haxe
get_character
def get_character(name: str) -> Any
Renvoie les propriétés d'un personnage par son nom.
| Paramètre | Type | Description |
|---|---|---|
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
def get_character_field(character: str, field: str) -> Any
Renvoie une propriété précise d'un personnage.
| Paramètre | Type | Description |
|---|---|---|
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
def set_character_field(character: str, field: str, value: Any) -> None
Modifie une propriété précise d'un personnage.
| Paramètre | Type | Description |
|---|---|---|
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
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ètre | Type | Description |
|---|---|---|
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
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ètre | Type | Description |
|---|---|---|
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
def get_top_level_state_field(name: str) -> Any
Renvoie directement une propriété de l'état de premier niveau.
| Paramètre | Type | Description |
|---|---|---|
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
def set_top_level_state_field(name: str, value: Any) -> None
Modifie directement une propriété de l'état de premier niveau.
| Paramètre | Type | Description |
|---|---|---|
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
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
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
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__
def __init__(_internal: Any) -> None
| Paramètre | Type | Description |
|---|---|---|
_internal |
Any |
Retourne
None
Node
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
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
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 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
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__
def __init__(_internal: Any) -> None
| Paramètre | Type | Description |
|---|---|---|
_internal |
Any |
Retourne
None
line
def line() -> int
Le numéro de ligne dans le code source où ce nœud apparaît (à partir de 1).
Retourne
int
column
def column() -> int
Le numéro de colonne dans le code source où ce nœud apparaît (à partir de 1).
Retourne
int
offset
def offset() -> int
La position absolue du caractère depuis le début du code source.
Retourne
int
length
def length() -> int
La longueur du passage du code source que représente ce nœud.
Retourne
int
node_id_to_string
def node_id_to_string() -> str
Renvoie l'identifiant de nœud lisible (par exemple '1.0.0.0').
Retourne
str
ChoiceOption
Une option de choix présentée au joueur.
text
text: str
Le texte de l'option de choix.
Retourne
str
JavaScript TypeScript C# C++ Java PHP Python Haxe
tags
tags: List[TextTag]
Les tags éventuellement associés au texte du choix.
Retourne
List[TextTag]
JavaScript TypeScript C# C++ Java PHP Python Haxe
enabled
enabled: bool
Indique si cette option de choix est actuellement activée.
Retourne
bool
JavaScript TypeScript C# C++ Java PHP Python Haxe
TextTag
Un tag placé dans un texte, pour la mise en forme ou tout autre usage.
closing
closing: bool
Indique s'il s'agit d'un tag fermant.
Retourne
bool
JavaScript TypeScript C# C++ Java PHP Python Haxe
value
value: str
La valeur ou le nom du tag.
Retourne
str
JavaScript TypeScript C# C++ Java PHP Python Haxe
offset
offset: int
La position de ce tag dans le texte.
Retourne
int
JavaScript TypeScript C# C++ Java PHP Python Haxe
DialogueHandler
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
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
FinishHandler = Callable[['Interpreter'], None]Appelé quand l'exécution du script se termine. Args : interpreter : l'instance d'interpréteur.
ImportsFileHandler
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.