C++ API Reference

The complete public API of the Loreline runtime.

New to Loreline in C++? Start with the integration guide. This page is the comprehensive reference.

Quick reference

Type	Members
`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`

The main public API for Loreline runtime. Provides easy access to the core functionality for parsing and running Loreline scripts.

The entry points are free functions rather than static methods. Call Loreline_init() once before any of them, and Loreline_update() from your main loop so timers and queued callbacks run.

`Loreline_parse`

function

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

Synchronous parsing: blocks until parsing + all imports complete. Returns NULL on parse error.

Parameter	Type	Description
`input`	`Loreline_String`	The Loreline script content as a string (`.lor` format)
`filePath`	`Loreline_String`	Optional file path of the input being parsed. If provided, requires `handleFile` as well.
`fileHandler`	`Loreline_FileHandler`	Optional file handler to read imports. If that handler is asynchronous, then `parse()` will return null and `callback` argument should be used
`fileHandlerData`	`void*`	Opaque pointer handed back to `fileHandler` on every call. Use it to reach your own state from the handler.

Returns Loreline_Script* The parsed script as an AST Script instance (if loaded synchronously)

Throws If the script contains syntax errors or other parsing issues

This is the first step in working with a Loreline script. The returned Script object can then be passed to methods play() or resume().

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

`Loreline_play`

function

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)

Playback. All trailing parameters are optional.

Parameter	Type	Description
`script`	`Loreline_Script*`	The parsed script (result from `parse()`)
`onDialogue`	`Loreline_DialogueHandler`	Function called when dialogue text should be displayed
`onChoice`	`Loreline_ChoiceHandler`	Function called when player needs to make a choice
`onFinish`	`Loreline_FinishHandler`	Function called when script execution completes
`beatName`	`Loreline_String`	Optional name of a specific beat to start from (defaults to first beat) optional: `Loreline_String()`
`options`	`Loreline_InterpreterOptions*`	Additional options optional: `NULL`
`userData`	`void*`	optional: `NULL`
`retain`	`Loreline_UserDataRetain`	optional: `NULL`
`release`	`Loreline_UserDataRelease`	optional: `NULL`

Returns Loreline_Interpreter* The interpreter instance that is running the script

This function takes care of initializing the interpreter and starting execution immediately. You'll need to provide handlers for dialogues, choices, and script completion.

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

`Loreline_resume`

function

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)

Resumes a previously saved Loreline script from its saved state.

Parameter	Type	Description
`script`	`Loreline_Script*`	The parsed script (result from `parse()`)
`onDialogue`	`Loreline_DialogueHandler`	Function called when dialogue text should be displayed
`onChoice`	`Loreline_ChoiceHandler`	Function called when player needs to make a choice
`onFinish`	`Loreline_FinishHandler`	Function called when script execution completes
`saveData`	`Loreline_String`	The saved game data (typically from `interpreter.save()`)
`beatName`	`Loreline_String`	Optional beat name to override where to resume from optional: `Loreline_String()`
`options`	`Loreline_InterpreterOptions*`	Optional options to configure interpreter behavior optional: `NULL`
`userData`	`void*`	optional: `NULL`
`retain`	`Loreline_UserDataRetain`	optional: `NULL`
`release`	`Loreline_UserDataRelease`	optional: `NULL`

Returns Loreline_Interpreter* The interpreter instance that is running the script

This allows you to continue a story from the exact point where it was saved, restoring all state variables, choices, and player progress.

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

`Loreline_extractTranslations`

function

Loreline_Translations* Loreline_extractTranslations(Loreline_Script* script)

Translations: extract from a script for localized playback

Parameter	Type	Description
`script`	`Loreline_Script*`	The parsed translation script (result from `parse()` on a `.XX.lor` file)

Returns Loreline_Translations* A translations map to pass as InterpreterOptions.translations

Given a translation file parsed with parse(), this returns a translations map that can be passed as options.translations to play() or resume().

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

`Loreline_loadLocale`

function

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

Translations: load all ..lor files from the script's import tree. For each file involved in the script (root + transitively imported), looks up the corresponding translation file by inserting .<locale> before the extension (e.g. characters.lor -> characters.fr.lor). Missing translation files are silently skipped. Pass the result to Loreline_optionsSetTranslations.

Parameter	Type	Description
`locale`	`Loreline_String`	The locale code (e.g. `"fr"`)
`script`	`Loreline_Script*`	The parsed source script (must have been parsed with a file path, or `filePath` must be provided)
`filePath`	`Loreline_String`	Optional override for where to look for translation files (defaults to `script.filePath`). Can be a `.lor`/`.lor.txt` file path or a directory.
`fileHandler`	`Loreline_FileHandler`	File handler used to read translation files
`fileHandlerData`	`void*`	Opaque pointer handed back to `fileHandler` on every call.

Returns Loreline_Translations* The merged translations map (synchronously when handleFile is sync)

For each file involved in the script (root + transitively imported), the corresponding translation file is looked up by inserting .<locale> before the extension (e.g. characters.lor -> characters.fr.lor). Missing translation files are silently skipped. The returned map can be passed as InterpreterOptions.translations to play() or resume().

filePath may be NULL: it defaults to the path the script was parsed from. Can also be a directory path to look up translation files in another folder.

Synchronous: blocks until all translation files have been loaded.

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

`Loreline_translationFormat`

function

void Loreline_translationFormat(Loreline_String name, bool enabled)

Enable or disable runtime support for an alternate translation file format.

Parameter	Type	Description
`name`	`Loreline_String`	The format identifier (see above)
`enabled`	`bool`	True to enable the format, false to disable

Returns void

By default, only .<locale>.lor files are tried by Loreline_loadLocale. Call this to opt in to additional formats:

"po": GNU gettext PO (.po)
"xliff": XLIFF 1.2 / 2.x (.xliff, .xlf)
"csv": CSV / TSV (.csv, .tsv)

Unknown names are accepted silently (forward-compat).

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

`Loreline_lastError`

function

Loreline_String Loreline_lastError(void)

Returns the error message from the most recent failed Loreline_parse() or Loreline_loadLocale() call, or an empty string when the most recent such call succeeded.

Returns Loreline_String

Used when a callback variant was supplied: the callback fires with a null script/translations to signal failure, and this function tells you what went wrong. Without a callback, errors typically surface as exceptions on supported targets. This still mirrors the same value so it can be read after recovery.

Not thread-safe: read immediately after the call returns.

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

`Loreline_printScript`

function

Loreline_String Loreline_printScript(Loreline_Script* script)

Prints a parsed script back into Loreline source code.

Parameter	Type	Description
`script`	`Loreline_Script*`	The parsed script (result from `parse()`)

Returns Loreline_String The printed source code as a string

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

`Loreline_update`

function

void Loreline_update(double delta)

Update: call from the host's main loop. Flushes pending callbacks and runs periodic GC.

Parameter	Type	Description
`delta`	`double`	Time elapsed since last frame in seconds

Returns void

C# C++ Java PHP Python Lua Haxe

`Loreline_Interpreter`

handle

typedef struct Loreline_Interpreter Loreline_Interpreter

Runs a parsed script: holds the story state, decides what happens next, and hands control back to your code at every line of dialogue and every choice.

There is no Interpreter class in C++. An interpreter is an opaque Loreline_Interpreter* handle returned by Loreline_play() or Loreline_resume(), and every operation below is a free function taking that handle as its first argument. Release it with Loreline_releaseInterpreter() when the run is over.

`Loreline_start`

function

void Loreline_start(Loreline_Interpreter* interp, Loreline_String beatName)

Starts script execution from the beginning or a specific beat.

Parameter	Type	Description
`interp` handle	`Loreline_Interpreter*`
`beatName`	`Loreline_String`	Optional name of the beat to start from. If null, execution starts from the first beat or a beat named "_" if it exists.

Returns void

Throws RuntimeError If the specified beat doesn't exist or if no beats are found in the script

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

`Loreline_save`

function

Loreline_String Loreline_save(Loreline_Interpreter* interp)

Saves the current state of the interpreter. This includes all state variables, character states, and execution stack, allowing execution to be resumed later from the exact same point.

Parameter	Type	Description
`interp` handle	`Loreline_Interpreter*`

Returns Loreline_String A SaveData object containing the serialized state

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

`Loreline_restore`

function

void Loreline_restore(Loreline_Interpreter* interp, Loreline_String saveData)

Restores the interpreter state from a SaveData object. This allows resuming execution from a previously saved state.

Parameter	Type	Description
`interp` handle	`Loreline_Interpreter*`
`saveData`	`Loreline_String`	The SaveData object containing the serialized state

Returns void

Throws RuntimeError If the save data version is incompatible

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

`Loreline_getCharacterField`

function

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

Gets a specific field of a character.

Parameter	Type	Description
`interp` handle	`Loreline_Interpreter*`
`character`	`Loreline_String`	The name of the character
`field`	`Loreline_String`	The name of the field to get

Returns Loreline_Value The field value or null if the character or field doesn't exist

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

`Loreline_setCharacterField`

function

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

Sets a specific field of a character.

Parameter	Type	Description
`interp` handle	`Loreline_Interpreter*`
`character`	`Loreline_String`	The name of the character
`field`	`Loreline_String`	The name of the field to set
`value`	`Loreline_Value`	The value to set

Returns void

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

`Loreline_getStateField`

function

Loreline_Value Loreline_getStateField(Loreline_Interpreter* interp, Loreline_String field)

Gets a state field by name, resolving from the current scope outward.

Parameter	Type	Description
`interp` handle	`Loreline_Interpreter*`
`field`	`Loreline_String`	The name of the field to get

Returns Loreline_Value The field value or null if not found

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

`Loreline_setStateField`

function

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

Sets a state field by name, resolving from the current scope outward.

Parameter	Type	Description
`interp` handle	`Loreline_Interpreter*`
`field`	`Loreline_String`	The name of the field to set
`value`	`Loreline_Value`	The value to set

Returns void

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

`Loreline_getTopLevelStateField`

function

Loreline_Value Loreline_getTopLevelStateField(Loreline_Interpreter* interp, Loreline_String field)

Gets a field from the top-level state directly.

Parameter	Type	Description
`interp` handle	`Loreline_Interpreter*`
`field`	`Loreline_String`	The name of the field to get

Returns Loreline_Value The field value or null if not found

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

`Loreline_setTopLevelStateField`

function

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

Sets a field on the top-level state directly.

Parameter	Type	Description
`interp` handle	`Loreline_Interpreter*`
`field`	`Loreline_String`	The name of the field to set
`value`	`Loreline_Value`	The value to set

Returns void

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

`Loreline_currentNode`

function

Loreline_Node Loreline_currentNode(Loreline_Interpreter* interp)

Current node: returns info about the node being executed. Returns a Loreline_Node with type set to null if no node is current.

Parameter	Type	Description
`interp` handle	`Loreline_Interpreter*`

Returns Loreline_Node The current node or null if no node is being executed

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

`Loreline_Script`

handle

typedef struct Loreline_Script Loreline_Script

Represents the root node of a Loreline script AST.

A script is an opaque Loreline_Script* handle. The host owns it and must release it with Loreline_releaseScript(). Along with the interpreter, it is the only handle that needs releasing: strings and values are reference counted.

`Loreline_scriptFromJson`

function

Loreline_Script* Loreline_scriptFromJson(Loreline_String json)

Reconstructs a Script from a JSON representation.

Parameter	Type	Description
`json`	`Loreline_String`	The JSON object (as returned by `script.toJson()`)

Returns Loreline_Script* The reconstructed Script

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

`Loreline_Node`

struct

Base class for all AST nodes. Contains position information and basic JSON conversion.

`type`

field

Loreline_String type

Returns the type of this node.

Returns Loreline_String String representation of node type

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

`Loreline_scriptToJson`

function

Loreline_String Loreline_scriptToJson(Loreline_Script* script, bool pretty)

Converts the node to a JSON representation.

Parameter	Type	Description
`script`	`Loreline_Script*`
`pretty`	`bool`

Returns Loreline_String Object containing node type and position

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

`line`

field

int line

Returns int

`column`

field

int column

Returns int

`offset`

field

int offset

Returns int

`length`

field

int length

Returns int

`Loreline_InterpreterOptions`

handle

typedef struct Loreline_InterpreterOptions Loreline_InterpreterOptions

Options used to configure the Loreline interpreter behavior

`Loreline_optionsAddFunction`

function

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

Optional map of additional functions to make available to the script

Parameter	Type	Description
`options`	`Loreline_InterpreterOptions*`
`name`	`Loreline_String`
`fn`	`Loreline_CustomFunction`
`userData`	`void*`

Returns void

JavaScript TypeScript C# GDScript C++ Java Haxe

`Loreline_optionsSetStrictAccess`

function

void Loreline_optionsSetStrictAccess(Loreline_InterpreterOptions* options, bool strict)

Tells whether access is strict or not. If set to true, trying to read or write an undefined variable will throw an error.

Parameter	Type	Description
`options`	`Loreline_InterpreterOptions*`
`strict`	`bool`

Returns void

JavaScript TypeScript C# GDScript C++ Java Haxe

`Loreline_optionsSetTranslations`

function

void Loreline_optionsSetTranslations(Loreline_InterpreterOptions* options, Loreline_Translations* translations)

Optional translations map for localization. Built from a parsed translation file using Loreline.extractTranslations().

Parameter	Type	Description
`options`	`Loreline_InterpreterOptions*`
`translations`	`Loreline_Translations*`

Returns void

JavaScript TypeScript C# GDScript C++ Java Haxe

`Loreline_ChoiceOption`

struct

Represents a choice option presented to the user.

`text`

field

Loreline_String text

The text of the choice option.

Returns Loreline_String

JavaScript TypeScript C# C++ Java PHP Python Haxe

`tags`

field

const Loreline_TextTag* tags

Any tags associated with the choice text.

Returns const Loreline_TextTag*

JavaScript TypeScript C# C++ Java PHP Python Haxe

`enabled`

field

bool enabled

Whether this choice option is currently enabled.

Returns bool

JavaScript TypeScript C# C++ Java PHP Python Haxe

`tagCount`

field

int tagCount

Returns int

`Loreline_TextTag`

struct

Represents a tag in text content, which can be used for styling or other purposes.

`closing`

field

bool closing

Whether this is a closing tag.

Returns bool

JavaScript TypeScript C# C++ Java PHP Python Haxe

`value`

field

Loreline_String value

The value or name of the tag.

Returns Loreline_String

JavaScript TypeScript C# C++ Java PHP Python Haxe

`offset`

field

int offset

The offset in the text where this tag appears.

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

Handler type for text output with callback. This is called when the script needs to display text to the user.

`Loreline_ChoiceHandler`

callback

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

Handler type for choice presentation with callback. This is called when the script needs to present choices to the user.

`Loreline_FinishHandler`

callback

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

Handler type to be called when the execution finishes.

`Loreline_FileHandler`

callback

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

File handler is async-capable: the host receives an opaque request token and MUST call Loreline_provideFile(request, content) exactly once, either synchronously inside the handler or later from any thread. Pass NULL content to signal "file not found".

`Loreline_CustomFunction`

callback

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

Sync custom function: called on the host thread, must return immediately.

`Loreline_Translations`

handle

typedef struct Loreline_Translations Loreline_Translations

Opaque type for a translations map. Obtained from Loreline.extractTranslations() and passed to InterpreterOptions.translations.

`Loreline_String`

class

A reference-counted string, copied by value and released automatically.

Every string crossing the boundary is a deep-copy snapshot: it holds no runtime pointer, so it is safe to keep and to pass between threads.

`Loreline_String`

constructor

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`

method

~Loreline_String()

`operator =`

operator

Loreline_String& operator=(const Loreline_String& o)

Loreline_String& operator=(Loreline_String&& o)

Parameter	Type	Description
`o`	`const Loreline_String&`

Returns Loreline_String&

`c_str`

method

const char* c_str() const

Returns const char*

`length`

method

size_t length() const

Returns size_t

`isNull`

method

bool isNull() const

Returns bool

`operator bool`

operator

operator bool() const

Returns bool

`Loreline_AsyncResolve`

handle

typedef struct Loreline_AsyncResolve Loreline_AsyncResolve

An opaque handle used to finish an asynchronous custom function.

Pass it to Loreline_resolveAsync() with the result, or to Loreline_cancelAsync() to drop the call without resuming the interpreter.

`Loreline_FileRequest`

handle

typedef struct Loreline_FileRequest Loreline_FileRequest

Opaque file-load request token. Passed to the host's Loreline_FileHandler; the host calls Loreline_provideFile(request, content), sync or async, to deliver the file content (or NULL for "not found"). The token is consumed by Loreline_provideFile, which must be called exactly once per request.

`Loreline_advance`

function

void Loreline_advance(Loreline_Interpreter* interp)

Hands control back to an interpreter's pending dialogue or choice. May be called at any point while the interpreter is alive, from a UI event or after an arbitrary delay. Calling with nothing pending is a no-op.

`Loreline_select`

function

void Loreline_select(Loreline_Interpreter* interp, int index)

Answers an interpreter's pending choice with the index of the selected option.

The counterpart of Loreline_advance() for choices. Calling it when no choice is pending does nothing.

`Loreline_Advance`

struct

The advance and select continuations handed to the dialogue and choice handlers. Each one is bound to the interpreter that produced it, so a host may store it and answer whenever it wants, and several interpreters can run side by side without their continuations getting mixed up. Copyable and cheap: it is just the handle.

void onDialogue(..., Loreline_Advance advance, void* userData) { advance(); // now // or keep advance around and call it from a button handler }

Holding one does NOT keep its interpreter alive: it carries the handle, not ownership. Do not call it after Loreline_releaseInterpreter. Bindings that wrap it in a reference-counted callable (the Godot addon, for one) do give it ownership, so there holding the callable is enough to keep the run alive, and dropping it without calling lets the run be collected.

`interpreter`

field

Loreline_Interpreter* interpreter

Returns Loreline_Interpreter*

`operator()`

operator

void operator()() const

Returns void

`Loreline_Select`

struct

The continuation handed to a choice handler, to be called with the index of the chosen option.

Bound to the interpreter that produced it, copyable, and cheap: it carries the handle, not ownership. See Loreline_Advance for the full lifetime rules.

`interpreter`

field

Loreline_Interpreter* interpreter

Returns Loreline_Interpreter*

`operator()`

operator

void operator()(int index) const

Returns void

`Loreline_Array`

class

A reference-counted array of Loreline_Value, copied by value and released automatically.

A deep-copy snapshot, not a view: mutating it never affects interpreter state. Pass it back through a setter to apply changes.

`Loreline_Array`

constructor

Loreline_Array()

Loreline_Array(const Loreline_Array& o)

Loreline_Array(Loreline_Array&& o)

`~Loreline_Array`

method

~Loreline_Array()

`operator =`

operator

Loreline_Array& operator=(const Loreline_Array& o)

Loreline_Array& operator=(Loreline_Array&& o)

Parameter	Type	Description
`o`	`const Loreline_Array&`

Returns Loreline_Array&

`create`

method

static Loreline_Array create()

Creates a new, empty array (host-side, to build setter values)

Returns Loreline_Array

`length`

method

int length() const

Returns int

`get`

method

Loreline_Value get(int index) const

Parameter	Type	Description
`index`	`int`

Returns Loreline_Value

`set`

method

void set(int index, Loreline_Value value)

Parameter	Type	Description
`index`	`int`
`value`	`Loreline_Value`

Returns void

`push`

method

void push(Loreline_Value value)

Parameter	Type	Description
`value`	`Loreline_Value`

Returns void

`isNull`

method

bool isNull() const

Returns bool

`operator bool`

operator

operator bool() const

Returns bool

`Loreline_Object`

class

A reference-counted, string-keyed object, copied by value and released automatically.

Entries keep insertion order and key lookup is a linear scan, which suits the field counts of story state. Same deep-copy snapshot semantics as Loreline_Array.

`Loreline_Object`

constructor

Loreline_Object()

Loreline_Object(const Loreline_Object& o)

Loreline_Object(Loreline_Object&& o)

`~Loreline_Object`

method

~Loreline_Object()

`operator =`

operator

Loreline_Object& operator=(const Loreline_Object& o)

Loreline_Object& operator=(Loreline_Object&& o)

Parameter	Type	Description
`o`	`const Loreline_Object&`

Returns Loreline_Object&

`create`

method

static Loreline_Object create()

Creates a new, empty object (host-side, to build setter values)

Returns Loreline_Object

`count`

method

int count() const

Returns int

`keyAt`

method

Loreline_String keyAt(int index) const

Parameter	Type	Description
`index`	`int`

Returns Loreline_String

`get`

method

Loreline_Value get(const char* key) const

Parameter	Type	Description
`key`	`const char*`

Returns Loreline_Value

`set`

method

void set(const char* key, Loreline_Value value)

Parameter	Type	Description
`key`	`const char*`
`value`	`Loreline_Value`

Returns void

`exists`

method

bool exists(const char* key) const

Parameter	Type	Description
`key`	`const char*`

Returns bool

`remove`

method

void remove(const char* key)

Parameter	Type	Description
`key`	`const char*`

Returns void

`isNull`

method

bool isNull() const

Returns bool

`operator bool`

operator

operator bool() const

Returns bool

`Loreline_Value`

struct

A tagged union holding any Loreline value: integer, float, boolean, string, array or object.

Read type first, then the matching member. This is what character and state field accessors exchange in both directions.

`type`

field

Loreline_ValueType type

Returns Loreline_ValueType

`intValue`

field

int intValue

Returns int

`floatValue`

field

double floatValue

Returns double

`boolValue`

field

bool boolValue

Returns bool

`Loreline_AsyncCustomFunction`

callback

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

Async custom function: called on the host thread, provides result later via resolve handle. Only works in statement context (not expressions/interpolation).

`Loreline_Retainer`

handle

typedef struct Loreline_Retainer Loreline_Retainer

Opaque host-provided retainer. The host decides what this points at; the Loreline wrapper only passes it between retain and release calls.

`Loreline_UserDataRetain`

callback

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

Called whenever the wrapper needs to keep the interpreter's userData alive: once when the host hands control back to Loreline (play/resume/ start/advance/select/resolveAsync), covering the run up to the next callback delivery, and once per queued callback dispatch, covering the handler invocation itself. Host implementations typically bump a refcount on whatever object backs userData and return a handle encoding how to release it. Return NULL if no retention is needed; release will then also be called with NULL. With these hooks provided, an interpreter stays alive exactly as long as the host keeps a reference to it or a callback is owed to the host, and is released naturally once neither is true.

`Loreline_UserDataRelease`

callback

typedef void (*Loreline_UserDataRelease)(Loreline_Retainer *retainer)

Called when the corresponding retain window closes (after a handler has run, after an exception escapes it, or when a run is delivered/aborted). Host decrements whatever retain bumped. Safe with NULL.

`Loreline_init`

function

void Loreline_init(void)

Starts the Loreline runtime. Call this once before any other function.

Calling it more than once is harmless.

`Loreline_dispose`

function

void Loreline_dispose(void)

Shutdown counterpart to Loreline_init().

As of this version it does nothing: the runtime and its thread stay alive, the thread idling on a condition variable. Call it at shutdown anyway, so your code keeps working if that changes.

`Loreline_gc`

function

void Loreline_gc(void)

Forces a garbage collection cycle in the Loreline runtime right away.

Optional: Loreline_update() already runs one every 15 seconds of accumulated delta. Call this at a pause of your choosing, such as a loading screen or a scene change, to reclaim memory at a moment you pick.

`Loreline_createThread`

function

void Loreline_createThread(void)

Threading: creates a dedicated internal thread for Loreline. When active, incoming calls route to the internal thread; callbacks are dispatched on the caller's thread via Loreline_update().

`Loreline_provideFile`

function

void Loreline_provideFile(Loreline_FileRequest* request, Loreline_String content)

File handler: deliver content (or NULL for "not found") to a request token. Must be called exactly once per token. Safe to call from any thread.

`Loreline_ParseCompletionCallback`

callback

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

Async parsing: returns immediately. Completion fires (on the host's update tick if Loreline_update is being called, otherwise inline) with the resulting Loreline_Script* (or NULL on parse error). The host owns the script and must call Loreline_releaseScript when done.

`Loreline_parseAsync`

function

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

`Loreline_releaseTranslations`

function

void Loreline_releaseTranslations(Loreline_Translations* translations)

Releases a translations handle returned by Loreline_extractTranslations() or Loreline_loadLocale().

`Loreline_LoadLocaleCallback`

callback

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

Translations: async variant of Loreline_loadLocale. Returns immediately; completion fires with the resulting handle (or NULL on error).

`Loreline_loadLocaleAsync`

function

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

`Loreline_createOptions`

function

Loreline_InterpreterOptions* Loreline_createOptions(void)

Interpreter options: configure custom functions, strict access, translations

`Loreline_releaseOptions`

function

void Loreline_releaseOptions(Loreline_InterpreterOptions* options)

Releases an options handle created by Loreline_createOptions().

`Loreline_optionsAddAsyncFunction`

function

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

Registers a custom function that finishes later, through a resolve handle.

The function is called on the host thread and returns immediately; the interpreter stays paused until Loreline_resolveAsync() is called. Only usable in statement context, not inside expressions or interpolation.

`Loreline_resolveAsync`

function

void Loreline_resolveAsync(Loreline_AsyncResolve* resolve, Loreline_Value result)

Resolve an async custom function call. Can be called from any thread.

`Loreline_cancelAsync`

function

void Loreline_cancelAsync(Loreline_AsyncResolve* resolve)

Cancel an async custom function call without resuming the interpreter. Releases the resolve handle and its internal GC root on the done closure, but does not invoke the closure. Use when the host drops the resolve handle without resolving (e.g. the GDScript Callable was released before resolve.call() fired). The Haxe-side Async state is cleaned up naturally when the interpreter itself is released.

`Loreline_releaseScript`

function

void Loreline_releaseScript(Loreline_Script* script)

Releases a script handle returned by Loreline_parse() or Loreline_scriptFromJson().

`Loreline_releaseInterpreter`

function

void Loreline_releaseInterpreter(Loreline_Interpreter* interp)

Releases an interpreter handle returned by Loreline_play() or Loreline_resume().

Do not call the advance or select continuations of an interpreter after releasing it.

Generated from Loreline v0.10.0.

C++ API Reference

Quick reference

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`