C# API Reference

The complete public API of the Loreline runtime.

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

Quick reference

TypeMembers
Engine Parse Play Resume ExtractTranslations LoadLocale TranslationFormat LastError Print Update
Interpreter Interpreter Start Save Restore Resume GetCharacter GetCharacterField GetStateField SetStateField GetTopLevelStateField SetTopLevelStateField CurrentNode
Script FromJson Script
Node Id Type ToJson FromJson Line Column Offset Length Node
Interpreter.InterpreterOptions Functions StrictAccess CustomCreateFields Translations Default
Interpreter.ChoiceOption Text Tags Enabled
Interpreter.TextTag Closing Value Offset
Interpreter.DialogueHandler
Interpreter.ChoiceHandler
Interpreter.FinishHandler
Engine.ImportsFileHandler
NodeId ToString operator NodeId operator long operator string
IFields LorelineCreate LorelineGet LorelineSet LorelineExists LorelineFields LorelineRemove
Engine.ImportsFileCallback
Engine.ParseCallback
Interpreter.Function
Interpreter.DialogueCallback
Interpreter.Dialogue Interpreter Character Text Tags Callback
Interpreter.ChoiceCallback
Interpreter.Choice Interpreter Options Callback
Interpreter.CreateFields
Interpreter.Finish Interpreter

Engine

class

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

The static entry class is Loreline.Engine: everything the other targets put on Loreline is a static method of Engine here.

Parse

method

public static Script Parse(string input, string filePath = null, ImportsFileHandler handleFile = null, ParseCallback callback = null)

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: null
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: null
callback ParseCallback If provided, will be called with the resulting script as argument. Mostly useful when reading file imports asynchronously optional: null

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

public static Interpreter Play(Script script, Interpreter.DialogueHandler handleDialogue, Interpreter.ChoiceHandler handleChoice, Interpreter.FinishHandler handleFinish, string beatName = null)
public static Interpreter Play(Script script, Interpreter.DialogueHandler handleDialogue, Interpreter.ChoiceHandler handleChoice, Interpreter.FinishHandler handleFinish, Interpreter.InterpreterOptions options)
public static Interpreter Play(Script script, Interpreter.DialogueHandler handleDialogue, Interpreter.ChoiceHandler handleChoice, Interpreter.FinishHandler handleFinish, string beatName, Interpreter.InterpreterOptions options)

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

ParameterTypeDescription
script Script The parsed script (result from parse())
handleDialogue Interpreter.DialogueHandler Function called when dialogue text should be displayed
handleChoice Interpreter.ChoiceHandler Function called when player needs to make a choice
handleFinish Interpreter.FinishHandler Function called when script execution completes
beatName string Optional name of a specific beat to start from (defaults to first beat) optional: null

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

public static Interpreter Resume(Script script, Interpreter.DialogueHandler handleDialogue, Interpreter.ChoiceHandler handleChoice, Interpreter.FinishHandler handleFinish, string saveData, string beatName = null)
public static Interpreter Resume(Script script, Interpreter.DialogueHandler handleDialogue, Interpreter.ChoiceHandler handleChoice, Interpreter.FinishHandler handleFinish, string saveData, Interpreter.InterpreterOptions options)
public static Interpreter Resume(Script script, Interpreter.DialogueHandler handleDialogue, Interpreter.ChoiceHandler handleChoice, Interpreter.FinishHandler handleFinish, string saveData, string beatName, Interpreter.InterpreterOptions options)

Resumes a previously saved Loreline script from its saved state.

ParameterTypeDescription
script Script The parsed script (result from parse())
handleDialogue Interpreter.DialogueHandler Function called when dialogue text should be displayed
handleChoice Interpreter.ChoiceHandler Function called when player needs to make a choice
handleFinish Interpreter.FinishHandler Function called when script execution completes
saveData string The saved game data (typically from interpreter.save())
beatName string Optional beat name to override where to resume from optional: null

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

public static object ExtractTranslations(Script script)

Extracts translations from a parsed translation script.

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

Returns object A translations object to pass as Translations

Given a translation file parsed with Parse, this returns a translations map that can be passed as 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, string filePath = null, ImportsFileHandler handleFile = null)

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 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: null
handleFile ImportsFileHandler File handler used to read translation files optional: null

Returns object A translations object to pass as Translations

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. Pass the result to Translations.

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

TranslationFormat

method

public static void TranslationFormat(string name, bool enabled)

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

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

LastError

method

public static Runtime.Error LastError()

Returns the error from the most recent failed Parse or LoadLocale call, or null on success.

Returns 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, string indent = " ", string newline = "\n")

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: "\n"

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 (e.g., Unity's Update). The first call switches wait() from blocking Thread.Sleep to non-blocking deferred mode. To avoid the first-frame edge case, call Engine.Update(0) once before Engine.Play().

ParameterTypeDescription
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. This class is responsible for executing a parsed Loreline script, managing the runtime state, and interacting with the host application through handler functions.

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.

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

JavaScript TypeScript C# Java Python Haxe

Start

method

public void Start(string beatName = null)

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

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. This includes all state variables, character states, and execution stack, allowing execution to be resumed later from the exact same point.

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. This allows resuming execution from a previously saved state.

ParameterTypeDescription
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. This should be called after Restore() to continue execution.

Returns void

JavaScript TypeScript C# Java PHP Python Lua Haxe

GetCharacter

method

public object GetCharacter(string name)

Gets a character by name.

ParameterTypeDescription
name string The name of the character to get

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

JavaScript TypeScript C# Java PHP Python Lua Haxe

GetCharacterField

method

public object GetCharacterField(string character, string 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 object The field value or null if the character or field doesn't exist

JavaScript TypeScript C# 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.

ParameterTypeDescription
name string The name of the field to get

Returns object The field value or null if not found

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.

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

ParameterTypeDescription
name string The name of the field to get

Returns object The field value or null if not found

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.

ParameterTypeDescription
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 Loreline script AST.

FromJson

method

public static new Script FromJson(string json)

Reconstructs a Script from a JSON string.

ParameterTypeDescription
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

Script

constructor

public Script(Runtime.Script runtimeScript) : base(runtimeScript)

Creates a new Script instance with the provided runtime script.

ParameterTypeDescription
runtimeScript Runtime.Script The parsed runtime script to wrap

Node

class

Represents a node in a Loreline AST.

Id

property

public readonly NodeId Id

The id of this node (should be unique within a single script hierarchy)

Returns NodeId

JavaScript TypeScript C# Java Haxe

Type

property

public readonly string Type

The type of the node as string

Returns string String representation of node type

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

ToJson

method

public string ToJson(bool pretty = false)

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

ParameterTypeDescription
pretty bool optional: false

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.

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

Returns Node The reconstructed Node

JavaScript TypeScript C# Java PHP Python Lua Haxe

Line

property

public readonly int Line

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

Returns int

Column

property

public readonly int Column

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

Returns int

Offset

property

public readonly int Offset

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

Returns int

Length

property

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

Node

constructor

public Node(Runtime.Node runtimeNode)
ParameterTypeDescription
runtimeNode Runtime.Node

Interpreter.InterpreterOptions

struct

Options used to configure the Loreline interpreter behavior

Functions

property

public Dictionary<string, Function> Functions

Optional map of additional functions to make available to the script

Returns Dictionary<string, Function>

JavaScript TypeScript C# GDScript C++ Java Haxe

StrictAccess

property

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

JavaScript TypeScript C# GDScript C++ Java Haxe

CustomCreateFields

property

public CreateFields CustomCreateFields

A custom instantiator to create fields objects.

Returns CreateFields

JavaScript TypeScript C# Java Haxe

Translations

property

public object Translations

Optional translations map for localization. Built from a parsed translation file using Engine.ExtractTranslations().

Returns object

JavaScript TypeScript C# GDScript C++ Java Haxe

Default

method

public static InterpreterOptions Default()

Retrieve default interpreter options

Returns InterpreterOptions

Interpreter.ChoiceOption

struct

Represents a choice option presented to the user.

Text

property

public string Text

The text of the choice option.

Returns string

JavaScript TypeScript C# C++ Java PHP Python Haxe

Tags

property

public TextTag[] Tags

Any tags associated with the choice text.

Returns TextTag[]

JavaScript TypeScript C# C++ Java PHP Python Haxe

Enabled

property

public bool Enabled

Whether this choice option is currently enabled.

Returns bool

JavaScript TypeScript C# C++ Java PHP Python Haxe

Interpreter.TextTag

struct

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

Closing

property

public bool Closing

Whether this is a closing tag.

Returns bool

JavaScript TypeScript C# C++ Java PHP Python Haxe

Value

property

public string Value

The value or name of the tag.

Returns string

JavaScript TypeScript C# C++ Java PHP Python Haxe

Offset

property

public int Offset

The offset in the text where this tag appears.

Returns int

JavaScript TypeScript C# C++ Java PHP Python Haxe

Interpreter.DialogueHandler

delegate

public delegate void DialogueHandler(Dialogue dialogue)

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

Unlike the other targets, C# handlers take a single struct rather than positional parameters: void OnDialogue(Interpreter.Dialogue dialogue), reading dialogue.Character, dialogue.Text and calling dialogue.Callback().

Interpreter.ChoiceHandler

delegate

public delegate void ChoiceHandler(Choice choice)

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

Interpreter.FinishHandler

delegate

public delegate void FinishHandler(Finish finish)

Handler type to be called when the execution finishes.

Engine.ImportsFileHandler

delegate

public delegate void ImportsFileHandler(string path, ImportsFileCallback callback)

Handler function for loading file imports

NodeId

struct

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

ToString

method

public override string ToString()

Converts the NodeId to a string representation.

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

JavaScript TypeScript C# Haxe

operator NodeId

operator

public NodeId(long value)
public static implicit operator NodeId(long value)
ParameterTypeDescription
value long

Returns NodeId

operator long

operator

public static explicit operator long(NodeId id)
ParameterTypeDescription
id NodeId

Returns long

operator string

operator

public static explicit operator string(NodeId id)
ParameterTypeDescription
id NodeId

Returns string

IFields

interface

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

LorelineCreate

method

void LorelineCreate(Interpreter interpreter)

Called when the object has been created from an interpreter

ParameterTypeDescription
interpreter Interpreter

Returns void

JavaScript TypeScript C# Haxe

LorelineGet

method

object LorelineGet(Interpreter interpreter, string key)

Get the value associated to the given field key

ParameterTypeDescription
interpreter Interpreter
key string

Returns object The value associated with the key

JavaScript TypeScript C# Haxe

LorelineSet

method

void LorelineSet(Interpreter interpreter, string key, object value)

Set the value associated to the given field key

ParameterTypeDescription
interpreter Interpreter
key string
value object

Returns void

JavaScript TypeScript C# Haxe

LorelineExists

method

bool LorelineExists(Interpreter interpreter, string key)

Check if a value exists for the given key

ParameterTypeDescription
interpreter Interpreter
key string

Returns bool True if the key exists, false otherwise

JavaScript TypeScript C# Haxe

LorelineFields

method

string[] LorelineFields(Interpreter interpreter)

Get all the fields of this object

ParameterTypeDescription
interpreter Interpreter

Returns string[] An array of field keys

JavaScript TypeScript C# Haxe

LorelineRemove

method

bool LorelineRemove(Interpreter interpreter, string key)

Remove the field associated to the given key

ParameterTypeDescription
interpreter Interpreter The interpreter instance
key string The field key to remove

Returns bool True if the key was found and removed, false otherwise

C# Haxe

Engine.ImportsFileCallback

delegate

public delegate void ImportsFileCallback(string data)

Delivers the content of an imported file back to the parser.

Engine.ParseCallback

delegate

public delegate void ParseCallback(Script script)

Receives the parsed script when imports were resolved asynchronously.

Fires with null when parsing failed; Engine.LastError() then says why.

Interpreter.Function

delegate

public delegate object Function(Interpreter interpreter, object[] args)

Delegate type for functions that can be called from the script.

Interpreter.DialogueCallback

delegate

public delegate void DialogueCallback()

Callback type for dialogue continuation.

Interpreter.Dialogue

struct

Contains information about a dialogue to be displayed to the user.

Interpreter

property

public Interpreter Interpreter

The interpreter instance.

Returns Interpreter

Character

property

public string Character

The character speaking (null for narrator text).

Returns string

Text

property

public string Text

The text content to display.

Returns string

Tags

property

public TextTag[] Tags

Any tags in the text.

Returns TextTag[]

Callback

property

public DialogueCallback Callback

Function to call when the text has been displayed.

Returns DialogueCallback

Interpreter.ChoiceCallback

delegate

public delegate void ChoiceCallback(int index)

Callback type for choice selection.

Interpreter.Choice

struct

Contains information about choices to be presented to the user.

Interpreter

property

public Interpreter Interpreter

The interpreter instance.

Returns Interpreter

Options

property

public ChoiceOption[] Options

The available choice options.

Returns ChoiceOption[]

Callback

property

public ChoiceCallback Callback

Function to call with the index of the selected choice.

Returns ChoiceCallback

Interpreter.CreateFields

delegate

public delegate object CreateFields(Interpreter interpreter, string type, Node node)

A custom instanciator to create fields objects.

Interpreter.Finish

struct

Contains information about the script execution completion.

Interpreter

property

public Interpreter Interpreter

The interpreter instance.

Returns Interpreter

Generated from Loreline v0.10.0.