Référence de l'API PHP

L'API publique complète du runtime Loreline.

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

Type	Membres
`Loreline`	`parse` `play` `resume` `extractTranslations` `loadLocale` `translationFormat` `lastError` `print` `update`
`Interpreter`	`start` `save` `restore` `resume` `getCharacter` `getCharacterField` `setCharacterField` `getStateField` `setStateField` `getTopLevelStateField` `setTopLevelStateField` `currentNode`
`Script`	`fromJson`
`Node`	`type` `toJson` `fromJson` `__construct` `line` `column` `offset` `length` `nodeIdToString`
`ChoiceOption`	`text` `tags` `enabled` `__construct`
`TextTag`	`closing` `value` `offset` `__construct`

`Loreline`

classe

API publique principale du runtime de fiction interactive Loreline.

Toutes les méthodes sont statiques. Usage typique :

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

méthode

public static function parse(string $source, ?string $filePath = null, ?callable $handleFile = null, ?callable $callback = null): ?Script

Analyse une chaîne de script Loreline et en fait un 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` est requis également. optionnel: `null`
`handleFile`	`?callable`	Handler de fichiers optionnel pour lire les imports. Si ce handler est asynchrone, `parse()` renverra null et l'argument `callback` devra être utilisé optionnel: `null`
`callback`	`?callable`	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: `null`

Retourne ?Script Le script analysé, sous forme d'instance AST Script (s'il a été chargé de façon synchrone)

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().

$filePath active la résolution des imports et requiert $handleFile. $callback reçoit le Script analysé, utile quand $handleFile se résout 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`

méthode

public static function play(Script $script, callable $handleDialogue, callable $handleChoice, callable $handleFinish, ?string $beatName = null, ?array $options = null): Interpreter

Démarre la lecture 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 : table associant un nom à function(Interpreter $interpreter, array $args): mixed
strictAccess : bool, si true, accéder à une variable non définie lève une erreur
translations : une table de traductions issue de extractTranslations() ou loadLocale()

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

`resume`

méthode

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 (typiquement issues de `interpreter.save()`)
`beatName`	`?string`	Nom de beat optionnel pour choisir où reprendre optionnel: `null`
`options`	`?array`	Options optionnelles pour configurer le comportement de l'interpréteur 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`

méthode

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 Une table de traductions à passer comme InterpreterOptions.translations

À 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().

Renvoie une table de traductions opaque à passer comme option translations à play() ou resume().

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

`loadLocale`

méthode

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 la table de traductions fusionnée (de façon synchrone quand $handleFile est synchrone), également transmise via $callback.

Paramètre	Type	Description
`locale`	`string`	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)
`filePath`	`?string`	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: `null`
`handleFile`	`?callable`	Handler de fichiers utilisé pour lire les fichiers de traduction optionnel: `null`
`callback`	`?callable`	Appelé avec la table de traductions fusionnée. Requis si `handleFile` est asynchrone. optionnel: `null`

Retourne mixed La table de traductions fusionnée (de façon synchrone quand handleFile est synchrone)

Pour chaque fichier concerné par le script (racine + imports transitifs), le fichier de traduction correspondant est recherché en insérant .<locale> avant l'extension (par exemple characters.lor -> characters.fr.lor). Les fichiers de traduction absents sont ignorés silencieusement. La table renvoyée peut être passée comme InterpreterOptions.translations à play() ou resume().

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

`translationFormat`

méthode

public static function translationFormat(string $name, bool $enabled): void

Active ou désactive la prise en charge d'un format de fichier de traduction alternatif. Noms connus : "po" (.po), "xliff" (.xliff, .xlf), "csv" (.csv, .tsv). Les noms inconnus sont acceptés silencieusement.

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 silencieusement (compatibilité avec de futurs formats).

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

`lastError`

méthode

public static function lastError(): mixed

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

Retourne mixed

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

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 produit, sous forme de chaîne

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

`update`

méthode

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.

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 et de l'état.

Les valeurs d'état franchissent la frontière sous forme de tableaux PHP natifs, avec une sémantique de copie instantanée : les accesseurs renvoient une copie indépendante, et modifier cette copie ne change pas l'état de l'histoire tant qu'elle n'est pas réécrite par un setter. C'est la projection PHP du contrat commun à toutes les cibles (les tableaux PHP étant des types valeur, une vue vivante est impossible avec de vrais tableaux).

`start`

méthode

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 aucun beat n'est trouvé dans le script

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

`save`

méthode

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`

méthode

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`

méthode

public function resume(): void

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

Retourne void

JavaScript TypeScript C# Java PHP Python Lua Haxe

`getCharacter`

méthode

public function getCharacter(string $name): mixed

Récupère les champs d'un personnage par son nom, sous forme de copie instantanée 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 champs du personnage, ou null si le personnage n'existe pas

JavaScript TypeScript C# Java PHP Python Lua Haxe

`getCharacterField`

méthode

public function getCharacterField(string $character, string $field): mixed

Récupère un champ précis d'un personnage, sous forme de copie instantanée en valeur PHP native.

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

Retourne mixed La valeur du champ, ou null si le personnage ou le champ n'existe pas

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

`setCharacterField`

méthode

public function setCharacterField(string $character, string $field, mixed $value): void

Écrit un champ précis 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 du champ à écrire
`value`	`mixed`	La valeur à écrire

Retourne void

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

`getStateField`

méthode

public function getStateField(string $name): mixed

Lit un champ d'état par son nom, en résolvant depuis la portée courante vers l'extérieur, sous forme de copie instantanée en valeur PHP native.

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

Retourne mixed La valeur du champ, ou null si elle est introuvable

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

`setStateField`

méthode

public function setStateField(string $name, mixed $value): void

Écrit un champ d'état par son nom, en résolvant depuis 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 du champ à écrire
`value`	`mixed`	La valeur à écrire

Retourne void

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

`getTopLevelStateField`

méthode

public function getTopLevelStateField(string $name): mixed

Lit directement un champ de l'état de premier niveau, sous forme de copie instantanée en valeur PHP native.

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

Retourne mixed La valeur du champ, ou null si elle est introuvable

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

`setTopLevelStateField`

méthode

public function setTopLevelStateField(string $name, mixed $value): void

Écrit directement un champ sur 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 du champ à écrire
`value`	`mixed`	La valeur à écrire

Retourne void

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

`currentNode`

méthode

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`

classe

Un AST de script Loreline analysé.

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

`fromJson`

méthode

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

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

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

`type`

méthode

public function type(): string

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

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

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

`toJson`

méthode

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`

méthode

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`

constructeur

public function __construct(protected mixed $internal)

Paramètre	Type	Description
`internal`	`mixed`

`line`

méthode

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`

méthode

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`

méthode

public function offset(): int

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

Retourne int

`length`

méthode

public function length(): int

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

Retourne int

`nodeIdToString`

méthode

public function nodeIdToString(): string

L'identifiant de nœud lisible (par exemple "1.0.0.0").

Retourne string

`ChoiceOption`

classe

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

`text`

propriété

public readonly string $text

Le texte de l'option de choix.

Retourne string

JavaScript TypeScript C# C++ Java PHP Python Haxe

`tags`

propriété

public readonly array $tags

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

Retourne array

JavaScript TypeScript C# C++ Java PHP Python Haxe

`enabled`

propriété

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`

constructeur

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`

classe

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

`closing`

propriété

public readonly bool $closing

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

Retourne bool

JavaScript TypeScript C# C++ Java PHP Python Haxe

`value`

propriété

public readonly string $value

La valeur ou le nom du tag.

Retourne string

JavaScript TypeScript C# C++ Java PHP Python Haxe

`offset`

propriété

public readonly int $offset

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

Retourne int

JavaScript TypeScript C# C++ Java PHP Python Haxe

`__construct`

constructeur

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 dans le texte où ce tag apparaît.
`closing`	`bool`	Indique s'il s'agit d'un tag fermant.

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

Voir aussi

PHP →

Exécuter des scripts Loreline en PHP, jusqu'à une page web complète.

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 PHP

Vue d'ensemble

Loreline#

parse#

play#

resume#

extractTranslations#

loadLocale#

translationFormat#

lastError#

print#

update#

Interpreter#

start#

save#

restore#

resume#

getCharacter#

getCharacterField#

setCharacterField#

getStateField#

setStateField#

getTopLevelStateField#

setTopLevelStateField#

currentNode#

Script#

fromJson#

Node#

type#

toJson#

fromJson#

__construct#

line#

column#

offset#

length#

nodeIdToString#

ChoiceOption#

text#

tags#

enabled#

__construct#

TextTag#

closing#

value#

offset#

__construct#

`Loreline`

`parse`

`play`

`resume`

`extractTranslations`

`loadLocale`

`translationFormat`

`lastError`

`print`

`update`

`Interpreter`

`start`

`save`

`restore`

`resume`

`getCharacter`

`getCharacterField`

`setCharacterField`

`getStateField`

`setStateField`

`getTopLevelStateField`

`setTopLevelStateField`

`currentNode`

`Script`

`fromJson`

`Node`

`type`

`toJson`

`fromJson`

`__construct`

`line`

`column`

`offset`

`length`

`nodeIdToString`

`ChoiceOption`

`text`

`tags`

`enabled`

`__construct`

`TextTag`

`closing`

`value`

`offset`

`__construct`