GDScript API Reference

The complete public API of the Loreline runtime.

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

Quick reference

Type	Members
`Loreline`	`parse` `play` `resume` `extract_translations` `load_locale` `translation_format` `print_script` `shared`
`LorelineInterpreter`	`start` `save_state` `restore_state` `get_character_field` `set_character_field` `get_state_field` `set_state_field` `get_top_level_state_field` `set_top_level_state_field` `current_node` `dialogue` `choice` `finished` `advance` `select`
`LorelineScript`	`from_json` `play` `resume`
`Node`	`to_json`
`LorelineOptions`	`set_function` `set_strict_access` `set_translations` `get_strict_access` `set_async_function` `remove_function`
`LorelineTranslations`
`LorelineParseResult`	`completed`
`LorelineLoadLocaleResult`	`completed`
`LorelineResourceLoader`

`Loreline`

class

Public entry point of the pure-GDScript Loreline runtime. Mirrors the native GDExtension API exactly, so projects can switch between the two backends without code changes (only one addon may be installed at a time, since both register the same class names).

Reach the runtime through Loreline.shared(), which creates the node on first use and adds it to the scene tree root. It is not a Godot autoload: there is nothing to register in the project settings.

`parse`

method

func parse(source: String, file_path: String = "", file_handler: Callable = Callable()) -> Signal

Parses Loreline source (or a res:// / user:// path) into a script. Returns a Signal: var script = await loreline.parse(...). file_handler, if provided, is called as (path, provide) and must call provide.call(content_or_null).

Parameter	Type	Description
`source`	`String`	The Loreline script content as a string (`.lor` format)
`file_path`	`String`	Optional file path of the input being parsed. If provided, requires `handleFile` as well. optional: `""`
`file_handler`	`Callable`	Optional file handler to read imports. If that handler is asynchronous, then `parse()` will return null and `callback` argument should be used optional: `Callable()`

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

`play`

method

func play(script: LorelineScript, on_dialogue: Callable = Callable(), on_choice: Callable = Callable(), on_finished: Callable = Callable(), beat_name: String = "", options: LorelineOptions = null) -> LorelineInterpreter

Runs a script, connecting the provided Callables to the interpreter's dialogue/choice/finished signals.

Parameter	Type	Description
`script`	`LorelineScript`	The parsed script (result from `parse()`)
`on_dialogue`	`Callable`	Function called when dialogue text should be displayed optional: `Callable()`
`on_choice`	`Callable`	Function called when player needs to make a choice optional: `Callable()`
`on_finished`	`Callable`	Function called when script execution completes optional: `Callable()`
`beat_name`	`String`	Optional name of a specific beat to start from (defaults to first beat) optional: `""`
`options`	`LorelineOptions`	Additional options optional: `null`

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

`resume`

method

func resume(script: LorelineScript, on_dialogue: Callable, on_choice: Callable, on_finished: Callable, save_data: String = "", beat_name: String = "", options: LorelineOptions = null) -> LorelineInterpreter

Resumes a script from save data, connecting the provided Callables.

Parameter	Type	Description
`script`	`LorelineScript`	The parsed script (result from `parse()`)
`on_dialogue`	`Callable`	Function called when dialogue text should be displayed
`on_choice`	`Callable`	Function called when player needs to make a choice
`on_finished`	`Callable`	Function called when script execution completes
`save_data`	`String`	The saved game data (typically from `interpreter.save()`) optional: `""`
`beat_name`	`String`	Optional beat name to override where to resume from optional: `""`
`options`	`LorelineOptions`	Optional options to configure interpreter behavior optional: `null`

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

`extract_translations`

method

func extract_translations() -> LorelineTranslations

Extracts translations from a parsed translation script.

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

`load_locale`

method

func load_locale(locale: String, script: LorelineScript, file_path: String = "", file_handler: Callable = Callable()) -> Signal

Loads translations for a locale (e.g. "fr") relative to the script. Returns a Signal resolving to a LorelineTranslations (or null).

Parameter	Type	Description
`locale`	`String`	The locale code (e.g. `"fr"`)
`script`	`LorelineScript`	The parsed source script (must have been parsed with a file path, or `filePath` must be provided)
`file_path`	`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. optional: `""`
`file_handler`	`Callable`	File handler used to read translation files optional: `Callable()`

Returns Signal 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().

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

`translation_format`

method

func translation_format(name: String, enabled: bool) -> void

Enables or disables a runtime translation file format ("po", "xliff", "csv").

Parameter	Type	Description
`name`	`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 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

`print_script`

method

func print_script() -> String

Prints the script back to Loreline source form.

Returns String The printed source code as a string

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

`shared`

method

static func shared() -> Loreline

Returns the shared Loreline node, creating it and adding it to the scene tree on first use.

Returns Loreline

This is the entry point for everything else: Loreline.shared().parse(...).

`LorelineInterpreter`

class

Wraps a running Loreline interpreter (pure-GDScript runtime). Mirrors the native GDExtension API: same signals, methods and Callable conventions, so the two backends are interchangeable.

`start`

method

func start(beat_name: String = "") -> void

Starts (or restarts) execution from the given beat.

Parameter	Type	Description
`beat_name`	`String`	Optional name of the beat to start from. If null, execution starts from the first beat or a beat named "_" if it exists. optional: `""`

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

`save_state`

method

func save_state() -> String

Returns the full interpreter state serialized as a JSON string.

Returns String A SaveData object containing the serialized state

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

`restore_state`

method

func restore_state(data: String) -> void

Restores interpreter state from a save_state() JSON string.

Parameter	Type	Description
`data`	`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

`get_character_field`

method

func get_character_field(character: String, field: String)

Gets 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 The field value or null if the character or field doesn't exist

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

`set_character_field`

method

func set_character_field(character: String, field: String, value) -> void

Sets 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`		The value to set

Returns void

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

`get_state_field`

method

func get_state_field(field: String)

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

Parameter	Type	Description
`field`	`String`	The name of the field to get

Returns The field value or null if not found

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

`set_state_field`

method

func set_state_field(field: String, value) -> void

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

Parameter	Type	Description
`field`	`String`	The name of the field to set
`value`		The value to set

Returns void

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

`get_top_level_state_field`

method

func get_top_level_state_field(field: String)

Gets a field from the top-level state directly.

Parameter	Type	Description
`field`	`String`	The name of the field to get

Returns The field value or null if not found

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

`set_top_level_state_field`

method

func set_top_level_state_field(field: String, value) -> void

Sets a field on the top-level state directly.

Parameter	Type	Description
`field`	`String`	The name of the field to set
`value`		The value to set

Returns void

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

`current_node`

method

func current_node() -> Dictionary

Information about the node currently being evaluated.

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

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

`dialogue`

signal

signal dialogue(interpreter, character: String, text: String, tags: Array, advance: Callable)

Emitted when a line of dialogue should be displayed.

Parameter	Type	Description
`interpreter`
`character`	`String`
`text`	`String`
`tags`	`Array`
`advance`	`Callable`

Call advance.call() when the player has read it, to let the story continue. character is empty for narration.

`choice`

signal

signal choice(interpreter, options: Array, select: Callable)

Emitted when the player has to pick between several options.

Parameter	Type	Description
`interpreter`
`options`	`Array`
`select`	`Callable`

Call select.call(index) with the chosen option's index. Each entry of options is a dictionary with text, tags and enabled.

`finished`

signal

signal finished(interpreter)

Emitted when the script has run to the end.

Parameter	Type	Description
`interpreter`

`advance`

method

func advance() -> void

Advances past the current dialogue (same as calling the advance Callable received with the dialogue signal).

Returns void

`select`

method

func select(index: int) -> void

Selects a choice option by index (same as calling the select Callable received with the choice signal).

Parameter	Type	Description
`index`	`int`

Returns void

`LorelineScript`

class

A parsed Loreline script. Mirrors the native GDExtension API.

`from_json`

method

static func from_json(json: String) -> LorelineScript

Recreates a script from to_json() output.

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

Returns LorelineScript The reconstructed Script

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

`play`

method

func play(beat_name: String = "", options: LorelineOptions = null) -> LorelineInterpreter

Runs the script. Prefer Loreline.play() which also wires Callables.

Parameter	Type	Description
`beat_name`	`String`	optional: `""`
`options`	`LorelineOptions`	optional: `null`

Returns LorelineInterpreter

`resume`

method

func resume(save_data: String, beat_name: String = "", options: LorelineOptions = null) -> LorelineInterpreter

Resumes the script from saved state. Prefer Loreline.resume().

Parameter	Type	Description
`save_data`	`String`
`beat_name`	`String`	optional: `""`
`options`	`LorelineOptions`	optional: `null`

Returns LorelineInterpreter

`Node`

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

Godot has no separate node type. The operations grouped here live on LorelineScript, which is what Loreline.parse() hands back.

`to_json`

method

func to_json(pretty: bool = false) -> String

Serializes the script AST to JSON.

Parameter	Type	Description
`pretty`	`bool`	optional: `false`

Returns String Object containing node type and position

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

`LorelineOptions`

class

Options for Loreline.play() / Loreline.resume(). Mirrors the native GDExtension API.

Custom function conventions:

sync: func(interp: LorelineInterpreter, args: Array) -> Variant
async: func(interp: LorelineInterpreter, args: Array, resolve: Callable) Call resolve.call() to resume execution. Calling resolve twice is a no-op; dropping it without calling leaves the interpreter paused.

Godot configures options through setters on a LorelineOptions object rather than through fields. Create one with LorelineOptions.new() and pass it to play() or resume().

`set_function`

method

func set_function(name: String, callable: Callable) -> void

Optional map of additional functions to make available to the script

Parameter	Type	Description
`name`	`String`
`callable`	`Callable`

Returns void

JavaScript TypeScript C# GDScript C++ Java Haxe

`set_strict_access`

method

func set_strict_access(strict: bool) -> void

Enables or disables strict access.

Parameter	Type	Description
`strict`	`bool`

Returns void

With strict access on, reading or writing an undefined variable raises an error instead of passing silently.

JavaScript TypeScript C# GDScript C++ Java Haxe

`set_translations`

method

func set_translations(translations: LorelineTranslations) -> void

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

Parameter	Type	Description
`translations`	`LorelineTranslations`

Returns void

JavaScript TypeScript C# GDScript C++ Java Haxe

`get_strict_access`

method

func get_strict_access() -> bool

Returns whether strict access is enabled.

Returns bool

`set_async_function`

method

func set_async_function(name: String, callable: Callable) -> void

Registers a custom function that finishes later.

Parameter	Type	Description
`name`	`String`
`callable`	`Callable`

Returns void

The Callable receives (interp, args, resolve) and the interpreter stays paused until resolve.call() is called. Calling resolve twice does nothing; dropping it without calling leaves the interpreter paused.

`remove_function`

method

func remove_function(name: String) -> void

Removes a previously registered custom function.

Parameter	Type	Description
`name`	`String`

Returns void

`LorelineTranslations`

class

Opaque holder for a translations map, obtained from LorelineScript.extract_translations() or Loreline.load_locale(), and passed to LorelineOptions.set_translations().

`LorelineParseResult`

class

One-shot await target returned by Loreline.parse(). Emission is deferred to the next process frame so awaiters connect first.

`completed`

signal

signal completed(script)

Emitted with the parsed LorelineScript, or null if parsing failed.

Parameter	Type	Description
`script`

`LorelineLoadLocaleResult`

class

One-shot await target returned by Loreline.load_locale(). Emission is deferred to the next process frame so awaiters connect first.

`completed`

signal

signal completed(translations)

Emitted with the loaded LorelineTranslations, or null if nothing was found.

Parameter	Type	Description
`translations`

`LorelineResourceLoader`

class

Makes .lor files recognized as resources, mirroring the native GDExtension's LorelineResourceLoader.

Beyond allowing load("res://story.lor"), this is what lets the export system see .lor files at all: a preset exporting "all resources" only picks up files some ResourceFormatLoader claims, so without this the story files are silently missing from every export and the game runs fine in the editor but shows nothing once exported.

The class_name above is load-bearing, not cosmetic: Godot picks custom resource format loaders up from the global script class registry, which is what makes this work with no plugin enabled and no project setup. Removing it silently stops .lor files from being exported.

Generated from Loreline v0.10.0.

GDScript API Reference

Quick reference

Loreline#

parse#

play#

resume#

extract_translations#

load_locale#

translation_format#

print_script#

shared#

LorelineInterpreter#

start#

save_state#

restore_state#

get_character_field#

set_character_field#

get_state_field#

set_state_field#

get_top_level_state_field#

set_top_level_state_field#

current_node#

dialogue#

choice#

finished#

advance#

select#

LorelineScript#

from_json#

play#

resume#

Node#

to_json#

LorelineOptions#

set_function#

set_strict_access#

set_translations#

get_strict_access#

set_async_function#

remove_function#

LorelineTranslations#

LorelineParseResult#

completed#

LorelineLoadLocaleResult#

completed#

LorelineResourceLoader#

`Loreline`

`parse`

`play`

`resume`

`extract_translations`

`load_locale`

`translation_format`

`print_script`

`shared`

`LorelineInterpreter`

`start`

`save_state`

`restore_state`

`get_character_field`

`set_character_field`

`get_state_field`

`set_state_field`

`get_top_level_state_field`

`set_top_level_state_field`

`current_node`

`dialogue`

`choice`

`finished`

`advance`

`select`

`LorelineScript`

`from_json`

`play`

`resume`

`Node`

`to_json`

`LorelineOptions`

`set_function`

`set_strict_access`

`set_translations`

`get_strict_access`

`set_async_function`

`remove_function`

`LorelineTranslations`

`LorelineParseResult`

`completed`

`LorelineLoadLocaleResult`

`completed`

`LorelineResourceLoader`