Lua API Reference
The complete public API of the Loreline runtime.
New to Loreline in Lua? Start with the integration guide. This page is the comprehensive reference.
Quick reference
loreline
The main public API for Loreline runtime. Provides easy access to the core functionality for parsing and running Loreline scripts.
parse
function M.parse(source, file_path, handle_file, callback)Parse a Loreline script string into a Script AST.
| Parameter | Type | Description |
|---|---|---|
source |
string |
The Loreline script content as a string (.lor format)
|
file_path |
string|nil |
Optional file path of the input being parsed. If provided, requires handleFile as well.
|
handle_file |
function|nil |
Optional file handler to read imports. If that handler is asynchronous, then parse() will return null and callback argument should be used
|
callback |
function|nil |
If provided, will be called with the resulting script as argument. Mostly useful when reading file imports asynchronously |
Returns
Script|nil
The parsed Script, or nil if loaded asynchronously.
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
play
function M.play(script, handle_dialogue, handle_choice, handle_finish, beat_name, options)Start playing a parsed script.
| Parameter | Type | Description |
|---|---|---|
script |
Script |
The parsed script (result from parse())
|
handle_dialogue |
function |
Function called when dialogue text should be displayed |
handle_choice |
function |
Function called when player needs to make a choice |
handle_finish |
function |
Function called when script execution completes |
beat_name |
string|nil |
Optional name of a specific beat to start from (defaults to first beat) |
options |
table|nil |
Additional options |
Returns
Interpreter
The running Interpreter instance.
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
resume
function M.resume(script, handle_dialogue, handle_choice, handle_finish, save_data, beat_name, options)Resume a script from saved state.
| Parameter | Type | Description |
|---|---|---|
script |
Script |
The parsed script (result from parse())
|
handle_dialogue |
function |
Function called when dialogue text should be displayed |
handle_choice |
function |
Function called when player needs to make a choice |
handle_finish |
function |
Function called when script execution completes |
save_data |
table |
The saved game data (typically from interpreter.save())
|
beat_name |
string|nil |
Optional beat name to override where to resume from |
options |
table|nil |
Optional options to configure interpreter behavior |
Returns
Interpreter
The running Interpreter instance.
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
extract_translations
function M.extract_translations(script)Extract translations from a parsed translation script.
| Parameter | Type | Description |
|---|---|---|
script |
Script |
The parsed translation script (result from parse() on a .XX.lor file)
|
Returns
table
A translations object to pass to play() or resume().
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
load_locale
function M.load_locale(locale, script, file_path, handle_file, callback)Load translations for a specific locale, walking the script's full 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.
| Parameter | Type | Description |
|---|---|---|
locale |
string |
The locale code (e.g. "fr")
|
script |
Script |
The parsed source script (must have been parsed with a file path, or filePath must be provided)
|
file_path |
string|nil |
Optional override for where to look for translation files (defaults to script.filePath). Can be a .lor/.lor.txt file path or a directory.
|
handle_file |
function |
File handler used to read translation files |
callback |
function|nil |
Called with the merged translations map. Required if handleFile is asynchronous.
|
Returns
table
The merged translations map (synchronously, when handle_file 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().
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
translation_format
function M.translation_format(name, enabled)Enable or disable runtime support for an alternate translation file format. By default only .<locale>.lor files are tried by load_locale. Call this to opt in to additional formats. Known names: "po" (.po), "xliff" (.xliff, .xlf), "csv" (.csv, .tsv). Unknown names are accepted silently for forward compatibility.
| Parameter | Type | Description |
|---|---|---|
name |
string |
The format identifier (see above) |
enabled |
boolean |
True to enable the format, false to disable |
By default only .<locale>.lor files are tried by 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 for future formats).
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
last_error
function M.last_error()Return the error from the most recent failed parse() or load_locale() call, or nil on success. In async mode (callback supplied) the callback fires with nil on failure and this function tells you what went wrong. In sync mode the call throws, and this is set to the same error so it can be inspected after the catch. Not thread-safe: read immediately after the call returns.
In async mode (callback supplied) the callback fires with null on failure and this method tells you what went wrong. In sync mode the call throws, and this is set to the same error so it can be inspected after the catch.
Not thread-safe: read immediately after the call returns.
JavaScript TypeScript C# C++ Java PHP Python Lua Haxe
print
function M.print(script, indent, newline)Print a parsed script back into Loreline source code.
| Parameter | Type | Description |
|---|---|---|
script |
Script |
The parsed script (result from parse())
|
indent |
string |
The indentation string to use (defaults to two spaces) |
newline |
string |
The newline string to use (defaults to "\n") |
Returns
string
The printed source code.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
update
function M.update(delta)Ticks pending wait() timers. Call this from your game loop every frame. The first call enables non-blocking deferred mode for wait(); before this is called, wait() falls back to blocking sleep (correct for CLI tools).
| Parameter | Type | Description |
|---|---|---|
delta |
number |
Time elapsed since last frame in seconds |
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.
start
function Interpreter:start(beat_name)Start or restart execution from a specific beat.
| Parameter | Type | Description |
|---|---|---|
beat_name |
string|nil |
Optional name of the beat to start from. If null, execution starts from the first beat or a beat named "_" if it exists. |
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
save
function Interpreter:save()Save the current interpreter state.
Returns
table
Opaque save-data that can be passed to loreline.resume() or interpreter:restore() later.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
restore
function Interpreter:restore(save_data)Restore the interpreter to a previously saved state.
| Parameter | Type | Description |
|---|---|---|
save_data |
table |
The SaveData object containing the serialized state |
Throws RuntimeError If the save data version is incompatible
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
resume
function Interpreter:resume()Resume execution after restoring state.
JavaScript TypeScript C# Java PHP Python Lua Haxe
get_character
function Interpreter:get_character(name)Get a character's fields by name.
| Parameter | Type | Description |
|---|---|---|
name |
string |
The name of the character to get |
Returns
table|nil
The character's fields, or nil if not found.
JavaScript TypeScript C# Java PHP Python Lua Haxe
get_character_field
function Interpreter:get_character_field(character, field)Get a specific field of a character.
| Parameter | Type | Description |
|---|---|---|
character |
string |
The name of the character |
field |
string |
The name of the field to get |
Returns
any
The field value, or nil if not found.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
set_character_field
function Interpreter:set_character_field(character, field, value)Set a specific field of a character.
| Parameter | Type | Description |
|---|---|---|
character |
string |
The name of the character |
field |
string |
The name of the field to set |
value |
any |
The value to set |
get_state_field
function Interpreter:get_state_field(name)Get a state field by name, resolving from the current scope outward.
| Parameter | Type | Description |
|---|---|---|
name |
string |
The name of the field to get |
Returns
any
The field value, or nil if not found.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
set_state_field
function Interpreter:set_state_field(name, value)Set a state field by name, resolving from the current scope outward.
| Parameter | Type | Description |
|---|---|---|
name |
string |
The name of the field to set |
value |
any |
The value to set |
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
get_top_level_state_field
function Interpreter:get_top_level_state_field(name)Get a field from the top-level state directly.
| Parameter | Type | Description |
|---|---|---|
name |
string |
The name of the field to get |
Returns
any
The field value, or nil if not found.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
set_top_level_state_field
function Interpreter:set_top_level_state_field(name, value)Set a field on the top-level state directly.
| Parameter | Type | Description |
|---|---|---|
name |
string |
The name of the field to set |
value |
any |
The value to set |
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
current_node
function Interpreter:current_node()Get the current node being executed. During a dialogue callback, this returns the dialogue statement node. During a choice callback, this returns the choice statement node.
Returns
Node|nil
The current node, or nil if no node is being executed.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
Script
Represents the root node of a Loreline script AST.
from_json
function Script.from_json(json_str)Reconstruct a Script from a JSON string.
| Parameter | Type | Description |
|---|---|---|
json_str |
string |
The JSON object (as returned by script.toJson())
|
Returns
Script
The reconstructed Script.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
Node
Base class for all AST nodes. Contains position information and basic JSON conversion.
node_type
function Node:node_type()Get the type of this node (e.g. "Script", "Beat", "Text", "Dialogue").
Returns
string
The node type.
JavaScript TypeScript C# C++ Java PHP Python Lua Haxe
to_json
function Node:to_json(pretty)Export this node as a JSON string.
| Parameter | Type | Description |
|---|---|---|
pretty |
boolean|nil |
Returns
string
A JSON string representation of the node tree.
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
from_json
function Node.from_json(json_str)Reconstruct a Node from a JSON string.
| Parameter | Type | Description |
|---|---|---|
json_str |
string |
The JSON object (as returned by node.toJson())
|
Returns
Node
The reconstructed Node.
JavaScript TypeScript C# Java PHP Python Lua Haxe
line
function Node:line()Get the line number in the source code where this node appears (1-based).
Returns
number
The line number.
column
function Node:column()Get the column number in the source code where this node appears (1-based).
Returns
number
The column number.
offset
function Node:offset()Get the absolute character offset from the start of the source code.
Returns
number
The offset.
length
function Node:length()Get the length of the source text span this node represents.
Returns
number
The length.
node_id_to_string
function Node:node_id_to_string()Return the human-readable node ID string (e.g. '1.0.0.0').
Returns
string
The dotted node ID.
Generated from Loreline v0.10.0.