Référence de l'API PHP
L'API publique complète du runtime Loreline pour chaque langage supporté.
Vous débutez avec Loreline en PHP ? 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); $interpreter = Loreline::play($script, $onDialogue, $onChoice, $onFinish);
Signatures des handlers :
- dialogue :
function(Interpreter $interpreter, ?string $character, string $text, TextTag[] $tags, callable $advance): void - choix :
function(Interpreter $interpreter, ChoiceOption[] $options, callable $select): void - fin :
function(Interpreter $interpreter): void - handler de fichiers d'import :
function(string $path, callable $callback): void
parse
public static function parse(string $source, ?string $filePath = null, ?callable $handleFile = null, ?callable $callback = null): ?Script
Analyse une chaîne contenant un script Loreline et la transforme en AST Script.
| Paramètre | Type | Description |
|---|---|---|
source |
string |
Le contenu du script Loreline sous forme de chaîne (format .lor)
|
filePath |
?string |
Chemin optionnel du fichier analysé. S'il est fourni, handleFile doit l'être aussi.
optionnel: null
|
handleFile |
?callable |
Handler optionnel qui lit les fichiers importés. S'il est asynchrone, parse() renvoie null : utilisez alors l'argument callback.
optionnel: null
|
callback |
?callable |
S'il est fourni, il est appelé avec le script obtenu. Utile surtout quand les imports sont lus de façon asynchrone.
optionnel: null
|
Retourne
?Script
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().
$filePath active la résolution des imports et nécessite $handleFile. $callback reçoit le Script analysé, ce qui sert quand $handleFile répond de façon asynchrone. Renvoie le Script analysé, ou null en cas de chargement asynchrone. Lève une exception si le script contient des erreurs de syntaxe.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
play
public static function play(Script $script, callable $handleDialogue, callable $handleChoice, callable $handleFinish, ?string $beatName = null, ?array $options = null): Interpreter
Démarre l'exécution d'un script analysé.
| Paramètre | Type | Description |
|---|---|---|
script |
Script |
Le script analysé (résultat de parse())
|
handleDialogue |
callable |
Fonction appelée quand un texte de dialogue doit être affiché |
handleChoice |
callable |
Fonction appelée quand le joueur doit faire un choix |
handleFinish |
callable |
Fonction appelée quand l'exécution du script se termine |
beatName |
?string |
Nom optionnel d'un beat précis par lequel démarrer (par défaut, le premier beat)
optionnel: null
|
options |
?array |
Options supplémentaires
optionnel: null
|
Retourne
Interpreter
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.
$options accepte un tableau associatif avec ces clés :
- functions : tableau qui associe un nom à
function(Interpreter $interpreter, array $args): mixed - strictAccess : bool ; à true, accéder à une variable non définie lève une erreur
- translations : les traductions renvoyées par
extractTranslations()ouloadLocale()
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
resume
public static function resume(Script $script, callable $handleDialogue, callable $handleChoice, callable $handleFinish, string $saveData, ?string $beatName = null, ?array $options = null): Interpreter
Reprend un script depuis un état sauvegardé.
| Paramètre | Type | Description |
|---|---|---|
script |
Script |
Le script analysé (résultat de parse())
|
handleDialogue |
callable |
Fonction appelée quand un texte de dialogue doit être affiché |
handleChoice |
callable |
Fonction appelée quand le joueur doit faire un choix |
handleFinish |
callable |
Fonction appelée quand l'exécution du script se termine |
saveData |
string |
Les données de sauvegarde (en général, celles renvoyées par interpreter.save())
|
beatName |
?string |
Nom optionnel d'un beat où reprendre, à la place du point sauvegardé
optionnel: null
|
options |
?array |
Options de configuration de l'interpréteur (optionnelles)
optionnel: null
|
Retourne
Interpreter
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.
$saveData est la chaîne JSON renvoyée par Interpreter::save(). $options a la même forme que dans play().
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
extractTranslations
public static function extractTranslations(Script $script): mixed
Extrait les traductions d'un script de traduction analysé (un fichier .XX.lor).
| Paramètre | Type | Description |
|---|---|---|
script |
Script |
Le script de traduction analysé (résultat de parse() sur un fichier .XX.lor)
|
Retourne
mixed
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().
Renvoie les traductions, sous forme opaque, à donner à play() ou resume() dans l'option translations.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
loadLocale
public static function loadLocale(string $locale, Script $script, ?string $filePath = null, ?callable $handleFile = null, ?callable $callback = null): mixed
Charge les traductions d'une langue donnée, en parcourant tout l'arbre d'imports du script. Renvoie les traductions fusionnées si $handleFile est synchrone, et les transmet aussi à $callback.
| Paramètre | Type | Description |
|---|---|---|
locale |
string |
Le code de langue (par exemple "fr")
|
script |
Script |
Le script source analysé (analysé avec un chemin de fichier, sinon fournissez filePath)
|
filePath |
?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: null
|
handleFile |
?callable |
Handler de fichiers utilisé pour lire les fichiers de traduction
optionnel: null
|
callback |
?callable |
Appelé avec les traductions fusionnées. Requis si handleFile est asynchrone.
optionnel: null
|
Retourne
mixed
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
translationFormat
public static function translationFormat(string $name, bool $enabled): void
Active ou désactive la prise en charge d'un autre format de fichier de traduction. Noms reconnus : "po" (.po), "xliff" (.xliff, .xlf), "csv" (.csv, .tsv). Les noms inconnus sont acceptés sans erreur.
| 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
lastError
public static function lastError(): mixed
Renvoie l'erreur du dernier appel à parse() ou loadLocale() s'il a échoué, ou null s'il a réussi.
Retourne
mixed
En mode asynchrone (avec callback), le callback reçoit null 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 cette méthode renvoie la même erreur, consultable 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
public static function print(Script $script, string $indent = ' ', string $newline = "\n"): string
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 |
string |
La chaîne d'indentation à utiliser (par défaut, deux espaces)
optionnel: ' '
|
newline |
string |
La chaîne de saut de ligne à utiliser (par défaut "\n")
optionnel: "\n"
|
Retourne
string
Le code source régénéré, sous forme de chaîne
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
update
public static function update(float $delta): void
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
void
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 et de l'état.
Les valeurs d'état arrivent côté PHP sous forme de tableaux natifs, qui sont des copies : les getters renvoient une copie indépendante, et la modifier ne change pas l'état de l'histoire tant qu'elle n'est pas réécrite avec un setter. C'est la règle commune à toutes les cibles, appliquée à PHP (les tableaux PHP étant des types valeur, une vue directe sur l'état est impossible avec de vrais tableaux).
start
public function start(?string $beatName = null): void
Démarre ou redémarre l'exécution depuis un beat précis (ou depuis le premier beat si null).
| Paramètre | Type | Description |
|---|---|---|
beatName |
?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: null
|
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
public function save(): string
Sauvegarde l'état courant de l'interpréteur.
Retourne
string
Un objet SaveData contenant l'état sérialisé
Renvoie l'état complet sérialisé en chaîne JSON, prêt à être stocké dans une session, un fichier ou une base de données, et accepté en retour par Loreline::resume() ou Interpreter::restore(). Le format est identique sur toutes les cibles Loreline : une sauvegarde faite ici peut être reprise par une autre intégration.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
restore
public function restore(string $saveData): void
Restaure l'interpréteur dans un état précédemment sauvegardé (une chaîne JSON renvoyée par save()).
| Paramètre | Type | Description |
|---|---|---|
saveData |
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
resume
public function resume(): void
Reprend l'exécution une fois l'état restauré.
Retourne
void
JavaScript TypeScript C# Java PHP Python Lua Haxe
getCharacter
public function getCharacter(string $name): mixed
Renvoie les propriétés d'un personnage par son nom, sous forme de copie en tableau PHP natif, ou null s'il est introuvable.
| Paramètre | Type | Description |
|---|---|---|
name |
string |
Le nom du personnage à récupérer |
Retourne
mixed
Les propriétés du personnage, ou null si le personnage n'existe pas
JavaScript TypeScript C# Java PHP Python Lua Haxe
getCharacterField
public function getCharacterField(string $character, string $field): mixed
Renvoie une propriété précise d'un personnage, sous forme de copie en valeur PHP native.
| Paramètre | Type | Description |
|---|---|---|
character |
string |
Le nom du personnage |
field |
string |
Le nom de la propriété à lire |
Retourne
mixed
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
setCharacterField
public function setCharacterField(string $character, string $field, mixed $value): void
Modifie une propriété précise d'un personnage. Les tableaux sont copiés en profondeur dans l'état de l'histoire.
| Paramètre | Type | Description |
|---|---|---|
character |
string |
Le nom du personnage |
field |
string |
Le nom de la propriété à modifier |
value |
mixed |
La nouvelle valeur |
Retourne
void
getStateField
public function getStateField(string $name): mixed
Renvoie une propriété de l'état par son nom, en la cherchant de la portée courante vers l'extérieur, sous forme de copie en valeur PHP native.
| Paramètre | Type | Description |
|---|---|---|
name |
string |
Le nom de la propriété à lire |
Retourne
mixed
La valeur de la propriété, ou null si la propriété est introuvable
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
setStateField
public function setStateField(string $name, mixed $value): void
Modifie une propriété de l'état par son nom, en la cherchant de la portée courante vers l'extérieur. Les tableaux sont copiés en profondeur dans l'état de l'histoire.
| Paramètre | Type | Description |
|---|---|---|
name |
string |
Le nom de la propriété à modifier |
value |
mixed |
La nouvelle valeur |
Retourne
void
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
getTopLevelStateField
public function getTopLevelStateField(string $name): mixed
Renvoie directement une propriété de l'état de premier niveau, sous forme de copie en valeur PHP native.
| Paramètre | Type | Description |
|---|---|---|
name |
string |
Le nom de la propriété à lire |
Retourne
mixed
La valeur de la propriété, ou null si la propriété est introuvable
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
setTopLevelStateField
public function setTopLevelStateField(string $name, mixed $value): void
Modifie directement une propriété de l'état de premier niveau. Les tableaux sont copiés en profondeur dans l'état de l'histoire.
| Paramètre | Type | Description |
|---|---|---|
name |
string |
Le nom de la propriété à modifier |
value |
mixed |
La nouvelle valeur |
Retourne
void
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
currentNode
public function currentNode(): ?Node
Renvoie le nœud en cours d'exécution, ou null.
Retourne
?Node
Le nœud courant, ou null 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.
fromJson
public static function fromJson(string $json): Script
Reconstruit un Script depuis une chaîne JSON (telle que renvoyée par toJson()).
| Paramètre | Type | Description |
|---|---|---|
json |
string |
L'objet JSON (tel que renvoyé par script.toJson())
|
Retourne
Script
Le Script reconstruit
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
Node
Classe de base des nœuds de l'AST Loreline.
Permet de lire le type, la position et l'identifiant unique du nœud, et de l'exporter en JSON.
type
public function type(): string
Le type de ce nœud (par exemple "Script", "Beat", "Text").
Retourne
string
Le type du nœud, sous forme de chaîne
JavaScript TypeScript C# C++ Java PHP Python Lua Haxe
toJson
public function toJson(bool $pretty = false): string
Exporte ce nœud en chaîne 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
fromJson
public static function fromJson(string $json): Node
Reconstruit un Node depuis une chaîne JSON (telle que renvoyée par toJson()).
| Paramètre | Type | Description |
|---|---|---|
json |
string |
L'objet JSON (tel que renvoyé par node.toJson())
|
Retourne
Node
Le Node reconstruit
JavaScript TypeScript C# Java PHP Python Lua Haxe
__construct
public function __construct(protected mixed $internal)
| Paramètre | Type | Description |
|---|---|---|
internal |
mixed |
line
public function line(): int
Le numéro de ligne dans le code source où ce nœud apparaît (à partir de 1).
Retourne
int
column
public function column(): int
Le numéro de colonne dans le code source où ce nœud apparaît (à partir de 1).
Retourne
int
offset
public function offset(): int
La position absolue du caractère depuis le début du code source.
Retourne
int
length
public function length(): int
La longueur du passage du code source que représente ce nœud.
Retourne
int
nodeIdToString
public function nodeIdToString(): string
L'identifiant du nœud sous une forme lisible (par exemple "1.0.0.0").
Retourne
string
ChoiceOption
Une option de choix présentée au joueur.
text
public readonly string $text
Le texte de l'option de choix.
Retourne
string
JavaScript TypeScript C# C++ Java PHP Python Haxe
tags
public readonly array $tags
Les tags éventuellement associés au texte du choix.
Retourne
array
JavaScript TypeScript C# C++ Java PHP Python Haxe
enabled
public readonly bool $enabled
Indique si cette option de choix est actuellement activée.
Retourne
bool
JavaScript TypeScript C# C++ Java PHP Python Haxe
__construct
public function __construct(public readonly string $text, public readonly array $tags, public readonly bool $enabled)
| Paramètre | Type | Description |
|---|---|---|
text |
string |
Le texte de l'option de choix. |
tags |
array |
Les tags éventuellement associés au texte du choix. |
enabled |
bool |
Indique si cette option de choix est actuellement activée. |
TextTag
Un tag placé dans un texte, pour la mise en forme ou tout autre usage.
closing
public readonly bool $closing
Indique s'il s'agit d'un tag fermant.
Retourne
bool
JavaScript TypeScript C# C++ Java PHP Python Haxe
value
public readonly string $value
La valeur ou le nom du tag.
Retourne
string
JavaScript TypeScript C# C++ Java PHP Python Haxe
offset
public readonly int $offset
La position de ce tag dans le texte.
Retourne
int
JavaScript TypeScript C# C++ Java PHP Python Haxe
__construct
public function __construct(public readonly string $value, public readonly int $offset, public readonly bool $closing)
| Paramètre | Type | Description |
|---|---|---|
value |
string |
La valeur ou le nom du tag. |
offset |
int |
La position de ce tag dans le texte. |
closing |
bool |
Indique s'il s'agit d'un tag fermant. |
Générée depuis Loreline v0.10.0.