Skip to content

3D engine that AI agents drive

12.8 KB
Raw Blame
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);
});