PHP API Reference

The complete public API of the Loreline runtime.

New to Loreline in PHP? 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`	`start` `save` `restore` `resume` `getCharacter` `getCharacterField` `setCharacterField` `getStateField` `setStateField` `getTopLevelStateField` `setTopLevelStateField` `currentNode`
`Script`	`fromJson`
`Node`	`type` `toJson` `fromJson` `__construct` `line` `column` `offset` `length` `nodeIdToString`
`ChoiceOption`	`text` `tags` `enabled` `__construct`
`TextTag`	`closing` `value` `offset` `__construct`

`Loreline`

class

Main public API for the Loreline interactive fiction runtime.

All methods are static. Typical usage:

$script = Loreline::parse($source); $interpreter = Loreline::play($script, $onDialogue, $onChoice, $onFinish);

Handler signatures:

dialogue: function(Interpreter $interpreter, ?string $character, string $text, TextTag[] $tags, callable $advance): void
choice: function(Interpreter $interpreter, ChoiceOption[] $options, callable $select): void
finish: function(Interpreter $interpreter): void
imports file handler: function(string $path, callable $callback): void

`parse`

method

public static function parse(string $source, ?string $filePath = null, ?callable $handleFile = null, ?callable $callback = null): ?Script

Parse a Loreline script string into a Script AST.

Parameter	Type	Description
`source`	`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`	`?callable`	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`	`?callable`	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().

$filePath enables import resolution and requires $handleFile. $callback receives the parsed Script, useful when $handleFile resolves asynchronously. Returns the parsed Script, or null when loading asynchronously. Throws if the script contains syntax errors.

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

`play`

method

public static function play(Script $script, callable $handleDialogue, callable $handleChoice, callable $handleFinish, ?string $beatName = null, ?array $options = null): Interpreter

Start playing a parsed script.

Parameter	Type	Description
`script`	`Script`	The parsed script (result from `parse()`)
`handleDialogue`	`callable`	Function called when dialogue text should be displayed
`handleChoice`	`callable`	Function called when player needs to make a choice
`handleFinish`	`callable`	Function called when script execution completes
`beatName`	`?string`	Optional name of a specific beat to start from (defaults to first beat) optional: `null`
`options`	`?array`	Additional options 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.

$options accepts an associative array with these keys:

functions: map of name to function(Interpreter $interpreter, array $args): mixed
strictAccess: bool, if true accessing undefined variables raises an error
translations: a translations map from extractTranslations()/loadLocale()

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

`resume`

method

public static function resume(Script $script, callable $handleDialogue, callable $handleChoice, callable $handleFinish, string $saveData, ?string $beatName = null, ?array $options = null): Interpreter

Resume a script from saved state.

Parameter	Type	Description
`script`	`Script`	The parsed script (result from `parse()`)
`handleDialogue`	`callable`	Function called when dialogue text should be displayed
`handleChoice`	`callable`	Function called when player needs to make a choice
`handleFinish`	`callable`	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`
`options`	`?array`	Optional options to configure interpreter behavior 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.

$saveData is the JSON string returned by Interpreter::save(). $options has the same shape as in play().

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

`extractTranslations`

method

public static function extractTranslations(Script $script): mixed

Extract translations from a parsed translation script (a .XX.lor file).

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

Returns mixed 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().

Returns an opaque translations map to pass as the translations option to play() or resume().

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

`loadLocale`

method

public static function loadLocale(string $locale, Script $script, ?string $filePath = null, ?callable $handleFile = null, ?callable $callback = null): mixed

Load translations for a specific locale, walking the script's full import tree. Returns the merged translations map (synchronously, when $handleFile is synchronous), also delivered through $callback.

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`	`?callable`	File handler used to read translation files optional: `null`
`callback`	`?callable`	Called with the merged translations map. Required if `handleFile` is asynchronous. optional: `null`

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

public static function translationFormat(string $name, bool $enabled): void

Enable or disable runtime support for an alternate translation file format. Known names: "po" (.po), "xliff" (.xliff, .xlf), "csv" (.csv, .tsv). Unknown names are accepted silently.

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:

"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

public static function lastError(): mixed

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

Returns mixed

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

public static function print(Script $script, string $indent = ' ', string $newline = "\n"): string

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

method

public static function update(float $delta): void

Tick pending wait() timers. Call from your game loop every frame.

Parameter	Type	Description
`delta`	`float`	Time elapsed since last frame in seconds

Returns void

The first call enables non blocking deferred mode for wait(); before this is called, wait() falls back to blocking sleep (correct for CLI tools).

C# C++ Java PHP Python Lua Haxe

`Interpreter`

class

A running Loreline script interpreter.

Provides methods to save/restore state and access character and state data.

State values cross the boundary as native PHP arrays with snapshot semantics: getters return an independent copy, and mutating that copy does not change story state until it is written back through a setter. This is the PHP projection of the cross platform contract (PHP arrays are value types, so live views are not possible with genuine arrays).

`start`

method

public function start(?string $beatName = null): void

Start or restart execution from a specific beat (or the first beat when null).

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`

method

public function save(): string

Save the current interpreter state.

Returns string A SaveData object containing the serialized state

Returns the full state serialized as a JSON string, ready to store in a session, a file or a database, and accepted back by Loreline::resume() or Interpreter::restore(). The format is the same across every Loreline target, so a save made here can be resumed by another integration.

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

`restore`

method

public function restore(string $saveData): void

Restore the interpreter to a previously saved state (a JSON string returned by save()).

Parameter	Type	Description
`saveData`	`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 function resume(): void

Resume execution after restoring state.

Returns void

JavaScript TypeScript C# Java PHP Python Lua Haxe

`getCharacter`

method

public function getCharacter(string $name): mixed

Get a character's fields by name, as a native PHP array snapshot, or null if not found.

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

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

JavaScript TypeScript C# Java PHP Python Lua Haxe

`getCharacterField`

method

public function getCharacterField(string $character, string $field): mixed

Get a specific field of a character, as a native PHP value snapshot.

Parameter	Type	Description
`character`	`string`	The name of the character
`field`	`string`	The name of the field to get

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

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

`setCharacterField`

method

public function setCharacterField(string $character, string $field, mixed $value): void

Set a specific field of a character. Arrays are deep copied into the story state.

Parameter	Type	Description
`character`	`string`	The name of the character
`field`	`string`	The name of the field to set
`value`	`mixed`	The value to set

Returns void

JavaScript TypeScript GDScript C++ Java PHP Python Lua Haxe

`getStateField`

method

public function getStateField(string $name): mixed

Get a state field by name, resolving from the current scope outward, as a native PHP value snapshot.

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

Returns mixed The field value or null if not found

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

`setStateField`

method

public function setStateField(string $name, mixed $value): void

Set a state field by name, resolving from the current scope outward. Arrays are deep copied into the story state.

Parameter	Type	Description
`name`	`string`	The name of the field to set
`value`	`mixed`	The value to set

Returns void

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

`getTopLevelStateField`

method

public function getTopLevelStateField(string $name): mixed

Get a field from the top-level state directly, as a native PHP value snapshot.

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

Returns mixed The field value or null if not found

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

`setTopLevelStateField`

method

public function setTopLevelStateField(string $name, mixed $value): void

Set a field on the top-level state directly. Arrays are deep copied into the story state.

Parameter	Type	Description
`name`	`string`	The name of the field to set
`value`	`mixed`	The value to set

Returns void

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

`currentNode`

method

public function currentNode(): ?Node

Return the current node being executed, or null.

Returns ?Node The current node or null if no node is being executed

During a dialogue callback, this returns the dialogue statement node. During a choice callback, this returns the choice statement node.

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

`Script`

class

A parsed Loreline script AST.

Obtain via Loreline::parse(). Pass to Loreline::play() or Loreline::resume() to execute.

`fromJson`

method

public static function fromJson(string $json): Script

Reconstruct a Script from a JSON string (as returned by toJson()).

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 Loreline AST nodes.

Provides access to the node type, position, unique ID, and JSON export.

`type`

method

public function type(): string

The type of this node (e.g. "Script", "Beat", "Text").

Returns string String representation of node type

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

`toJson`

method

public function toJson(bool $pretty = false): string

Export this node as a JSON string.

Parameter	Type	Description
`pretty`	`bool`	optional: `false`

Returns string Object containing node type and position

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

`fromJson`

method

public static function fromJson(string $json): Node

Reconstruct a Node from a JSON string (as returned by toJson()).

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

`__construct`

constructor

public function __construct(protected mixed $internal)

Parameter	Type	Description
`internal`	`mixed`

`line`

method

public function line(): int

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

Returns int

`column`

method

public function column(): int

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

Returns int

`offset`

method

public function offset(): int

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

Returns int

`length`

method

public function length(): int

The length of the source text span this node represents.

Returns int

`nodeIdToString`

method

public function nodeIdToString(): string

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

Returns string

`ChoiceOption`

class

A choice option presented to the user.

`text`

property

public readonly string $text

The text of the choice option.

Returns string

JavaScript TypeScript C# C++ Java PHP Python Haxe

`tags`

property

public readonly array $tags

Any tags associated with the choice text.

Returns array

JavaScript TypeScript C# C++ Java PHP Python Haxe

`enabled`

property

public readonly bool $enabled

Whether this choice option is currently enabled.

Returns bool

JavaScript TypeScript C# C++ Java PHP Python Haxe

`__construct`

constructor

public function __construct(public readonly string $text, public readonly array $tags, public readonly bool $enabled)

Parameter	Type	Description
`text`	`string`	The text of the choice option.
`tags`	`array`	Any tags associated with the choice text.
`enabled`	`bool`	Whether this choice option is currently enabled.

`TextTag`

class

A tag embedded in text content, used for styling or other purposes.

`closing`

property

public readonly bool $closing

Whether this is a closing tag.

Returns bool

JavaScript TypeScript C# C++ Java PHP Python Haxe

`value`

property

public readonly string $value

The value or name of the tag.

Returns string

JavaScript TypeScript C# C++ Java PHP Python Haxe

`offset`

property

public readonly int $offset

The offset in the text where this tag appears.

Returns int

JavaScript TypeScript C# C++ Java PHP Python Haxe

`__construct`

constructor

public function __construct(public readonly string $value, public readonly int $offset, public readonly bool $closing)

Parameter	Type	Description
`value`	`string`	The value or name of the tag.
`offset`	`int`	The offset in the text where this tag appears.
`closing`	`bool`	Whether this is a closing tag.

Generated from Loreline v0.10.0.

PHP API Reference

Quick reference

Loreline#

parse#

play#

resume#

extractTranslations#

loadLocale#

translationFormat#

lastError#

print#

update#

Interpreter#

start#

save#

restore#

resume#

getCharacter#

getCharacterField#

setCharacterField#

getStateField#

setStateField#

getTopLevelStateField#

setTopLevelStateField#

currentNode#

Script#

fromJson#

Node#

type#

toJson#

fromJson#

__construct#

line#

column#

offset#

length#

nodeIdToString#

ChoiceOption#

text#

tags#

enabled#

__construct#

TextTag#

closing#

value#

offset#

__construct#

`Loreline`

`parse`

`play`

`resume`

`extractTranslations`

`loadLocale`

`translationFormat`

`lastError`

`print`

`update`

`Interpreter`

`start`

`save`

`restore`

`resume`

`getCharacter`

`getCharacterField`

`setCharacterField`

`getStateField`

`setStateField`

`getTopLevelStateField`

`setTopLevelStateField`

`currentNode`

`Script`

`fromJson`

`Node`

`type`

`toJson`

`fromJson`

`__construct`

`line`

`column`

`offset`

`length`

`nodeIdToString`

`ChoiceOption`

`text`

`tags`

`enabled`

`__construct`

`TextTag`

`closing`

`value`

`offset`

`__construct`