Référence de l'API C++

L'API publique complète du runtime Loreline.

Vous débutez avec Loreline en C++ ? Commencez par le guide d'intégration. Cette page est la référence exhaustive.

Vue d'ensemble

Type	Membres
`Loreline`	`Loreline_parse` `Loreline_play` `Loreline_resume` `Loreline_extractTranslations` `Loreline_loadLocale` `Loreline_translationFormat` `Loreline_lastError` `Loreline_printScript` `Loreline_update`
`Loreline_Interpreter`	`Loreline_start` `Loreline_save` `Loreline_restore` `Loreline_getCharacterField` `Loreline_setCharacterField` `Loreline_getStateField` `Loreline_setStateField` `Loreline_getTopLevelStateField` `Loreline_setTopLevelStateField` `Loreline_currentNode`
`Loreline_Script`	`Loreline_scriptFromJson`
`Loreline_Node`	`type` `Loreline_scriptToJson` `line` `column` `offset` `length`
`Loreline_InterpreterOptions`	`Loreline_optionsAddFunction` `Loreline_optionsSetStrictAccess` `Loreline_optionsSetTranslations`
`Loreline_ChoiceOption`	`text` `tags` `enabled` `tagCount`
`Loreline_TextTag`	`closing` `value` `offset`
`Loreline_DialogueHandler`
`Loreline_ChoiceHandler`
`Loreline_FinishHandler`
`Loreline_FileHandler`
`Loreline_CustomFunction`
`Loreline_Translations`
`Loreline_String`	`Loreline_String` `~Loreline_String` `operator =` `c_str` `length` `isNull` `operator bool`
`Loreline_AsyncResolve`
`Loreline_FileRequest`
`Loreline_advance`
`Loreline_select`
`Loreline_Advance`	`interpreter` `operator()`
`Loreline_Select`	`interpreter` `operator()`
`Loreline_Array`	`Loreline_Array` `~Loreline_Array` `operator =` `create` `length` `get` `set` `push` `isNull` `operator bool`
`Loreline_Object`	`Loreline_Object` `~Loreline_Object` `operator =` `create` `count` `keyAt` `get` `set` `exists` `remove` `isNull` `operator bool`
`Loreline_Value`	`type` `intValue` `floatValue` `boolValue`
`Loreline_AsyncCustomFunction`
`Loreline_Retainer`
`Loreline_UserDataRetain`
`Loreline_UserDataRelease`
`Loreline_init`
`Loreline_dispose`
`Loreline_gc`
`Loreline_createThread`
`Loreline_provideFile`
`Loreline_ParseCompletionCallback`
`Loreline_parseAsync`
`Loreline_releaseTranslations`
`Loreline_LoadLocaleCallback`
`Loreline_loadLocaleAsync`
`Loreline_createOptions`
`Loreline_releaseOptions`
`Loreline_optionsAddAsyncFunction`
`Loreline_resolveAsync`
`Loreline_cancelAsync`
`Loreline_releaseScript`
`Loreline_releaseInterpreter`

`Loreline`

L'API publique principale du runtime Loreline. Donne accès simplement aux fonctionnalités de base pour analyser et exécuter des scripts Loreline.

Les points d'entrée sont des fonctions libres et non des méthodes statiques. Appelez Loreline_init() une fois avant toute autre, et Loreline_update() depuis votre boucle principale pour que les timers et les callbacks en attente s'exécutent.

`Loreline_parse`

fonction

Loreline_Script* Loreline_parse(Loreline_String input, Loreline_String filePath, Loreline_FileHandler fileHandler, void* fileHandlerData)

Analyse synchrone : bloque jusqu'à la fin de l'analyse et de tous les imports. Renvoie NULL en cas d'erreur d'analyse.

Paramètre	Type	Description
`input`	`Loreline_String`	Le contenu du script Loreline sous forme de chaîne (format `.lor`)
`filePath`	`Loreline_String`	Chemin optionnel du fichier analysé. S'il est fourni, `handleFile` est requis également.
`fileHandler`	`Loreline_FileHandler`	Handler de fichiers optionnel pour lire les imports. Si ce handler est asynchrone, `parse()` renverra null et l'argument `callback` devra être utilisé
`fileHandlerData`	`void*`	Pointeur opaque redonné à `fileHandler` à chaque appel. Sert à retrouver votre propre état depuis le handler.

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

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

`Loreline_play`

fonction

Loreline_Interpreter* Loreline_play(Loreline_Script* script, Loreline_DialogueHandler onDialogue, Loreline_ChoiceHandler onChoice, Loreline_FinishHandler onFinish, Loreline_String beatName = Loreline_String(), Loreline_InterpreterOptions* options = NULL, void* userData = NULL, Loreline_UserDataRetain retain = NULL, Loreline_UserDataRelease release = NULL)

Lecture. Tous les paramètres finaux sont optionnels.

Paramètre	Type	Description
`script`	`Loreline_Script*`	Le script analysé (résultat de `parse()`)
`onDialogue`	`Loreline_DialogueHandler`	Fonction appelée quand un texte de dialogue doit être affiché
`onChoice`	`Loreline_ChoiceHandler`	Fonction appelée quand le joueur doit faire un choix
`onFinish`	`Loreline_FinishHandler`	Fonction appelée quand l'exécution du script se termine
`beatName`	`Loreline_String`	Nom optionnel d'un beat précis par lequel démarrer (par défaut, le premier beat) optionnel: `Loreline_String()`
`options`	`Loreline_InterpreterOptions*`	Options supplémentaires optionnel: `NULL`
`userData`	`void*`	optionnel: `NULL`
`retain`	`Loreline_UserDataRetain`	optionnel: `NULL`
`release`	`Loreline_UserDataRelease`	optionnel: `NULL`

Retourne Loreline_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.

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

`Loreline_resume`

fonction

Loreline_Interpreter* Loreline_resume(Loreline_Script* script, Loreline_DialogueHandler onDialogue, Loreline_ChoiceHandler onChoice, Loreline_FinishHandler onFinish, Loreline_String saveData, Loreline_String beatName = Loreline_String(), Loreline_InterpreterOptions* options = NULL, void* userData = NULL, Loreline_UserDataRetain retain = NULL, Loreline_UserDataRelease release = NULL)

Reprend un script Loreline précédemment sauvegardé depuis son état enregistré.

Paramètre	Type	Description
`script`	`Loreline_Script*`	Le script analysé (résultat de `parse()`)
`onDialogue`	`Loreline_DialogueHandler`	Fonction appelée quand un texte de dialogue doit être affiché
`onChoice`	`Loreline_ChoiceHandler`	Fonction appelée quand le joueur doit faire un choix
`onFinish`	`Loreline_FinishHandler`	Fonction appelée quand l'exécution du script se termine
`saveData`	`Loreline_String`	Les données de sauvegarde (typiquement issues de `interpreter.save()`)
`beatName`	`Loreline_String`	Nom de beat optionnel pour choisir où reprendre optionnel: `Loreline_String()`
`options`	`Loreline_InterpreterOptions*`	Options optionnelles pour configurer le comportement de l'interpréteur optionnel: `NULL`
`userData`	`void*`	optionnel: `NULL`
`retain`	`Loreline_UserDataRetain`	optionnel: `NULL`
`release`	`Loreline_UserDataRelease`	optionnel: `NULL`

Retourne Loreline_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.

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

`Loreline_extractTranslations`

fonction

Loreline_Translations* Loreline_extractTranslations(Loreline_Script* script)

Traductions : extraire depuis un script pour une lecture localisée

Paramètre	Type	Description
`script`	`Loreline_Script*`	Le script de traduction analysé (résultat de `parse()` sur un fichier `.XX.lor`)

Retourne Loreline_Translations* 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().

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

`Loreline_loadLocale`

fonction

Loreline_Translations* Loreline_loadLocale(Loreline_String locale, Loreline_Script* script, Loreline_String filePath, Loreline_FileHandler fileHandler, void* fileHandlerData)

Traductions : charge tous les fichiers ..lor depuis l'arbre d'imports du script. 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. Passez le résultat à Loreline_optionsSetTranslations.

Paramètre	Type	Description
`locale`	`Loreline_String`	Le code de langue (par exemple `"fr"`)
`script`	`Loreline_Script*`	Le script source analysé (il doit avoir été analysé avec un chemin de fichier, ou `filePath` doit être fourni)
`filePath`	`Loreline_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.
`fileHandler`	`Loreline_FileHandler`	Handler de fichiers utilisé pour lire les fichiers de traduction
`fileHandlerData`	`void*`	Pointeur opaque redonné à `fileHandler` à chaque appel.

Retourne Loreline_Translations* 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().

filePath peut être NULL : il vaut alors le chemin depuis lequel script a été analysé. Peut aussi être un chemin de dossier, pour chercher les fichiers de traduction ailleurs.

Synchrone : bloque jusqu'à ce que tous les fichiers de traduction soient chargés.

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

`Loreline_translationFormat`

fonction

void Loreline_translationFormat(Loreline_String name, bool enabled)

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

Paramètre	Type	Description
`name`	`Loreline_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, Loreline_loadLocale n'essaie que les fichiers .<locale>.lor. Appelez cette fonction 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é ascendante).

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

`Loreline_lastError`

fonction

Loreline_String Loreline_lastError(void)

Renvoie le message d'erreur du dernier appel échoué à Loreline_parse() ou Loreline_loadLocale(), ou une chaîne vide si ce dernier appel a réussi.

Retourne Loreline_String

Utilisé quand une variante à callback a été fournie : le callback se déclenche avec un script ou des traductions nuls pour signaler l'échec, et cette fonction indique ce qui n'a pas fonctionné. Sans callback, les erreurs remontent généralement sous forme d'exceptions sur les cibles qui le permettent. Cette fonction reflète malgré tout la même valeur, qui peut donc être lue après récupération.

Pas thread-safe : à lire immédiatement après le retour de l'appel.

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

`Loreline_printScript`

fonction

Loreline_String Loreline_printScript(Loreline_Script* script)

Régénère le code source Loreline à partir d'un script analysé.

Paramètre	Type	Description
`script`	`Loreline_Script*`	Le script analysé (résultat de `parse()`)

Retourne Loreline_String Le code source produit, sous forme de chaîne

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

`Loreline_update`

fonction

void Loreline_update(double delta)

Mise à jour : à appeler depuis la boucle principale de l'hôte. Vide les callbacks en attente et exécute le ramasse-miettes périodique.

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

Retourne void

C# C++ Java PHP Python Lua Haxe

`Loreline_Interpreter`

handle

typedef struct Loreline_Interpreter Loreline_Interpreter

Exécute un script analysé : détient l'état de l'histoire, décide de la suite, et rend la main à votre code à chaque ligne de dialogue et à chaque choix.

Il n'y a pas de classe Interpreter en C++. Un interpréteur est un handle opaque Loreline_Interpreter* renvoyé par Loreline_play() ou Loreline_resume(), et chaque opération ci-dessous est une fonction libre qui prend ce handle en premier argument. Libérez-le avec Loreline_releaseInterpreter() une fois l'exécution terminée.

`Loreline_start`

fonction

void Loreline_start(Loreline_Interpreter* interp, Loreline_String beatName)

Démarre l'exécution du script depuis le début ou depuis un beat précis.

Paramètre	Type	Description
`interp` handle	`Loreline_Interpreter*`
`beatName`	`Loreline_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.

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

`Loreline_save`

fonction

Loreline_String Loreline_save(Loreline_Interpreter* interp)

Sauvegarde l'état courant de l'interpréteur. Cela comprend toutes les variables d'état, l'état des personnages et la pile d'exécution, ce qui permet de reprendre l'exécution plus tard exactement au même point.

Paramètre	Type	Description
`interp` handle	`Loreline_Interpreter*`

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

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

`Loreline_restore`

fonction

void Loreline_restore(Loreline_Interpreter* interp, Loreline_String saveData)

Restaure l'état de l'interpréteur depuis un objet SaveData. Cela permet de reprendre l'exécution depuis un état précédemment sauvegardé.

Paramètre	Type	Description
`interp` handle	`Loreline_Interpreter*`
`saveData`	`Loreline_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

`Loreline_getCharacterField`

fonction

Loreline_Value Loreline_getCharacterField(Loreline_Interpreter* interp, Loreline_String character, Loreline_String field)

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

Paramètre	Type	Description
`interp` handle	`Loreline_Interpreter*`
`character`	`Loreline_String`	Le nom du personnage
`field`	`Loreline_String`	Le nom du champ à lire

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

`Loreline_setCharacterField`

fonction

void Loreline_setCharacterField(Loreline_Interpreter* interp, Loreline_String character, Loreline_String field, Loreline_Value value)

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

Paramètre	Type	Description
`interp` handle	`Loreline_Interpreter*`
`character`	`Loreline_String`	Le nom du personnage
`field`	`Loreline_String`	Le nom du champ à écrire
`value`	`Loreline_Value`	La valeur à écrire

Retourne void

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

`Loreline_getStateField`

fonction

Loreline_Value Loreline_getStateField(Loreline_Interpreter* interp, Loreline_String field)

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

Paramètre	Type	Description
`interp` handle	`Loreline_Interpreter*`
`field`	`Loreline_String`	Le nom du champ à lire

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

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

`Loreline_setStateField`

fonction

void Loreline_setStateField(Loreline_Interpreter* interp, Loreline_String field, Loreline_Value value)

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

Paramètre	Type	Description
`interp` handle	`Loreline_Interpreter*`
`field`	`Loreline_String`	Le nom du champ à écrire
`value`	`Loreline_Value`	La valeur à écrire

Retourne void

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

`Loreline_getTopLevelStateField`

fonction

Loreline_Value Loreline_getTopLevelStateField(Loreline_Interpreter* interp, Loreline_String field)

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

Paramètre	Type	Description
`interp` handle	`Loreline_Interpreter*`
`field`	`Loreline_String`	Le nom du champ à lire

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

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

`Loreline_setTopLevelStateField`

fonction

void Loreline_setTopLevelStateField(Loreline_Interpreter* interp, Loreline_String field, Loreline_Value value)

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

Paramètre	Type	Description
`interp` handle	`Loreline_Interpreter*`
`field`	`Loreline_String`	Le nom du champ à écrire
`value`	`Loreline_Value`	La valeur à écrire

Retourne void

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

`Loreline_currentNode`

fonction

Loreline_Node Loreline_currentNode(Loreline_Interpreter* interp)

Nœud courant : renvoie des informations sur le nœud en cours d'exécution. Renvoie un Loreline_Node dont le type est null si aucun nœud n'est courant.

Paramètre	Type	Description
`interp` handle	`Loreline_Interpreter*`

Retourne Loreline_Node Le nœud courant, ou null si aucun nœud n'est en cours d'exécution

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

`Loreline_Script`

handle

typedef struct Loreline_Script Loreline_Script

Représente le nœud racine de l'AST d'un script Loreline.

Un script est un handle opaque Loreline_Script*. L'hôte en est propriétaire et doit le libérer avec Loreline_releaseScript(). Avec l'interpréteur, c'est le seul handle à libérer : les chaînes et les valeurs sont comptées par référence.

`Loreline_scriptFromJson`

fonction

Loreline_Script* Loreline_scriptFromJson(Loreline_String json)

Reconstruit un Script depuis sa représentation JSON.

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

Retourne Loreline_Script* Le Script reconstruit

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

`Loreline_Node`

struct

Classe de base de tous les nœuds de l'AST. Contient les informations de position et la conversion JSON de base.

`type`

champ

Loreline_String type

Renvoie le type de ce nœud.

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

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

`Loreline_scriptToJson`

fonction

Loreline_String Loreline_scriptToJson(Loreline_Script* script, bool pretty)

Convertit le nœud en représentation JSON.

Paramètre	Type	Description
`script`	`Loreline_Script*`
`pretty`	`bool`

Retourne Loreline_String Objet contenant le type et la position du nœud

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

`line`

champ

int line

Retourne int

`column`

champ

int column

Retourne int

`offset`

champ

int offset

Retourne int

`length`

champ

int length

Retourne int

`Loreline_InterpreterOptions`

handle

typedef struct Loreline_InterpreterOptions Loreline_InterpreterOptions

Options de configuration du comportement de l'interpréteur Loreline

`Loreline_optionsAddFunction`

fonction

void Loreline_optionsAddFunction(Loreline_InterpreterOptions* options, Loreline_String name, Loreline_CustomFunction fn, void* userData)

Table optionnelle de fonctions supplémentaires à rendre disponibles au script

Paramètre	Type	Description
`options`	`Loreline_InterpreterOptions*`
`name`	`Loreline_String`
`fn`	`Loreline_CustomFunction`
`userData`	`void*`

Retourne void

JavaScript TypeScript C# GDScript C++ Java Haxe

`Loreline_optionsSetStrictAccess`

fonction

void Loreline_optionsSetStrictAccess(Loreline_InterpreterOptions* options, bool strict)

Indique si l'accès est strict ou non. Si true, lire ou écrire une variable non définie lève une erreur.

Paramètre	Type	Description
`options`	`Loreline_InterpreterOptions*`
`strict`	`bool`

Retourne void

JavaScript TypeScript C# GDScript C++ Java Haxe

`Loreline_optionsSetTranslations`

fonction

void Loreline_optionsSetTranslations(Loreline_InterpreterOptions* options, Loreline_Translations* translations)

Table de traductions optionnelle pour la localisation. Construite depuis un fichier de traduction analysé avec Loreline.extractTranslations().

Paramètre	Type	Description
`options`	`Loreline_InterpreterOptions*`
`translations`	`Loreline_Translations*`

Retourne void

JavaScript TypeScript C# GDScript C++ Java Haxe

`Loreline_ChoiceOption`

struct

Représente une option de choix présentée à l'utilisateur.

`text`

champ

Loreline_String text

Le texte de l'option de choix.

Retourne Loreline_String

JavaScript TypeScript C# C++ Java PHP Python Haxe

`tags`

champ

const Loreline_TextTag* tags

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

Retourne const Loreline_TextTag*

JavaScript TypeScript C# C++ Java PHP Python Haxe

`enabled`

champ

bool enabled

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

Retourne bool

JavaScript TypeScript C# C++ Java PHP Python Haxe

`tagCount`

champ

int tagCount

Retourne int

`Loreline_TextTag`

struct

Représente un tag dans un contenu textuel, utilisable pour la mise en forme ou à d'autres fins.

`closing`

champ

bool closing

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

Retourne bool

JavaScript TypeScript C# C++ Java PHP Python Haxe

`value`

champ

Loreline_String value

La valeur ou le nom du tag.

Retourne Loreline_String

JavaScript TypeScript C# C++ Java PHP Python Haxe

`offset`

champ

int offset

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

Retourne int

JavaScript TypeScript C# C++ Java PHP Python Haxe

`Loreline_DialogueHandler`

callback

typedef void (*Loreline_DialogueHandler)(Loreline_Interpreter* interpreter, Loreline_String character, Loreline_String text, const Loreline_TextTag* tags, int tagCount, Loreline_Advance advance, void* userData)

Type de handler pour la sortie de texte avec callback. Appelé quand le script doit afficher du texte à l'utilisateur.

`Loreline_ChoiceHandler`

callback

typedef void (*Loreline_ChoiceHandler)(Loreline_Interpreter* interpreter, const Loreline_ChoiceOption* options, int optionCount, Loreline_Select select, void* userData)

Type de handler pour la présentation des choix avec callback. Appelé quand le script doit présenter des choix à l'utilisateur.

`Loreline_FinishHandler`

callback

typedef void (*Loreline_FinishHandler)(Loreline_Interpreter* interpreter, void* userData)

Type de handler appelé quand l'exécution se termine.

`Loreline_FileHandler`

callback

typedef void (*Loreline_FileHandler)(Loreline_String path, Loreline_FileRequest* request, void* userData)

Le handler de fichiers accepte l'asynchrone : l'hôte reçoit un jeton de requête opaque et DOIT appeler Loreline_provideFile(request, content) exactement une fois, soit de façon synchrone dans le handler, soit plus tard depuis n'importe quel thread. Passez un contenu NULL pour signaler « fichier introuvable ».

`Loreline_CustomFunction`

callback

typedef Loreline_Value (*Loreline_CustomFunction)(Loreline_Interpreter* interp, const Loreline_Value* args, int argCount, void* userData)

Fonction personnalisée synchrone : appelée sur le thread hôte, doit retourner immédiatement.

`Loreline_Translations`

handle

typedef struct Loreline_Translations Loreline_Translations

Type opaque pour une table de traductions. Obtenu via Loreline.extractTranslations() et passé à InterpreterOptions.translations.

`Loreline_String`

classe

Une chaîne à comptage de références, copiée par valeur et libérée automatiquement.

Toute chaîne qui franchit la frontière est une copie profonde instantanée : elle ne contient aucun pointeur vers le runtime, on peut donc la conserver et la passer entre threads sans risque.

`Loreline_String`

constructeur

Loreline_String()

Loreline_String(const char* s)

Loreline_String(const char* s, size_t len)

Loreline_String(const Loreline_String& o)

Loreline_String(Loreline_String&& o)

`~Loreline_String`

méthode

~Loreline_String()

`operator =`

opérateur

Loreline_String& operator=(const Loreline_String& o)

Loreline_String& operator=(Loreline_String&& o)

Paramètre	Type	Description
`o`	`const Loreline_String&`

Retourne Loreline_String&

`c_str`

méthode

const char* c_str() const

Retourne const char*

`length`

méthode

size_t length() const

Retourne size_t

`isNull`

méthode

bool isNull() const

Retourne bool

`operator bool`

opérateur

operator bool() const

Retourne bool

`Loreline_AsyncResolve`

handle

typedef struct Loreline_AsyncResolve Loreline_AsyncResolve

Un handle opaque servant à terminer une fonction personnalisée asynchrone.

Passez-le à Loreline_resolveAsync() avec le résultat, ou à Loreline_cancelAsync() pour abandonner l'appel sans reprendre l'interpréteur.

`Loreline_FileRequest`

handle

typedef struct Loreline_FileRequest Loreline_FileRequest

Jeton opaque de requête de chargement de fichier. Passé au Loreline_FileHandler de l'hôte ; l'hôte appelle Loreline_provideFile(request, content), de façon synchrone ou asynchrone, pour fournir le contenu du fichier (ou NULL pour « introuvable »). Le jeton est consommé par Loreline_provideFile, qui doit être appelé exactement une fois par requête.

`Loreline_advance`

fonction

void Loreline_advance(Loreline_Interpreter* interp)

Rend la main à un dialogue ou à un choix en attente sur un interpréteur. Peut être appelé à tout moment tant que l'interpréteur est vivant, depuis un événement d'interface ou après un délai quelconque. L'appeler alors que rien n'est en attente n'a aucun effet.

`Loreline_select`

fonction

void Loreline_select(Loreline_Interpreter* interp, int index)

Répond à un choix en attente sur un interpréteur, avec l'indice de l'option sélectionnée.

L'équivalent de Loreline_advance() pour les choix. L'appeler alors qu'aucun choix n'est en attente n'a aucun effet.

`Loreline_Advance`

struct

Les continuations advance et select remises aux handlers de dialogue et de choix. Chacune est liée à l'interpréteur qui l'a produite, si bien qu'un hôte peut la conserver et répondre quand il le souhaite, et que plusieurs interpréteurs peuvent tourner côte à côte sans que leurs continuations se mélangent. Copiable et peu coûteuse : ce n'est que le handle.

void onDialogue(..., Loreline_Advance advance, void* userData) { advance(); // maintenant // ou conservez advance et appelez-le depuis un handler de bouton }

En conserver une ne maintient PAS son interpréteur en vie : elle porte le handle, pas la propriété. Ne l'appelez pas après Loreline_releaseInterpreter. Les bindings qui l'enveloppent dans un callable à comptage de références (l'addon Godot, par exemple) lui donnent bien la propriété : conserver le callable suffit alors à maintenir l'exécution en vie, et l'abandonner sans l'appeler laisse l'exécution être collectée.

`interpreter`

champ

Loreline_Interpreter* interpreter

Retourne Loreline_Interpreter*

`operator()`

opérateur

void operator()() const

Retourne void

`Loreline_Select`

struct

La continuation remise au handler de choix, à appeler avec l'indice de l'option choisie.

Liée à l'interpréteur qui l'a produite, copiable et peu coûteuse : elle porte le handle, pas la propriété. Voir Loreline_Advance pour les règles de durée de vie complètes.

`interpreter`

champ

Loreline_Interpreter* interpreter

Retourne Loreline_Interpreter*

`operator()`

opérateur

void operator()(int index) const

Retourne void

`Loreline_Array`

classe

Un tableau de Loreline_Value à comptage de références, copié par valeur et libéré automatiquement.

Une copie profonde instantanée, pas une vue : le modifier n'affecte jamais l'état de l'interpréteur. Repassez-le par un setter pour appliquer les changements.

`Loreline_Array`

constructeur

Loreline_Array()

Loreline_Array(const Loreline_Array& o)

Loreline_Array(Loreline_Array&& o)

`~Loreline_Array`

méthode

~Loreline_Array()

`operator =`

opérateur

Loreline_Array& operator=(const Loreline_Array& o)

Loreline_Array& operator=(Loreline_Array&& o)

Paramètre	Type	Description
`o`	`const Loreline_Array&`

Retourne Loreline_Array&

`create`

méthode

static Loreline_Array create()

Crée un nouveau tableau vide (côté hôte, pour construire des valeurs à écrire)

Retourne Loreline_Array

`length`

méthode

int length() const

Retourne int

`get`

méthode

Loreline_Value get(int index) const

Paramètre	Type	Description
`index`	`int`

Retourne Loreline_Value

`set`

méthode

void set(int index, Loreline_Value value)

Paramètre	Type	Description
`index`	`int`
`value`	`Loreline_Value`

Retourne void

`push`

méthode

void push(Loreline_Value value)

Paramètre	Type	Description
`value`	`Loreline_Value`

Retourne void

`isNull`

méthode

bool isNull() const

Retourne bool

`operator bool`

opérateur

operator bool() const

Retourne bool

`Loreline_Object`

classe

Un objet à clés textuelles et à comptage de références, copié par valeur et libéré automatiquement.

Les entrées conservent leur ordre d'insertion et la recherche par clé est un parcours linéaire, ce qui convient au nombre de champs d'un état d'histoire. Mêmes règles de copie profonde instantanée que Loreline_Array.

`Loreline_Object`

constructeur

Loreline_Object()

Loreline_Object(const Loreline_Object& o)

Loreline_Object(Loreline_Object&& o)

`~Loreline_Object`

méthode

~Loreline_Object()

`operator =`

opérateur

Loreline_Object& operator=(const Loreline_Object& o)

Loreline_Object& operator=(Loreline_Object&& o)

Paramètre	Type	Description
`o`	`const Loreline_Object&`

Retourne Loreline_Object&

`create`

méthode

static Loreline_Object create()

Crée un nouvel objet vide (côté hôte, pour construire des valeurs à écrire)

Retourne Loreline_Object

`count`

méthode

int count() const

Retourne int

`keyAt`

méthode

Loreline_String keyAt(int index) const

Paramètre	Type	Description
`index`	`int`

Retourne Loreline_String

`get`

méthode

Loreline_Value get(const char* key) const

Paramètre	Type	Description
`key`	`const char*`

Retourne Loreline_Value

`set`

méthode

void set(const char* key, Loreline_Value value)

Paramètre	Type	Description
`key`	`const char*`
`value`	`Loreline_Value`

Retourne void

`exists`

méthode

bool exists(const char* key) const

Paramètre	Type	Description
`key`	`const char*`

Retourne bool

`remove`

méthode

void remove(const char* key)

Paramètre	Type	Description
`key`	`const char*`

Retourne void

`isNull`

méthode

bool isNull() const

Retourne bool

`operator bool`

opérateur

operator bool() const

Retourne bool

`Loreline_Value`

struct

Une union étiquetée qui contient n'importe quelle valeur Loreline : entier, flottant, booléen, chaîne, tableau ou objet.

Lisez d'abord type, puis le membre correspondant. C'est ce que les accesseurs de champs de personnage et d'état échangent dans les deux sens.

`type`

champ

Loreline_ValueType type

Retourne Loreline_ValueType

`intValue`

champ

int intValue

Retourne int

`floatValue`

champ

double floatValue

Retourne double

`boolValue`

champ

bool boolValue

Retourne bool

`Loreline_AsyncCustomFunction`

callback

typedef void (*Loreline_AsyncCustomFunction)(Loreline_Interpreter* interp, const Loreline_Value* args, int argCount, Loreline_AsyncResolve* resolve, void* userData)

Fonction personnalisée asynchrone : appelée sur le thread hôte, fournit son résultat plus tard via un handle resolve. Ne fonctionne qu'en contexte d'instruction (pas dans les expressions ni l'interpolation).

`Loreline_Retainer`

handle

typedef struct Loreline_Retainer Loreline_Retainer

Retenue opaque fournie par l'hôte. L'hôte décide de ce qu'elle désigne ; l'enveloppe Loreline ne fait que la transmettre entre les appels de retenue et de libération.

`Loreline_UserDataRetain`

callback

typedef Loreline_Retainer *(*Loreline_UserDataRetain)(void *userData)

Appelé chaque fois que l'enveloppe doit maintenir en vie le userData de l'interpréteur : une fois quand l'hôte rend la main à Loreline (play/resume/start/advance/select/resolveAsync), ce qui couvre l'exécution jusqu'à la prochaine remise de callback, et une fois par callback mis en file, ce qui couvre l'appel du handler lui-même. Les implémentations hôtes incrémentent en général un compteur de références sur l'objet qui porte userData et renvoient un handle indiquant comment le libérer. Renvoyez NULL si aucune retenue n'est nécessaire ; la libération sera alors appelée avec NULL elle aussi. Avec ces points d'ancrage, un interpréteur reste vivant exactement tant que l'hôte en garde une référence ou qu'un callback lui est dû, et il est libéré naturellement dès que ni l'un ni l'autre n'est vrai.

`Loreline_UserDataRelease`

callback

typedef void (*Loreline_UserDataRelease)(Loreline_Retainer *retainer)

Appelé à la fermeture de la fenêtre de retenue correspondante (après l'exécution d'un handler, après qu'une exception s'en est échappée, ou quand une exécution est remise ou interrompue). L'hôte décrémente ce que la retenue avait incrémenté. Sans danger avec NULL.

`Loreline_init`

fonction

void Loreline_init(void)

Démarre le runtime Loreline. À appeler une fois avant toute autre fonction.

L'appeler plusieurs fois est sans danger.

`Loreline_dispose`

fonction

void Loreline_dispose(void)

Pendant d'arrêt de Loreline_init().

Dans cette version, cette fonction ne fait rien : le runtime et son thread restent en vie, le thread dormant sur une variable de condition. Appelez-la quand même à l'arrêt, pour que votre code continue de fonctionner si cela change.

`Loreline_gc`

fonction

void Loreline_gc(void)

Force immédiatement un cycle de ramasse-miettes dans le runtime Loreline.

Optionnel : Loreline_update() en exécute déjà un toutes les 15 secondes de delta cumulé. Appelez celle-ci lors d'une pause de votre choix, un écran de chargement ou un changement de scène, pour récupérer la mémoire au moment que vous décidez.

`Loreline_createThread`

fonction

void Loreline_createThread(void)

Threads : crée un thread interne dédié à Loreline. Quand il est actif, les appels entrants sont routés vers ce thread interne ; les callbacks sont distribués sur le thread appelant via Loreline_update().

`Loreline_provideFile`

fonction

void Loreline_provideFile(Loreline_FileRequest* request, Loreline_String content)

Handler de fichiers : fournit un contenu (ou NULL pour « introuvable ») à un jeton de requête. Doit être appelé exactement une fois par jeton. Appelable depuis n'importe quel thread.

`Loreline_ParseCompletionCallback`

callback

typedef void (*Loreline_ParseCompletionCallback)(Loreline_Script* script, void* userData)

Analyse asynchrone : retourne immédiatement. La complétion se déclenche (sur le tick de mise à jour de l'hôte si Loreline_update est appelée, sinon en ligne) avec le Loreline_Script* résultant (ou NULL en cas d'erreur d'analyse). L'hôte possède le script et doit appeler Loreline_releaseScript quand il a fini.

`Loreline_parseAsync`

fonction

void Loreline_parseAsync(Loreline_String input, Loreline_String filePath, Loreline_FileHandler fileHandler, void* fileHandlerData, Loreline_ParseCompletionCallback completionHandler, void* completionHandlerData)

`Loreline_releaseTranslations`

fonction

void Loreline_releaseTranslations(Loreline_Translations* translations)

Libère un handle de traductions renvoyé par Loreline_extractTranslations() ou Loreline_loadLocale().

`Loreline_LoadLocaleCallback`

callback

typedef void (*Loreline_LoadLocaleCallback)(Loreline_Translations* translations, void* userData)

Traductions : variante asynchrone de Loreline_loadLocale. Retourne immédiatement ; la complétion se déclenche avec le handle résultant (ou NULL en cas d'erreur).

`Loreline_loadLocaleAsync`

fonction

void Loreline_loadLocaleAsync(Loreline_String locale, Loreline_Script* script, Loreline_String filePath, Loreline_FileHandler fileHandler, void* fileHandlerData, Loreline_LoadLocaleCallback completionHandler, void* completionHandlerData)

`Loreline_createOptions`

fonction

Loreline_InterpreterOptions* Loreline_createOptions(void)

Options de l'interpréteur : configurer les fonctions personnalisées, l'accès strict, les traductions

`Loreline_releaseOptions`

fonction

void Loreline_releaseOptions(Loreline_InterpreterOptions* options)

Libère un handle d'options créé par Loreline_createOptions().

`Loreline_optionsAddAsyncFunction`

fonction

void Loreline_optionsAddAsyncFunction(Loreline_InterpreterOptions* options, Loreline_String name, Loreline_AsyncCustomFunction fn, void* userData)

Enregistre une fonction personnalisée qui se termine plus tard, via un handle resolve.

La fonction est appelée sur le thread hôte et retourne immédiatement ; l'interpréteur reste en pause jusqu'à l'appel de Loreline_resolveAsync(). Utilisable uniquement en contexte d'instruction, pas dans les expressions ni l'interpolation.

`Loreline_resolveAsync`

fonction

void Loreline_resolveAsync(Loreline_AsyncResolve* resolve, Loreline_Value result)

Résout un appel de fonction personnalisée asynchrone. Appelable depuis n'importe quel thread.

`Loreline_cancelAsync`

fonction

void Loreline_cancelAsync(Loreline_AsyncResolve* resolve)

Annule un appel de fonction personnalisée asynchrone sans reprendre l'interpréteur. Libère le handle resolve et sa racine de ramasse-miettes interne sur la closure de fin, mais n'appelle pas la closure. À utiliser quand l'hôte abandonne le handle resolve sans le résoudre (par exemple si le Callable GDScript a été libéré avant que resolve.call() ne se déclenche). L'état Async côté Haxe est nettoyé naturellement quand l'interpréteur lui-même est libéré.

`Loreline_releaseScript`

fonction

void Loreline_releaseScript(Loreline_Script* script)

Libère un handle de script renvoyé par Loreline_parse() ou Loreline_scriptFromJson().

`Loreline_releaseInterpreter`

fonction

void Loreline_releaseInterpreter(Loreline_Interpreter* interp)

Libère un handle d'interpréteur renvoyé par Loreline_play() ou Loreline_resume().

N'appelez pas les continuations advance ou select d'un interpréteur après l'avoir libéré.

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

Voir aussi

C++ →

Intégrer Loreline dans un projet C++.

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 C++

Vue d'ensemble

Loreline#

Loreline_parse#

Loreline_play#

Loreline_resume#

Loreline_extractTranslations#

Loreline_loadLocale#

Loreline_translationFormat#

Loreline_lastError#

Loreline_printScript#

Loreline_update#

Loreline_Interpreter#

Loreline_start#

Loreline_save#

Loreline_restore#

Loreline_getCharacterField#

Loreline_setCharacterField#

Loreline_getStateField#

Loreline_setStateField#

Loreline_getTopLevelStateField#

Loreline_setTopLevelStateField#

Loreline_currentNode#

Loreline_Script#

Loreline_scriptFromJson#

Loreline_Node#

type#

Loreline_scriptToJson#

line#

column#

offset#

length#

Loreline_InterpreterOptions#

Loreline_optionsAddFunction#

Loreline_optionsSetStrictAccess#

Loreline_optionsSetTranslations#

Loreline_ChoiceOption#

text#

tags#

enabled#

tagCount#

Loreline_TextTag#

closing#

value#

offset#

Loreline_DialogueHandler#

Loreline_ChoiceHandler#

Loreline_FinishHandler#

Loreline_FileHandler#

Loreline_CustomFunction#

Loreline_Translations#

Loreline_String#

Loreline_String#

~Loreline_String#

operator =#

c_str#

length#

isNull#

operator bool#

Loreline_AsyncResolve#

Loreline_FileRequest#

Loreline_advance#

Loreline_select#

Loreline_Advance#

interpreter#

operator()#

Loreline_Select#

interpreter#

operator()#

Loreline_Array#

Loreline_Array#

~Loreline_Array#

operator =#

create#

length#

get#

set#

push#

isNull#

operator bool#

`Loreline`

`Loreline_parse`

`Loreline_play`

`Loreline_resume`

`Loreline_extractTranslations`

`Loreline_loadLocale`

`Loreline_translationFormat`

`Loreline_lastError`

`Loreline_printScript`

`Loreline_update`

`Loreline_Interpreter`

`Loreline_start`

`Loreline_save`

`Loreline_restore`

`Loreline_getCharacterField`

`Loreline_setCharacterField`

`Loreline_getStateField`

`Loreline_setStateField`

`Loreline_getTopLevelStateField`

`Loreline_setTopLevelStateField`

`Loreline_currentNode`

`Loreline_Script`

`Loreline_scriptFromJson`

`Loreline_Node`

`type`

`Loreline_scriptToJson`

`line`

`column`

`offset`

`length`

`Loreline_InterpreterOptions`

`Loreline_optionsAddFunction`

`Loreline_optionsSetStrictAccess`

`Loreline_optionsSetTranslations`

`Loreline_ChoiceOption`

`text`

`tags`

`enabled`

`tagCount`

`Loreline_TextTag`

`closing`

`value`

`offset`

`Loreline_DialogueHandler`

`Loreline_ChoiceHandler`

`Loreline_FinishHandler`

`Loreline_FileHandler`

`Loreline_CustomFunction`

`Loreline_Translations`

`Loreline_String`

`Loreline_String`

`~Loreline_String`

`operator =`

`c_str`

`length`

`isNull`

`operator bool`

`Loreline_AsyncResolve`

`Loreline_FileRequest`

`Loreline_advance`

`Loreline_select`

`Loreline_Advance`

`interpreter`

`operator()`

`Loreline_Select`

`interpreter`

`operator()`

`Loreline_Array`

`Loreline_Array`

`~Loreline_Array`

`operator =`

`create`

`length`

`get`

`set`

`push`

`isNull`

`operator bool`

`Loreline_Object`

`Loreline_Object`