A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file script-graph-runner.test.ts
* @brief The script-graph interpreter's promises, each pinned on its own.
*
* These are the claims an author reads off the picture: pin 0 runs before pin 1,
* one wire is one value, a loop can end, and a loop that cannot end stops the
* instance instead of the frame.
*/
import { describe, it, expect } from 'vitest';
import { AiRegistry } from '../src/ai/fsm/registry';
import { Blackboard } from '../src/ai/fsm/Blackboard';
import {
compileScriptGraph, createScriptRunState, stepScriptGraph, destroyScriptGraph,
fireScriptGraphEvent, type ScriptTickContext,
} from '../src/logic/ScriptGraphRunner';
import { SCRIPT_GRAPH_VERSION, type ScriptGraph, type ScriptGraphEdge, type ScriptGraphNode } from '../src/logic/types';
import { scriptCatalog, scriptGraphPrefabRefs } from '../src/logic/nodes';
interface TestCtx { log: string[]; }
/** A registry of verbs whose every effect is visible in `ctx.log`. */
function registry(): { reg: AiRegistry<TestCtx>; evaluations: { n: number } } {
const reg = new AiRegistry<TestCtx>();
const evaluations = { n: 0 };
reg.registerAction('test.say', {
params: [{ name: 'text', type: 'string' }],
run: (ctx, _bb, _arg, params) => { ctx.log.push(String(params?.text ?? '')); },
});
reg.registerAction('test.spawn', {
outputs: [{ name: 'entity', type: 'entity' }],
run: (ctx, _bb, _arg, _params, out) => {
ctx.log.push('spawn');
if (out) out.entity = 40 + ctx.log.length;
},
});
reg.registerValue('test.tick', {
outputs: [{ name: 'n', type: 'number' }],
evaluate: (_ctx, _bb, _params, out) => { out.n = ++evaluations.n; },
});
reg.registerValue('test.add', {
params: [{ name: 'a', type: 'number' }, { name: 'b', type: 'number' }],
outputs: [{ name: 'sum', type: 'number' }],
evaluate: (_ctx, _bb, params, out) => { out.sum = Number(params.a ?? 0) + Number(params.b ?? 0); },
});
reg.registerValue('test.lessThan', {
params: [{ name: 'a', type: 'number' }, { name: 'b', type: 'number' }],
outputs: [{ name: 'result', type: 'bool' }],
evaluate: (_ctx, _bb, params, out) => { out.result = Number(params.a ?? 0) < Number(params.b ?? 0); },
});
return { reg, evaluations };
}
const node = (id: string, kind: string, extra: Partial<ScriptGraphNode> = {}): ScriptGraphNode =>
({ id, kind, ...extra });
const edge = (from: string, fromPort: string, to: string, toPort: string): ScriptGraphEdge =>
({ id: `${from}.${fromPort}->${to}.${toPort}`, from, fromPort, to, toPort });
function graphOf(nodes: ScriptGraphNode[], edges: ScriptGraphEdge[], variables?: ScriptGraph['variables']): ScriptGraph {
return { version: SCRIPT_GRAPH_VERSION, nodes, edges, ...(variables ? { variables } : {}) };
}
interface Run {
log: string[];
problems: string[];
tick(dt?: number): void;
destroy(): void;
fire(type: string, target?: number, other?: number): void;
halted(): boolean;
}
function run(graph: ScriptGraph, reg: AiRegistry<TestCtx>, budget?: number): Run {
const compiled = compileScriptGraph(graph, scriptCatalog(reg));
const state = createScriptRunState(compiled);
const ctx: TestCtx = { log: [] };
const problems: string[] = [...compiled.problems];
const tickCtx = (dt: number): ScriptTickContext<TestCtx> => ({
ctx, bb: new Blackboard(), registry: reg, dt,
onProblem: (m) => problems.push(m),
...(budget === undefined ? {} : { budget }),
});
return {
log: ctx.log,
problems,
tick: (dt = 1 / 60) => stepScriptGraph(compiled, state, tickCtx(dt)),
destroy: () => destroyScriptGraph(compiled, state, tickCtx(0)),
fire: (type, target = 7, other = 0) => fireScriptGraphEvent(compiled, state, tickCtx(0), type, target, other),
halted: () => state.halted,
};
}
describe('exec flows depth-first', () => {
it('finishes pin 0s whole chain before pin 1 starts', () => {
const { reg } = registry();
const g = graphOf([
node('start', 'event.start'),
node('seq', 'flow.sequence', { literals: { count: 2 } }),
node('a1', 'call', { ref: 'test.say', literals: { text: 'a1' } }),
node('a2', 'call', { ref: 'test.say', literals: { text: 'a2' } }),
node('b1', 'call', { ref: 'test.say', literals: { text: 'b1' } }),
], [
edge('start', 'then', 'seq', ''),
edge('seq', '0', 'a1', ''),
edge('a1', 'then', 'a2', ''),
edge('seq', '1', 'b1', ''),
]);
const r = run(g, reg);
r.tick();
expect(r.log).toEqual(['a1', 'a2', 'b1']);
});
it('branches on the value its condition wire carries', () => {
const { reg } = registry();
const g = graphOf([
node('start', 'event.start'),
node('lt', 'call', { ref: 'test.lessThan', literals: { a: 1, b: 2 } }),
node('br', 'flow.branch'),
node('yes', 'call', { ref: 'test.say', literals: { text: 'yes' } }),
node('no', 'call', { ref: 'test.say', literals: { text: 'no' } }),
], [
edge('start', 'then', 'br', ''),
edge('lt', 'result', 'br', 'cond'),
edge('br', 'true', 'yes', ''),
edge('br', 'false', 'no', ''),
]);
expect(runOnce(g, reg)).toEqual(['yes']);
});
it('runs event.start once and event.update every tick', () => {
const { reg } = registry();
const g = graphOf([
node('start', 'event.start'),
node('upd', 'event.update'),
node('s', 'call', { ref: 'test.say', literals: { text: 'start' } }),
node('u', 'call', { ref: 'test.say', literals: { text: 'update' } }),
], [edge('start', 'then', 's', ''), edge('upd', 'then', 'u', '')]);
const r = run(g, reg);
r.tick();
r.tick();
expect(r.log).toEqual(['start', 'update', 'update']);
});
it('publishes the frame delta on the update entry', () => {
const { reg } = registry();
const g = graphOf([
node('upd', 'event.update'),
node('scale', 'call', { ref: 'test.add', literals: { b: 0 } }),
node('say', 'call', { ref: 'test.say' }),
], [
edge('upd', 'then', 'say', ''),
edge('upd', 'dt', 'scale', 'a'),
edge('scale', 'sum', 'say', 'text'),
]);
const r = run(g, reg);
r.tick(0.25);
// Not 0: an entry that declares a port and produces nothing is a graph
// whose every node runs and whose world never moves.
expect(r.log).toEqual(['0.25']);
});
it('runs event.destroy only on teardown', () => {
const { reg } = registry();
const g = graphOf([
node('bye', 'event.destroy'),
node('s', 'call', { ref: 'test.say', literals: { text: 'bye' } }),
], [edge('bye', 'then', 's', '')]);
const r = run(g, reg);
r.tick();
expect(r.log).toEqual([]);
r.destroy();
expect(r.log).toEqual(['bye']);
});
});
describe('data is pulled', () => {
it('takes the literal when no wire arrives, the wire when one does', () => {
const { reg } = registry();
const g = graphOf([
node('start', 'event.start'),
node('sum', 'call', { ref: 'test.add', literals: { a: 2, b: 3 } }),
node('say', 'call', { ref: 'test.say' }),
], [edge('start', 'then', 'say', ''), edge('sum', 'sum', 'say', 'text')]);
expect(runOnce(g, reg)).toEqual(['5']);
});
it('evaluates a pure node once per activation of the node reading it', () => {
const { reg, evaluations } = registry();
// One `test.tick` feeding BOTH inputs of one add: the author sees one
// wire leaving it, so both pins must see the same number.
const g = graphOf([
node('start', 'event.start'),
node('t', 'call', { ref: 'test.tick' }),
node('sum', 'call', { ref: 'test.add' }),
node('say', 'call', { ref: 'test.say' }),
], [
edge('start', 'then', 'say', ''),
edge('t', 'n', 'sum', 'a'),
edge('t', 'n', 'sum', 'b'),
edge('sum', 'sum', 'say', 'text'),
]);
const r = run(g, reg);
r.tick();
expect(evaluations.n).toBe(1);
expect(r.log).toEqual(['2']);
});
it('re-evaluates a pure node on the next activation', () => {
const { reg, evaluations } = registry();
const g = graphOf([
node('upd', 'event.update'),
node('t', 'call', { ref: 'test.tick' }),
node('say', 'call', { ref: 'test.say' }),
], [edge('upd', 'then', 'say', ''), edge('t', 'n', 'say', 'text')]);
const r = run(g, reg);
r.tick();
r.tick();
expect(evaluations.n).toBe(2);
expect(r.log).toEqual(['1', '2']);
});
it('reads what an effectful node last handed back', () => {
const { reg } = registry();
const g = graphOf([
node('start', 'event.start'),
node('sp', 'call', { ref: 'test.spawn' }),
node('say', 'call', { ref: 'test.say' }),
], [
edge('start', 'then', 'sp', ''),
edge('sp', 'then', 'say', ''),
edge('sp', 'entity', 'say', 'text'),
]);
expect(runOnce(g, reg)).toEqual(['spawn', '41']);
});
it('publishes who else the event named, so a graph can act on them', () => {
const { reg } = registry();
const g = graphOf([
node('on', 'event.on', { literals: { type: 'trigger_enter' } }),
node('say', 'call', { ref: 'test.say' }),
], [edge('on', 'then', 'say', ''), edge('on', 'other', 'say', 'text')]);
const r = run(g, reg);
r.fire('trigger_enter', 3, 99);
expect(r.log).toEqual(['99']);
});
it('publishes the event target on the entry that heard it', () => {
const { reg } = registry();
const g = graphOf([
node('on', 'event.on', { literals: { type: 'click' } }),
node('say', 'call', { ref: 'test.say' }),
], [edge('on', 'then', 'say', ''), edge('on', 'target', 'say', 'text')]);
const r = run(g, reg);
r.fire('other');
expect(r.log).toEqual([]);
r.fire('click', 12);
expect(r.log).toEqual(['12']);
});
});
describe('variables belong to the instance', () => {
it('starts at the declared default and keeps what was written', () => {
const { reg } = registry();
const g = graphOf([
node('upd', 'event.update'),
node('get', 'var.get', { literals: { name: 'count' } }),
node('inc', 'call', { ref: 'test.add', literals: { b: 1 } }),
node('set', 'var.set', { literals: { name: 'count' } }),
node('say', 'call', { ref: 'test.say' }),
], [
edge('upd', 'then', 'set', ''),
edge('get', 'value', 'inc', 'a'),
edge('inc', 'sum', 'set', 'value'),
edge('set', 'then', 'say', ''),
edge('get', 'value', 'say', 'text'),
], [{ name: 'count', type: 'number', default: 10 }]);
const r = run(g, reg);
r.tick();
r.tick();
// `say` reads the variable on its OWN activation, after `set` wrote it.
expect(r.log).toEqual(['11', '12']);
});
});
describe('a loop can end, and one that cannot is stopped', () => {
it('leaves flow.while when its condition goes false', () => {
const { reg } = registry();
const g = graphOf([
node('start', 'event.start'),
node('i', 'var.get', { literals: { name: 'i' } }),
node('lt', 'call', { ref: 'test.lessThan', literals: { b: 3 } }),
node('w', 'flow.while'),
node('inc', 'call', { ref: 'test.add', literals: { b: 1 } }),
node('set', 'var.set', { literals: { name: 'i' } }),
node('body', 'call', { ref: 'test.say', literals: { text: 'x' } }),
node('done', 'call', { ref: 'test.say', literals: { text: 'done' } }),
], [
edge('start', 'then', 'w', ''),
edge('i', 'value', 'lt', 'a'),
edge('lt', 'result', 'w', 'cond'),
edge('w', 'body', 'body', ''),
edge('body', 'then', 'set', ''),
edge('i', 'value', 'inc', 'a'),
edge('inc', 'sum', 'set', 'value'),
edge('w', 'done', 'done', ''),
], [{ name: 'i', type: 'number', default: 0 }]);
const r = run(g, reg);
r.tick();
expect(r.log).toEqual(['x', 'x', 'x', 'done']);
expect(r.halted()).toBe(false);
});
it('stops the instance at the budget, names the node, and says so once', () => {
const { reg } = registry();
const g = graphOf([
node('start', 'event.start'),
node('w', 'flow.while', { literals: { cond: true } }),
node('body', 'call', { ref: 'test.say', literals: { text: 'x' } }),
], [
edge('start', 'then', 'w', ''),
edge('w', 'body', 'body', ''),
edge('body', 'then', 'w', ''),
]);
const r = run(g, reg, 20);
r.tick();
expect(r.halted()).toBe(true);
expect(r.problems).toHaveLength(1);
expect(r.problems[0]).toContain('step budget');
const after = r.log.length;
r.tick();
expect(r.log).toHaveLength(after);
expect(r.problems).toHaveLength(1);
});
});
describe('flow.delay waits without blocking the frame', () => {
it('continues on the tick its time is up', () => {
const { reg } = registry();
const g = graphOf([
node('start', 'event.start'),
node('d', 'flow.delay', { literals: { seconds: 0.1 } }),
node('say', 'call', { ref: 'test.say', literals: { text: 'late' } }),
], [edge('start', 'then', 'd', ''), edge('d', 'then', 'say', '')]);
const r = run(g, reg);
r.tick(0.06);
expect(r.log).toEqual([]);
r.tick(0.06);
expect(r.log).toEqual(['late']);
r.tick(0.06);
expect(r.log).toEqual(['late']);
});
});
describe('entity.spawn', () => {
it('names the prefab it needs, so whoever loads the graph can prepare it', () => {
const g = graphOf([
node('a', 'entity.spawn', { literals: { prefab: 'assets/bullet.esprefab' } }),
node('b', 'entity.spawn', { literals: { prefab: 'assets/bullet.esprefab' } }),
node('c', 'entity.spawn', { literals: { prefab: 'assets/enemy.esprefab' } }),
node('d', 'flow.branch'),
], []);
// Deduplicated: two nodes spawning one prefab is one preparation.
expect(scriptGraphPrefabRefs(g)).toEqual(['assets/bullet.esprefab', 'assets/enemy.esprefab']);
});
it('reports a prefab nothing prepared instead of spawning nothing quietly', () => {
const { reg } = registry();
const g = graphOf([
node('start', 'event.start'),
node('sp', 'entity.spawn', { literals: { prefab: 'assets/gone.esprefab' } }),
node('say', 'call', { ref: 'test.say', literals: { text: 'after' } }),
], [edge('start', 'then', 'sp', ''), edge('sp', 'then', 'say', '')]);
const r = run(g, reg);
r.tick();
expect(r.problems.some((p) => p.includes('was not prepared'))).toBe(true);
// …and the chain continues: one unspawnable prefab is not the graph.
expect(r.log).toEqual(['after']);
});
});
describe('a graph that asks for what is not there says so', () => {
it('reports an unregistered name at compile rather than running past it', () => {
const { reg } = registry();
const g = graphOf([
node('start', 'event.start'),
node('nope', 'call', { ref: 'test.missing' }),
], [edge('start', 'then', 'nope', '')]);
const r = run(g, reg);
expect(r.problems.some((p) => p.includes('test.missing'))).toBe(true);
});
it('does not run a node whose input wire has no source', () => {
const { reg } = registry();
const g = graphOf([
node('start', 'event.start'),
node('gone', 'call', { ref: 'test.missing' }),
node('say', 'call', { ref: 'test.say', literals: { text: 'fallback' } }),
node('after', 'call', { ref: 'test.say', literals: { text: 'after' } }),
], [
edge('start', 'then', 'say', ''),
edge('gone', 'n', 'say', 'text'),
edge('say', 'then', 'after', ''),
]);
const r = run(g, reg);
r.tick();
// Not `fallback`: the port's zero is a value nobody authored, and a node
// that runs on one writes nonsense downstream instead of stopping here.
expect(r.log).toEqual([]);
expect(r.problems.some((p) => p.includes('no source'))).toBe(true);
});
it('reports a data cycle instead of recursing forever', () => {
const { reg } = registry();
const g = graphOf([
node('start', 'event.start'),
node('a', 'call', { ref: 'test.add' }),
node('say', 'call', { ref: 'test.say' }),
], [
edge('start', 'then', 'say', ''),
edge('a', 'sum', 'a', 'a'),
edge('a', 'sum', 'say', 'text'),
]);
const r = run(g, reg);
r.tick();
expect(r.problems.some((p) => p.includes('cycle'))).toBe(true);
});
});
function runOnce(g: ScriptGraph, reg: AiRegistry<TestCtx>): string[] {
const r = run(g, reg);
r.tick();
return r.log;
}
describe('a graph whose file contradicts itself', () => {
it('reports two nodes under one id instead of letting one replace the other', () => {
const { reg } = registry();
const g = graphOf([
node('start', 'event.start'),
node('twin', 'call', { ref: 'test.say', literals: { text: 'first' } }),
node('twin', 'call', { ref: 'test.say', literals: { text: 'second' } }),
], [edge('start', 'then', 'twin', '')]);
const r = run(g, reg);
r.tick();
// Every lookup here is by id, so the second would quietly become the
// node every wire drawn to either one lands on.
expect(r.problems.join('\n')).toMatch(/a second node carries this id/);
});
});