← Documentation

JavaScript API Reference

The complete public API of the Loreline runtime.

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

Quick reference

TypeMembers
Loreline parse play resume extractTranslations loadLocale translationFormat lastError print
Interpreter constructor start save restore resume getCharacter getCharacterField setCharacterField getStateField setStateField getTopLevelStateField setTopLevelStateField currentNode currentNodeFilePath
Script body filePath fromJson
Node id pos type toJson fromJson each
InterpreterOptions functions strictAccess customCreateFields translations
ChoiceOption text tags enabled
TextTag closing value offset
DialogueHandler
ChoiceHandler
FinishHandler
ImportsFileHandler
ImportsErrorHandler
FunctionsMap
Translations
SaveData
Tokens
Error message pos stack toString
Position line column offset length toString
NodeId toString toInt64
Int64 high low
Fields lorelineCreate lorelineGet lorelineSet lorelineExists lorelineFields

Loreline

class

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

parse

method 

parse(input, filePath, handleFile, callback)

Parses the given text input and creates an executable Script instance from it.

ParameterTypeDescription
input string The Loreline script content as a string (.lor format)
filePath string Optional file path of the input being parsed. If provided, requires handleFile as well. optional
handleFile ImportsFileHandler Optional file handler to read imports. If that handler is asynchronous, then parse() will return null and callback argument should be used optional
callback (script: Script) => void If provided, will be called with the resulting script as argument. Mostly useful when reading file imports asynchronously optional

Returns Script | null 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 

play(script, handleDialogue, handleChoice, handleFinish, beatName, options)

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

ParameterTypeDescription
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
beatName string Optional name of a specific beat to start from (defaults to first beat) optional
options InterpreterOptions Additional options optional

Returns 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

resume

method 

resume(script, handleDialogue, handleChoice, handleFinish, saveData, beatName, options)

Resumes a previously saved Loreline script from its saved state.

ParameterTypeDescription
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 SaveData The saved game data (typically from interpreter.save())
beatName string Optional beat name to override where to resume from optional
options InterpreterOptions Optional options to configure interpreter behavior optional

Returns 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

extractTranslations

method 

extractTranslations(script)

Extracts translations from a parsed translation script.

ParameterTypeDescription
script Script The parsed translation script (result from parse() on a .XX.lor file)

Returns 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

loadLocale

method 

loadLocale(locale, script, filePath, handleFile, callback)

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

ParameterTypeDescription
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)
filePath string | null 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
handleFile ImportsFileHandler File handler used to read translation files optional
callback (translations: Translations) => void Called with the merged translations map. Required if handleFile is asynchronous. optional

Returns Translations | null 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

translationFormat

method 

translationFormat(name, enabled)

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

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

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

lastError

method 

lastError()

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

Returns Error | null

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

method 

print(script, indent, newline)

Prints a parsed script back into Loreline source code.

ParameterTypeDescription
script Script The parsed script (result from parse())
indent string The indentation string to use (defaults to two spaces) optional
newline string The newline string to use (defaults to "\n") optional

Returns string The printed source code as a string

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

Interpreter

class

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.

constructor

constructor 

constructor(script, handleDialogue, handleChoice, handleFinish, options)

Creates a new Loreline script interpreter.

ParameterTypeDescription
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
options InterpreterOptions Additional options optional

JavaScript TypeScript C# Java Python Haxe

start

method 

start(beatName)

Starts script execution from the beginning or a specific beat.

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

method 

save()

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.

Returns SaveData A SaveData object containing the serialized state

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

restore

method 

restore(saveData)

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

ParameterTypeDescription
saveData SaveData 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 

resume()

Resumes execution after restoring state. This should be called after restore() to continue execution.

Returns void

JavaScript TypeScript C# Java PHP Python Lua Haxe

getCharacter

method 

getCharacter(name)

Gets a character by name.

ParameterTypeDescription
name string The name of the character to get

Returns any The character's fields or null if the character doesn't exist

JavaScript TypeScript C# Java PHP Python Lua Haxe

getCharacterField

method 

getCharacterField(character, name)

Gets a specific field of a character.

ParameterTypeDescription
character string The name of the character
name string The name of the field to get

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

Container values (key-value objects and arrays) are plain JS objects and arrays: field accessors and custom functions exchange idiomatic JS values in both directions.

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

setCharacterField

method 

setCharacterField(character, name, value)

Sets a specific field of a character.

ParameterTypeDescription
character string The name of the character
name string The name of the field to set
value any The value to set

Returns void

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

getStateField

method 

getStateField(name)

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

ParameterTypeDescription
name string The name of the field to get

Returns any The field value or null if not found

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

setStateField

method 

setStateField(name, value)

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

ParameterTypeDescription
name string The name of the field to set
value any The value to set

Returns void

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

getTopLevelStateField

method 

getTopLevelStateField(name)

Gets a field from the top-level state directly.

ParameterTypeDescription
name string The name of the field to get

Returns any The field value or null if not found

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

setTopLevelStateField

method 

setTopLevelStateField(name, value)

Sets a field on the top-level state directly.

ParameterTypeDescription
name string The name of the field to set
value any The value to set

Returns void

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

currentNode

method 

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

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

currentNodeFilePath

method 

currentNodeFilePath(rootPath)

Returns the file path of the file containing the current node. Resolves through import chains relative to the given root file path.

ParameterTypeDescription
rootPath string The file path of the root/main script

Returns string The file path of the file containing the current node, or rootPath if in the root file

JavaScript TypeScript Haxe

Script

class

Represents the root node of a Loreline script AST.

body

property 

body

Array of top-level declarations in the script.

Returns Array<Node>

JavaScript TypeScript Haxe

filePath

property 

filePath

The file path this script was parsed from. May be null if the script was parsed without a file path.

Returns string | null

JavaScript TypeScript Haxe

fromJson

method 

fromJson(json)

Reconstructs a Script from a JSON representation.

ParameterTypeDescription
json any 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 AST nodes. Contains position information and basic JSON conversion.

id

property 

id

A unique identifier for this node within the AST, used to distinguish it from other nodes in the script.

Returns NodeId

JavaScript TypeScript C# Java Haxe

pos

property 

pos

Source code position where this node appears.

Returns Position

JavaScript TypeScript Haxe

type

method 

type()

Returns the type of this node.

Returns string String representation of node type

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

toJson

method 

toJson()

Converts the node to a JSON representation.

Returns any Object containing node type and position

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

fromJson

method 

fromJson(json)

Reconstructs a Node from a JSON representation.

ParameterTypeDescription
json any The JSON object (as returned by node.toJson())

Returns Node The reconstructed Node

JavaScript TypeScript C# Java PHP Python Lua Haxe

each

method 

each(handleNode)

Traverses all child nodes of this node.

ParameterTypeDescription
handleNode (node: Node, parent: Node) => void Function to call for each child node

Returns void

JavaScript TypeScript Haxe

InterpreterOptions

interface

Options used to configure the Loreline interpreter behavior

functions

property 

functions

Optional map of additional functions to make available to the script

Returns FunctionsMap

JavaScript TypeScript C# GDScript C++ Java Haxe

strictAccess

property 

strictAccess

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

Returns boolean

JavaScript TypeScript C# GDScript C++ Java Haxe

customCreateFields

property 

customCreateFields()

A custom instantiator to create fields objects.

Returns (interpreter: Interpreter, type: string, node: Node) => any

JavaScript TypeScript C# Java Haxe

translations

property 

translations

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

Returns Translations

JavaScript TypeScript C# GDScript C++ Java Haxe

ChoiceOption

interface

Represents a choice option presented to the user.

text

property 

text

The text of the choice option.

Returns string

JavaScript TypeScript C# C++ Java PHP Python Haxe

tags

property 

tags

Any tags associated with the choice text.

Returns Array<TextTag>

JavaScript TypeScript C# C++ Java PHP Python Haxe

enabled

property 

enabled

Whether this choice option is currently enabled.

Returns boolean

JavaScript TypeScript C# C++ Java PHP Python Haxe

TextTag

interface

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

closing

property 

closing

Whether this is a closing tag.

Returns boolean

JavaScript TypeScript C# C++ Java PHP Python Haxe

value

property 

value

The value or name of the tag.

Returns string

JavaScript TypeScript C# C++ Java PHP Python Haxe

offset

property 

offset

The offset in the text where this tag appears.

Returns number

JavaScript TypeScript C# C++ Java PHP Python Haxe

DialogueHandler

type alias

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

ChoiceHandler

type alias

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

FinishHandler

type alias

Handler type to be called when the execution finishes.

ImportsFileHandler

type alias

Handler function for loading file imports

ImportsErrorHandler

type alias

Handler function for import errors

FunctionsMap

type alias

Map of function names to their implementations

Translations

type alias

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

SaveData

type alias

Opaque type for saved game data.

Tokens

type alias

Tokens type

Error

interface

Represents an error in the Loreline system.

message

property 

message

The error message describing what went wrong.

Returns string

JavaScript TypeScript

pos

property 

pos

The position in the source code where the error occurred.

Returns Position

JavaScript TypeScript

stack

property 

stack

The call stack of this error

Returns Array<any>

JavaScript TypeScript

toString

method 

toString()

Converts the error to a human-readable string.

Returns string Formatted error message with position

JavaScript TypeScript

Position

interface

Represents a position within source code, tracking line number, column, and offset information. Used throughout the compiler to pinpoint locations of tokens, nodes, and error messages.

line

property 

line

The line number in the source code, starting from 1.

Returns number

JavaScript TypeScript

column

property 

column

The column number in the source code, starting from 1. Represents the character position within the current line.

Returns number

JavaScript TypeScript

offset

property 

offset

The absolute character offset from the start of the source code. Used for precise positioning and span calculations.

Returns number

JavaScript TypeScript

length

property 

length

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

Returns number

JavaScript TypeScript

toString

method 

toString()

Converts the position to a human-readable string.

Returns string Formatted position string

JavaScript TypeScript

NodeId

interface

Represents a unique identifier for a node within the AST. Uses a structured ID system with section, branch, block, and node components.

toString

method 

toString()

Converts the NodeId to a string representation.

Returns string String in the format "section.branch.block.node"

JavaScript TypeScript C# Haxe

toInt64

method 

toInt64()

Converts the NodeId to its Int64 representation.

Returns Int64 The Int64 value of this NodeId

JavaScript TypeScript Haxe

Int64

interface

An object to store a Int64 from two high and low number values.

high

property 

high

High value of the Int64

Returns number

JavaScript TypeScript

low

property 

low

Low value of the Int64

Returns number

JavaScript TypeScript

Fields

interface

Base interface to hold loreline values This interface allows to map loreline object fields to game-specific objects.

lorelineCreate

method 

lorelineCreate(interpreter)

Called when the object has been created from an interpreter

ParameterTypeDescription
interpreter Interpreter

Returns void

JavaScript TypeScript C# Haxe

lorelineGet

method 

lorelineGet(interpreter, key)

Get the value associated to the given field key

ParameterTypeDescription
interpreter Interpreter
key string

Returns any

JavaScript TypeScript C# Haxe

lorelineSet

method 

lorelineSet(interpreter, key, value)

Set the value associated to the given field key

ParameterTypeDescription
interpreter Interpreter
key string
value any

Returns void

JavaScript TypeScript C# Haxe

lorelineExists

method 

lorelineExists(interpreter, key)

Check if a value exists for the given key

ParameterTypeDescription
interpreter Interpreter
key string

Returns boolean

JavaScript TypeScript C# Haxe

lorelineFields

method 

lorelineFields(interpreter)

Get all the fields of this object

ParameterTypeDescription
interpreter Interpreter

Returns string[]

JavaScript TypeScript C# Haxe

Generated from Loreline v0.10.0.

See also
JavaScript →
Run Loreline scripts in Node.js or the browser.
API Reference →
Every public class and method of the Loreline runtime, for each target language.