Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

9.6 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('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('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), /requestAnimationFrame/);
});