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

TypeMembres
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. 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, puis Loreline_update() dans 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ètreTypeDescription
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

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)

Exécution de l'histoire. Les derniers paramètres sont tous optionnels.

ParamètreTypeDescription
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 à partir d'une sauvegarde.

ParamètreTypeDescription
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

fonction

Loreline_Translations* Loreline_extractTranslations(Loreline_Script* script)

Traductions : extraction depuis un script, pour une exécution localisée

ParamètreTypeDescription
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

fonction

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

Traductions : charge les fichiers ..lor de chaque fichier de 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, sans erreur. Passez le résultat à Loreline_optionsSetTranslations.

ParamètreTypeDescription
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

fonction

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ètreTypeDescription
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

fonction

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

fonction

Loreline_String Loreline_printScript(Loreline_Script* script)

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

ParamètreTypeDescription
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

fonction

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ètreTypeDescription
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é : 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 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ètreTypeDescription
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

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ètreTypeDescription
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 à partir d'un objet SaveData, pour reprendre l'exécution là où elle avait été sauvegardée.

ParamètreTypeDescription
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)

Renvoie une propriété précise d'un personnage.

ParamètreTypeDescription
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

fonction

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

Modifie une propriété d'un personnage.

ParamètreTypeDescription
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

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

Loreline_getStateField

fonction

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ètreTypeDescription
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

fonction

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ètreTypeDescription
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

fonction

Loreline_Value Loreline_getTopLevelStateField(Loreline_Interpreter* interp, Loreline_String field)

Renvoie directement une propriété de l'état de premier niveau.

ParamètreTypeDescription
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

fonction

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

Modifie directement une propriété de l'état de premier niveau.

ParamètreTypeDescription
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

fonction

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ètreTypeDescription
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 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

fonction

Loreline_Script* Loreline_scriptFromJson(Loreline_String json)

Reconstruit un Script depuis sa représentation JSON.

ParamètreTypeDescription
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 Le type du nœud, sous forme de chaîne

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ètreTypeDescription
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)

Dictionnaire optionnel de fonctions supplémentaires que le script pourra appeler

ParamètreTypeDescription
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ètreTypeDescription
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)

Traductions optionnelles pour la localisation. Construites depuis un fichier de traduction analysé avec Loreline.extractTranslations().

ParamètreTypeDescription
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 au joueur.

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 de ce tag dans le texte.

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 l'affichage de texte, avec callback. Appelé quand le script doit afficher du texte au joueur.

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 au joueur.

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

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 qui contient les 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 é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

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ètreTypeDescription
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 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

fonction

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

fonction

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

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 à garder l'exécution en vie, et l'abandonner sans l'appeler permet au ramasse-miettes de la libérer.

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

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ètreTypeDescription
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ètreTypeDescription
index int

Retourne Loreline_Value

set

méthode

void set(int index, Loreline_Value value)
ParamètreTypeDescription
index int
value Loreline_Value

Retourne void

push

méthode

void push(Loreline_Value value)
ParamètreTypeDescription
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 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

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ètreTypeDescription
o const Loreline_Object&

Retourne Loreline_Object&

create

méthode

static Loreline_Object create()

Crée un nouveau dictionnaire 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ètreTypeDescription
index int

Retourne Loreline_String

get

méthode

Loreline_Value get(const char* key) const
ParamètreTypeDescription
key const char*

Retourne Loreline_Value

set

méthode

void set(const char* key, Loreline_Value value)
ParamètreTypeDescription
key const char*
value Loreline_Value

Retourne void

exists

méthode

bool exists(const char* key) const
ParamètreTypeDescription
key const char*

Retourne bool

remove

méthode

void remove(const char* key)
ParamètreTypeDescription
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 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

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, elle fournit son résultat plus tard via un handle resolve. Utilisable seulement comme instruction, pas dans une expression ni une interpolation.

Loreline_Retainer

handle

typedef struct Loreline_Retainer Loreline_Retainer

Jeton 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

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'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

callback

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

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)

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

fonction

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

fonction

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

fonction

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

callback

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

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. Rend la main tout de suite ; le callback de fin reçoit le handle obtenu (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 : fonctions personnalisées, accès strict et 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 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

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

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.