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.

Instance Members #

Optional translations map (localization key -> translated string literal). When set, evaluateString() substitutes tagged text with translated versions.

Pluggable processors that transform string literals before evaluation. Each processor receives an NStringLiteral and returns a (possibly transformed) NStringLiteral.

Starts script execution from the beginning or a specific beat.

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

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

Gets a character by name.

Gets a specific field of a character.

Sets a specific field on a character.

Sets a state field by name, resolving from the current scope outward. Walks the execution stack from innermost scope to outermost to find the field, then falls back to the top-level state if not found anywhere.

Gets a field from the top-level state directly.

Sets a field on the top-level state directly.

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 the file path of the file containing the current node. Uses the Lens to walk up through import statements and resolve the path relative to the given root file path.

Resolves a beat by name against the RUNTIME scope walk (registered nested beats first, then top-level beats). Only used as fallback for node-less contexts (function code, engine helpers); node-anchored resolution goes through resolveBeatRefFromNode (lexical).

Resolves a beat by name like resolveBeatByName, but also builds the scope chain to capture for a beat reference: the resolution path from the root up to and including the declaring scope (empty for top-level beats). Used to create RuntimeBeatRef values.

Resolves a beat by name from the given node's LEXICAL position, using the same resolution as the editor (Lens): innermost enclosing beat outward, order-independent, nested beats shadowing outer and top-level ones. When the resolved beat's declaring scope is live on the stack, the returned reference captures that scope chain (like beat references do), so the beat keeps its lexical context when invoked.

Falls back to the runtime scope walk only when no node is available (function code and engine helpers).

Creates a new Loreline script interpreter.

Private Members #

The script being executed.

User-defined dialogue handler, which takes care of displaying the dialogues.

User-defined choice handler, which takes care of displaying the choices and providing a response to the interpreter.

User-defined finish handler, which is called when the current execution has finished.

The top level state, which is shared across the whole script execution.

Top level characters can be referenced and their state can also be modified from anywhere in the script.

All the top level beats available, by beat name (their identifier in the script).

States associated to a specific node id. These are persistent, like the top level state, but are only available from where they have been declared and the sub-scopes. If some state fields already existed in a parent scope, the parent ones will be shadowed by the child ones.

Top level functions available by default in this script.

Built-in functions instance, giving access to RNG for alternative blocks.

The current execution stack, which consists of scopes added on top of one another. Each scope can have its own local beats and temporary states.

The lens instance allowing to get more information about the AST.

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

Current scope associated with current execution state.

Current insertion associated with current scope or a parent scope, with current execution state.

The next scope id to assign when pushing a new scope. Every time we reset the stack, this counter is also reset.

The next insertion id to assign when creating a new insertion. Every time we reset the stack, this counter is also reset.

List of pending callbacks that should be run synchronously.

Internal flag to know if we are currently flushing sync callbacks (to prevent unexpected recursive flushes).

Keep track of which callback is the one that would trigger finish.

When loading saved data and failing to restore a full stack of scope, this contains the beat to resume as fallback. That beat will always be a top level beat.

When a choice with insertions is waiting for user input, this holds the collected options. Persisted in save data so that on restore, insertion bodies are not re-evaluated (which would cause side effects to run twice).

Nearest insertion carried by a scope at or below the given stack level.

A custom instanciator to create fields objects.

Registers an implicit (empty) character for every dialogue speaker mentioned inside the default unnamed beat ("_"), unless a top-level character or state field already uses that name. Runs after explicit declarations are initialized so it never overrides them.

Walks scopes for name resolution, innermost to outermost, starting at startIndex (-1 for the innermost scope). When a scope carries a captured chain (the closure boundary of a beat invoked through a beat reference), the walk diverts into that chain (innermost to outermost, recursively) and then STOPS, skipping the scopes below the boundary: resolution inside a ref-invoked beat is lexical, not dynamic. visit returns true to stop the walk.

Serializes a scope to save data.

Serializes a state to save data.

Serializes all top-level characters to save data.

Serializes all node states to save data.

Serializes a beat reference for save data.

Serializes a node reference for save data.

Serializes a character for save data.

Serializes fields for save data. Only fields that have changed from their original values are included.

Serializes a value for save data. Handles recursive serialization of objects and arrays.

Core function that resumes execution from a given scope. Works by recreating the execution flow as if we had been running from the beginning.

Resumes execution of a node body.

Resumes execution of a beat.

Resumes execution of a choice option.

Resumes execution of a choice

Resumes execution of an if statement.

Resumes execution of an alternative block.

Resumes execution of a beat call.

Resumes execution through a dynamic beat call statement (beat(expr)). The restored child scope already knows which beat it was running (restored by node id), so no expression re-evaluation is needed.

Restores the execution stack from saved data.

Restores a single scope from saved data, including its insertion reference. Used by both restoreStack() (for the main stack) and restoreInsertion() (for insertion stacks).

Restores a RuntimeInsertion from serialized data. Uses a cache to handle circular references (insertion.stack contains scopes that reference the same insertion).

Restores a ChoiceOption from serialized data.

Finds the top-level beat to resume from if stack restoration fails.

Restores a node from a saved reference.

Restores a beat from a saved reference.

Restores a state from saved data.

Restores characters from saved data.

Restores node states from saved data.

Restores a character from saved data.

Restores fields from saved data.

Restores a value from its saved form. Handles recursive restoration of objects and arrays.

Initializes top-level functions available to the script. This includes built-in functions and any user-provided functions.

Registers a single host-provided function under key.

Host functions registered via the public API are documented to receive (interpreter, args). The core calls functions with the script arguments spread positionally (like built-ins), so on bindings without a native adapter we wrap each one to re-collect those into an array and prepend the interpreter. Bindings with their own adapter (JVM/C#/C++) don't set the loreline_auto_wrap_functions define and store the function as-is.

Wraps a callback function to control whether it executes synchronously or asynchronously. This is crucial for managing the execution flow of the script.

Flushes all pending synchronous callbacks. This ensures that all pending operations are completed before continuing.

Pops the top scope from the execution stack.

Pushes a new scope onto the execution stack.

Initializes a top-level state declaration. Evaluates all fields and stores their values.

Initializes a top-level beat declaration. Registers the beat in the top-level beats map.

Initializes a top-level character declaration. Creates a new character state and evaluates all fields.

Initializes a state declaration within a scope. Evaluates all fields and stores their values.

Evaluates transition/insertion/call arguments in the caller scope and checks arity against the target beat's declared parameters. Returns the evaluated values, or null when there are no arguments.

Seeds beat parameters as beat-scoped temporary state on the given scope. Missing arguments get their default value (evaluated now, in the new scope, so defaults can read outer state), or null.

Finishes script execution and calls the finish handler.

Transitions to a new beat, clearing the current execution stack.

Evaluates a node, dispatching to the appropriate handler based on node type.

Evaluates a beat declaration. Adds the beat to the current scope so it can be referenced by other nodes.

Evaluates a node body by creating a new scope and executing each node in sequence.

Evaluates a beat by executing its body.

Evaluates a state declaration. Initializes the state fields with their evaluated values.

Evaluates a text statement by evaluating the content and calling the dialogue handler.

Evaluates a dialogue statement by evaluating the content and calling the dialogue handler.

Evaluates a choice statement by evaluating the options and calling the choice handler.

Phase 2 of choice evaluation: present collected options to the user and handle their selection.

Evaluates a dynamic beat call statement: beat(expr, args...). Runs the resolved beat as a stack-preserving call, carrying the captured scope chain when the target is a beat reference.

Evaluates a choice option by executing its body.

Evaluates an if statement by evaluating the condition and executing the appropriate branch.

Evaluates an alternative block (sequence, cycle, once, pick, shuffle).

Executes alternative items in shuffled order, one at a time.

Gets the visit count for a beat from nodeStates.

Increments the visit count for a beat in nodeStates.

Gets the visit count for an alternative block from nodeStates.

Sets the visit count for an alternative block in nodeStates.

Returns whether a once-only choice option has already been chosen.

Marks a once-only choice option as chosen in nodeStates.

Evaluates an assignment by resolving the target, evaluating the value, and applying the assignment.

Determines whether an expression is an "original script expression" - meaning it only depends on values directly present in the script and not on runtime state.

Original script expressions can be evaluated at parse time and safely stored as default values, as they don't depend on dynamic context like variables or function calls that might change during runtime.

Determines if a node is a beat call. A beat call is a special function call that executes a beat instead of a normal function.

Returns true if the call is the dynamic call(target, args...) special form: a bare call identifier that isn't shadowed by any script binding.

Builds the scope chain to capture for a lexically resolved beat: the live scopes from root up to and including the beat's declaring scope, honoring closure boundaries. Returns an empty array when the beat is top-level or its declaring scope is not live (chainless).

Resolves a runtime value to a beat reference, for dynamic targets like beat(expr), -> beat(expr) and + beat(expr). Accepts a beat reference (keeps its captured chain), a beat value (wrapped without capture), or a string resolved lexically from the node's position (capturing the declaring chain when it is live, exactly like static name resolution).

Builds the error for an unresolved beat name. When the name exists somewhere else in the script (another scope), the error teaches the beat-reference workflow instead of just failing.

Resolves a call node to a beat reference if the call's target is a bare identifier naming a beat (lexical resolution from the call's position). This allows handling beat calls differently from regular function calls.

Evaluates a call node. If the call references a beat, it executes the beat. Otherwise, it evaluates it as a regular function call.

Evaluates a transition node. Transitions cause execution to jump to a different beat, clearing the current execution stack.

If translations are available, checks for a hash comment on the node and returns the translated string literal if found. Otherwise returns the original string.

Walks the import ancestor chain from the node's own file up to root, trying each scoped key in turn. A translation defined in an ancestor's .<lang>.lor file applies to descendants that don't translate the same key themselves. Siblings (non-ancestor files) never share translations.

Evaluates a string literal into text with tags. This handles interpolation and tag processing.

Processes plural pipe syntax in string literal parts. Transforms word1|word2 and (text1|text2) patterns in Raw parts preceded by Expr parts into synthetic NCall nodes that invoke the plural() function.

Evaluates a condition expression for an if statement or choice option. Converts the result to a boolean according to Loreline's rules.

Invokes an already-resolved function value with evaluated arguments. Handles async results and wraps errors, exactly like standalone function calls always did.

Returns true if the given bare identifier resolves to any existing binding: scope temporary state, node state, top level state field, character, function or beat. Unlike resolveAccess(), this never auto-creates anything and never throws.

Evaluates the call(target, args...) special form: the first argument resolves to a FUNCTION (a function value, or a string naming one), called with the remaining arguments. Beats are rejected with a hint to use beat(...) instead.

Evaluates a function call in an expression context. If next is provided, the function may execute asynchronously. If next is null, the function must execute synchronously.

Evaluates an array literal to a runtime array. Each element is evaluated recursively.

Evaluates an object literal to a runtime object. Each field value is evaluated recursively.

Evaluates an expression to its runtime value. This is the core expression evaluation function that handles all expression types.

Reads the value from a runtime access. This handles field access, array access, character access, and function access.

Writes a value to a runtime access location. This handles field access and array access. Character and function access cannot be written to.

Resolves an assignment target to a runtime access. This is used to determine where to write a value in an assignment.

Resolves an access expression to a runtime access. This handles finding variables, character fields, and functions in the appropriate scopes.

Helper for getting human-readable type names in errors

Performs a binary operation on two values. Handles arithmetic, comparison, and logical operations.

Converts a value to its string representation. Used for string interpolation and output.

Metadata #