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
Engine
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 onLorelineis a static method ofEnginehere.
Parse
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.
| Parameter | Type | Description |
|---|---|---|
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
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.
| Parameter | Type | Description |
|---|---|---|
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
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.
| Parameter | Type | Description |
|---|---|---|
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
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 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
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.
| 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)
|
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
public static void TranslationFormat(string name, bool enabled)
Enable or disable runtime support for an alternate translation file format.
| 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. 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
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.
Print
public static string Print(Script script, string indent = " ", string newline = "\n")
Prints a parsed script back into Loreline source code.
| Parameter | Type | Description |
|---|---|---|
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
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().
| Parameter | Type | Description |
|---|---|---|
delta |
double |
Time elapsed since last frame in seconds |
Returns
void
Interpreter
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
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 |
Start
public void Start(string beatName = null)
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.
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
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
public void Restore(string savedData)
Restores the interpreter state from a previously saved state. This allows resuming execution 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
public void Resume()
Resumes execution after restoring state. This should be called after Restore() to continue execution.
Returns
void
GetCharacter
public object GetCharacter(string name)
Gets a character by name.
| Parameter | Type | Description |
|---|---|---|
name |
string |
The name of the character to get |
Returns
object
The character's fields or null if the character doesn't exist
GetCharacterField
public object GetCharacterField(string character, string name)
Gets a specific field of a character.
| Parameter | Type | Description |
|---|---|---|
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
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 if not found
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
SetStateField
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
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 if not found
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
SetTopLevelStateField
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
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
Represents the root node of a Loreline script AST.
FromJson
public static new 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
Script
public Script(Runtime.Script runtimeScript) : base(runtimeScript)
Creates a new Script instance with the provided runtime script.
| Parameter | Type | Description |
|---|---|---|
runtimeScript |
Runtime.Script |
The parsed runtime script to wrap |
Node
Represents a node in a Loreline AST.
Id
public readonly NodeId Id
The id of this node (should be unique within a single script hierarchy)
Returns
NodeId
Type
public readonly string Type
The type of the node as string
Returns
string
String representation of node type
ToJson
public string ToJson(bool pretty = false)
Converts the node to a JSON representation. This can be used for debugging or serialization purposes.
| Parameter | Type | Description |
|---|---|---|
pretty |
bool |
optional: false
|
Returns
string
A JSON string representation of the node
JavaScript TypeScript C# GDScript C++ Java PHP Python Lua Haxe
FromJson
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
Line
public readonly int Line
The line number in the source code where this node appears (1-based).
Returns
int
Column
public readonly int Column
The column number in the source code where this node appears (1-based).
Returns
int
Offset
public readonly int Offset
The absolute character offset from the start of the source code.
Returns
int
Length
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
public Node(Runtime.Node runtimeNode)
| Parameter | Type | Description |
|---|---|---|
runtimeNode |
Runtime.Node |
Interpreter.InterpreterOptions
Options used to configure the Loreline interpreter behavior
Functions
public Dictionary<string, Function> Functions
Optional map of additional functions to make available to the script
Returns
Dictionary<string, Function>
StrictAccess
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
CustomCreateFields
public CreateFields CustomCreateFields
A custom instantiator to create fields objects.
Returns
CreateFields
Translations
public object Translations
Optional translations map for localization. Built from a parsed translation file using Engine.ExtractTranslations().
Returns
object
Default
public static InterpreterOptions Default()
Retrieve default interpreter options
Returns
InterpreterOptions
Interpreter.ChoiceOption
Represents a choice option presented to the user.
Text
public string Text
The text of the choice option.
Returns
string
Tags
public TextTag[] Tags
Any tags associated with the choice text.
Returns
TextTag[]
Enabled
public bool Enabled
Whether this choice option is currently enabled.
Returns
bool
Interpreter.TextTag
Represents a tag in text content, which can be used for styling or other purposes.
Closing
public bool Closing
Whether this is a closing tag.
Returns
bool
Value
public string Value
The value or name of the tag.
Returns
string
Offset
public int Offset
The offset in the text where this tag appears.
Returns
int
Interpreter.DialogueHandler
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), readingdialogue.Character,dialogue.Textand callingdialogue.Callback().
Interpreter.ChoiceHandler
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
public delegate void FinishHandler(Finish finish)Handler type to be called when the execution finishes.
Engine.ImportsFileHandler
public delegate void ImportsFileHandler(string path, ImportsFileCallback callback)Handler function for loading file imports
NodeId
Represents a unique identifier for a node within the AST. Uses a structured ID system with section, branch, block, and node components.
ToString
public override string ToString()
Converts the NodeId to a string representation.
Returns
string
String in the format "section.branch.block.node"
operator NodeId
public NodeId(long value)public static implicit operator NodeId(long value)
| Parameter | Type | Description |
|---|---|---|
value |
long |
Returns
NodeId
operator long
public static explicit operator long(NodeId id)
| Parameter | Type | Description |
|---|---|---|
id |
NodeId |
Returns
long
operator string
public static explicit operator string(NodeId id)
| Parameter | Type | Description |
|---|---|---|
id |
NodeId |
Returns
string
IFields
Base interface to hold loreline values. This interface allows to map loreline object fields to game-specific objects.
LorelineCreate
void LorelineCreate(Interpreter interpreter)
Called when the object has been created from an interpreter
| Parameter | Type | Description |
|---|---|---|
interpreter |
Interpreter |
Returns
void
LorelineGet
object LorelineGet(Interpreter interpreter, string key)
Get the value associated to the given field key
| Parameter | Type | Description |
|---|---|---|
interpreter |
Interpreter |
|
key |
string |
Returns
object
The value associated with the key
LorelineSet
void LorelineSet(Interpreter interpreter, string key, object value)
Set the value associated to the given field key
| Parameter | Type | Description |
|---|---|---|
interpreter |
Interpreter |
|
key |
string |
|
value |
object |
Returns
void
LorelineExists
bool LorelineExists(Interpreter interpreter, string key)
Check if a value exists for the given key
| Parameter | Type | Description |
|---|---|---|
interpreter |
Interpreter |
|
key |
string |
Returns
bool
True if the key exists, false otherwise
LorelineFields
string[] LorelineFields(Interpreter interpreter)
Get all the fields of this object
| Parameter | Type | Description |
|---|---|---|
interpreter |
Interpreter |
Returns
string[]
An array of field keys
LorelineRemove
bool LorelineRemove(Interpreter interpreter, string key)
Remove the field associated to the given key
| Parameter | Type | Description |
|---|---|---|
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
public delegate void ImportsFileCallback(string data)Delivers the content of an imported file back to the parser.
Engine.ParseCallback
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
public delegate object Function(Interpreter interpreter, object[] args)Delegate type for functions that can be called from the script.
Interpreter.DialogueCallback
public delegate void DialogueCallback()Callback type for dialogue continuation.
Interpreter.Dialogue
Contains information about a dialogue to be displayed to the user.
Interpreter
public Interpreter Interpreter
The interpreter instance.
Returns
Interpreter
Character
public string Character
The character speaking (null for narrator text).
Returns
string
Text
public string Text
The text content to display.
Returns
string
Tags
public TextTag[] Tags
Any tags in the text.
Returns
TextTag[]
Callback
public DialogueCallback Callback
Function to call when the text has been displayed.
Returns
DialogueCallback
Interpreter.ChoiceCallback
public delegate void ChoiceCallback(int index)Callback type for choice selection.
Interpreter.Choice
Contains information about choices to be presented to the user.
Interpreter
public Interpreter Interpreter
The interpreter instance.
Returns
Interpreter
Options
public ChoiceOption[] Options
The available choice options.
Returns
ChoiceOption[]
Callback
public ChoiceCallback Callback
Function to call with the index of the selected choice.
Returns
ChoiceCallback
Interpreter.CreateFields
public delegate object CreateFields(Interpreter interpreter, string type, Node node)A custom instanciator to create fields objects.
Interpreter.Finish
Contains information about the script execution completion.
Interpreter
public Interpreter Interpreter
The interpreter instance.
Returns
Interpreter
Generated from Loreline v0.10.0.