@bendyline/molen-kernel/testing

Molen headless deterministic simulation kernel (no DOM, no three.js).

import { /* … */ } from '@bendyline/molen-kernel/testing';

Classes

ReplayPlayer

Scrubs a deterministic replay: seek to any tick by restoring the nearest cached keyframe and re-stepping forward. Keyframes are cached at keyframeInterval so checkpoint-safe seeking is O(interval). Scripts with untracked closures seek from the beginning — see docs-src/guide/scripting.md ("State that survives save/load and replay"). Used for replay scrubbing and machinima.

Constructors

Constructor

new ReplayPlayer(
   build, 
   commands, 
   opts
): ReplayPlayer;

Parameters

build

WorldBuilder

commands

Command[]

opts

keyframeInterval?

number

totalTicks

number

Returns

ReplayPlayer

Properties

length

readonly length: number;

Methods

seek()

seek(tick): World;

Return a world at the given tick (clamped to [0, length]).

Parameters

tick

number

Returns

World

Interfaces

AssertContext

Properties

events

events: object[];

All events emitted over the run, with the tick they occurred on.

event

event: EngineEvent;

tick

tick: number;

---

AssertionResult

Properties

message

message: string;

op

op: string;

pass

pass: boolean;

target

target: string;

Echo of the assertion's selector or event for reporting.

---

ComponentDiff

Properties

after?

optional after?: JsonObject;

before?

optional before?: JsonObject;

component

component: string;

entity

entity: string;

kind

kind: "added" | "removed" | "changed";

---

DivergenceReport

Properties

diff

diff: ComponentDiff[];

tick

tick: number;

---

HeadlessResult

Properties

events

events: RecordedEvent[];

finalHash

finalHash: string;

ticks

ticks: number;

world

world: World;

---

ParsedSelector

Properties

predicates

predicates: Predicate[];

valuePath

valuePath: (string | number)[];

Trailing value path tokens, e.g. ["health", "hp"] or ["transform", "pos", 1].

---

RecordedEvent

Properties

event

event: EngineEvent;

tick

tick: number;

---

ReplayResult

Properties

actualHash

actualHash: string;

expectedHash?

optional expectedHash?: string;

firstDivergentTick?

optional firstDivergentTick?: number;

Set when the result is being compared against a reference run that diverged.

ok

ok: boolean;

ticks

ticks: number;

---

SelectMatch

Properties

components

components: ComponentMap;

id

id: string;

value?

optional value?: JsonValue;

The resolved value at the selector's value path, if one was given.

Type Aliases

WorldBuilder

type WorldBuilder = () => World;

A factory that returns a fully-configured world (entities + systems + command handlers).

Returns

World

Functions

diffKeyframes()

function diffKeyframes(a, b): ComponentDiff[];

Component-level diff between two keyframes (a = before, b = after).

Parameters

a

Keyframe

b

Keyframe

Returns

ComponentDiff[]

---

firstDivergentTick()

function firstDivergentTick(
   buildA, 
   buildB, 
   ticks, 
   commandsA?, 
   commandsB?
): DivergenceReport | null;

Step two worlds in lockstep and report the first tick at which their state hashes diverge, with a component-level diff at that tick. Returns null if they agree for all ticks. Used both for determinism tests (same builder twice) and to localize replay divergence.

Parameters

buildA

WorldBuilder

buildB

WorldBuilder

ticks

number

commandsA?

Command[]

commandsB?

Command[]

Returns

DivergenceReport | null

---

formatAssertionResults()

function formatAssertionResults(results): string;

Format assertion results as an agent-facing block.

Parameters

results

AssertionResult[]

Returns

string

---

parseSelector()

function parseSelector(selector): ParsedSelector;

Parameters

selector

string

Returns

ParsedSelector

---

perTickHashes()

function perTickHashes(
   build, 
   commands, 
   ticks
): string[];

Per-tick state hashes for ticks steps (index i = hash after tick i).

Parameters

build

WorldBuilder

commands

Command[]

ticks

number

Returns

string[]

---

runAssertions()

function runAssertions(
   world, 
   doc, 
   ctx?
): AssertionResult[];

Evaluate an assertion document against the final world state and recorded events.

Parameters

world

World

doc

AssertionDoc

ctx?

AssertContext

Returns

AssertionResult[]

---

runHeadless()

function runHeadless(build, opts): HeadlessResult;

Run a built world for ticks, submitting recorded commands and capturing every emitted event with the tick it occurred on. The backbone of molen sim run and the MCP run_simulation tool.

Parameters

build

WorldBuilder

opts

commands?

Command[]

onTick?

(world) => void

ticks

number

Returns

HeadlessResult

---

runReplay()

function runReplay(
   build, 
   commands, 
   ticks, 
   expectedHash?
): ReplayResult;

Submit a recorded command stream and run ticks. Commands are queued at their recorded tickExecuted, so replay is faithful regardless of original late-command rewriting.

Parameters

build

WorldBuilder

commands

Command[]

ticks

number

expectedHash?

string

Returns

ReplayResult

---

select()

function select(world, selector): SelectMatch[];

Evaluate a selector against the world; returns matching entities (+ resolved value path).

Parameters

world

World

selector

string

Returns

SelectMatch[]

References

buildWorld

Re-exports buildWorld

---

createWorldFromScene

Re-exports createWorldFromScene

---

resolveEntityComponents

Re-exports resolveEntityComponents

---

resolvePrefab

Re-exports resolvePrefab

---

stateHash

Re-exports stateHash

---

World

Re-exports World

---

WorldSetup

Re-exports WorldSetup