3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import assert from 'node:assert/strict';
import test from 'node:test';
import { createRuntime, RUNTIME_LIMITS } from '../src/runtime.js';
// A manual clock and frame scheduler: one frame runs only when the test calls frame(milliseconds).
function createHarness(options = {}) {
let time = 1000;
let pending = null;
let nextHandle = 1;
const visibilityCallbacks = new Set();
const visibility = {
hidden: false,
subscribe(callback) {
visibilityCallbacks.add(callback);
return () => visibilityCallbacks.delete(callback);
},
};
const scheduler = {
request(callback) {
pending = { callback, handle: nextHandle };
nextHandle += 1;
return pending.handle;
},
cancel(handle) {
if (pending?.handle === handle) pending = null;
},
};
const rendered = [];
const target = { render: frame => rendered.push(frame) };
const runtime = createRuntime(target, { scheduler, clock: () => time, visibility, ...options });
return {
runtime,
rendered,
visibility,
hasPendingFrame: () => pending !== null,
frame(milliseconds) {
time += milliseconds;
const { callback } = pending;
pending = null;
callback();
},
setHidden(hidden) {
visibility.hidden = hidden;
for (const callback of visibilityCallbacks) callback();
},
};
}
function recorder(name, log) {
return {
name,
init: () => log.push(`${name}:init`),
fixedUpdate: step => log.push(`${name}:fixed:${step.toFixed(4)}`),
update: delta => log.push(`${name}:update:${delta.toFixed(4)}`),
dispose: () => log.push(`${name}:dispose`),
};
}
const countOf = (log, kind) => log.filter(line => line.includes(`:${kind}:`)).length;
test('fixed mode accumulates leftover time between frames', () => {
const log = [];
const harness = createHarness({ mode: 'fixed', fixedRate: 100, systems: [recorder('a', log)] });
harness.runtime.start();
harness.frame(0);
harness.frame(25);
assert.equal(countOf(log, 'fixed'), 2);
harness.frame(5);
assert.equal(countOf(log, 'fixed'), 3);
assert.equal(countOf(log, 'update'), 0);
assert.equal(harness.runtime.stats.fixedSteps, 3);
assert.equal(harness.rendered.length, 3);
});
test('variable mode calls update with the frame time and no fixed update', () => {
const log = [];
const harness = createHarness({ mode: 'variable', systems: [recorder('a', log)] });
harness.runtime.start();
harness.frame(0);
harness.frame(20);
harness.frame(10);
assert.deepEqual(log.filter(line => line.includes(':update:')), ['a:update:0.0000', 'a:update:0.0200', 'a:update:0.0100']);
assert.equal(countOf(log, 'fixed'), 0);
assert.equal(harness.runtime.stats.alpha, 1);
});
test('both mode renders with the interpolation alpha of the leftover step', () => {
const alphas = [];
const harness = createHarness({
mode: 'both',
fixedStepSeconds: 0.01,
frame: context => {
alphas.push(context.alpha);
return {};
},
});
harness.runtime.start();
harness.frame(0);
harness.frame(25);
harness.frame(10);
assert.equal(alphas[0], 0);
assert.ok(Math.abs(alphas[1] - 0.5) < 1e-9);
assert.ok(Math.abs(alphas[2] - 0.5) < 1e-9);
});
test('a long frame is clamped and the step count is capped', () => {
const log = [];
const harness = createHarness({ mode: 'fixed', fixedStepSeconds: 0.01, maximumFrameSeconds: 1, maximumStepsPerFrame: 5, systems: [recorder('a', log)] });
harness.runtime.start();
harness.frame(0);
harness.frame(60000);
assert.equal(harness.runtime.stats.lastFixedSteps, 5);
assert.ok(harness.runtime.stats.droppedSeconds > 0.9);
harness.frame(10);
assert.equal(harness.runtime.stats.lastFixedSteps, 1);
});
test('systems run in order and dispose in reverse', () => {
const log = [];
const harness = createHarness({ mode: 'both', fixedStepSeconds: 0.01, systems: [recorder('first', log), recorder('second', log)] });
harness.runtime.start();
harness.frame(0);
harness.frame(10);
assert.deepEqual(log.slice(0, 2), ['first:init', 'second:init']);
const fixedRun = log.filter(line => line.includes(':fixed:'));
assert.deepEqual(fixedRun.map(line => line.split(':')[0]), ['first', 'second']);
assert.ok(log.indexOf('first:update:0.0100') < log.indexOf('second:update:0.0100'));
harness.runtime.dispose();
assert.deepEqual(log.slice(-2), ['second:dispose', 'first:dispose']);
});
test('dispose runs every system even when one throws, then reports the failure (#2617)', () => {
const log = [];
const systems = [recorder('first', log), recorder('second', log), recorder('third', log)];
systems[1].dispose = () => {
log.push('second:dispose');
throw new Error('second dispose failed');
};
const harness = createHarness({ systems });
harness.runtime.start();
assert.throws(() => harness.runtime.dispose(), /second dispose failed/);
assert.deepEqual(log.filter(line => line.endsWith(':dispose')), ['third:dispose', 'second:dispose', 'first:dispose']);
assert.deepEqual(harness.runtime.systems, []);
assert.equal(harness.hasPendingFrame(), false);
harness.runtime.dispose();
assert.equal(log.filter(line => line.endsWith(':dispose')).length, 3, 'a second dispose does nothing');
});
test('systems can be left out, inserted, swapped and removed', () => {
const log = [];
const harness = createHarness({ mode: 'variable', systems: [{ name: 'game', update: () => log.push('game') }] });
harness.runtime.start();
harness.runtime.addSystem({ name: 'input', update: () => log.push('input') }, 0);
assert.deepEqual(harness.runtime.systems, ['input', 'game']);
harness.frame(0);
assert.deepEqual(log, ['input', 'game']);
const events = [];
harness.runtime.replaceSystem('game', { name: 'game', update: () => log.push('game2'), init: () => events.push('init2') });
assert.deepEqual(events, ['init2']);
harness.frame(10);
assert.deepEqual(log.slice(2), ['input', 'game2']);
harness.runtime.removeSystem('input');
assert.deepEqual(harness.runtime.systems, ['game']);
assert.throws(() => harness.runtime.removeSystem('input'), /No runtime system named "input"/);
assert.throws(() => harness.runtime.addSystem({ name: 'game' }), /already exists/);
});
test('pause holds the loop and resume does not simulate the paused time', () => {
const log = [];
const harness = createHarness({ mode: 'variable', systems: [recorder('a', log)] });
harness.runtime.start();
harness.frame(0);
harness.runtime.pause();
assert.equal(harness.hasPendingFrame(), false);
assert.equal(harness.runtime.paused, true);
harness.runtime.resume();
assert.equal(harness.hasPendingFrame(), true);
harness.frame(5000);
assert.equal(log.at(-1), 'a:update:0.0000');
assert.equal(harness.runtime.running, true);
});
test('a hidden tab pauses the loop and a visible tab resumes it', () => {
const harness = createHarness({ mode: 'variable' });
harness.runtime.start();
harness.frame(0);
harness.setHidden(true);
assert.equal(harness.hasPendingFrame(), false);
harness.setHidden(false);
assert.equal(harness.hasPendingFrame(), true);
harness.frame(9000);
assert.equal(harness.runtime.stats.elapsedSeconds, 0);
});
test('pauseWhenHidden false keeps running in a hidden tab', () => {
const harness = createHarness({ mode: 'variable', pauseWhenHidden: false });
harness.runtime.start();
harness.setHidden(true);
harness.frame(0);
assert.equal(harness.hasPendingFrame(), true);
});
test('stop cancels the frame, keeps systems initialised and start resumes', () => {
const log = [];
const harness = createHarness({ mode: 'variable', systems: [recorder('a', log)] });
harness.runtime.start();
harness.frame(0);
harness.runtime.stop();
assert.equal(harness.hasPendingFrame(), false);
assert.equal(harness.runtime.running, false);
harness.runtime.start();
assert.equal(log.filter(line => line === 'a:init').length, 1);
assert.equal(log.includes('a:dispose'), false);
assert.equal(harness.hasPendingFrame(), true);
});
test('stats report frame time, average and the update and render split', () => {
const harness = createHarness({ mode: 'variable' });
harness.runtime.start();
harness.frame(0);
harness.frame(16);
harness.frame(20);
const stats = harness.runtime.stats;
assert.equal(stats.frames, 3);
assert.equal(stats.frameMilliseconds, 20);
assert.equal(stats.averageFrameMilliseconds, 18);
assert.equal(stats.maximumFrameMilliseconds, 20);
assert.ok(Math.abs(stats.framesPerSecond - 1000 / 18) < 1e-9);
});
test('a throwing system stops the loop and names the system', () => {
const harness = createHarness({ mode: 'variable', systems: [{ name: 'bad', update() { throw new Error('boom'); } }] });
harness.runtime.start();
assert.throws(() => harness.frame(0), /Runtime system "bad" update failed: boom/);
assert.equal(harness.runtime.running, false);
assert.equal(harness.hasPendingFrame(), false);
});
test('a hook that throws a non-Error names the system, the hook and the original text (#2615)', () => {
const frozen = Object.freeze(new Error('frozen boom'));
const cases = [
['a string', 'boom', 'boom'],
['null', null, 'null'],
['a frozen Error', frozen, 'frozen boom'],
];
for (const [label, thrown, text] of cases) {
const harness = createHarness({ mode: 'variable', systems: [{ name: 'bad', update() { throw thrown; } }] });
let caught;
try {
harness.runtime.step(0);
} catch (error) {
caught = error;
}
assert.ok(caught instanceof Error, label);
assert.equal(caught.message, `Runtime system "bad" update failed: ${text}`, label);
assert.equal(caught.cause, thrown, `${label} is kept as the cause`);
}
});
test('an ordinary Error keeps its identity and gets the prefixed message (#2615)', () => {
const failure = new Error('boom');
const harness = createHarness({ mode: 'variable', systems: [{ name: 'bad', update() { throw failure; } }] });
assert.throws(() => harness.runtime.step(0), error => error === failure && error.message === 'Runtime system "bad" update failed: boom');
});
test('step runs one frame without a scheduler', () => {
const log = [];
const harness = createHarness({ mode: 'fixed', fixedStepSeconds: 0.01, systems: [recorder('a', log)] });
harness.runtime.step(20);
assert.equal(countOf(log, 'fixed'), 2);
assert.equal(harness.rendered.length, 1);
});
test('a disposed runtime refuses to start', () => {
const harness = createHarness();
harness.runtime.dispose();
assert.throws(() => harness.runtime.start(), /was disposed/);
});
test('input is validated with messages that say what to pass', () => {
const target = { render() {} };
const scheduler = { request: () => 1, cancel() {} };
assert.throws(() => createRuntime({}, { scheduler }), /render\(frame\)/);
assert.throws(() => createRuntime(target, { scheduler, mode: 'turbo' }), /one of fixed, variable, both/);
assert.throws(() => createRuntime(target, { scheduler, fixedRate: 0 }), /fixedRate must be a number/);
assert.throws(() => createRuntime(target, { scheduler, fixedRate: 60, fixedStepSeconds: 0.01 }), /not both/);
assert.throws(() => createRuntime(target, { scheduler, maximumStepsPerFrame: RUNTIME_LIMITS.maximumStepsPerFrameLimit + 1 }), /maximumStepsPerFrame/);
assert.throws(() => createRuntime(target, { scheduler, systems: {} }), /array of system objects/);
assert.throws(() => createRuntime(target, { scheduler, systems: [{ update() {} }] }), /unique name/);
assert.throws(() => createRuntime(target, { scheduler, systems: [{ name: 'x', update: 3 }] }), /update must be a function/);
assert.throws(() => createRuntime(target, { scheduler, frame: 3 }), /frame must be a function/);
assert.throws(() => createRuntime(target, { scheduler, clock: 'x' }), /clock must be a function/);
assert.doesNotThrow(() => createRuntime(target, { scheduler, clock: () => 0 }));
assert.doesNotThrow(() => createRuntime(target, { scheduler }));
assert.throws(() => createRuntime(target), /requestAnimationFrame/);
});
test('a system whose init threw is initialised again by the next start', () => {
let initCalls = 0;
const failingOnce = { name: 'late', init() { initCalls += 1; if (initCalls === 1) throw new Error('not ready'); }, update() {} };
const harness = createHarness({ mode: 'variable', systems: [failingOnce] });
assert.throws(() => harness.runtime.start(), /Runtime system "late" init failed: not ready/);
harness.runtime.start();
assert.equal(initCalls, 2);
});
test('one NaN reading from the clock does not stop time for good', () => {
let reading = 1000;
const log = [];
const harness = createHarness({ mode: 'variable', clock: () => reading, systems: [recorder('a', log)] });
harness.runtime.start();
harness.frame(0);
reading = Number.NaN;
harness.frame(0);
reading = 1100;
harness.frame(0);
reading = 1116;
harness.frame(0);
assert.ok(Number.isFinite(harness.runtime.stats.elapsedSeconds));
assert.ok(harness.runtime.stats.elapsedSeconds > 0.01);
});