Référence de l'API C++
L'API publique complète du runtime Loreline pour chaque langage supporté.
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
Loreline
L'API publique principale du runtime Loreline. Elle donne un accès simple aux fonctions de base pour analyser et exécuter des scripts Loreline.
Les points d'entrée sont des fonctions libres, pas des méthodes statiques. Appelez
Loreline_init()une fois avant toutes les autres, puisLoreline_update()dans votre boucle principale pour que les timers et les callbacks en attente s'exécutent.
Loreline_parse
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 doit l'être aussi.
|
fileHandler |
Loreline_FileHandler |
Handler optionnel qui lit les fichiers importés. S'il est asynchrone, parse() renvoie null : utilisez alors l'argument callback.
|
fileHandlerData |
void* |
Pointeur opaque transmis à fileHandler à chaque appel. Il vous permet de retrouver votre propre état depuis le handler.
|
Retourne
Loreline_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().
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
Loreline_play
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)
Exécution de l'histoire. Les derniers paramètres sont tous 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
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 à partir d'une sauvegarde.
| 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 (en général, celles renvoyées par interpreter.save())
|
beatName |
Loreline_String |
Nom optionnel d'un beat où reprendre, à la place du point sauvegardé
optionnel: Loreline_String()
|
options |
Loreline_InterpreterOptions* |
Options de configuration de l'interpréteur (optionnelles)
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
Loreline_Translations* Loreline_extractTranslations(Loreline_Script* script)
Traductions : extraction depuis un script, pour une exécution 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*
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().
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
Loreline_loadLocale
Loreline_Translations* Loreline_loadLocale(Loreline_String locale, Loreline_Script* script, Loreline_String filePath, Loreline_FileHandler fileHandler, void* fileHandlerData)
Traductions : charge les fichiers ..<locale> avant l'extension (par exemple characters.lor -> characters.fr.lor). Les fichiers de traduction absents sont ignorés, sans erreur. 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é (analysé avec un chemin de fichier, sinon fournissez filePath)
|
filePath |
Loreline_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.
|
fileHandler |
Loreline_FileHandler |
Handler de fichiers utilisé pour lire les fichiers de traduction |
fileHandlerData |
void* |
Pointeur opaque transmis à fileHandler à chaque appel.
|
Retourne
Loreline_Translations*
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().
filePath peut être NULL : on utilise alors le chemin d'où script a été analysé. Ce peut aussi être un 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
void Loreline_translationFormat(Loreline_String name, bool enabled)
Active ou désactive la prise en charge d'un autre format de fichier de traduction.
| 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 sans erreur, pour rester compatible avec les versions futures.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
Loreline_lastError
Loreline_String Loreline_lastError(void)
Renvoie le message d'erreur laissé par le dernier appel à Loreline_parse() ou Loreline_loadLocale() s'il a échoué, ou une chaîne vide s'il a réussi.
Retourne
Loreline_String
Utile avec les variantes à callback : le callback reçoit un script ou des traductions NULL en cas d'échec, et cette fonction dit ce qui s'est mal passé. Sans callback, les erreurs remontent en général sous forme d'exceptions sur les cibles qui en ont. La même erreur reste lisible ici, même après avoir intercepté l'exception.
Pas thread-safe : à lire immédiatement après le retour de l'appel.
JavaScript TypeScript C# C++ Java PHP Python Lua Haxe
Loreline_printScript
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 régénéré, sous forme de chaîne
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
Loreline_update
void Loreline_update(double delta)
Mise à jour : à appeler depuis la boucle principale de l'hôte. Exécute les callbacks en attente et lance périodiquement le ramasse-miettes.
| Paramètre | Type | Description |
|---|---|---|
delta |
double |
Temps écoulé depuis la frame précédente, en secondes |
Retourne
void
Loreline_Interpreter
typedef struct Loreline_Interpreter Loreline_InterpreterExécute un script analysé : garde l'état de l'histoire, décide de la suite et rend la main à votre code à chaque réplique et à chaque choix.
Il n'y a pas de classe
Interpreteren C++. Un interpréteur est un handle opaqueLoreline_Interpreter*renvoyé parLoreline_play()ouLoreline_resume(), et chaque opération ci-dessous est une fonction libre qui prend ce handle en premier argument. Libérez-le avecLoreline_releaseInterpreter()une fois l'exécution terminée.
Loreline_start
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 le script ne contient aucun beat
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
Loreline_save
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
void Loreline_restore(Loreline_Interpreter* interp, Loreline_String saveData)
Restaure l'état de l'interpréteur à partir d'un objet SaveData, pour reprendre l'exécution là où elle avait été sauvegardée.
| 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
Loreline_Value Loreline_getCharacterField(Loreline_Interpreter* interp, Loreline_String character, Loreline_String field)
Renvoie une propriété précise d'un personnage.
| Paramètre | Type | Description |
|---|---|---|
interp handle |
Loreline_Interpreter* |
|
character |
Loreline_String |
Le nom du personnage |
field |
Loreline_String |
Le nom de la propriété à lire |
Retourne
Loreline_Value
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
Loreline_setCharacterField
void Loreline_setCharacterField(Loreline_Interpreter* interp, Loreline_String character, Loreline_String field, Loreline_Value value)
Modifie une propriété d'un personnage.
| Paramètre | Type | Description |
|---|---|---|
interp handle |
Loreline_Interpreter* |
|
character |
Loreline_String |
Le nom du personnage |
field |
Loreline_String |
Le nom de la propriété à modifier |
value |
Loreline_Value |
La nouvelle valeur |
Retourne
void
Loreline_getStateField
Loreline_Value Loreline_getStateField(Loreline_Interpreter* interp, Loreline_String field)
Renvoie une propriété de l'état par son nom, en cherchant d'abord dans la portée courante, puis dans les portées englobantes.
| Paramètre | Type | Description |
|---|---|---|
interp handle |
Loreline_Interpreter* |
|
field |
Loreline_String |
Le nom de la propriété à lire |
Retourne
Loreline_Value
La valeur de la propriété, ou null si la propriété est introuvable
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
Loreline_setStateField
void Loreline_setStateField(Loreline_Interpreter* interp, Loreline_String field, Loreline_Value value)
Modifie une propriété de l'état par son nom, en cherchant d'abord dans la portée courante, puis dans les portées englobantes.
| Paramètre | Type | Description |
|---|---|---|
interp handle |
Loreline_Interpreter* |
|
field |
Loreline_String |
Le nom de la propriété à modifier |
value |
Loreline_Value |
La nouvelle valeur |
Retourne
void
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
Loreline_getTopLevelStateField
Loreline_Value Loreline_getTopLevelStateField(Loreline_Interpreter* interp, Loreline_String field)
Renvoie directement une propriété de l'état de premier niveau.
| Paramètre | Type | Description |
|---|---|---|
interp handle |
Loreline_Interpreter* |
|
field |
Loreline_String |
Le nom de la propriété à lire |
Retourne
Loreline_Value
La valeur de la propriété, ou null si la propriété est introuvable
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
Loreline_setTopLevelStateField
void Loreline_setTopLevelStateField(Loreline_Interpreter* interp, Loreline_String field, Loreline_Value value)
Modifie directement une propriété de l'état de premier niveau.
| Paramètre | Type | Description |
|---|---|---|
interp handle |
Loreline_Interpreter* |
|
field |
Loreline_String |
Le nom de la propriété à modifier |
value |
Loreline_Value |
La nouvelle valeur |
Retourne
void
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
Loreline_currentNode
Loreline_Node Loreline_currentNode(Loreline_Interpreter* interp)
Nœud courant : renvoie des informations sur le nœud en cours d'exécution, ou un Loreline_Node dont le type est null si rien ne s'exécute.
| 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
typedef struct Loreline_Script Loreline_ScriptRepré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 avecLoreline_releaseScript(). Avec celui de l'interpréteur, c'est le seul handle à libérer : chaînes et valeurs utilisent un comptage de références.
Loreline_scriptFromJson
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
Classe de base de tous les nœuds de l'AST. Contient les informations de position et la conversion JSON de base.
type
Loreline_String type
Renvoie le type de ce nœud.
Retourne
Loreline_String
Le type du nœud, sous forme de chaîne
JavaScript TypeScript C# C++ Java PHP Python Lua Haxe
Loreline_scriptToJson
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
int line
Retourne
int
column
int column
Retourne
int
offset
int offset
Retourne
int
length
int length
Retourne
int
Loreline_InterpreterOptions
typedef struct Loreline_InterpreterOptions Loreline_InterpreterOptionsOptions de configuration du comportement de l'interpréteur Loreline
Loreline_optionsAddFunction
void Loreline_optionsAddFunction(Loreline_InterpreterOptions* options, Loreline_String name, Loreline_CustomFunction fn, void* userData)
Dictionnaire optionnel de fonctions supplémentaires que le script pourra appeler
| Paramètre | Type | Description |
|---|---|---|
options |
Loreline_InterpreterOptions* |
|
name |
Loreline_String |
|
fn |
Loreline_CustomFunction |
|
userData |
void* |
Retourne
void
Loreline_optionsSetStrictAccess
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
Loreline_optionsSetTranslations
void Loreline_optionsSetTranslations(Loreline_InterpreterOptions* options, Loreline_Translations* translations)
Traductions optionnelles pour la localisation. Construites depuis un fichier de traduction analysé avec Loreline.extractTranslations().
| Paramètre | Type | Description |
|---|---|---|
options |
Loreline_InterpreterOptions* |
|
translations |
Loreline_Translations* |
Retourne
void
Loreline_ChoiceOption
Représente une option de choix présentée au joueur.
text
Loreline_String text
Le texte de l'option de choix.
Retourne
Loreline_String
JavaScript TypeScript C# C++ Java PHP Python Haxe
tags
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
bool enabled
Indique si cette option de choix est actuellement activée.
Retourne
bool
JavaScript TypeScript C# C++ Java PHP Python Haxe
tagCount
int tagCount
Retourne
int
Loreline_TextTag
Représente un tag dans un contenu textuel, utilisable pour la mise en forme ou à d'autres fins.
closing
bool closing
Indique s'il s'agit d'un tag fermant.
Retourne
bool
JavaScript TypeScript C# C++ Java PHP Python Haxe
value
Loreline_String value
La valeur ou le nom du tag.
Retourne
Loreline_String
JavaScript TypeScript C# C++ Java PHP Python Haxe
offset
int offset
La position de ce tag dans le texte.
Retourne
int
JavaScript TypeScript C# C++ Java PHP Python Haxe
Loreline_DialogueHandler
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 l'affichage de texte, avec callback. Appelé quand le script doit afficher du texte au joueur.
Loreline_ChoiceHandler
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 au joueur.
Loreline_FinishHandler
typedef void (*Loreline_FinishHandler)(Loreline_Interpreter* interpreter, void* userData)Type de handler appelé quand l'exécution se termine.
Loreline_FileHandler
typedef void (*Loreline_FileHandler)(Loreline_String path, Loreline_FileRequest* request, void* userData)Le handler de fichiers peut répondre de façon asynchrone : l'hôte reçoit un jeton de requête opaque et DOIT appeler Loreline_provideFile(request, content) exactement une fois, soit directement dans le handler, soit plus tard depuis n'importe quel thread. Passez un contenu NULL pour signaler "fichier introuvable".
Loreline_CustomFunction
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
typedef struct Loreline_Translations Loreline_TranslationsType opaque qui contient les traductions. Obtenu via Loreline.extractTranslations() et passé à InterpreterOptions.translations.
Loreline_String
Une chaîne à comptage de références, copiée par valeur et libérée automatiquement.
Toute chaîne échangée avec le runtime en est une copie complète : elle ne pointe vers rien dans le runtime, et peut donc être conservée et passée d'un thread à l'autre sans risque.
Loreline_String
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
~Loreline_String()
operator =
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
const char* c_str() const
Retourne
const char*
length
size_t length() const
Retourne
size_t
isNull
bool isNull() const
Retourne
bool
operator bool
operator bool() const
Retourne
bool
Loreline_AsyncResolve
typedef struct Loreline_AsyncResolve Loreline_AsyncResolveUn 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
typedef struct Loreline_FileRequest Loreline_FileRequestJeton opaque d'une requête de chargement de fichier. Il est passé au Loreline_FileHandler de l'hôte, qui appelle Loreline_provideFile(request, content), tout de suite ou plus tard, pour fournir le contenu (ou NULL pour "introuvable"). Loreline_provideFile consomme le jeton et doit être appelé exactement une fois par requête.
Loreline_advance
void Loreline_advance(Loreline_Interpreter* interp)Rend la main à un interpréteur qui attend la fin d'une réplique ou d'un choix. Peut être appelé à tout moment tant que l'interpréteur existe, depuis un événement d'interface ou après un délai quelconque. Sans rien en attente, l'appel n'a aucun effet.
Loreline_select
void Loreline_select(Loreline_Interpreter* interp, int index)Répond au choix en attente d'un interpréteur avec l'indice de l'option choisie.
L'équivalent de Loreline_advance() pour les choix. L'appeler alors qu'aucun choix n'est en attente n'a aucun effet.
Loreline_Advance
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 à garder l'exécution en vie, et l'abandonner sans l'appeler permet au ramasse-miettes de la libérer.
interpreter
Loreline_Interpreter* interpreter
Retourne
Loreline_Interpreter*
operator()
void operator()() const
Retourne
void
Loreline_Select
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
Loreline_Interpreter* interpreter
Retourne
Loreline_Interpreter*
operator()
void operator()(int index) const
Retourne
void
Loreline_Array
Un tableau de Loreline_Value à comptage de références, copié par valeur et libéré automatiquement.
Une copie complète, pas une vue : modifier ce tableau ne change jamais l'état de l'interpréteur. Repassez-le à un setter pour appliquer les changements.
Loreline_Array
Loreline_Array()Loreline_Array(const Loreline_Array& o)Loreline_Array(Loreline_Array&& o)
~Loreline_Array
~Loreline_Array()
operator =
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
static Loreline_Array create()
Crée un nouveau tableau vide (côté hôte, pour construire des valeurs à écrire)
Retourne
Loreline_Array
length
int length() const
Retourne
int
get
Loreline_Value get(int index) const
| Paramètre | Type | Description |
|---|---|---|
index |
int |
Retourne
Loreline_Value
set
void set(int index, Loreline_Value value)
| Paramètre | Type | Description |
|---|---|---|
index |
int |
|
value |
Loreline_Value |
Retourne
void
push
void push(Loreline_Value value)
| Paramètre | Type | Description |
|---|---|---|
value |
Loreline_Value |
Retourne
void
isNull
bool isNull() const
Retourne
bool
operator bool
operator bool() const
Retourne
bool
Loreline_Object
Un dictionnaire à clés textuelles et à comptage de références, copié par valeur et libéré automatiquement.
Les entrées gardent leur ordre d'insertion, et une clé se cherche par parcours linéaire, ce qui suffit pour le nombre de propriétés d'un état d'histoire. Comme Loreline_Array, c'est une copie complète, pas une vue.
Loreline_Object
Loreline_Object()Loreline_Object(const Loreline_Object& o)Loreline_Object(Loreline_Object&& o)
~Loreline_Object
~Loreline_Object()
operator =
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
static Loreline_Object create()
Crée un nouveau dictionnaire vide (côté hôte, pour construire des valeurs à écrire)
Retourne
Loreline_Object
count
int count() const
Retourne
int
keyAt
Loreline_String keyAt(int index) const
| Paramètre | Type | Description |
|---|---|---|
index |
int |
Retourne
Loreline_String
get
Loreline_Value get(const char* key) const
| Paramètre | Type | Description |
|---|---|---|
key |
const char* |
Retourne
Loreline_Value
set
void set(const char* key, Loreline_Value value)
| Paramètre | Type | Description |
|---|---|---|
key |
const char* |
|
value |
Loreline_Value |
Retourne
void
exists
bool exists(const char* key) const
| Paramètre | Type | Description |
|---|---|---|
key |
const char* |
Retourne
bool
remove
void remove(const char* key)
| Paramètre | Type | Description |
|---|---|---|
key |
const char* |
Retourne
void
isNull
bool isNull() const
Retourne
bool
operator bool
operator bool() const
Retourne
bool
Loreline_Value
Une union étiquetée qui contient n'importe quelle valeur Loreline : entier, flottant, booléen, chaîne, tableau ou dictionnaire.
Lisez d'abord type, puis le membre correspondant. C'est le type que les accesseurs des propriétés de personnage et d'état reçoivent et renvoient.
type
Loreline_ValueType type
Retourne
Loreline_ValueType
intValue
int intValue
Retourne
int
floatValue
double floatValue
Retourne
double
boolValue
bool boolValue
Retourne
bool
Loreline_AsyncCustomFunction
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, elle fournit son résultat plus tard via un handle resolve. Utilisable seulement comme instruction, pas dans une expression ni une interpolation.
Loreline_Retainer
typedef struct Loreline_Retainer Loreline_RetainerJeton de rétention opaque fourni par l'hôte. L'hôte décide de ce qu'il désigne ; l'enveloppe Loreline se contente de le transmettre entre les appels à retain et à release.
Loreline_UserDataRetain
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'au prochain 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 rien n'a besoin d'être retenu ; release sera alors appelé avec NULL lui aussi. Avec ces deux fonctions fournies, un interpréteur reste en vie exactement tant que l'hôte en garde une référence ou qu'il lui doit encore un callback, et il est libéré dès que ce n'est plus le cas.
Loreline_UserDataRelease
typedef void (*Loreline_UserDataRelease)(Loreline_Retainer *retainer)Appelé à la fin de la période couverte par le retain correspondant (après l'exécution d'un handler, si une exception en sort, ou quand une exécution se termine ou est interrompue). L'hôte décrémente ce que retain avait incrémenté. Accepte NULL sans problème.
Loreline_init
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
void Loreline_dispose(void)Arrête le runtime Loreline : le pendant de Loreline_init().
Pour l'instant, elle ne fait rien : le runtime et son thread restent en vie, et le thread attend sur une variable de condition. Appelez-la quand même à l'arrêt, pour que votre code reste correct si cela change.
Loreline_gc
void Loreline_gc(void)Force immédiatement un cycle de ramasse-miettes dans le runtime Loreline.
Optionnel : Loreline_update() en lance déjà un toutes les 15 secondes de delta cumulé. Appelez cette fonction pendant une pause, comme un écran de chargement ou un changement de scène, pour libérer la mémoire au moment qui vous arrange.
Loreline_createThread
void Loreline_createThread(void)Threads : crée un thread interne dédié à Loreline. Quand il est actif, les appels entrants sont transmis à ce thread ; les callbacks, eux, s'exécutent sur le thread qui appelle Loreline_update().
Loreline_provideFile
void Loreline_provideFile(Loreline_FileRequest* request, Loreline_String content)Handler de fichiers : fournit le contenu demandé par un jeton de requête (ou NULL pour "introuvable"). À appeler exactement une fois par jeton, depuis n'importe quel thread.
Loreline_ParseCompletionCallback
typedef void (*Loreline_ParseCompletionCallback)(Loreline_Script* script, void* userData)Analyse asynchrone : rend la main tout de suite. Le callback de fin est appelé (au prochain Loreline_update si l'hôte en appelle, sinon directement) avec le Loreline_Script* obtenu, ou NULL en cas d'erreur d'analyse. L'hôte possède le script et doit appeler Loreline_releaseScript quand il n'en a plus besoin.
Loreline_parseAsync
void Loreline_parseAsync(Loreline_String input, Loreline_String filePath, Loreline_FileHandler fileHandler, void* fileHandlerData, Loreline_ParseCompletionCallback completionHandler, void* completionHandlerData)Loreline_releaseTranslations
void Loreline_releaseTranslations(Loreline_Translations* translations)Libère un handle de traductions renvoyé par Loreline_extractTranslations() ou Loreline_loadLocale().
Loreline_LoadLocaleCallback
typedef void (*Loreline_LoadLocaleCallback)(Loreline_Translations* translations, void* userData)Traductions : variante asynchrone de Loreline_loadLocale. Rend la main tout de suite ; le callback de fin reçoit le handle obtenu (ou NULL en cas d'erreur).
Loreline_loadLocaleAsync
void Loreline_loadLocaleAsync(Loreline_String locale, Loreline_Script* script, Loreline_String filePath, Loreline_FileHandler fileHandler, void* fileHandlerData, Loreline_LoadLocaleCallback completionHandler, void* completionHandlerData)Loreline_createOptions
Loreline_InterpreterOptions* Loreline_createOptions(void)Options de l'interpréteur : fonctions personnalisées, accès strict et traductions
Loreline_releaseOptions
void Loreline_releaseOptions(Loreline_InterpreterOptions* options)Libère un handle d'options créé par Loreline_createOptions().
Loreline_optionsAddAsyncFunction
void Loreline_optionsAddAsyncFunction(Loreline_InterpreterOptions* options, Loreline_String name, Loreline_AsyncCustomFunction fn, void* userData)Enregistre une fonction personnalisée asynchrone, terminée plus tard avec un handle resolve.
La fonction est appelée sur le thread hôte et rend la main aussitôt ; l'interpréteur reste en pause jusqu'à l'appel de Loreline_resolveAsync(). Utilisable seulement comme instruction, pas dans une expression ni une interpolation.
Loreline_resolveAsync
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
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 la racine GC interne qui retient la closure de fin, sans appeler cette 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é de lui-même quand l'interpréteur est libéré.
Loreline_releaseScript
void Loreline_releaseScript(Loreline_Script* script)Libère un handle de script renvoyé par Loreline_parse() ou Loreline_scriptFromJson().
Loreline_releaseInterpreter
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.