Python API Reference

The complete public API of the Loreline runtime.

New to Loreline in Python? 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` `last_error` `print` `update`
`Interpreter`	`__init__` `start` `save` `restore` `resume` `get_character` `get_character_field` `set_character_field` `get_state_field` `set_state_field` `get_top_level_state_field` `set_top_level_state_field` `current_node`
`Script`	`from_json` `__init__`
`Node`	`type` `to_json` `from_json` `__init__` `line` `column` `offset` `length` `node_id_to_string`
`ChoiceOption`	`text` `tags` `enabled`
`TextTag`	`closing` `value` `offset`
`DialogueHandler`
`ChoiceHandler`
`FinishHandler`
`ImportsFileHandler`

`Loreline`

class

Main public API for the Loreline interactive fiction runtime.

All methods are static. Typical usage::

script = Loreline.parse(source) interp = Loreline.play(script, on_dialogue, on_choice, on_finish)

`parse`

method

def parse(source: str, file_path: Optional[str] = None, handle_file: Optional[ImportsFileHandler] = None, callback: Optional[Callable[[Script], None]] = None) -> Optional[Script]

Parse a Loreline script string into a Script AST.

Parameter	Type	Description
`source`	`str`	The Loreline script content as a string (`.lor` format)
`file_path`	`Optional[str]`	Optional file path of the input being parsed. If provided, requires `handleFile` as well. optional: `None`
`handle_file`	`Optional[ImportsFileHandler]`	Optional file handler to read imports. If that handler is asynchronous, then `parse()` will return null and `callback` argument should be used optional: `None`
`callback`	`Optional[Callable[[Script], None]]`	If provided, will be called with the resulting script as argument. Mostly useful when reading file imports asynchronously optional: `None`

Returns Optional[Script] The parsed Script, or None 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`

method

def play(script: Script, handle_dialogue: DialogueHandler, handle_choice: ChoiceHandler, handle_finish: FinishHandler, beat_name: Optional[str] = None, functions: Optional[dict] = None, strict_access: bool = False, translations: Any = None) -> Interpreter

Start playing a parsed script.

Parameter	Type	Description
`script`	`Script`	The parsed script (result from `parse()`)
`handle_dialogue`	`DialogueHandler`	Function called when dialogue text should be displayed
`handle_choice`	`ChoiceHandler`	Function called when player needs to make a choice
`handle_finish`	`FinishHandler`	Function called when script execution completes
`beat_name`	`Optional[str]`	Optional name of a specific beat to start from (defaults to first beat) optional: `None`
`functions`	`Optional[dict]`	Map of name to `function(interpreter, args)`, made available to the script. optional: `None`
`strict_access`	`bool`	When true, reading or writing an undefined variable raises an error. optional: `False`
`translations`	`Any`	Translations map from `extract_translations()` or `load_locale()`. optional: `None`

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`

method

def resume(script: Script, handle_dialogue: DialogueHandler, handle_choice: ChoiceHandler, handle_finish: FinishHandler, save_data: Any, beat_name: Optional[str] = None, functions: Optional[dict] = None, strict_access: bool = False, translations: Any = None) -> Interpreter

Resume a script from saved state.

Parameter	Type	Description
`script`	`Script`	The parsed script (result from `parse()`)
`handle_dialogue`	`DialogueHandler`	Function called when dialogue text should be displayed
`handle_choice`	`ChoiceHandler`	Function called when player needs to make a choice
`handle_finish`	`FinishHandler`	Function called when script execution completes
`save_data`	`Any`	The saved game data (typically from `interpreter.save()`)
`beat_name`	`Optional[str]`	Optional beat name to override where to resume from optional: `None`
`functions`	`Optional[dict]`	Map of name to `function(interpreter, args)`, made available to the script. optional: `None`
`strict_access`	`bool`	When true, reading or writing an undefined variable raises an error. optional: `False`
`translations`	`Any`	Translations map from `extract_translations()` or `load_locale()`. optional: `None`

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`

method

def extract_translations(script: Script) -> Any

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 Any A translations object to pass as the translations argument 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`

method

def load_locale(locale: str, script: Script, file_path: Optional[str] = None, handle_file: Optional[ImportsFileHandler] = None, callback: Optional[Callable[[Any], None]] = None) -> Any

Load translations for a specific locale, walking the script's full import tree.

Parameter	Type	Description
`locale`	`str`	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`	`Optional[str]`	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: `None`
`handle_file`	`Optional[ImportsFileHandler]`	File handler used to read translation files optional: `None`
`callback`	`Optional[Callable[[Any], None]]`	Called with the merged translations map. Required if `handleFile` is asynchronous. optional: `None`

Returns Any The merged translations map (synchronously, when handle_file is sync).

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.

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

`translation_format`

method

def translation_format(name: str, enabled: bool) -> None

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

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

Returns None

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.

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

`last_error`

method

def last_error() -> Optional[Any]

Return the error from the most recent failed parse() or load_locale() call, or None on success.

Returns Optional[Any]

In async mode (callback supplied) the callback fires with None on failure and this method tells you what went wrong. In sync mode the call throws, and this field 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`

method

def print(script: Script, indent: str = '  ', newline: str = '\n') -> str

Print a parsed script back into Loreline source code.

Parameter	Type	Description
`script`	`Script`	The parsed script (result from `parse()`)
`indent`	`str`	The indentation string to use (defaults to two spaces) optional: `' '`
`newline`	`str`	The newline string to use (defaults to "\n") optional: `'\n'`

Returns str The printed source code.

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

`update`

method

def update(delta: float) -> None

Tick pending wait() timers. Call from your game loop every frame.

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

Returns None

The first call enables non-blocking deferred mode for wait(); before this is called, wait() falls back to blocking sleep (correct for CLI tools).

C# C++ Java PHP Python Lua Haxe

`Interpreter`

class

A running Loreline script interpreter.

Provides methods to save/restore state and access character data.

`init`

constructor

def __init__(_internal: Any) -> None

Creates a new Loreline script interpreter.

Parameter	Type	Description
`_internal`	`Any`	The wrapped runtime interpreter. Build interpreters with `Loreline.play()` rather than calling this directly.

Returns None

JavaScript TypeScript C# Java Python Haxe

`start`

method

def start(beat_name: Optional[str] = None) -> None

Start or restart execution from a specific beat.

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

Returns None

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`

method

def save() -> Any

Save the current interpreter state.

Returns Any A SaveData object containing the serialized state

Returns an opaque save-data object that can be passed to Loreline.resume() or Interpreter.restore() later.

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

`restore`

method

def restore(save_data: Any) -> None

Restore the interpreter to a previously saved state.

Parameter	Type	Description
`save_data`	`Any`	The SaveData object containing the serialized state

Returns None

Throws RuntimeError If the save data version is incompatible

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

`resume`

method

def resume() -> None

Resume execution after restoring state.

Returns None

JavaScript TypeScript C# Java PHP Python Lua Haxe

`get_character`

method

def get_character(name: str) -> Any

Get a character's fields by name.

Parameter	Type	Description
`name`	`str`	The name of the character to get

Returns Any The character's fields object, or None if not found.

JavaScript TypeScript C# Java PHP Python Lua Haxe

`get_character_field`

method

def get_character_field(character: str, field: str) -> Any

Get a specific field of a character.

Parameter	Type	Description
`character`	`str`	The name of the character
`field`	`str`	The name of the field to get

Returns Any The field value, or None if not found.

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

`set_character_field`

method

def set_character_field(character: str, field: str, value: Any) -> None

Set a specific field of a character.

Parameter	Type	Description
`character`	`str`	The name of the character
`field`	`str`	The name of the field to set
`value`	`Any`	The value to set

Returns None

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

`get_state_field`

method

def get_state_field(name: str) -> Any

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

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

Returns Any The field value, or None if not found.

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

`set_state_field`

method

def set_state_field(name: str, value: Any) -> None

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

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

Returns None

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

`get_top_level_state_field`

method

def get_top_level_state_field(name: str) -> Any

Get a field from the top-level state directly.

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

Returns Any The field value, or None if not found.

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

`set_top_level_state_field`

method

def set_top_level_state_field(name: str, value: Any) -> None

Set a field on the top-level state directly.

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

Returns None

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

`current_node`

method

def current_node() -> Optional[Node]

Return the current node being executed.

Returns Optional[Node] The current Node, or None if no node is being executed.

During a dialogue callback, this returns the dialogue statement node. During a choice callback, this returns the choice statement node.

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

`Script`

class

A parsed Loreline script AST.

Obtain via Loreline.parse(). Pass to Loreline.play() or Loreline.resume() to execute.

`from_json`

method

def from_json(json_str: str) -> 'Script'

Reconstruct a Script from a JSON string.

Parameter	Type	Description
`json_str`	`str`	The JSON object (as returned by `script.toJson()`)

Returns 'Script' The reconstructed Script.

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

`init`

constructor

def __init__(_internal: Any) -> None

Parameter	Type	Description
`_internal`	`Any`

Returns None

`Node`

class

Base class for Loreline AST nodes.

Provides access to the node type, unique ID, and JSON export.

`type`

method

def type() -> str

The type of this node (e.g. "Script", "Beat", "Text").

Returns str String representation of node type

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

`to_json`

method

def to_json(pretty: bool = False) -> str

Export this node as a JSON string.

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

Returns str A JSON string representation of the node tree.

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

`from_json`

method

def from_json(json_str: str) -> 'Node'

Reconstruct a Node from a JSON string.

Parameter	Type	Description
`json_str`	`str`	The JSON object (as returned by `node.toJson()`)

Returns 'Node' The reconstructed Node.

JavaScript TypeScript C# Java PHP Python Lua Haxe

`init`

constructor

def __init__(_internal: Any) -> None

Parameter	Type	Description
`_internal`	`Any`

Returns None

`line`

method

def line() -> int

The line number in the source code where this node appears (1-based).

Returns int

`column`

method

def column() -> int

The column number in the source code where this node appears (1-based).

Returns int

`offset`

method

def offset() -> int

The absolute character offset from the start of the source code.

Returns int

`length`

method

def length() -> int

The length of the source text span this node represents.

Returns int

`node_id_to_string`

method

def node_id_to_string() -> str

Return the human-readable node ID string (e.g. '1.0.0.0').

Returns str

`ChoiceOption`

class

A choice option presented to the user.

`text`

property

text: str

The text of the choice option.

Returns str

JavaScript TypeScript C# C++ Java PHP Python Haxe

`tags`

property

tags: List[TextTag]

Any tags associated with the choice text.

Returns List[TextTag]

JavaScript TypeScript C# C++ Java PHP Python Haxe

`enabled`

property

enabled: bool

Whether this choice option is currently enabled.

Returns bool

JavaScript TypeScript C# C++ Java PHP Python Haxe

`TextTag`

class

A tag embedded in text content, used for styling or other purposes.

`closing`

property

closing: bool

Whether this is a closing tag.

Returns bool

JavaScript TypeScript C# C++ Java PHP Python Haxe

`value`

property

value: str

The value or name of the tag.

Returns str

JavaScript TypeScript C# C++ Java PHP Python Haxe

`offset`

property

offset: int

The offset in the text where this tag appears.

Returns int

JavaScript TypeScript C# C++ Java PHP Python Haxe

`DialogueHandler`

type alias

DialogueHandler = Callable[['Interpreter', Optional[str], str, List[TextTag], Callable[[], None]], None]

Called when dialogue text should be displayed. Args: interpreter: The interpreter instance. character: The character speaking (None for narrator text). text: The text content to display. tags: Any tags in the text. advance: Function to call when the text has been displayed.

`ChoiceHandler`

type alias

ChoiceHandler = Callable[['Interpreter', List[ChoiceOption], Callable[[int], None]], None]

Called when the player needs to make a choice. Args: interpreter: The interpreter instance. options: The available choice options. select: Function to call with the index of the selected choice.

`FinishHandler`

type alias

FinishHandler = Callable[['Interpreter'], None]

Called when script execution completes. Args: interpreter: The interpreter instance.

`ImportsFileHandler`

type alias

ImportsFileHandler = Callable[[str, Callable[[str], None]], None]

Called to load an imported file. Args: path: The path of the file to load. callback: Function to call with the loaded file content.

Generated from Loreline v0.10.0.

Python API Reference

Quick reference

Loreline#

parse#

play#

resume#

extract_translations#

load_locale#

translation_format#

last_error#

print#

update#

Interpreter#

__init__#

start#

save#

restore#

resume#

get_character#

get_character_field#

set_character_field#

get_state_field#

set_state_field#

get_top_level_state_field#

set_top_level_state_field#

current_node#

Script#

from_json#

__init__#

Node#

type#

to_json#

from_json#

__init__#

line#

column#

offset#

length#

node_id_to_string#

ChoiceOption#

text#

tags#

enabled#

TextTag#

closing#

value#

offset#

DialogueHandler#

ChoiceHandler#

FinishHandler#

ImportsFileHandler#

`Loreline`

`parse`

`play`

`resume`

`extract_translations`

`load_locale`

`translation_format`

`last_error`

`print`

`update`

`Interpreter`

`init`

`start`

`save`

`restore`

`resume`

`get_character`

`get_character_field`

`set_character_field`

`get_state_field`

`set_state_field`

`get_top_level_state_field`

`set_top_level_state_field`

`current_node`

`Script`

`from_json`

`init`

`Node`

`type`

`to_json`

`from_json`

`init`

`line`

`column`

`offset`

`length`

`node_id_to_string`

`ChoiceOption`

`text`

`tags`

`enabled`

`TextTag`

`closing`

`value`

`offset`

`DialogueHandler`

`ChoiceHandler`

`FinishHandler`

`ImportsFileHandler`