Skip to content

3D engine that AI agents drive

17.4 KB
Raw Blame
import assert from 'node:assert/strict';
import test from 'node:test';
import { createInput } from '../src/input.js';
import {
  createCameraClip, createCameraRigOfKind, createChaseCamera, createCharacterController, createController, createFlightController,
  createFollowCamera, createOrbitCamera, createSideScrollerCamera, createVehicleController, listCameraRigKinds, listControllerKinds,
  registerCameraRig, registerController, replaceCameraRig, replaceController,
} from '../src/player.js';
import { createRuntime } from '../src/runtime.js';

const STEP_MILLISECONDS = 1000 / 60;
const fakeRenderer = { render: () => {} };
const scheduler = { request: () => 1, cancel: () => {} };

// Test course along -Z: stairs (z -4 to -6, 0.3 per step), a platform (z -6 to -9, 1.2 high), a gap (z -9 to -11), a ramp
// (z -11 to -16 rising to 1.5) and a wall at z -20 (5 high, 6 wide).
const STAIRS = [0, 1, 2, 3].map(index => ({
  min: [-2, 0, -4 - 0.5 * (index + 1)],
  max: [2, 0.3 * (index + 1), -4 - 0.5 * index],
}));
const PLATFORM = { min: [-2, 0, -9], max: [2, 1.2, -6] };
const WALL = { min: [-3, 0, -21], max: [3, 5, -20] };
const OBSTACLES = [...STAIRS, PLATFORM, WALL];

function courseGround(x, z) {
  if (z < -9 && z >= -11) return -50;
  if (z < -11 && z >= -16) return (-11 - z) * 0.3;
  if (z < -16) return 1.5;
  return 0;
}

function createScriptedInput() {
  return createInput({
    actions: { jump: ['script/jump'], run: ['script/run'] },
    axes: {
      moveX: ['script/right', { control: 'script/left', scale: -1 }],
      moveForward: ['script/forward', { control: 'script/back', scale: -1 }],
      lookX: ['script/lookRight', { control: 'script/lookLeft', scale: -1 }],
      lookY: ['script/lookUp', { control: 'script/lookDown', scale: -1 }],
    },
  });
}

function createGame(makeController, makeRig) {
  const input = createScriptedInput();
  const controller = makeController(input);
  const systems = [input, controller];
  const rig = makeRig ? makeRig(controller, input) : null;
  if (rig) systems.push(rig);
  const runtime = createRuntime(fakeRenderer, { mode: 'fixed', fixedStepSeconds: 1 / 60, systems, scheduler });
  return { input, controller, rig, runtime };
}

function stepOnce(game, beforeStep) {
  beforeStep?.();
  game.runtime.step(STEP_MILLISECONDS);
}

function insideAnyBox(point, boxes) {
  return boxes.some(({ min, max }) => point.every((value, axis) => value > min[axis] && value < max[axis]));
}

test('the character clears stairs, a gap and a ramp, stops at the wall, and the camera never enters it', () => {
  const clip = createCameraClip({ obstacles: OBSTACLES, ground: courseGround });
  const game = createGame(
    input => createCharacterController({ input, position: [0, 0, -1], ground: courseGround, obstacles: OBSTACLES, runSpeed: 6 }),
    (controller, input) => createFollowCamera({ subject: controller.state, input, yaw: Math.PI, clipEye: clip, followSeconds: 0 }),
  );
  const { input, controller, rig } = game;
  input.press('script/forward');
  input.press('script/run');
  let jumpedAcrossGap = false;
  let reachedPlatform = false;
  let landedBeyondGap = false;
  let lowestY = Infinity;
  for (let index = 0; index < 600; index += 1) {
    stepOnce(game, () => {
      if (controller.state.position[2] < -8.4 && controller.state.grounded && !jumpedAcrossGap) {
        jumpedAcrossGap = true;
        input.press('script/jump');
      } else {
        input.release('script/jump');
      }
    });
    const [x, y, z] = controller.state.position;
    lowestY = Math.min(lowestY, y);
    if (y >= 1.19 && z < -6.5) reachedPlatform = true;
    if (z < -11.5 && controller.state.grounded) landedBeyondGap = true;
    assert.ok(z > -20 + 0.4 - 1e-6, `tunnelled into the wall: z ${z} at step ${index}`);
    const { eye } = rig.pose({ alpha: 1 });
    assert.equal(insideAnyBox(eye, OBSTACLES), false, `camera inside a box at step ${index}: ${eye}`);
    assert.ok(eye[1] >= courseGround(eye[0], eye[2]), `camera under the ground at step ${index}`);
    assert.ok(Number.isFinite(x));
  }
  assert.ok(rig.pose({ alpha: 1 }).eye[2] > -20, 'the camera should be pulled in front of the wall, not left behind it');
  assert.ok(reachedPlatform, 'never stood on the platform');
  assert.ok(landedBeyondGap, 'never landed beyond the gap');
  assert.ok(lowestY > -1, `fell into the gap (lowest y ${lowestY})`);
  assert.ok(controller.state.position[2] > -19.7 && controller.state.position[2] < -19.5, `ended at z ${controller.state.position[2]}`);
});

test('the clip pulls the camera in front of a wall it would sit behind', () => {
  const clip = createCameraClip({ obstacles: [WALL], padding: 0.25 });
  const eye = clip([0, 1.5, -19.5], [0, 2, -24.5]);
  assert.ok(eye[2] > -20 && eye[2] < -19.5, `eye z was ${eye[2]}`);
  assert.deepEqual(clip([0, 1.5, -10], [0, 2, -5]), [0, 2, -5]);
});

test('the clip keeps the camera above sloped ground', () => {
  const clip = createCameraClip({ ground: (x, z) => 3 + 0 * x * z, padding: 0.5 });
  const eye = clip([0, 5, 0], [0, 0, 6]);
  assert.ok(eye[1] >= 3.5 - 0.05, `eye y was ${eye[1]}`);
});

test('the clip treats a non-finite ground height as ground height 0', () => {
  const clip = createCameraClip({ ground: () => NaN, padding: 0.5 });
  const eye = clip([0, 5, 0], [0, -4, 6]);
  assert.ok(eye.every(Number.isFinite), `eye was ${eye}`);
  assert.ok(eye[1] >= 0.5 - 0.05, `eye y was ${eye[1]}`);
});

test('the car drives the course on its own controller and chase camera and stops at the wall', () => {
  const clip = createCameraClip({ obstacles: OBSTACLES, ground: courseGround });
  const game = createGame(
    input => createVehicleController({ input, position: [0, 0, 6], ground: courseGround, obstacles: OBSTACLES }),
    (controller, input) => createChaseCamera({ subject: controller.state, input, clipEye: clip }),
  );
  const { input, controller, rig } = game;
  input.press('script/forward');
  let topSpeed = 0;
  let crossedGap = false;
  for (let index = 0; index < 900; index += 1) {
    stepOnce(game);
    topSpeed = Math.max(topSpeed, controller.state.speed);
    if (controller.state.position[2] < -11.5) crossedGap = true;
    assert.ok(controller.state.position[1] > -1, `car fell into the gap at step ${index}`);
    assert.equal(insideAnyBox(rig.pose({ alpha: 1 }).eye, OBSTACLES), false, `camera inside a box at step ${index}`);
  }
  assert.ok(topSpeed > 15, `top speed was ${topSpeed}`);
  assert.ok(crossedGap, 'the car never crossed the gap');
  assert.ok(controller.state.position[2] > -20 + 1 - 1e-6, `car went into the wall: z ${controller.state.position[2]}`);
  assert.ok(controller.state.speed < 0.5, `car still moving at ${controller.state.speed}`);
});

test('the car steers with a bicycle model, reverses and brakes', () => {
  const game = createGame(input => createVehicleController({ input }));
  const { input, controller } = game;
  input.press('script/forward');
  for (let index = 0; index < 120; index += 1) stepOnce(game);
  assert.ok(controller.state.forwardSpeed > 19);
  const yawBefore = controller.state.yaw;
  input.press('script/right');
  for (let index = 0; index < 30; index += 1) stepOnce(game);
  assert.ok(controller.state.yaw > yawBefore + 0.2, 'right steer should turn toward +X');
  assert.ok(controller.state.steer > 0.9);
  input.release('script/right');
  input.release('script/forward');
  input.press('script/jump');
  for (let index = 0; index < 60; index += 1) stepOnce(game);
  assert.equal(controller.state.braking, true);
  assert.ok(Math.abs(controller.state.forwardSpeed) < 1e-6);
  input.release('script/jump');
  input.press('script/back');
  for (let index = 0; index < 120; index += 1) stepOnce(game);
  assert.ok(controller.state.forwardSpeed < -5.9);
});

test('the flyer climbs over the wall with its own controller and chase camera', () => {
  const clip = createCameraClip({ obstacles: OBSTACLES, ground: courseGround });
  const game = createGame(
    input => createFlightController({ input, position: [0, 3, 4], ground: courseGround, obstacles: OBSTACLES }),
    (controller, input) => createChaseCamera({ subject: controller.state, input, clipEye: clip }),
  );
  const { input, controller, rig } = game;
  let highestY = 0;
  for (let index = 0; index < 330; index += 1) {
    stepOnce(game, () => {
      if (index < 40) input.press('script/forward');
      else input.release('script/forward');
    });
    highestY = Math.max(highestY, controller.state.position[1]);
    assert.equal(insideAnyBox(rig.pose({ alpha: 1 }).eye, OBSTACLES), false, `camera inside a box at step ${index}`);
  }
  assert.ok(highestY > 6, `highest y was ${highestY}`);
  assert.ok(controller.state.position[2] < -25, `flyer stopped at z ${controller.state.position[2]}`);
  assert.equal(controller.state.airborne, true);
});

test('the flyer stops at the wall when it flies into it low, and skims the ground', () => {
  const game = createGame(input => createFlightController({ input, position: [0, 2, 0], ground: (x, z) => (z < -9 ? 0 : 0), obstacles: [WALL], cruiseSpeed: 10 }));
  const { controller } = game;
  for (let index = 0; index < 480; index += 1) stepOnce(game);
  assert.ok(controller.state.position[2] > -20 + 0.8 - 1e-6, `flew through the wall: z ${controller.state.position[2]}`);
  assert.ok(controller.state.velocity[2] > -0.01, 'still moving into the wall');
  controller.teleport([0, 2, 5], 0);
  game.input.press('script/back');
  for (let index = 0; index < 90; index += 1) stepOnce(game);
  assert.equal(controller.state.grounded, true);
  assert.equal(controller.state.pitch, 0);
  assert.ok(controller.state.position[1] >= 0);
});

test('a zero-length variable update leaves vehicle and flyer state finite', () => {
  const makers = [
    input => createVehicleController({ input, position: [0, 0, 6], ground: courseGround, obstacles: OBSTACLES }),
    input => createFlightController({ input, position: [0, 3, 4], ground: courseGround, obstacles: OBSTACLES }),
  ];
  for (const makeController of makers) {
    const game = createGame(makeController);
    game.input.press('script/forward');
    stepOnce(game);
    stepOnce(game);
    game.controller.update(0, { mode: 'variable' });
    game.controller.fixedUpdate(0);
    stepOnce(game);
    const { state } = game.controller;
    const numbers = [...state.position, ...state.velocity, state.speed, state.yaw];
    assert.ok(numbers.every(Number.isFinite), `${game.controller.kind} state is not finite: ${numbers}`);
  }
});

test('one non-finite axis sample leaves vehicle, flyer and orbit camera state finite (#2612)', () => {
  let sample = 1;
  const input = { getAxis: () => sample, isHeld: () => false, wasPressed: () => false };
  const makers = [
    ['vehicle', () => createVehicleController({ input })],
    ['flyer', () => createFlightController({ input })],
    ['orbit', () => createOrbitCamera({ subject: { position: [0, 0, 0] }, input, zoom: 'zoom' })],
  ];
  for (const [kind, make] of makers) {
    sample = 1;
    const system = make();
    const runtime = createRuntime(fakeRenderer, { mode: 'fixed', fixedStepSeconds: 1 / 60, systems: [system], scheduler });
    runtime.step(STEP_MILLISECONDS);
    for (const bad of [NaN, Infinity, 1]) {
      sample = bad;
      runtime.step(STEP_MILLISECONDS);
    }
    const state = system.state ?? system;
    const numbers = Object.values(state).flatMap(value => (typeof value === 'number' ? [value] : Array.isArray(value) ? value : []));
    assert.ok(numbers.length > 0 && numbers.every(Number.isFinite), `${kind} state is not finite after a bad sample: ${numbers}`);
    if (kind === 'orbit') {
      const { eye, target } = system.pose({ alpha: 1 });
      assert.ok([...eye, ...target].every(Number.isFinite), `orbit pose is not finite: ${eye} ${target}`);
    }
  }
});

test('flight and driving are deterministic for the same inputs', () => {
  const finalStates = [0, 1].map(() => {
    const game = createGame(input => createFlightController({ input }));
    game.input.press('script/right');
    game.input.press('script/forward');
    for (let index = 0; index < 100; index += 1) stepOnce(game);
    return JSON.stringify(game.controller.state);
  });
  assert.equal(finalStates[0], finalStates[1]);
});

test('the orbit camera turns with look and zooms inside its limits', () => {
  const input = createInput({ axes: { lookX: ['script/lookRight'], lookY: ['script/lookUp'], zoom: ['script/zoomIn'] } });
  const subject = { position: [0, 0, 0], yaw: 0 };
  const rig = createOrbitCamera({ subject, input, zoom: 'zoom', minimumDistance: 2, maximumDistance: 9, distance: 6 });
  const runtime = createRuntime(fakeRenderer, { mode: 'fixed', fixedStepSeconds: 1 / 60, systems: [input, rig], scheduler });
  input.press('script/lookRight');
  input.press('script/zoomIn');
  for (let index = 0; index < 40; index += 1) runtime.step(STEP_MILLISECONDS);
  assert.ok(rig.yaw > 1, `yaw was ${rig.yaw}`);
  assert.equal(rig.distance, 2);
  const { eye, target } = rig.pose({ alpha: 1 });
  approximately(Math.hypot(eye[0] - target[0], eye[1] - target[1], eye[2] - target[2]), 2);
});

test('the chase camera swings round to the subject yaw', () => {
  const subject = { position: [0, 0, 0], yaw: 2 };
  const rig = createChaseCamera({ subject, yaw: 0 });
  const runtime = createRuntime(fakeRenderer, { mode: 'fixed', fixedStepSeconds: 1 / 60, systems: [rig], scheduler });
  for (let index = 0; index < 120; index += 1) runtime.step(STEP_MILLISECONDS);
  approximately(rig.yaw, 2, 0.01);
});

test('the side-scroller camera looks along -Z and leads the subject by its velocity', () => {
  const subject = { position: [0, 1, 0], velocity: [5, 0, 0], yaw: 0 };
  const rig = createSideScrollerCamera({ subject, distance: 8, lookAhead: 3, followSeconds: 0 });
  const runtime = createRuntime(fakeRenderer, { mode: 'fixed', fixedStepSeconds: 1 / 60, systems: [rig], scheduler });
  runtime.step(STEP_MILLISECONDS);
  const { eye, target } = rig.pose({ alpha: 1 });
  approximately(target[0], 3);
  approximately(eye[0], 3);
  approximately(eye[2] - target[2], 8);
  approximately(eye[1], target[1]);
});

test('custom controller and rig kinds register, build and swap at runtime', () => {
  registerController('test-boat', options => ({
    name: options.name ?? 'boat',
    state: { position: [...(options.position ?? [0, 0, 0])], yaw: options.yaw ?? 0 },
    fixedUpdate() {},
  }));
  registerCameraRig('test-fixed', options => ({
    name: options.name ?? 'camera',
    subject: options.subject,
    yaw: options.yaw ?? 0,
    pose: () => ({ eye: [0, 10, 10], target: options.subject.position, up: [0, 1, 0] }),
    fixedUpdate() {},
  }));
  assert.ok(listControllerKinds().includes('test-boat'));
  assert.ok(listCameraRigKinds().includes('test-fixed'));
  const game = createGame(
    input => createController('character', { input, name: 'player', position: [1, 0, 2] }),
    (controller, input) => createCameraRigOfKind('follow', { subject: controller.state, input, name: 'camera' }),
  );
  game.runtime.step(STEP_MILLISECONDS);
  const boat = replaceController(game.runtime, 'player', 'test-boat');
  assert.deepEqual(boat.state.position, game.controller.state.position);
  assert.equal(game.runtime.getSystem('player'), boat);
  const car = replaceController(game.runtime, 'player', 'vehicle', { input: game.input });
  assert.deepEqual(car.state.position, game.controller.state.position);
  const rig = replaceCameraRig(game.runtime, 'camera', 'test-fixed', { subject: car.state });
  assert.equal(game.runtime.getSystem('camera'), rig);
  assert.deepEqual(rig.pose().eye, [0, 10, 10]);
  game.runtime.step(STEP_MILLISECONDS);
});

test('errors name the option and what to pass', () => {
  const input = createScriptedInput();
  assert.throws(() => createVehicleController({ input, maximumSpeed: -1 }), /createVehicleController maximumSpeed must be a number from 0 to 100, got -1/);
  assert.throws(() => createFlightController({ input, cruiseSpeed: 1000 }), /createFlightController cruiseSpeed must be a number/);
  assert.throws(() => createVehicleController({}), /needs options.input/);
  assert.throws(() => createCameraClip({ padding: -1 }), /createCameraClip padding/);
  assert.throws(() => createCameraClip({ obstacles: [{ min: [1, 1, 1], max: [0, 0, 0] }] }), /min must not exceed max/);
  assert.throws(() => createController('missing'), /no kind "missing". Registered kinds: character/);
  assert.throws(() => registerController('vehicle', () => ({})), /already registered/);
  assert.throws(() => registerController('', () => ({})), /non-empty string/);
  assert.throws(() => registerCameraRig('x-rig', null), /must be a function/);
  registerController('test-broken', () => ({}));
  assert.throws(() => createController('test-broken'), /must return a runtime system with state.position/);
  assert.throws(() => createOrbitCamera({ subject: { position: [0, 0, 0] }, zoom: 'zoom' }), /needs options.input/);
});

test('a refused teleport leaves the controller where it was (#2614)', () => {
  const input = createScriptedInput();
  const controllers = [
    createCharacterController({ input, position: [1, 2, 3], yaw: 0.5 }),
    createVehicleController({ input, position: [1, 2, 3], yaw: 0.5 }),
    createFlightController({ input, position: [1, 2, 3], yaw: 0.5 }),
  ];
  for (const controller of controllers) {
    const before = structuredClone(controller.state);
    assert.throws(() => controller.teleport([9, 9, 9], NaN), /teleport yaw must be a number/);
    assert.deepEqual(controller.state, before, controller.kind);
  }
});

function approximately(actual, expected, tolerance = 1e-6) {
  assert.ok(Math.abs(actual - expected) <= tolerance, `expected ${actual} to be within ${tolerance} of ${expected}`);
}