FirstPersonCamera.core.ts

FirstPersonCamera — pure core.

Two things the walking camera needs that have nothing to do with a renderer or a world: the collision sweep that turns "I want to step there" into "here is where you actually end up", and the little codec that remembers the pose between visits. Plain numbers in, plain numbers out, so both are unit-tested with a handful of boxes and no engine at all.

FirstPersonCamera.core.ts

import type { BoxBounds } from '../Obstacle/Obstacle.defs';
import { resolveCircleVsBox } from '../Obstacle/Obstacle.core';

/** A floor-plane point, `[x, z]`. */
export type WalkPoint = readonly [number, number];

Contact tolerance. A player the sweep has parked exactly one radius off a face sits at face - r, and face - (face - r) is not quite r in floating point. Without a little give, next frame that reads as a sliver of overlap: the box is taken for one the player is "inside", and the never-deeper rule pins them to the wall instead of letting them slide.

FirstPersonCamera.core.ts

const EPS = 1e-9;

Sweep a circle of radius from from toward to through boxes and return where it ends up.

The step is walked in substeps no longer than half a radius, and after each one the circle is pushed back out of anything it overlaps along the contact normal (resolveCircleVsBox from Obstacle.core, reused as-is). That push removes only the part of the motion that points INTO the box and keeps the rest, which is what makes a wall feel like a wall rather than glue: walking diagonally into a cabinet, the player slides along its front instead of stopping dead, and at a corner the normal is the corner's own, so the circle rounds it rather than catching on it.

The substep is what makes this a SWEEP and not a check of where the step lands. From a clear spot the centre sits at least a radius from every box surface, so a move of half a radius can never carry it inside one; every push is therefore a push out from a surface — never resolveCircleVsBox's centre-inside branch, which ejects through the nearest face and would send a hitched-frame step (a tab switch, 3 m in one go) out the far side of a 20 cm wall. The same reasoning is why it cannot pass clean through a box.

A box the circle already overlaps at from — a pose restored into a freshly placed prop, a spawn point inside a wall — is handled apart: it never displaces the player (no teleport out the far side), it only refuses any step that would push DEEPER into it. Backing out is always allowed.

Why not the classic two-axis resolve (X then Z, each stopped at the face it hits)? It is the right tool for a BOX-shaped player and the wrong one for a circle: pressed diagonally into a cabinet corner, an exact circle is refused on X (that alone would clip the corner) and refused on Z (likewise), one axis at a time, and wedges on the edge instead of rounding it — the auto-walk stalled there in testing. The normal push has no such seam; on a flat face the two are the same motion.

FirstPersonCamera.core.ts

export function resolveWalk(
  from: WalkPoint,
  to: WalkPoint,
  radius: number,
  boxes: readonly BoxBounds[],
): [number, number] {
  const clear: BoxBounds[] = [];
  const inside: BoxBounds[] = [];
  for (const box of boxes) {
    (circleOverlapsBox(from[0], from[1], radius, box) ? inside : clear).push(box);
  }

  const dx = to[0] - from[0];
  const dz = to[1] - from[1];
  const steps = Math.max(1, Math.ceil(Math.hypot(dx, dz) / (radius / 2)));
  // Each substep is a lerp from `from` plus everything the boxes have pushed
  // so far (rather than a running sum of increments), so a walk nothing
  // touched lands on `to` to the bit and a slide keeps its sideways part
  // exactly.
  let ox = 0;
  let oz = 0;
  for (let i = 1; i <= steps; i++) {
    const last = i === steps;
    const px = (last ? to[0] : from[0] + dx * (i / steps)) + ox;
    const pz = (last ? to[1] : from[1] + dz * (i / steps)) + oz;
    const [nx, nz] = settle(px, pz, radius, clear);
    ox += nx - px;
    oz += nz - pz;
  }
  let x = to[0] + ox;
  let z = to[1] + oz;

  // Already inside something: never pushed, never allowed deeper.
  for (const box of inside) {
    const cx = (box.minX + box.maxX) / 2;
    const cz = (box.minZ + box.maxZ) / 2;
    if (Math.abs(x - cx) < Math.abs(from[0] - cx)) x = from[0];
    if (Math.abs(z - cz) < Math.abs(from[1] - cz)) z = from[1];
  }
  return [x, z];
}

True when a circle of r at (x, z) overlaps box. Touching counts as clear, to within {@link EPS} — the circle the sweep parked against a face last frame must not read as "inside" this frame.

FirstPersonCamera.core.ts

export function circleOverlapsBox(x: number, z: number, r: number, box: BoxBounds): boolean {
  const nx = x < box.minX ? box.minX : x > box.maxX ? box.maxX : x;
  const nz = z < box.minZ ? box.minZ : z > box.maxZ ? box.maxZ : z;
  const dx = x - nx;
  const dz = z - nz;
  return dx * dx + dz * dz < r * r - EPS;
}

Push the circle out of every box it overlaps until nothing moves it. Leaving one box can land it in a neighbour (two cabinets closer together than the player is wide), hence the passes; the cap is belt and braces. A push smaller than {@link EPS} is rounding, not contact, and is ignored.

FirstPersonCamera.core.ts

function settle(x: number, z: number, r: number, boxes: readonly BoxBounds[]): [number, number] {
  for (let pass = 0; pass < 8; pass++) {
    let moved = false;
    for (const box of boxes) {
      const [nx, nz] = resolveCircleVsBox(x, z, r, box);
      if (Math.abs(nx - x) > EPS || Math.abs(nz - z) > EPS) {
        x = nx;
        z = nz;
        moved = true;
      }
    }
    if (!moved) break;
  }
  return [x, z];
}

// ── Pose persistence ─────────────────────────────────────────────────────────

/** What a visit leaves behind: where you stood and which way you looked. */
export interface PersistedPose {
  x: number;
  z: number;
  yaw: number;
}

/** The slice of `localStorage` the codec needs — anything with these two works. */
export interface PoseStore {
  getItem(key: string): string | null;
  setItem(key: string, value: string): void;
}

Read a remembered pose. Anything that isn't three finite numbers under the key — nothing stored yet, a hand-edited value, a store that throws (some embedded and private-browsing contexts do) — reads as null, never as an exception.

FirstPersonCamera.core.ts

export function readPose(store: PoseStore | null | undefined, key: string): PersistedPose | null {
  if (!store) return null;
  try {
    const raw = store.getItem(key);
    if (!raw) return null;
    const parsed = JSON.parse(raw) as Partial<PersistedPose> | null;
    if (!parsed || typeof parsed !== 'object') return null;
    const { x, z, yaw } = parsed;
    if (!Number.isFinite(x) || !Number.isFinite(z) || !Number.isFinite(yaw)) return null;
    return { x: x as number, z: z as number, yaw: yaw as number };
  } catch {
    return null;
  }
}

/** Remember a pose. Returns false, rather than throwing, when the store refuses. */
export function writePose(store: PoseStore | null | undefined, key: string, pose: PersistedPose): boolean {
  if (!store) return false;
  try {
    store.setItem(key, JSON.stringify({ x: pose.x, z: pose.z, yaw: pose.yaw }));
    return true;
  } catch {
    return false;
  }
}

FirstPersonCamera.defs.ts

FirstPersonCamera — definitions.

Holds the FirstPersonCameraComponent class and the shapes its data and events travel in. No System lives here, which is the point: another component can name FirstPersonCamera in a query, or type an event it listens for, without pulling FirstPersonCamera's behaviour into its own bundle. Import from here, not from FirstPersonCamera.ts.

FirstPersonCamera.defs.ts

import { Component } from '@babylonjsmarket/ecs';
export { FirstPersonCameraEvents } from './FirstPersonCamera.events';

/** Rectangle (metres) the camera is clamped to, so it can't leave the room. */
export interface FirstPersonCameraBounds {
  minX: number;
  maxX: number;
  minZ: number;
  maxZ: number;
}

/** Input shape accepted by the constructor (and the scene JSON). */
export interface FirstPersonCameraInput {
  /** Eye height above the floor, in metres. ~1.7 is a standing adult. */
  eyeHeight?: number;
  /** Start position on the floor plane, `[x, z]`. */
  position?: [number, number];
  /** Initial facing, in radians. 0 looks toward +Z. */
  yaw?: number;
  /** Walk speed, world units / second. */
  moveSpeed?: number;
  /** Turn speed, radians / second (A / D). */
  turnSpeed?: number;
  /**
   * Seconds an auto-approach takes — clicking a machine to walk over to it.
   * Fixed, not distance-based: a click across the hall and a click at your
   * elbow should both read as one gesture. 0.7 is the hand-written room's.
   */
  approachDuration?: number;
  /** Vertical field of view, in radians. */
  fov?: number;
  /** Near clip-plane distance, metres. */
  near?: number;
  /** Far clip-plane distance, metres. */
  far?: number;
  /**
   * When set, the camera position is clamped to this rectangle every frame so
   * the player can't walk through the walls. Inset it from the wall faces by
   * roughly the player's shoulder width. Omit for unbounded movement.
   */
  bounds?: FirstPersonCameraBounds;
  /**
   * Walk collision against the scene's Obstacle footprints: the player slides
   * along cabinets and props instead of walking through them. Default TRUE.
   * `bounds` still applies on top, as the outer belt.
   */
  collide?: boolean;
  /**
   * The player's body radius for that collision, in metres — a shoulder's
   * half-width. Default 0.45.
   */
  radius?: number;
  /**
   * localStorage key under which the live pose (x, z, yaw) is remembered and
   * restored next visit, so a reload puts you back where you were standing.
   * Omit for a fresh start at `position` every time.
   */
  persistKey?: string;
}

export class FirstPersonCameraComponent extends Component {
  // Declared, not read off the class name: a minified build renames classes,
  // and the scene file still has to find this class by name.
  static componentType = 'FirstPersonCamera';

  eyeHeight: number;
  /** Start position `[x, z]`; the live pose lives on the System's runtime map. */
  startX: number;
  startZ: number;
  yaw: number;
  moveSpeed: number;
  turnSpeed: number;
  approachDuration: number;
  fov: number;
  near: number;
  far: number;
  bounds?: FirstPersonCameraBounds;
  collide: boolean;
  radius: number;
  persistKey?: string;

  constructor(data: FirstPersonCameraInput = {}) {
    super();
    this.eyeHeight = data.eyeHeight ?? 1.7;
    this.startX = data.position?.[0] ?? 0;
    this.startZ = data.position?.[1] ?? 0;
    this.yaw = data.yaw ?? 0;
    this.moveSpeed = data.moveSpeed ?? 3;
    this.turnSpeed = data.turnSpeed ?? 1.8;
    this.approachDuration = data.approachDuration ?? 0.7;
    this.fov = data.fov ?? 1.1;
    this.near = data.near ?? 0.1;
    this.far = data.far ?? 200;
    this.bounds = data.bounds;
    this.collide = data.collide ?? true;
    this.radius = data.radius ?? 0.45;
    this.persistKey = data.persistKey;
  }

  serialize(): FirstPersonCameraInput {
    return {
      eyeHeight: this.eyeHeight,
      position: [this.startX, this.startZ],
      yaw: this.yaw,
      moveSpeed: this.moveSpeed,
      turnSpeed: this.turnSpeed,
      approachDuration: this.approachDuration,
      fov: this.fov,
      near: this.near,
      far: this.far,
      ...(this.bounds ? { bounds: { ...this.bounds } } : {}),
      collide: this.collide,
      radius: this.radius,
      ...(this.persistKey ? { persistKey: this.persistKey } : {}),
    };
  }
}

FirstPersonCamera.events.ts

FirstPersonCamera — event names.

The EventBus contract for FirstPersonCamera: what it emits and what it listens for. A listener imports these names from here, never from FirstPersonCamera.ts, so it can hear FirstPersonCamera without carrying FirstPersonCamera's System. bjs download hands this file out free with any component that imports it, and it does not make FirstPersonCamera a dependency to buy.

FirstPersonCamera.events.ts

// FirstPersonCameraEvents — from FirstPersonCamera
export const FirstPersonCameraEvents = {
  /**
   * The walking camera exists. Payload `{ entityId, handle }` — `handle` is the
   * renderer's camera handle, so anything that must follow the player's ears or
   * eyes (Sound's audio listener) can attach to it without asking the System.
   */
  CREATED: 'firstpersoncamera.created',
  /**
   * Ask the walking camera to WALK ITSELF to a spot: `{ x, z, yaw? }`. It
   * paths there at its own moveSpeed/turnSpeed rather than teleporting, and any
   * movement key cancels it — the player is never trapped in an animation.
   */
  GOTO: 'firstpersoncamera.goto',
  /**
   * Emitted once the camera reaches a GOTO target, or gives one up: payload
   * `{ entityId, x, z, yaw, cancelled }`, where `cancelled` is true when a
   * movement key took over or an Obstacle blocked the path for good.
   */
  ARRIVED: 'firstpersoncamera.arrived',
} as const;

FirstPersonCamera.ts

FirstPersonCamera — a walk-around, eye-height first-person camera driven by the keyboard. Creates a FREE perspective camera through the RendererAdapter and poses it every frame; W/S walk, A/D turn (tank), Q/E strafe, always at a fixed eye height. Optional bounds keep the player inside the room, and the scene's Obstacle footprints keep them out of the furniture: every step — a key press or a GOTO auto-walk — goes through the pure sweep in FirstPersonCamera.core.ts, which slides the player along a cabinet face rather than stopping them dead.

Zero imports from @babylonjs or three — the camera is created and posed entirely through world.renderer (createPerspectiveCamera / setCameraPose), so the same component runs under the Babylon and Three adapters unchanged.

FirstPersonCamera.ts

import { System } from '@babylonjsmarket/ecs';
import type { Entity, EventBus } from '@babylonjsmarket/ecs';
import type { CameraHandle, Quaternion, Vec3 } from '@babylonjsmarket/ecs/renderer-types';
import { KeyboardInputEvents } from '@babylonjsmarket/arcade';
import { FirstPersonCameraEvents } from './FirstPersonCamera.events';
import { collectObstacleBoxes, type ObstacleBox } from '../Obstacle/Obstacle';
import { readPose, resolveWalk, writePose, type PoseStore } from './FirstPersonCamera.core';
import { FirstPersonCameraComponent } from './FirstPersonCamera.defs';

export { FirstPersonCameraComponent } from './FirstPersonCamera.defs';
export type {
  FirstPersonCameraInput,
  FirstPersonCameraBounds,
} from './FirstPersonCamera.defs';
export { resolveWalk, readPose, writePose } from './FirstPersonCamera.core';
export type { PersistedPose, PoseStore, WalkPoint } from './FirstPersonCamera.core';

const FORWARD_KEYS = new Set(['KeyW', 'ArrowUp']);
const BACK_KEYS = new Set(['KeyS', 'ArrowDown']);
const TURN_LEFT_KEYS = new Set(['KeyA', 'ArrowLeft']);
const TURN_RIGHT_KEYS = new Set(['KeyD', 'ArrowRight']);
const STRAFE_LEFT_KEYS = new Set(['KeyQ']);
const STRAFE_RIGHT_KEYS = new Set(['KeyE']);

/** Live (non-serializable) pose + camera handle, kept off the pure-data Component. */
interface FirstPersonCameraRuntime {
  handle?: CameraHandle;
  x: number;
  z: number;
  yaw: number;
  /**
   * An in-flight approach: where it started, where it ends, and how far through
   * it is. Held as a whole path rather than a target, because the move is a
   * timed glide, not a walk that is re-steered every frame.
   */
  goto?: {
    fromX: number; fromZ: number; fromYaw: number;
    x: number; z: number; yaw?: number;
    /** Signed shortest turn from fromYaw to the final facing. */
    dYaw: number;
    t: number;
    duration: number;
  };
  /** Seconds since the pose was last written to storage. */
  persistAccum: number;
  /** The pose last written, so an idle player costs no storage writes. */
  persisted?: { x: number; z: number; yaw: number };
}

/** How often the pose is remembered while the player moves, in seconds. */
const PERSIST_INTERVAL = 1;

type GotoStep = 'walking' | 'arrived';

/** Shortest signed angle from `a` to `b`, so a turn never takes the long way. */
function angleDelta(a: number, b: number): number {
  let d = (b - a) % (Math.PI * 2);
  if (d > Math.PI) d -= Math.PI * 2;
  if (d < -Math.PI) d += Math.PI * 2;
  return d;
}

The browser's localStorage, or null where there is none (SSR, tests without a DOM) or where merely touching it throws (sandboxed iframes).

FirstPersonCamera.ts

function poseStore(): PoseStore | null {
  if (typeof window === 'undefined') return null;
  try {
    return window.localStorage ?? null;
  } catch {
    return null;
  }
}

export class FirstPersonCameraSystem extends System {
  private forward = 0;
  private back = 0;
  private turnLeft = 0;
  private turnRight = 0;
  private strafeLeft = 0;
  private strafeRight = 0;

  private readonly runtime = new WeakMap<FirstPersonCameraComponent, FirstPersonCameraRuntime>();
  private readonly _quat: Quaternion = { x: 0, y: 0, z: 0, w: 1 };
  private readonly _pos: Vec3 = [0, 0, 0];
  /** This frame's obstacle snapshot; collected on first use, dropped at frame end. */
  private frameBoxes: ObstacleBox[] | null = null;

  private keydownHandler: ((e: KeyboardEvent) => void) | null = null;
  private keyupHandler: ((e: KeyboardEvent) => void) | null = null;

  protected query = { required: [FirstPersonCameraComponent] };

  constructor(eventBus: EventBus) {
    super(eventBus);
  }

  protected onInitialize(): void {
    this.listen(KeyboardInputEvents.KEYDOWN, (e: { code: string }) => this.setKey(e.code, 1));
    // Walk-me-there requests (e.g. clicking a cabinet). Event-driven so nothing
    // needs a reference to this System.
    this.listen(FirstPersonCameraEvents.GOTO, (e: { x: number; z: number; yaw?: number }) => {
      for (const entity of this.entities) {
        const comp = entity.get(FirstPersonCameraComponent);
        if (comp) {
          const rt = this.getRuntime(comp);
          rt.goto = this.planApproach(comp, rt, e);
        }
      }
    });
    this.listen(KeyboardInputEvents.KEYUP, (e: { code: string }) => this.setKey(e.code, 0));

    // Bridge DOM keyboard events to the bus so scaffolded projects walk around
    // out of the box without a separate input-source system. Tests skip this
    // branch (no `window`) and emit the bus events directly.
    if (typeof window !== 'undefined') {
      this.keydownHandler = (e: KeyboardEvent) =>
        this.eventBus.emit(KeyboardInputEvents.KEYDOWN, { code: e.code });
      this.keyupHandler = (e: KeyboardEvent) =>
        this.eventBus.emit(KeyboardInputEvents.KEYUP, { code: e.code });
      window.addEventListener('keydown', this.keydownHandler);
      window.addEventListener('keyup', this.keyupHandler);
    }

    // Systems-after-entities (live SceneLoader) path: the entity already exists
    // when we initialize, so create its camera now.
    for (const entity of this.entities) {
      const comp = entity.get(FirstPersonCameraComponent);
      if (comp) this.ensureCamera(entity, comp);
    }
  }

  protected onEntityAdded(entity: Entity): void {
    const comp = entity.get(FirstPersonCameraComponent);
    if (comp) this.ensureCamera(entity, comp);
  }

  protected onEntityRemoved(entity: Entity): void {
    // A scene swap mid-walk still remembers where you were.
    const comp = entity.get(FirstPersonCameraComponent);
    if (comp) this.persist(comp, this.getRuntime(comp), true);
  }

  protected onShutdown(): void {
    for (const entity of this.entities) {
      const comp = entity.get(FirstPersonCameraComponent);
      if (comp) this.persist(comp, this.getRuntime(comp), true);
    }
    if (typeof window !== 'undefined') {
      if (this.keydownHandler) window.removeEventListener('keydown', this.keydownHandler);
      if (this.keyupHandler) window.removeEventListener('keyup', this.keyupHandler);
    }
    this.keydownHandler = null;
    this.keyupHandler = null;
  }

  /**
   * The live pose for a component, seeded from its start pose — or, when it
   * has a `persistKey`, from wherever the player stood last time.
   */
  private getRuntime(comp: FirstPersonCameraComponent): FirstPersonCameraRuntime {
    let rt = this.runtime.get(comp);
    if (!rt) {
      rt = { x: comp.startX, z: comp.startZ, yaw: comp.yaw, persistAccum: 0 };
      const saved = comp.persistKey ? readPose(poseStore(), comp.persistKey) : null;
      if (saved) {
        rt.x = saved.x;
        rt.z = saved.z;
        rt.yaw = saved.yaw;
        rt.persisted = { ...saved };
      }
      this.runtime.set(comp, rt);
    }
    return rt;
  }

  /** Create the perspective camera once, seeded at the component's start pose. */
  private ensureCamera(entity: Entity, comp: FirstPersonCameraComponent): void {
    const r = this.world?.renderer;
    if (!r) return;
    const rt = this.getRuntime(comp);
    if (rt.handle) return;
    rt.handle = r.createPerspectiveCamera('firstPerson', {
      fov: comp.fov,
      near: comp.near,
      far: comp.far,
      position: [rt.x, comp.eyeHeight, rt.z],
      orientation: yawQuaternion(rt.yaw, this._quat),
    });
    // Announce the handle: the audio listener (Sound) rides this camera so
    // spatial falloff is judged from the player's head, not the world origin.
    this.eventBus.emit(FirstPersonCameraEvents.CREATED, {
      entityId: entity.id,
      handle: rt.handle,
    });
  }

  /** The obstacle footprints, collected at most once per frame. */
  private boxes(): ObstacleBox[] {
    if (!this.frameBoxes) this.frameBoxes = this.world ? collectObstacleBoxes(this.world) : [];
    return this.frameBoxes;
  }

  /**
   * Move the player toward (nx, nz): the collision sweep first, then the
   * bounds clamp as the outer belt. Every step, keyed or automatic, comes
   * through here.
   */
  private moveTo(comp: FirstPersonCameraComponent, rt: FirstPersonCameraRuntime, nx: number, nz: number): void {
    if (comp.collide) {
      [nx, nz] = resolveWalk([rt.x, rt.z], [nx, nz], comp.radius, this.boxes());
    }
    rt.x = nx;
    rt.z = nz;
    this.clampToBounds(comp, rt);
  }

  /** Keep the camera inside the room rectangle. The outer belt, always on. */
  private clampToBounds(comp: FirstPersonCameraComponent, rt: FirstPersonCameraRuntime): void {
    if (!comp.bounds) return;
    rt.x = clamp(rt.x, comp.bounds.minX, comp.bounds.maxX);
    rt.z = clamp(rt.z, comp.bounds.minZ, comp.bounds.maxZ);
  }

  /**
   * Lay out an approach: a fixed-length glide from where the camera is now to
   * the spot in front of the machine, ending on the facing that looks at it.
   *
   * Held as a path rather than re-solved each frame so the motion is one smooth
   * move. Duration is fixed, not distance-based, which is what makes a click
   * across the hall and a click at your elbow both feel like one gesture.
   */
  private planApproach(
    comp: FirstPersonCameraComponent,
    rt: FirstPersonCameraRuntime,
    e: { x: number; z: number; yaw?: number },
  ): FirstPersonCameraRuntime['goto'] {
    const finalYaw = e.yaw ?? rt.yaw;
    return {
      fromX: rt.x,
      fromZ: rt.z,
      fromYaw: rt.yaw,
      x: e.x,
      z: e.z,
      yaw: e.yaw,
      // Take the short way round, so a machine behind you never spins the
      // camera the long way through 300 degrees.
      dYaw: angleDelta(rt.yaw, finalYaw),
      t: 0,
      duration: Math.max(1e-3, comp.approachDuration),
    };
  }

  /**
   * Advance an approach by `dt`.
   *
   * This is a GLIDE, and deliberately not the tank motion the keys produce.
   * Turning to face the target, walking, then turning again to face the machine
   * reads as three separate robotic moves and takes as long as the room is
   * wide. Easing position and facing together over a fixed time is what the
   * hand-written room did, and it is the thing that made clicking a cabinet
   * feel like walking up to one.
   *
   * It is also on rails: obstacles are ignored for the duration. A glide that
   * caught on a cabinet corner would stall in the open with no way to explain
   * itself, and the destination is always a clear spot in front of a machine.
   * The player still wins instantly — any movement key cancels.
   */
  private stepToward(
    comp: FirstPersonCameraComponent,
    rt: FirstPersonCameraRuntime,
    dt: number,
  ): GotoStep {
    const g = rt.goto;
    if (!g) return 'arrived';

    g.t += dt;
    const u = Math.min(1, g.t / g.duration);
    // Ease out: quick off the mark, settling into the spot rather than
    // stopping dead. Same curve the old room used.
    const k = 1 - (1 - u) * (1 - u);

    rt.x = g.fromX + (g.x - g.fromX) * k;
    rt.z = g.fromZ + (g.z - g.fromZ) * k;
    rt.yaw = g.fromYaw + g.dYaw * k;
    this.clampToBounds(comp, rt);

    if (u < 1) return 'walking';

    rt.x = g.x;
    rt.z = g.z;
    if (g.yaw !== undefined) rt.yaw = g.yaw;
    this.clampToBounds(comp, rt);
    rt.goto = undefined;
    return 'arrived';
  }

  private setKey(code: string, value: 0 | 1): void {
    if (FORWARD_KEYS.has(code)) this.forward = value;
    else if (BACK_KEYS.has(code)) this.back = value;
    else if (TURN_LEFT_KEYS.has(code)) this.turnLeft = value;
    else if (TURN_RIGHT_KEYS.has(code)) this.turnRight = value;
    else if (STRAFE_LEFT_KEYS.has(code)) this.strafeLeft = value;
    else if (STRAFE_RIGHT_KEYS.has(code)) this.strafeRight = value;
  }

  /**
   * Remember the pose under `persistKey`: about once a second while it
   * changes, and always when `force` (shutdown, entity removal). Storage that
   * is missing or refuses is simply skipped.
   */
  private persist(comp: FirstPersonCameraComponent, rt: FirstPersonCameraRuntime, force: boolean, dt = 0): void {
    if (!comp.persistKey) return;
    rt.persistAccum += dt;
    if (!force && rt.persistAccum < PERSIST_INTERVAL) return;
    rt.persistAccum = 0;
    const p = rt.persisted;
    if (p && p.x === rt.x && p.z === rt.z && p.yaw === rt.yaw) return;
    if (writePose(poseStore(), comp.persistKey, rt)) {
      rt.persisted = { x: rt.x, z: rt.z, yaw: rt.yaw };
    }
  }

  protected onUpdate(dt: number): void {
    const r = this.world?.renderer;
    if (!r) return;
    this.frameBoxes = null;

    // Both signs are set by the CANONICAL frame, not by taste. Yaw 0 looks +Z
    // and forward(yaw) = (sin yaw, 0, cos yaw), so d/dyaw of forward at the
    // spawn pose (yaw = π, looking -Z) is -X — increasing yaw swings the view
    // toward -X, which the right-handed renderer draws on the LEFT. So turning
    // RIGHT has to DECREASE yaw. Both of these read the other way round until
    // 2026-09-02, carried over from a left-handed room where they were right.
    const turn = this.turnLeft - this.turnRight;
    const fwd = this.forward - this.back;
    const strafe = this.strafeRight - this.strafeLeft;

    for (const entity of this.entities) {
      const comp = entity.get(FirstPersonCameraComponent);
      if (!comp) continue;
      // Idempotent: creates the camera on the first frame it can (covers the
      // case where the renderer wasn't ready when the entity was added), and
      // returns early once the handle exists.
      this.ensureCamera(entity, comp);
      const rt = this.getRuntime(comp);
      if (!rt.handle) continue;

      // A GOTO walks the camera to a spot on its own. The player always wins:
      // ANY movement key cancels it, so you can never be stuck watching the
      // camera drive itself somewhere you didn't want to go.
      if (rt.goto) {
        if (turn !== 0 || fwd !== 0 || strafe !== 0) {
          rt.goto = undefined;
          this.eventBus.emit(FirstPersonCameraEvents.ARRIVED, {
            entityId: entity.id,
            x: rt.x,
            z: rt.z,
            yaw: rt.yaw,
            cancelled: true,
          });
        } else {
          const step = this.stepToward(comp, rt, dt);
          if (step !== 'walking') {
            this.eventBus.emit(FirstPersonCameraEvents.ARRIVED, {
              entityId: entity.id,
              x: rt.x,
              z: rt.z,
              yaw: rt.yaw,
              // A glide always finishes. `cancelled` is now only ever true on
              // the branch above, where a movement key took over.
              cancelled: false,
            });
          }
          this._pos[0] = rt.x;
          this._pos[1] = comp.eyeHeight;
          this._pos[2] = rt.z;
          r.setCameraPose(rt.handle, this._pos, yawQuaternion(rt.yaw, this._quat));
          this.persist(comp, rt, false, dt);
          continue;
        }
      }

      rt.yaw += turn * comp.turnSpeed * dt;

      if (fwd !== 0 || strafe !== 0) {
        const sin = Math.sin(rt.yaw);
        const cos = Math.cos(rt.yaw);
        // forward = (sin, 0, cos). The player's right hand is forward × up,
        // which in a right-handed frame is (-cos, 0, sin) — NOT (cos, 0, -sin),
        // the left-handed answer this used to carry. At the spawn pose that is
        // the difference between strafing toward +X (what you see on your
        // right) and toward -X.
        const step = comp.moveSpeed * dt;
        this.moveTo(
          comp,
          rt,
          rt.x + (sin * fwd - cos * strafe) * step,
          rt.z + (cos * fwd + sin * strafe) * step,
        );
      }

      this._pos[0] = rt.x;
      this._pos[1] = comp.eyeHeight;
      this._pos[2] = rt.z;
      r.setCameraPose(rt.handle, this._pos, yawQuaternion(rt.yaw, this._quat));
      this.persist(comp, rt, false, dt);
    }
    this.frameBoxes = null;
  }
}

/** A yaw-only orientation quaternion (rotation about +Y), written into `out`. */
function yawQuaternion(yaw: number, out: Quaternion): Quaternion {
  const half = yaw * 0.5;
  out.x = 0;
  out.y = Math.sin(half);
  out.z = 0;
  out.w = Math.cos(half);
  return out;
}

function clamp(v: number, min: number, max: number): number {
  return v < min ? min : v > max ? max : v;
}
export { FirstPersonCameraEvents } from './FirstPersonCamera.events';

FirstPersonCamera.contract.test.ts

13 ✓

ArcadeECS contract: FirstPersonCamera

Component() with no args constructs and applies defaults
Component merges sample input on top of defaults
Component.serialize() round-trips into a constructor input
System constructor signature is exactly (eventBus)
System declares a non-empty query.required
world.addSystem + initialize + update runs clean with no entity
adding the Component attaches the entity to the System
world.update(dt) does not throw with the entity attached
Adapter handles: create/dispose balance across entity lifecycle
EventBus has no lingering listeners after world.destroy()
Declared event names follow the "{domain}.{action}" convention
Emits at least one declared output event during an update
Registers a listener for each declared input event

Last run 2026-10-08

FirstPersonCamera.contract.test.ts

import { FirstPersonCameraEvents } from './FirstPersonCamera.events';
import { KeyboardInputEvents } from '@babylonjsmarket/arcade';
import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import { FirstPersonCameraComponent, FirstPersonCameraSystem } from './FirstPersonCamera';

runMechanicContract({
  name: 'FirstPersonCamera',
  componentClass: FirstPersonCameraComponent,
  systemClass: FirstPersonCameraSystem,
  sampleInput: { eyeHeight: 1.55, position: [0, 4.8], yaw: Math.PI, moveSpeed: 2.2, radius: 0.45 },
  events: {
    input: [KeyboardInputEvents.KEYDOWN, KeyboardInputEvents.KEYUP, FirstPersonCameraEvents.GOTO],
    output: [FirstPersonCameraEvents.CREATED],
  },
  makeInputPayload(event) {
    if (event === FirstPersonCameraEvents.GOTO) return { x: 1, z: 1 };
    return { code: 'KeyW' };
  },
});

FirstPersonCamera.core.test.ts

22 ✓

resolveWalk — the walk-collision sweep

with no boxes, the step lands exactly where it was aimed
a step that touches nothing is untouched
head-on: stops one radius short of the face it walked into
head-on from the far side stops at the far face, not the near one
glancing: slides along the face instead of stopping dead
glancing along a box: X is stopped at the side, Z carries on
corner: the circle rounds the corner rather than catching on it
corner: a step aimed into a corner slides round it instead of wedging
corner: a long step that clips a corner is deflected round it, never through it
corner: a step aimed straight at a corner point stops one radius from it
substeps a long diagonal step so it neither tunnels nor lands inside
touching is clear: standing exactly one radius off a face does not get pushed
keeps sliding on the frames AFTER first contact, rounding noise and all
starting inside: can back out, cannot push deeper, is never displaced
a large step never tunnels through a thin wall
two neighbours closer than the body is wide: the result does not depend on their order
passes a box it only skirts on the other axis

circleOverlapsBox

overlaps a face, clears when a radius away, and rounds the corners

pose persistence codec

round-trips a pose
reads nothing when nothing was stored, or the store is missing
rejects anything that is not three finite numbers
a store that throws reads as empty and writes as refused

Last run 2026-10-08

FirstPersonCamera.core.test.ts

import { describe, expect, it, vi } from 'vitest';
import type { BoxBounds } from '../Obstacle/Obstacle.defs';
import { circleOverlapsBox, readPose, resolveWalk, writePose } from './FirstPersonCamera.core';

const R = 0.45;
/** A cabinet-sized box: 1 m wide (x ∈ [0, 1]) and 1 m deep (z ∈ [0, 1]). */
const box: BoxBounds = { minX: 0, maxX: 1, minZ: 0, maxZ: 1 };
/** A long wall across the room at z ∈ [1, 2]. */
const wall: BoxBounds = { minX: -5, maxX: 5, minZ: 1, maxZ: 2 };

describe('resolveWalk — the walk-collision sweep', () => {
  it('with no boxes, the step lands exactly where it was aimed', () => {
    expect(resolveWalk([0, 0], [1.5, -2], R, [])).toEqual([1.5, -2]);
  });

  it('a step that touches nothing is untouched', () => {
    expect(resolveWalk([-3, -3], [-2.5, -2.5], R, [box, wall])).toEqual([-2.5, -2.5]);
  });

  it('head-on: stops one radius short of the face it walked into', () => {
    // Walking +Z straight at the wall from z = 0; the wall's near face is z = 1.
    const [x, z] = resolveWalk([0, 0], [0, 3], R, [wall]);
    expect(x).toBe(0);
    expect(z).toBeCloseTo(1 - R, 10);
  });

  it('head-on from the far side stops at the far face, not the near one', () => {
    const [, z] = resolveWalk([0, 3], [0, 0], R, [wall]);
    expect(z).toBeCloseTo(2 + R, 10);
  });

  it('glancing: slides along the face instead of stopping dead', () => {
    // Diagonal into the wall: the Z axis is stopped at the face, the X axis
    // keeps the sideways part of the step — the slide.
    const [x, z] = resolveWalk([0, 0], [0.5, 3], R, [wall]);
    expect(x).toBe(0.5);
    expect(z).toBeCloseTo(1 - R, 10);
  });

  it('glancing along a box: X is stopped at the side, Z carries on', () => {
    const [x, z] = resolveWalk([-1, 0.5], [0.5, 0.8], R, [box]);
    expect(x).toBeCloseTo(-R, 10);
    expect(z).toBeCloseTo(0.8, 10);
  });

  it('corner: the circle rounds the corner rather than catching on it', () => {
    // Coming diagonally at the (0, 0) corner. X passes clean (at z = -1 the
    // circle is a full metre off the box); Z then finds the circle clipping
    // the corner and pushes it back out along the corner's normal — so it
    // ends exactly one radius from the corner, on the diagonal it came in on.
    const [x, z] = resolveWalk([-1, -1], [-0.2, -0.2], R, [box]);
    expect(x).toBeLessThan(0);
    expect(z).toBeLessThan(0);
    expect(x).toBeCloseTo(z, 10);
    expect(Math.hypot(x - box.minX, z - box.minZ)).toBeCloseTo(R, 10);
  });

  it('corner: a step aimed into a corner slides round it instead of wedging', () => {
    // Tangent to the (0.6, 1.9) corner and pushing up-and-right into it.
    // Axis by axis both moves would be refused; the normal push turns them
    // into a slide along the corner — x gains, z gives a touch — and the
    // circle stays exactly one radius off the corner.
    const b: BoxBounds = { minX: 0.6, maxX: 1.2, minZ: 1.9, maxZ: 2.5 };
    const start: [number, number] = [0.537, 1.9 - Math.sqrt(R * R - 0.063 * 0.063)];
    expect(Math.hypot(start[0] - b.minX, start[1] - b.minZ)).toBeCloseTo(R, 10);
    const [x, z] = resolveWalk(start, [start[0] + 0.037, start[1] + 0.093], R, [b]);
    expect(x).toBeGreaterThan(start[0] + 0.02);
    expect(z).toBeLessThanOrEqual(start[1] + 1e-9);
    expect(Math.hypot(x - b.minX, z - b.minZ)).toBeCloseTo(R, 10);
  });

  it('corner: a long step that clips a corner is deflected round it, never through it', () => {
    // Skimming past the box's -Z side with 0.2 of the radius inside the
    // corner, 5 m in one step. The corner turns the circle aside (z gives)
    // and it carries on; at no point is it inside the box.
    const [x, z] = resolveWalk([-2, -0.25], [3, -0.25], R, [box]);
    expect(z).toBeLessThan(-0.25);
    expect(x).toBeGreaterThan(-2);
    expect(circleOverlapsBox(x, z, R, box)).toBe(false);
  });

  it('corner: a step aimed straight at a corner point stops one radius from it', () => {
    const [x, z] = resolveWalk([-0.4, -0.4], [0, 0], R, [box]);
    expect(x).toBeLessThan(0);
    expect(z).toBeLessThan(0);
    expect(Math.hypot(x - box.minX, z - box.minZ)).toBeCloseTo(R, 10);
  });

  it('substeps a long diagonal step so it neither tunnels nor lands inside', () => {
    // 6 m in one go, through a cabinet-sized box on the diagonal.
    const [x, z] = resolveWalk([-2, -2], [4, 4], R, [box]);
    expect(circleOverlapsBox(x, z, R, box)).toBe(false);
    // Deflected off the near corner, not carried through the box.
    expect(x).toBeGreaterThan(-2);
    expect(z).toBeGreaterThan(-2);
  });

  it('touching is clear: standing exactly one radius off a face does not get pushed', () => {
    expect(resolveWalk([0, 1 - R], [0, 1 - R], R, [wall])).toEqual([0, 1 - R]);
  });

  it('keeps sliding on the frames AFTER first contact, rounding noise and all', () => {
    // The sweep parks the player at face - R; in floating point that is not
    // quite R off the face (1.9 - 0.45 → 1.4500000000000002), and a naive
    // cross-axis test sees a sliver of overlap and pins them to the wall.
    const b: BoxBounds = { minX: 0.6, maxX: 1.2, minZ: 1.9, maxZ: 2.5 };
    const parked = b.minZ - R;
    expect(R * R - (b.minZ - parked) ** 2).not.toBe(0); // the noise is real
    expect(circleOverlapsBox(0.62, parked, R, b)).toBe(false); // parked is touching, not inside
    const [x, z] = resolveWalk([0.62, parked], [0.66, parked + 0.1], R, [b]);
    expect(x).toBe(0.66); // the slide goes on…
    expect(z).toBeCloseTo(parked, 12); // …while the wall still holds
  });

  it('starting inside: can back out, cannot push deeper, is never displaced', () => {
    const inside: [number, number] = [0.5, 0.2]; // inside `box`, near its z = 0 face
    // Backing out toward the near face is allowed.
    expect(resolveWalk(inside, [0.5, 0.1], R, [box])).toEqual([0.5, 0.1]);
    // Pushing toward the centre is refused on that axis…
    expect(resolveWalk(inside, [0.5, 0.6], R, [box])).toEqual([0.5, 0.2]);
    // …while the other axis can still move away from the centre.
    expect(resolveWalk(inside, [0.3, 0.6], R, [box])).toEqual([0.3, 0.2]);
    // Standing still is standing still — no ejection out the far face.
    expect(resolveWalk(inside, inside, R, [box])).toEqual(inside);
  });

  it('a large step never tunnels through a thin wall', () => {
    // A hitched frame: 3 m in one step through a 20 cm wall.
    const thin: BoxBounds = { minX: -5, maxX: 5, minZ: 1, maxZ: 1.2 };
    const [, z] = resolveWalk([0, 0], [0, 3], R, [thin]);
    expect(z).toBeCloseTo(1 - R, 10);
  });

  it('two neighbours closer than the body is wide: the result does not depend on their order', () => {
    const a: BoxBounds = { minX: 1, maxX: 2, minZ: -1, maxZ: 1 };
    const b: BoxBounds = { minX: 2.3, maxX: 3, minZ: -1, maxZ: 1 };
    const ab = resolveWalk([0, 0], [2.7, 0], R, [a, b]);
    const ba = resolveWalk([0, 0], [2.7, 0], R, [b, a]);
    expect(ab).toEqual(ba);
    expect(ab[0]).toBeCloseTo(1 - R, 10);
  });

  it('passes a box it only skirts on the other axis', () => {
    // Walking +Z alongside the box, a full radius clear of its side.
    const [x, z] = resolveWalk([-0.5, -1], [-0.5, 2], R, [box]);
    expect(x).toBe(-0.5);
    expect(z).toBe(2);
  });
});

describe('circleOverlapsBox', () => {
  it('overlaps a face, clears when a radius away, and rounds the corners', () => {
    expect(circleOverlapsBox(0.5, -0.2, R, box)).toBe(true);
    expect(circleOverlapsBox(0.5, -R, R, box)).toBe(false);
    // Corner: 0.4 off in both axes is 0.566 away — clear; 0.3 is 0.42 — overlap.
    expect(circleOverlapsBox(-0.4, -0.4, R, box)).toBe(false);
    expect(circleOverlapsBox(-0.3, -0.3, R, box)).toBe(true);
    // Centre inside the box.
    expect(circleOverlapsBox(0.5, 0.5, R, box)).toBe(true);
    // Past the +X / +Z faces too (the other arm of each clamp).
    expect(circleOverlapsBox(1.2, 1.2, R, box)).toBe(true);
    expect(circleOverlapsBox(1.5, 0.5, R, box)).toBe(false);
  });
});

describe('pose persistence codec', () => {
  const memory = () => {
    const data = new Map<string, string>();
    return {
      getItem: (k: string) => data.get(k) ?? null,
      setItem: (k: string, v: string) => void data.set(k, v),
    };
  };

  it('round-trips a pose', () => {
    const store = memory();
    expect(writePose(store, 'room', { x: 1.5, z: -2, yaw: Math.PI })).toBe(true);
    expect(readPose(store, 'room')).toEqual({ x: 1.5, z: -2, yaw: Math.PI });
  });

  it('reads nothing when nothing was stored, or the store is missing', () => {
    expect(readPose(memory(), 'room')).toBeNull();
    expect(readPose(null, 'room')).toBeNull();
    expect(readPose(undefined, 'room')).toBeNull();
    expect(writePose(null, 'room', { x: 0, z: 0, yaw: 0 })).toBe(false);
  });

  it('rejects anything that is not three finite numbers', () => {
    const store = memory();
    store.setItem('room', 'not json');
    expect(readPose(store, 'room')).toBeNull();
    store.setItem('room', 'null');
    expect(readPose(store, 'room')).toBeNull();
    store.setItem('room', '"a string"');
    expect(readPose(store, 'room')).toBeNull();
    store.setItem('room', JSON.stringify({ x: 1, z: 'two', yaw: 0 }));
    expect(readPose(store, 'room')).toBeNull();
    store.setItem('room', JSON.stringify({ x: 1, z: 2 }));
    expect(readPose(store, 'room')).toBeNull();
  });

  it('a store that throws reads as empty and writes as refused', () => {
    const angry = {
      getItem: vi.fn(() => {
        throw new Error('SecurityError');
      }),
      setItem: vi.fn(() => {
        throw new Error('QuotaExceededError');
      }),
    };
    expect(readPose(angry, 'room')).toBeNull();
    expect(writePose(angry, 'room', { x: 0, z: 0, yaw: 0 })).toBe(false);
  });
});

FirstPersonCamera.test.ts

32 ✓

FirstPersonCamera

emits CREATED with the camera handle once the camera exists
applies defaults
round-trips collide / radius / persistKey, omitting an unset persistKey
round-trips through serialize (with and without bounds)
creates a perspective camera at the start pose (eye height)
walks forward (+Z at yaw 0) when W is held
strafes toward the hand you would actually raise: -X at yaw 0, +X at yaw π
turns the view right on D, which decreases yaw
clamps to bounds so the player cannot leave the room
bridges real DOM keyboard events to movement
creates the camera for an entity that exists before initialize (SceneLoader order)
removes its DOM listeners on shutdown

FirstPersonCamera › GOTO — walking itself to a spot

walks to the requested spot and settles on the requested facing
emits ARRIVED once it gets there
a movement key CANCELS the walk — the player always wins
stays inside its bounds while auto-walking

FirstPersonCamera › collision — Obstacles are solid

stops one radius short of a cabinet it walks straight into
slides along a face when it approaches at an angle
collide: false walks straight through
bounds still clamp on top of the sweep
an approach glides over obstacles and lands on the spot
moves and turns at the same time, easing out
a GOTO that can slide round a box still arrives

FirstPersonCamera › pose persistence (persistKey)

restores the remembered pose on attach instead of the start pose
ignores a malformed entry and starts at the start pose
writes the live pose about once a second while it changes, not every frame
writes on shutdown so the last steps are not lost
writes when the camera entity is removed (a scene swap)
without a persistKey nothing is ever stored
a storage that throws is shrugged off
a window whose localStorage getter throws is treated as no storage
a window with no localStorage at all is treated as no storage

Last run 2026-10-08

FirstPersonCamera.test.ts

// @vitest-environment jsdom
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { FirstPersonCameraComponent, FirstPersonCameraSystem } from './FirstPersonCamera';
import { EventBus, World } from '@babylonjsmarket/ecs';
import { FirstPersonCameraEvents } from './FirstPersonCamera.events';
import { MockRendererAdapter } from '@babylonjsmarket/ecs';
import { ObstacleComponent } from '../Obstacle/Obstacle.defs';

/** Last recorded call to a given adapter method, or undefined. */
function lastCall(renderer: MockRendererAdapter, method: string) {
  for (let i = renderer.calls.length - 1; i >= 0; i--) {
    if (renderer.calls[i].method === method) return renderer.calls[i];
  }
  return undefined;
}

describe('FirstPersonCamera', () => {
  let eventBus: EventBus;
  let world: World;
  let renderer: MockRendererAdapter;
  let system: FirstPersonCameraSystem;

  beforeEach(() => {
    eventBus = new EventBus();
    renderer = new MockRendererAdapter();
    world = new World({ eventBus, renderer });
    system = new FirstPersonCameraSystem(eventBus);
    world.addSystem(system);
    world.initialize();
  });

  it('emits CREATED with the camera handle once the camera exists', () => {
    const seen: { entityId: string; handle?: unknown }[] = [];
    eventBus.on(FirstPersonCameraEvents.CREATED, (e: { entityId: string; handle?: unknown }) => seen.push(e));
    const entity = world.createEntity();
    entity.add(new FirstPersonCameraComponent());
    expect(seen).toHaveLength(1);
    expect(seen[0].entityId).toBe(entity.id);
    expect(seen[0].handle).toBeDefined();
    // The handle is the one the adapter handed back for the perspective camera.
    world.update(1 / 60);
    expect(seen).toHaveLength(1);
  });

  it('applies defaults', () => {
    const c = new FirstPersonCameraComponent();
    expect(c.eyeHeight).toBe(1.7);
    expect(c.startX).toBe(0);
    expect(c.startZ).toBe(0);
    expect(c.moveSpeed).toBe(3);
    expect(c.turnSpeed).toBe(1.8);
    expect(c.bounds).toBeUndefined();
    // Collision is on by default, at a shoulder's half-width.
    expect(c.collide).toBe(true);
    expect(c.radius).toBe(0.45);
    expect(c.persistKey).toBeUndefined();
  });

  it('round-trips collide / radius / persistKey, omitting an unset persistKey', () => {
    const c = new FirstPersonCameraComponent({ collide: false, radius: 0.3, persistKey: 'room.pose' });
    const out = c.serialize();
    expect(out).toMatchObject({ collide: false, radius: 0.3, persistKey: 'room.pose' });
    expect(new FirstPersonCameraComponent(out).serialize()).toEqual(out);
    expect('persistKey' in new FirstPersonCameraComponent().serialize()).toBe(false);
  });

  it('round-trips through serialize (with and without bounds)', () => {
    const withBounds = new FirstPersonCameraComponent({
      eyeHeight: 2,
      position: [1, -2],
      yaw: 0.5,
      moveSpeed: 4,
      bounds: { minX: -5, maxX: 5, minZ: -6, maxZ: 6 },
    });
    const rt = new FirstPersonCameraComponent(withBounds.serialize());
    expect(rt.eyeHeight).toBe(2);
    expect(rt.startX).toBe(1);
    expect(rt.startZ).toBe(-2);
    expect(rt.yaw).toBe(0.5);
    expect(rt.bounds).toEqual({ minX: -5, maxX: 5, minZ: -6, maxZ: 6 });

    // No bounds → serialize omits the bounds key.
    const noBounds = new FirstPersonCameraComponent({ position: [3, 4] });
    expect(noBounds.serialize().bounds).toBeUndefined();
    expect(new FirstPersonCameraComponent(noBounds.serialize()).bounds).toBeUndefined();
  });

  it('creates a perspective camera at the start pose (eye height)', () => {
    const e = world.createEntity('Camera');
    e.add(new FirstPersonCameraComponent({ eyeHeight: 2, position: [3, 4] }));
    const call = lastCall(renderer, 'createPerspectiveCamera');
    expect(call).toBeDefined();
    const spec = call!.args[1] as { position: number[] };
    expect(spec.position).toEqual([3, 2, 4]); // [startX, eyeHeight, startZ]
  });

  it('walks forward (+Z at yaw 0) when W is held', () => {
    const e = world.createEntity('Camera');
    e.add(new FirstPersonCameraComponent({ moveSpeed: 10, eyeHeight: 1.7 }));

    eventBus.emit('keyboard.keydown', { code: 'KeyW' });
    world.update(0.1);

    const pos = lastCall(renderer, 'setCameraPose')!.args[1] as number[];
    expect(pos[2]).toBeCloseTo(1.0, 5); // 10 u/s * 0.1 s along +Z
    expect(pos[0]).toBeCloseTo(0, 5);
    expect(pos[1]).toBeCloseTo(1.7, 5); // pinned at eye height
  });

  // The canonical frame: yaw 0 looks +Z, +Y is up, and the renderer is
  // right-handed. Your right hand is forward x up, so at yaw 0 it points at -X
  // — which is also why the adapter contract puts +X on the screen's LEFT for
  // an identity camera. Turn to face -Z (yaw π, the arcade room's spawn) and
  // your right becomes +X, on the screen's right, as it should be.
  it('strafes toward the hand you would actually raise: -X at yaw 0, +X at yaw π', () => {
    const e = world.createEntity('Camera');
    e.add(new FirstPersonCameraComponent({ moveSpeed: 10 }));

    eventBus.emit('keyboard.keydown', { code: 'KeyE' });
    world.update(0.1);

    const pos = lastCall(renderer, 'setCameraPose')!.args[1] as number[];
    expect(pos[0]).toBeCloseTo(-1.0, 5); // right = -X while facing +Z
    expect(pos[2]).toBeCloseTo(0, 5);

    // Release E, hold Q → strafe back toward the origin.
    eventBus.emit('keyboard.keyup', { code: 'KeyE' });
    eventBus.emit('keyboard.keydown', { code: 'KeyQ' });
    world.update(0.1);
    const pos2 = lastCall(renderer, 'setCameraPose')!.args[1] as number[];
    expect(pos2[0]).toBeCloseTo(0, 5);

    // Same key, turned around: facing -Z, strafing right now carries you +X.
    eventBus.emit('keyboard.keyup', { code: 'KeyQ' });
    const spun = world.createEntity('CameraSpun');
    spun.add(new FirstPersonCameraComponent({ moveSpeed: 10, yaw: Math.PI }));
    eventBus.emit('keyboard.keydown', { code: 'KeyE' });
    world.update(0.1);
    const pos3 = lastCall(renderer, 'setCameraPose')!.args[1] as number[];
    expect(pos3[0]).toBeCloseTo(1.0, 5);
    eventBus.emit('keyboard.keyup', { code: 'KeyE' });
  });

  // D must turn the VIEW to the right, which means yaw goes DOWN: forward is
  // (sin yaw, 0, cos yaw), so raising yaw swings the view toward -X and the
  // right-handed renderer draws that on the left. Getting this backwards is
  // exactly what shipped on 2026-09-02 and felt like inverted steering.
  it('turns the view right on D, which decreases yaw', () => {
    const e = world.createEntity('Camera');
    e.add(new FirstPersonCameraComponent({ turnSpeed: 1 }));

    eventBus.emit('keyboard.keydown', { code: 'KeyD' });
    world.update(0.5); // yaw -= 0.5 rad
    const q = lastCall(renderer, 'setCameraPose')!.args[2] as { y: number; w: number };
    expect(q.y).toBeCloseTo(Math.sin(-0.25), 5);
    expect(q.w).toBeCloseTo(Math.cos(-0.25), 5);

    // A turns the other way (arrow keys too).
    eventBus.emit('keyboard.keyup', { code: 'KeyD' });
    eventBus.emit('keyboard.keydown', { code: 'ArrowLeft' });
    world.update(0.5); // yaw back to 0
    const q2 = lastCall(renderer, 'setCameraPose')!.args[2] as { y: number };
    expect(q2.y).toBeCloseTo(0, 5);
  });

  it('clamps to bounds so the player cannot leave the room', () => {
    const e = world.createEntity('Camera');
    e.add(
      new FirstPersonCameraComponent({
        moveSpeed: 100,
        position: [0, 0],
        bounds: { minX: -5, maxX: 5, minZ: -5, maxZ: 5 },
      }),
    );
    eventBus.emit('keyboard.keydown', { code: 'KeyW' });
    world.update(1); // would travel 100 u forward without clamping
    const pos = lastCall(renderer, 'setCameraPose')!.args[1] as number[];
    expect(pos[2]).toBeCloseTo(5, 5);
  });

  it('bridges real DOM keyboard events to movement', () => {
    const e = world.createEntity('Camera');
    e.add(new FirstPersonCameraComponent({ moveSpeed: 10 }));

    window.dispatchEvent(new KeyboardEvent('keydown', { code: 'KeyW' }));
    world.update(0.1);
    const moved = lastCall(renderer, 'setCameraPose')!.args[1] as number[];
    expect(moved[2]).toBeGreaterThan(0);

    window.dispatchEvent(new KeyboardEvent('keyup', { code: 'KeyW' }));
    const z = (lastCall(renderer, 'setCameraPose')!.args[1] as number[])[2];
    world.update(0.1); // key released → no further travel
    const z2 = (lastCall(renderer, 'setCameraPose')!.args[1] as number[])[2];
    expect(z2).toBeCloseTo(z, 5);
  });

  it('creates the camera for an entity that exists before initialize (SceneLoader order)', () => {
    // Live path: entities are created first, then systems are added + the world
    // initialized — so onInitialize must sweep the already-present entities.
    const eb = new EventBus();
    const r = new MockRendererAdapter();
    const w = new World({ eventBus: eb, renderer: r });
    const e = w.createEntity('Camera');
    e.add(new FirstPersonCameraComponent({ position: [2, 3], eyeHeight: 1.8 }));
    w.addSystem(new FirstPersonCameraSystem(eb));
    w.initialize();
    const call = lastCall(r, 'createPerspectiveCamera');
    expect(call).toBeDefined();
    expect((call!.args[1] as { position: number[] }).position).toEqual([2, 1.8, 3]);
  });

  describe('GOTO — walking itself to a spot', () => {
    /** Run `frames` updates and read the final camera position. */
    const settle = (frames: number) => {
      for (let i = 0; i < frames; i++) world.update(1 / 60);
      const call = lastCall(renderer, 'setCameraPose');
      return (call!.args[1] as number[]);
    };

    it('walks to the requested spot and settles on the requested facing', () => {
      const e = world.createEntity('Camera');
      e.add(new FirstPersonCameraComponent({ position: [0, 0], moveSpeed: 6, turnSpeed: 8 }));
      world.update(1 / 60);
      eventBus.emit(FirstPersonCameraEvents.GOTO, { x: 0, z: 4, yaw: Math.PI });
      const pos = settle(180);
      expect(pos[0]).toBeCloseTo(0, 1);
      expect(pos[2]).toBeCloseTo(4, 1);
    });

    it('emits ARRIVED once it gets there', () => {
      const arrived: unknown[] = [];
      eventBus.on(FirstPersonCameraEvents.ARRIVED, (p) => arrived.push(p));
      const e = world.createEntity('Camera');
      e.add(new FirstPersonCameraComponent({ position: [0, 0], moveSpeed: 6, turnSpeed: 8 }));
      world.update(1 / 60);
      eventBus.emit(FirstPersonCameraEvents.GOTO, { x: 0, z: 2 });
      settle(180);
      expect(arrived).toHaveLength(1);
      expect((arrived[0] as { cancelled: boolean }).cancelled).toBe(false);
    });

    it('a movement key CANCELS the walk — the player always wins', () => {
      const arrived: unknown[] = [];
      eventBus.on(FirstPersonCameraEvents.ARRIVED, (p) => arrived.push(p));
      const e = world.createEntity('Camera');
      e.add(new FirstPersonCameraComponent({ position: [0, 0], moveSpeed: 2, turnSpeed: 8 }));
      world.update(1 / 60);
      eventBus.emit(FirstPersonCameraEvents.GOTO, { x: 0, z: 20 });
      settle(5);
      window.dispatchEvent(new KeyboardEvent('keydown', { code: 'KeyS' }));
      const posAtCancel = settle(1);
      window.dispatchEvent(new KeyboardEvent('keyup', { code: 'KeyS' }));
      const after = settle(60);

      expect(arrived).toHaveLength(1);
      expect((arrived[0] as { cancelled: boolean }).cancelled).toBe(true);
      // It is no longer driving itself toward z = 20 — S walked it back instead.
      expect(after[2]).toBeLessThan(posAtCancel[2] + 0.5);
    });

    it('stays inside its bounds while auto-walking', () => {
      const e = world.createEntity('Camera');
      e.add(
        new FirstPersonCameraComponent({
          position: [0, 0],
          moveSpeed: 8,
          turnSpeed: 8,
          bounds: { minX: -1, maxX: 1, minZ: -1, maxZ: 1 },
        }),
      );
      world.update(1 / 60);
      eventBus.emit(FirstPersonCameraEvents.GOTO, { x: 50, z: 50 });
      const pos = settle(120);
      expect(pos[0]).toBeLessThanOrEqual(1.0001);
      expect(pos[2]).toBeLessThanOrEqual(1.0001);
    });
  });

  describe('collision — Obstacles are solid', () => {
    /** A solid box footprint at `center` with the given half-extents. */
    const obstacle = (center: [number, number], halfWidth: number, halfDepth: number) => {
      const e = world.createEntity();
      e.add(new ObstacleComponent({ center, halfWidth, halfDepth }));
      return e;
    };
    const pose = () => lastCall(renderer, 'setCameraPose')!.args[1] as number[];

    it('stops one radius short of a cabinet it walks straight into', () => {
      // Cabinet centred 3 m ahead, 1 m deep: its near face is at z = 2.5.
      obstacle([0, 3], 0.5, 0.5);
      const e = world.createEntity('Camera');
      e.add(new FirstPersonCameraComponent({ moveSpeed: 10, radius: 0.45 }));
      eventBus.emit('keyboard.keydown', { code: 'KeyW' });
      world.update(1); // would reach z = 10 unopposed
      expect(pose()[2]).toBeCloseTo(2.5 - 0.45, 5);
      // Holding the key keeps pressing, never tunnels.
      world.update(1);
      expect(pose()[2]).toBeCloseTo(2.05, 5);
    });

    it('slides along a face when it approaches at an angle', () => {
      // A long wall ahead; strafing right while walking forward carries on
      // along the wall once the forward part is stopped.
      obstacle([0, 3], 10, 0.5);
      const e = world.createEntity('Camera');
      e.add(new FirstPersonCameraComponent({ moveSpeed: 4 }));
      eventBus.emit('keyboard.keydown', { code: 'KeyW' });
      eventBus.emit('keyboard.keydown', { code: 'KeyE' });
      world.update(1);
      const p = pose();
      expect(p[2]).toBeCloseTo(2.5 - 0.45, 5); // stopped at the wall
      expect(p[0]).toBeCloseTo(-4, 5); // the strafe went through in full (-X: facing +Z)
    });

    it('collide: false walks straight through', () => {
      obstacle([0, 3], 0.5, 0.5);
      const e = world.createEntity('Camera');
      e.add(new FirstPersonCameraComponent({ moveSpeed: 10, collide: false }));
      eventBus.emit('keyboard.keydown', { code: 'KeyW' });
      world.update(1);
      expect(pose()[2]).toBeCloseTo(10, 5);
    });

    it('bounds still clamp on top of the sweep', () => {
      obstacle([0, 30], 0.5, 0.5); // far beyond the room; the wall belt should win
      const e = world.createEntity('Camera');
      e.add(new FirstPersonCameraComponent({ moveSpeed: 100, bounds: { minX: -5, maxX: 5, minZ: -5, maxZ: 5 } }));
      eventBus.emit('keyboard.keydown', { code: 'KeyW' });
      world.update(1);
      expect(pose()[2]).toBeCloseTo(5, 5);
    });

    it('an approach glides over obstacles and lands on the spot', () => {
      // Deliberate: the approach is on rails. A glide that snagged on a cabinet
      // corner would stop in open floor with no way to explain itself, and the
      // destination is always a clear spot in front of a machine. Walking under
      // your own keys still collides — that is the test above.
      const arrived: { cancelled: boolean; x: number; z: number }[] = [];
      eventBus.on(FirstPersonCameraEvents.ARRIVED, (p: { cancelled: boolean; x: number; z: number }) =>
        arrived.push(p),
      );
      obstacle([0, 2], 2, 0.5); // a bar straight across the way
      const e = world.createEntity('Camera');
      e.add(new FirstPersonCameraComponent({ position: [0, 0], approachDuration: 0.5 }));
      world.update(1 / 60);
      eventBus.emit(FirstPersonCameraEvents.GOTO, { x: 0, z: 5, yaw: Math.PI });
      for (let i = 0; i < 60; i++) world.update(1 / 60);
      expect(arrived).toHaveLength(1);
      expect(arrived[0].cancelled).toBe(false);
      expect(pose()[2]).toBeCloseTo(5, 5);
      // Settled: more frames, no more events, no drift.
      for (let i = 0; i < 30; i++) world.update(1 / 60);
      expect(arrived).toHaveLength(1);
      expect(pose()[2]).toBeCloseTo(5, 5);
    });

    it('moves and turns at the same time, easing out', () => {
      // The whole point of the change. Turning to face the target, then
      // walking, then turning again to face the machine reads as three robotic
      // moves and takes as long as the room is wide; the hand-written room
      // eased position and facing together over a fixed 0.7 s, and that is what
      // made clicking a cabinet feel like walking up to one.
      const e = world.createEntity('Camera');
      e.add(new FirstPersonCameraComponent({ position: [0, 0], yaw: 0, approachDuration: 1 }));
      world.update(1 / 60);
      // Target dead behind and to the side, so a turn-then-walk would show up
      // as a long spell of turning with no movement at all.
      eventBus.emit(FirstPersonCameraEvents.GOTO, { x: 4, z: -4, yaw: Math.PI });

      for (let i = 0; i < 30; i++) world.update(1 / 60); // half way through
      const half = pose();
      const q = lastCall(renderer, 'setCameraPose')!.args[2] as { y: number };
      // Ease-out 1-(1-u)^2 at u = 0.5 is 0.75 of the way there, on both axes...
      expect(half[0]).toBeCloseTo(3, 1);
      expect(half[2]).toBeCloseTo(-3, 1);
      // ...and the facing has come along with it, not waited its turn.
      expect(Math.abs(q.y)).toBeGreaterThan(0.5);

      for (let i = 0; i < 35; i++) world.update(1 / 60);
      const end = pose();
      expect(end[0]).toBeCloseTo(4, 5);
      expect(end[2]).toBeCloseTo(-4, 5);
    });

    it('a GOTO that can slide round a box still arrives', () => {
      // The target is off to the right of a box that sits on the diagonal:
      // the forward part of each step is stopped at the box's front, the
      // sideways part carries the player along it and past — the slide —
      // and the walk goes on to the target rather than giving up.
      obstacle([0.9, 2.2], 0.3, 0.3);
      const e = world.createEntity('Camera');
      e.add(new FirstPersonCameraComponent({ position: [0, 0], moveSpeed: 6, turnSpeed: 8 }));
      world.update(1 / 60);
      const arrived: { cancelled: boolean }[] = [];
      eventBus.on(FirstPersonCameraEvents.ARRIVED, (p: { cancelled: boolean }) => arrived.push(p));
      eventBus.emit(FirstPersonCameraEvents.GOTO, { x: 2, z: 5 });
      for (let i = 0; i < 300; i++) world.update(1 / 60);
      expect(arrived).toHaveLength(1);
      expect(arrived[0].cancelled).toBe(false);
      expect(pose()[0]).toBeCloseTo(2, 1);
      expect(pose()[2]).toBeCloseTo(5, 1);
    });
  });

  describe('pose persistence (persistKey)', () => {
    const KEY = 'test.room.pose';
    // Node 25 puts its own `localStorage` on the global — a stub with no
    // getItem/setItem unless `--localstorage-file` is set — and it shadows
    // jsdom's. Install a real in-memory Storage for these tests and put the
    // original back after, so what the System sees is what a browser gives it.
    let store: Storage;
    let original: PropertyDescriptor | undefined;
    beforeEach(() => {
      const data = new Map<string, string>();
      store = {
        get length() {
          return data.size;
        },
        clear: () => data.clear(),
        getItem: (k: string) => data.get(k) ?? null,
        key: (i: number) => [...data.keys()][i] ?? null,
        removeItem: (k: string) => void data.delete(k),
        setItem: (k: string, v: string) => void data.set(k, String(v)),
      };
      original = Object.getOwnPropertyDescriptor(window, 'localStorage');
      Object.defineProperty(window, 'localStorage', { value: store, configurable: true, writable: true });
    });
    afterEach(() => {
      if (original) Object.defineProperty(window, 'localStorage', original);
    });

    it('restores the remembered pose on attach instead of the start pose', () => {
      window.localStorage.setItem(KEY, JSON.stringify({ x: 3, z: -2, yaw: 1.25 }));
      const e = world.createEntity('Camera');
      e.add(new FirstPersonCameraComponent({ position: [0, 0], yaw: 0, eyeHeight: 1.6, persistKey: KEY }));
      const spec = lastCall(renderer, 'createPerspectiveCamera')!.args[1] as { position: number[]; orientation: { y: number } };
      expect(spec.position).toEqual([3, 1.6, -2]);
      expect(spec.orientation.y).toBeCloseTo(Math.sin(1.25 / 2), 5);
    });

    it('ignores a malformed entry and starts at the start pose', () => {
      window.localStorage.setItem(KEY, '{"x": "nope"}');
      const e = world.createEntity('Camera');
      e.add(new FirstPersonCameraComponent({ position: [1, 2], persistKey: KEY }));
      const spec = lastCall(renderer, 'createPerspectiveCamera')!.args[1] as { position: number[] };
      expect(spec.position).toEqual([1, 1.7, 2]);
    });

    it('writes the live pose about once a second while it changes, not every frame', () => {
      const e = world.createEntity('Camera');
      e.add(new FirstPersonCameraComponent({ position: [0, 0], moveSpeed: 1, persistKey: KEY }));
      eventBus.emit('keyboard.keydown', { code: 'KeyW' });
      const setItem = vi.spyOn(store, 'setItem');
      world.update(0.5);
      expect(setItem).not.toHaveBeenCalled(); // half a second in: not yet
      world.update(0.6);
      expect(setItem).toHaveBeenCalledTimes(1); // past the interval: written
      const saved = JSON.parse(window.localStorage.getItem(KEY)!);
      expect(saved.z).toBeCloseTo(1.1, 5);
      // Idle now: the next interval has nothing new to say.
      eventBus.emit('keyboard.keyup', { code: 'KeyW' });
      world.update(1.5);
      expect(setItem).toHaveBeenCalledTimes(1);
      setItem.mockRestore();
    });

    it('writes on shutdown so the last steps are not lost', () => {
      const e = world.createEntity('Camera');
      e.add(new FirstPersonCameraComponent({ position: [0, 0], moveSpeed: 2, persistKey: KEY }));
      eventBus.emit('keyboard.keydown', { code: 'KeyW' });
      world.update(0.25); // 0.5 m, well inside the throttle window
      expect(window.localStorage.getItem(KEY)).toBeNull();
      world.removeSystem(system);
      expect(JSON.parse(window.localStorage.getItem(KEY)!).z).toBeCloseTo(0.5, 5);
    });

    it('writes when the camera entity is removed (a scene swap)', () => {
      const e = world.createEntity('Camera');
      e.add(new FirstPersonCameraComponent({ position: [4, 4], persistKey: KEY }));
      world.update(1 / 60);
      world.removeEntity(e.id);
      expect(JSON.parse(window.localStorage.getItem(KEY)!)).toMatchObject({ x: 4, z: 4 });
    });

    it('without a persistKey nothing is ever stored', () => {
      const e = world.createEntity('Camera');
      e.add(new FirstPersonCameraComponent({ position: [0, 0], moveSpeed: 1 }));
      const setItem = vi.spyOn(store, 'setItem');
      eventBus.emit('keyboard.keydown', { code: 'KeyW' });
      world.update(2);
      world.removeSystem(system);
      expect(setItem).not.toHaveBeenCalled();
      setItem.mockRestore();
    });

    it('a storage that throws is shrugged off', () => {
      const getItem = vi.spyOn(store, 'getItem').mockImplementation(() => {
        throw new Error('SecurityError');
      });
      const setItem = vi.spyOn(store, 'setItem').mockImplementation(() => {
        throw new Error('QuotaExceededError');
      });
      const e = world.createEntity('Camera');
      expect(() => e.add(new FirstPersonCameraComponent({ position: [0, 0], moveSpeed: 1, persistKey: KEY }))).not.toThrow();
      eventBus.emit('keyboard.keydown', { code: 'KeyW' });
      expect(() => world.update(2)).not.toThrow();
      expect(() => world.removeSystem(system)).not.toThrow();
      getItem.mockRestore();
      setItem.mockRestore();
    });

    it('a window whose localStorage getter throws is treated as no storage', () => {
      Object.defineProperty(window, 'localStorage', {
        configurable: true,
        get() {
          throw new Error('SecurityError');
        },
      });
      const e = world.createEntity('Camera');
      expect(() => e.add(new FirstPersonCameraComponent({ persistKey: KEY }))).not.toThrow();
      expect(() => world.removeSystem(system)).not.toThrow();
    });

    it('a window with no localStorage at all is treated as no storage', () => {
      Object.defineProperty(window, 'localStorage', { value: undefined, configurable: true, writable: true });
      const e = world.createEntity('Camera');
      expect(() => e.add(new FirstPersonCameraComponent({ persistKey: KEY }))).not.toThrow();
      expect(() => world.removeSystem(system)).not.toThrow();
    });
  });

  it('removes its DOM listeners on shutdown', () => {
    const e = world.createEntity('Camera');
    e.add(new FirstPersonCameraComponent({ moveSpeed: 10 }));
    world.removeSystem(system); // → onShutdown removes the window listeners

    const before = renderer.calls.length;
    window.dispatchEvent(new KeyboardEvent('keydown', { code: 'KeyW' }));
    // No system is listening anymore, so nothing new is driven.
    expect(renderer.calls.length).toBe(before);
  });
});