Java API Reference

The complete public API of the Loreline runtime.

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

Quick reference

Type	Members
`Loreline`	`parse` `play` `resume` `extractTranslations` `loadLocale` `translationFormat` `lastError` `print` `update`
`Interpreter`	`Interpreter` `start` `save` `restore` `resume` `getCharacter` `getCharacterField` `setCharacterField` `getStateField` `setStateField` `getTopLevelStateField` `setTopLevelStateField` `currentNode`
`Script`	`fromJson`
`Node`	`id` `type` `toJson` `fromJson` `line` `column` `offset` `length` `nodeIdToString`
`InterpreterOptions`	`functions` `strictAccess` `customCreateFields` `translations` `InterpreterOptions`
`ChoiceOption`	`text` `tags` `enabled` `ChoiceOption`
`TextTag`	`closing` `value` `offset` `TextTag`
`DialogueHandler`	`handle`
`ChoiceHandler`	`handle`
`FinishHandler`	`handle`
`ImportsFileHandler`	`handle`
`CreateFieldsHandler`	`create`
`LorelineFunction`	`call`

`Loreline`

class

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

`parse`

method

public static Script parse(String input)

public static Script parse(String input, String filePath, ImportsFileHandler handleFile)

Parses the given text input and creates a Script instance.

Parameter	Type	Description
`input`	`String`	The Loreline script content as a string (`.lor` format)

Returns Script the parsed script

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

public static Interpreter play(Script script, DialogueHandler handleDialogue, ChoiceHandler handleChoice, FinishHandler handleFinish)

public static Interpreter play(Script script, DialogueHandler handleDialogue, ChoiceHandler handleChoice, FinishHandler handleFinish, String beatName, InterpreterOptions options)

Starts playing a Loreline script from the beginning or a specific beat.

Parameter	Type	Description
`script`	`Script`	The parsed script (result from `parse()`)
`handleDialogue`	`DialogueHandler`	Function called when dialogue text should be displayed
`handleChoice`	`ChoiceHandler`	Function called when player needs to make a choice
`handleFinish`	`FinishHandler`	Function called when script execution completes

Returns Interpreter the 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

public static Interpreter resume(Script script, DialogueHandler handleDialogue, ChoiceHandler handleChoice, FinishHandler handleFinish, String saveData)

public static Interpreter resume(Script script, DialogueHandler handleDialogue, ChoiceHandler handleChoice, FinishHandler handleFinish, String saveData, String beatName, InterpreterOptions options)

Resumes a previously saved Loreline script.

Parameter	Type	Description
`script`	`Script`	The parsed script (result from `parse()`)
`handleDialogue`	`DialogueHandler`	Function called when dialogue text should be displayed
`handleChoice`	`ChoiceHandler`	Function called when player needs to make a choice
`handleFinish`	`FinishHandler`	Function called when script execution completes
`saveData`	`String`	The saved game data (typically from `interpreter.save()`)

Returns Interpreter the 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

`extractTranslations`

method

public static Object extractTranslations(Script script)

Extracts translations from a parsed translation script.

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

Returns Object a translations object 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

`loadLocale`

method

public static Object loadLocale(String locale, Script script, ImportsFileHandler handleFile)

public static Object loadLocale(String locale, Script script, String filePath, ImportsFileHandler handleFile)

Loads translations for a specific locale. Walks the script's full import tree and loads .<locale>.lor files for each. Defaults to looking up translations next to the source files.

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)
`handleFile`	`ImportsFileHandler`	File handler used to read translation files

Returns Object a translations object to pass as InterpreterOptions.translations

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

`translationFormat`

method

public static void translationFormat(String name, boolean enabled)

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

Parameter	Type	Description
`name`	`String`	The format identifier (see above)
`enabled`	`boolean`	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. Known names:

"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

`lastError`

method

public static loreline.runtime.Error lastError()

Returns the error from the most recent failed parse() or loadLocale() call, or null on success.

Returns loreline.runtime.Error

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

public static String print(Script script)

public static String print(Script script, String indent, String newline)

Prints a parsed script back into Loreline source code.

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

Returns String the printed source code as a string

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

`update`

method

public static void update(double 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`	`double`	Time elapsed since last frame in seconds

Returns void

C# C++ Java PHP Python Lua Haxe

`Interpreter`

class

Main interpreter class for Loreline scripts. Wraps the Haxe-generated runtime interpreter with a Java-friendly API.

`Interpreter`

constructor

public Interpreter(Script script, DialogueHandler handleDialogue, ChoiceHandler handleChoice, FinishHandler handleFinish)

public Interpreter(Script script, DialogueHandler handleDialogue, ChoiceHandler handleChoice, FinishHandler handleFinish, InterpreterOptions options)

Creates a new Loreline script interpreter.

Parameter	Type	Description
`script`	`Script`	The parsed script to execute
`handleDialogue`	`DialogueHandler`	Function to call when displaying dialogue text
`handleChoice`	`ChoiceHandler`	Function to call when presenting choices
`handleFinish`	`FinishHandler`	Function to call when execution finishes

JavaScript TypeScript C# Java Python Haxe

`start`

method

public void start(String beatName)

Starts script execution from the beginning or a specific beat.

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

`save`

method

public String save()

Saves the current state of the interpreter.

Returns String a JSON string containing the serialized state

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

`restore`

method

public void restore(String savedData)

Restores the interpreter state from a previously saved state.

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

`resume`

method

public void resume()

Resumes execution after restoring state.

Returns void

JavaScript TypeScript C# Java PHP Python Lua Haxe

`getCharacter`

method

public Object getCharacter(String name)

Gets a character's fields by name.

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

Returns Object the character's fields or null

JavaScript TypeScript C# Java PHP Python Lua Haxe

`getCharacterField`

method

public Object getCharacterField(String character, String field)

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 Object the field value or null

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

`setCharacterField`

method

public void setCharacterField(String character, String field, Object value)

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

Returns void

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

`getStateField`

method

public Object getStateField(String name)

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

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

Returns Object the field value or null

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

`setStateField`

method

public void setStateField(String name, Object value)

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

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

Returns void

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

`getTopLevelStateField`

method

public Object getTopLevelStateField(String name)

Gets a field from the top-level state directly.

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

Returns Object the field value or null

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

`setTopLevelStateField`

method

public void setTopLevelStateField(String name, Object value)

Sets a field on the top-level state directly.

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

Returns void

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

`currentNode`

method

public Node currentNode()

Returns 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 the current node or null if no node is being executed

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

`Script`

class

Represents the root node of a parsed Loreline script AST. This is the result of calling Loreline#parse(String) or similar parse methods.

`fromJson`

method

public static Script fromJson(String json)

Reconstructs a Script from a JSON string.

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

class

Base class for all Loreline AST nodes. Provides access to the node type, unique ID, and JSON export.

`id`

field

public final long id

The unique ID of this node within a single script hierarchy, as a raw Int64 value. Use nodeIdToString() for a human-readable representation.

Returns long

JavaScript TypeScript C# Java Haxe

`type`

field

public final String type

The type of the node as a string (e.g. "Script", "Beat", "Text", "Dialogue").

Returns String String representation of node type

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

`toJson`

method

public String toJson(boolean pretty)

public String toJson()

Converts the node to a JSON string representation. This can be used for debugging or serialization purposes.

Parameter	Type	Description
`pretty`	`boolean`

Returns String a JSON string representation of the node

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

`fromJson`

method

public static Node fromJson(String json)

Reconstructs a Node from a JSON string.

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

Returns Node the reconstructed Node

JavaScript TypeScript C# Java PHP Python Lua Haxe

`line`

field

public final int line

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

Returns int

`column`

field

public final int column

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

Returns int

`offset`

field

public final int offset

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

Returns int

`length`

field

public final int length

The length of the source text span this node represents. A value of 0 indicates a point position rather than a span.

Returns int

`nodeIdToString`

method

public String nodeIdToString()

Returns the human-readable node ID string (e.g. "1.0.0.0").

Returns String the node ID as a dotted string

`InterpreterOptions`

class

Options for configuring a Loreline interpreter.

`functions`

field

public Map<String, LorelineFunction> functions

Optional map of custom functions to make available in the script.

Returns Map<String, LorelineFunction>

JavaScript TypeScript C# GDScript C++ Java Haxe

`strictAccess`

field

public boolean strictAccess

Whether to enable strict variable access (throw on undefined variables).

Returns boolean

JavaScript TypeScript C# GDScript C++ Java Haxe

`customCreateFields`

field

public CreateFieldsHandler customCreateFields

A custom instantiator to create fields objects.

Returns CreateFieldsHandler

JavaScript TypeScript C# Java Haxe

`translations`

field

public Object translations

Optional translations map for localization.

Returns Object

JavaScript TypeScript C# GDScript C++ Java Haxe

`InterpreterOptions`

constructor

public InterpreterOptions()

`ChoiceOption`

class

Represents a choice option presented to the user.

`text`

field

public final String text

The text of the choice option.

Returns String

JavaScript TypeScript C# C++ Java PHP Python Haxe

`tags`

field

public final List<TextTag> tags

Any tags associated with the choice text.

Returns List<TextTag>

JavaScript TypeScript C# C++ Java PHP Python Haxe

`enabled`

field

public final boolean enabled

Whether this choice option is currently enabled.

Returns boolean

JavaScript TypeScript C# C++ Java PHP Python Haxe

`ChoiceOption`

constructor

public ChoiceOption(String text, List<TextTag> tags, boolean enabled)

Parameter	Type	Description
`text`	`String`
`tags`	`List<TextTag>`
`enabled`	`boolean`

`TextTag`

class

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

`closing`

field

public final boolean closing

Whether this is a closing tag.

Returns boolean

JavaScript TypeScript C# C++ Java PHP Python Haxe

`value`

field

public final String value

The value or name of the tag.

Returns String

JavaScript TypeScript C# C++ Java PHP Python Haxe

`offset`

field

public final int offset

The offset in the text where this tag appears.

Returns int

JavaScript TypeScript C# C++ Java PHP Python Haxe

`TextTag`

constructor

public TextTag(boolean closing, String value, int offset)

Parameter	Type	Description
`closing`	`boolean`
`value`	`String`
`offset`	`int`

`DialogueHandler`

interface

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

`handle`

method

void handle(Interpreter interpreter, String character, String text, List<TextTag> tags, Runnable advance)

Called when dialogue text should be displayed.

Parameter	Type	Description
`interpreter`	`Interpreter`	the interpreter instance
`character`	`String`	the character speaking (null for narrator text)
`text`	`String`	the text content to display
`tags`	`List<TextTag>`	any tags in the text
`advance`	`Runnable`	function to call when the text has been displayed

Returns void

`ChoiceHandler`

interface

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

`handle`

method

void handle(Interpreter interpreter, List<ChoiceOption> options, IntConsumer select)

Called when choices should be presented.

Parameter	Type	Description
`interpreter`	`Interpreter`	the interpreter instance
`options`	`List<ChoiceOption>`	the available choice options
`select`	`IntConsumer`	function to call with the index of the selected choice

Returns void

`FinishHandler`

interface

Handler type to be called when the execution finishes.

`handle`

method

void handle(Interpreter interpreter)

Called when the script execution completes.

Parameter	Type	Description
`interpreter`	`Interpreter`	the interpreter instance

Returns void

`ImportsFileHandler`

interface

Handler function for loading file imports

`handle`

method

void handle(String path, Consumer<String> callback)

Called to resolve a file import.

Parameter	Type	Description
`path`	`String`	the path of the file to import
`callback`	`Consumer<String>`	function to invoke with the file content (or `null` if the file cannot be found). Must be called exactly once, either synchronously or later.

Returns void

`CreateFieldsHandler`

interface

`create`

method

Object create(Interpreter interpreter, String type)

Parameter	Type	Description
`interpreter`	`Interpreter`
`type`	`String`

Returns Object

`LorelineFunction`

interface

`call`

method

Object call(Interpreter interpreter, Object[] args)

Called when the function is invoked from the script.

Parameter	Type	Description
`interpreter`	`Interpreter`	the interpreter instance
`args`	`Object[]`	the arguments passed to the function

Returns Object the result of the function

Generated from Loreline v0.10.0.

Java API Reference

Quick reference

Loreline#

parse#

play#

resume#

extractTranslations#

loadLocale#

translationFormat#

lastError#

print#

update#

Interpreter#

Interpreter#

start#

save#

restore#

resume#

getCharacter#

getCharacterField#

setCharacterField#

getStateField#

setStateField#

getTopLevelStateField#

setTopLevelStateField#

currentNode#

Script#

fromJson#

Node#

id#

type#

toJson#

fromJson#

line#

column#

offset#

length#

nodeIdToString#

InterpreterOptions#

functions#

strictAccess#

customCreateFields#

translations#

InterpreterOptions#

ChoiceOption#

text#

tags#

enabled#

ChoiceOption#

TextTag#

closing#

value#

offset#

TextTag#

DialogueHandler#

handle#

ChoiceHandler#

handle#

FinishHandler#

handle#

ImportsFileHandler#

handle#

CreateFieldsHandler#

create#

LorelineFunction#

call#

`Loreline`

`parse`

`play`

`resume`

`extractTranslations`

`loadLocale`

`translationFormat`

`lastError`

`print`

`update`

`Interpreter`

`Interpreter`

`start`

`save`

`restore`

`resume`

`getCharacter`

`getCharacterField`

`setCharacterField`

`getStateField`

`setStateField`

`getTopLevelStateField`

`setTopLevelStateField`

`currentNode`

`Script`

`fromJson`

`Node`

`id`

`type`

`toJson`

`fromJson`

`line`

`column`

`offset`

`length`

`nodeIdToString`

`InterpreterOptions`

`functions`

`strictAccess`

`customCreateFields`

`translations`

`InterpreterOptions`

`ChoiceOption`

`text`

`tags`

`enabled`

`ChoiceOption`

`TextTag`

`closing`

`value`

`offset`

`TextTag`

`DialogueHandler`

`handle`

`ChoiceHandler`

`handle`

`FinishHandler`

`handle`

`ImportsFileHandler`

`handle`

`CreateFieldsHandler`

`create`

`LorelineFunction`

`call`