CabinetLink.defs.ts

CabinetLink — definitions.

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

CabinetLink.defs.ts

import { Component } from '@babylonjsmarket/ecs';
import type { Vec3 } from '@babylonjsmarket/ecs/renderer-types';
export { CabinetLinkEvents } from './CabinetLink.events';

export interface CabinetLinkInput {
  /**
   * Key of the game this cabinet fronts, e.g. `'frogger'`. Matches a folder
   * under `src/games/` and the key in that project's GAMES registry.
   */
  game?: string;
  /** Where double-click navigates. Defaults to `/games/<game>/`. */
  route?: string;
  /** Human label, for HUD/overlay use. Defaults to `game`. */
  title?: string;
  /**
   * Where the player is walked to on single click. Omit and the System stands
   * them `standoff` metres out from the cabinet along its facing, which is what
   * you want for a cabinet against a wall.
   */
  standPoint?: [number, number];
  /** Distance in front of the cabinet to stand. Metres. */
  standoff?: number;
  /**
   * The cabinet's facing yaw (radians), used to work out "in front". Should
   * match the Mesh's rotation Y. 0 = facing +Z.
   */
  facing?: number;
  /**
   * Whether a double-click LAUNCHES this machine. False makes it scenery you
   * can still walk up to and look at — clicking always walks you over, on every
   * machine, which is most of what you do in an arcade.
   */
  interactive?: boolean;
  /**
   * How close the PLAYER must already be (XZ metres from the cabinet) for the
   * confirming double-click to launch. Further away, the click reports
   * `cabinetlink.launch.outofrange` and the walk the first click started just
   * carries on — the player arrives, and double-clicks again. Omit for no
   * gate: a double-click launches from anywhere, as it always did.
   */
  launchDistance?: number;
}

export class CabinetLinkComponent 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 = 'CabinetLink';

  game: string;
  route: string;
  title: string;
  standPoint?: [number, number];
  standoff: number;
  facing: number;
  interactive: boolean;
  launchDistance: number;

  constructor(data: CabinetLinkInput = {}) {
    super();
    this.game = data.game ?? '';
    this.route = data.route ?? (this.game ? `/games/${this.game}/` : '');
    this.title = data.title ?? this.game;
    this.standPoint = data.standPoint ? [data.standPoint[0], data.standPoint[1]] : undefined;
    // ~1.2 m: close enough to read the screen, far enough not to clip into it.
    this.standoff = data.standoff ?? 1.2;
    this.facing = data.facing ?? 0;
    this.interactive = data.interactive ?? true;
    this.launchDistance = data.launchDistance ?? Infinity;
  }

  /**
   * Floor spot the player should stand on, and the yaw that turns them to LOOK
   * at the cabinet, given the cabinet's own position.
   *
   * The player ends up `standoff` metres along the cabinet's facing direction
   * and turned 180° from it — facing back at the machine.
   */
  approachFrom(cabinet: Vec3): { x: number; z: number; yaw: number } {
    const yaw = this.facing + Math.PI; // look back at the cabinet
    if (this.standPoint) {
      return { x: this.standPoint[0], z: this.standPoint[1], yaw };
    }
    return {
      x: cabinet[0] + Math.sin(this.facing) * this.standoff,
      z: cabinet[2] + Math.cos(this.facing) * this.standoff,
      yaw,
    };
  }

  serialize(): CabinetLinkInput {
    return {
      game: this.game,
      route: this.route,
      title: this.title,
      standPoint: this.standPoint ? [this.standPoint[0], this.standPoint[1]] : undefined,
      standoff: this.standoff,
      facing: this.facing,
      interactive: this.interactive,
      // Infinity is the "no gate" default and does not survive JSON, so the
      // key is simply left out — the constructor puts it back.
      ...(Number.isFinite(this.launchDistance) ? { launchDistance: this.launchDistance } : {}),
    };
  }
}

CabinetLink.events.ts

CabinetLink — event names.

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

CabinetLink.events.ts

// CabinetLinkEvents — from CabinetLink
export const CabinetLinkEvents = {
  /** A cabinet was single-clicked; the player is walking over. */
  FOCUSED: 'cabinetlink.focused',
  /**
   * A cabinet was double-clicked: start its game. Payload carries the `game`
   * key and its `route`. The host app decides what that means (the create-arcade
   * scaffold pushes the route and swaps scenes), so this component never
   * touches the router.
   */
  LAUNCH: 'cabinetlink.launch',
  /**
   * The confirming click landed but the player is still further from the
   * machine than its `launchDistance`. Nothing launches; the walk the first
   * click started keeps going, so the player simply arrives closer and tries
   * again. Payload `{ entityId, game, title, distance, launchDistance }`.
   */
  OUT_OF_RANGE: 'cabinetlink.launch.outofrange',
} as const;

CabinetLink.ts

CabinetLink.ts — renderer-agnostic System turning pointer clicks on a cabinet into "walk me over" and "start the game".

Pure data lives in CabinetLink.defs.ts. This System owns the pointer listeners and the ray pick, and talks to everything else over the EventBus: it emits FirstPersonCameraEvents.GOTO to move the player and CabinetLinkEvents.LAUNCH for the host app to route on. It never imports a camera or a router — the one thing it needs from the camera, where the player is standing when they confirm, it reads back through the renderer from the handle the walking camera announced on its CREATED event.

CabinetLink.ts

import { CabinetLinkEvents } from './CabinetLink.events';
import { FirstPersonCameraEvents } from '../FirstPersonCamera/FirstPersonCamera.events';
import { System } from '@babylonjsmarket/ecs';
import type { Entity, EventBus } from '@babylonjsmarket/ecs';
import type { CameraHandle, Quaternion, Vec3 } from '@babylonjsmarket/ecs/renderer-types';
import { MeshComponent } from '../Mesh/Mesh.defs';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';
import { CabinetLinkComponent, type CabinetLinkInput } from './CabinetLink.defs';

export { CabinetLinkComponent, type CabinetLinkInput };

Milliseconds within which a second click on the SAME cabinet counts as a double-click. Deliberately ours rather than the DOM's dblclick: we need the first click to act immediately (start walking) while still recognising the second, and dblclick fires only after the browser's own delay.

CabinetLink.ts

const DOUBLE_CLICK_MS = 400;

/** A world-space point, as the pick reports it. */
interface HitPoint {
  x: number;
  y: number;
  z: number;
}

export class CabinetLinkSystem extends System {
  protected query = { required: [CabinetLinkComponent] };

  private pointerHandler: ((e: PointerEvent) => void) | null = null;
  private canvas: HTMLCanvasElement | null = null;
  /** The armed first click: which cabinet, when, and where on it the pick landed. */
  private lastClick: { entityId: string; at: number; hit: HitPoint } | null = null;
  /** The walking camera, once it has announced itself; where the player IS. */
  private cameraHandle: CameraHandle | null = null;
  private readonly _camPos: Vec3 = [0, 0, 0];
  private readonly _camQuat: Quaternion = { x: 0, y: 0, z: 0, w: 1 };
  /** The clock the double-click window is measured on; a test swaps it for a fake. */
  now: () => number = () => Date.now();

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

  protected onInitialize(): void {
    this.listen(FirstPersonCameraEvents.CREATED, (e: { entityId: string; handle?: CameraHandle }) => {
      if (e?.handle) this.cameraHandle = e.handle;
    });

    if (typeof window === 'undefined') return; // headless tests drive handleClick directly
    const canvas = this.world?.renderer?.getRenderingCanvas?.() ?? null;
    if (!canvas) return;
    this.canvas = canvas;
    this.pointerHandler = (e: PointerEvent) => {
      // Only the primary button, and only real clicks on the canvas.
      if (e.button !== 0) return;
      const rect = canvas.getBoundingClientRect();
      this.handleClick(e.clientX - rect.left, e.clientY - rect.top);
    };
    canvas.addEventListener('pointerdown', this.pointerHandler);
  }

  /** Nothing to do per frame — this System is purely event/pointer driven. */
  protected onUpdate(): void {}

  protected onShutdown(): void {
    if (this.canvas && this.pointerHandler) {
      this.canvas.removeEventListener('pointerdown', this.pointerHandler);
    }
    this.canvas = null;
    this.pointerHandler = null;
    this.lastClick = null;
    this.cameraHandle = null;
  }

  /**
   * Resolve a canvas-space click to a cabinet and act on it. Public so a host
   * app (or a test) can feed synthetic coordinates without a DOM.
   */
  handleClick(x: number, y: number): void {
    const r = this.world?.renderer;
    if (!r) return;
    const hit = r.pickAtScreenPoint(x, y);
    const entity = hit ? this.entityForMesh(hit.meshId) : undefined;

    const now = this.now();
    const pending =
      this.lastClick && now - this.lastClick.at <= DOUBLE_CLICK_MS ? this.lastClick : null;

    if (pending) {
      // A second click inside the window. It CONFIRMS the pending cabinet
      // unless it clearly landed on a different one.
      //
      // The leniency is not sloppiness — it's required. The first click starts
      // the player walking, so by the time the second lands the camera has
      // already moved and the same screen pixel is usually pointing at a wall.
      // Demanding a second hit on the same mesh would make double-click almost
      // impossible to perform.
      if (entity && entity.id !== pending.entityId) {
        this.approach(entity, hit!, now);
        return;
      }
      const target = this.entityById(pending.entityId);
      const comp = target?.get(CabinetLinkComponent);
      this.lastClick = null; // a third click starts a fresh pair
      if (!target || !comp?.interactive) return;

      // The proximity gate: measured from where the PLAYER stands, not from
      // where the click landed — a click on a far marquee is still a click
      // from across the room. The walk keeps going either way; too far just
      // means "not yet".
      const distance = this.distanceFromCamera(this.cabinetPosition(target, pending.hit));
      if (distance !== null && distance > comp.launchDistance) {
        this.eventBus.emit(CabinetLinkEvents.OUT_OF_RANGE, {
          entityId: target.id,
          game: comp.game,
          title: comp.title,
          distance,
          launchDistance: comp.launchDistance,
        });
        return;
      }
      this.eventBus.emit(CabinetLinkEvents.LAUNCH, {
        entityId: target.id,
        game: comp.game,
        route: comp.route,
        title: comp.title,
      });
      return;
    }

    // A first click on ANY machine walks you to it. Clicking the floor does
    // nothing and arms nothing.
    if (!entity) return;
    this.approach(entity, hit!, now);
  }

  /**
   * Walk the player to `entity` and arm it as the double-click candidate.
   *
   * Deliberately NOT gated on `interactive`. Walking up to a machine to look at
   * its art is the thing you do in an arcade, and most of the machines in a
   * room are scenery — gating the walk made nineteen of twenty-one cabinets
   * ignore the click entirely, which reads as a broken page rather than as a
   * cabinet with no game behind it. `interactive` gates the LAUNCH.
   */
  private approach(entity: Entity, hit: HitPoint, now: number): void {
    const comp = entity.get(CabinetLinkComponent);
    if (!comp) return;
    this.lastClick = { entityId: entity.id, at: now, hit: { x: hit.x, y: hit.y, z: hit.z } };
    const spot = comp.approachFrom(this.cabinetPosition(entity, hit));
    this.eventBus.emit(FirstPersonCameraEvents.GOTO, spot);
    this.eventBus.emit(CabinetLinkEvents.FOCUSED, {
      entityId: entity.id,
      game: comp.game,
      title: comp.title,
      ...spot,
    });
  }

  private entityById(id: string): Entity | undefined {
    for (const entity of this.entities) if (entity.id === id) return entity;
    return undefined;
  }

  /**
   * Map a picked mesh back to its cabinet entity.
   *
   * An instanced model's parts are named `<entityId>_<partName>` by the
   * adapter's clone naming, so a hit on the side art or the marquee still
   * resolves to the machine it belongs to — matching only the root would make
   * most of the cabinet unclickable.
   */
  private entityForMesh(meshId: string): Entity | undefined {
    if (!meshId) return undefined;
    for (const entity of this.entities) {
      if (meshId === entity.id || meshId.startsWith(`${entity.id}_`)) return entity;
    }
    return undefined;
  }

  /**
   * The cabinet's own floor position.
   *
   * Read from the sibling Mesh (or MeshPrimitive) rather than from the pick:
   * the pick lands wherever on the machine the pointer happened to hit — the
   * top of the marquee, the side art — and standing "in front of" THAT would
   * put the player at a different spot depending on where they clicked.
   */
  private cabinetPosition(entity: Entity, hit: HitPoint): Vec3 {
    const mesh = entity.get(MeshComponent);
    if (mesh) return [...mesh.params.position] as Vec3;
    const prim = entity.get(MeshPrimitiveComponent);
    if (prim) return [...prim.position] as Vec3;
    return [hit.x, hit.y, hit.z];
  }

  /**
   * XZ distance from the player's eyes to `point`, or `null` when there is no
   * walking camera to measure from (a scene with no FirstPersonCamera, or one
   * that hasn't announced itself yet) — in which case the gate stays open.
   */
  private distanceFromCamera(point: Vec3): number | null {
    const r = this.world?.renderer;
    if (!r || !this.cameraHandle) return null;
    r.getCameraPose(this.cameraHandle, this._camPos, this._camQuat);
    return Math.hypot(point[0] - this._camPos[0], point[2] - this._camPos[2]);
  }
}
export { CabinetLinkEvents } from './CabinetLink.events';

CabinetLink.contract.test.ts

12 ✓

ArcadeECS contract: CabinetLink

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
Registers a listener for each declared input event

Last run 2026-10-08

CabinetLink.contract.test.ts

import { CabinetLinkEvents } from './CabinetLink.events';
import { FirstPersonCameraEvents } from '../FirstPersonCamera/FirstPersonCamera.events';
import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import { CabinetLinkComponent, CabinetLinkSystem } from './CabinetLink';

runMechanicContract({
  name: 'CabinetLink',
  componentClass: CabinetLinkComponent,
  systemClass: CabinetLinkSystem,
  sampleInput: { game: 'frogger', facing: Math.PI / 2, standoff: 1.3, launchDistance: 1.5 },
  events: {
    input: [FirstPersonCameraEvents.CREATED],
    // FOCUSED / LAUNCH / OUT_OF_RANGE / GOTO need a pointer pick, which the
    // bare battery has no hand for; CabinetLink.test.ts drives every one.
  },
  makeInputPayload() {
    return { entityId: 'Player', handle: undefined };
  },
});

CabinetLink.test.ts

37 ✓

CabinetLinkComponent

derives its route from the game key
lets an explicit route win over the derived one
has no route when it fronts no game
serialize round-trips
launchDistance defaults to no gate (Infinity) and stays out of the serialized form
a finite launchDistance round-trips

CabinetLinkComponent › approachFrom

stands the player in front of a cabinet facing +Z, looking back at it
follows the cabinet’s facing when it is turned
an explicit standPoint overrides the computed one but still faces the cabinet

CabinetLinkSystem

a single click walks the player to the front of that cabinet
resolves a click on a CHILD mesh back to its cabinet
a single click does NOT launch
a second click on the same cabinet, in time, launches its game
a slow second click is two separate walks, not a launch
clicking a DIFFERENT cabinet quickly is not a double-click
a third click starts a fresh pair rather than launching again
a second click still launches even after the walk moved the view off the cabinet
a second click on a DIFFERENT cabinet retargets instead of launching
a click on nothing arms nothing — the next click is not a launch
ignores clicks that hit nothing
ignores clicks on meshes that belong to no cabinet
a non-interactive cabinet is scenery you can still walk up to

CabinetLinkSystem › launchDistance — the proximity gate

launches when the player is within reach
too far: reports OUT_OF_RANGE with the distances, does not launch, leaves the walk running
measures from the PLAYER, not from the click point
after the walk brings the player close, the next double-click launches
with no launchDistance the gate is open from anywhere (today’s behaviour)
with no walking camera announced there is nothing to measure from, so it launches
a CREATED without a handle is ignored
a cabinet with no mesh at all is measured from the first click’s pick point
forgets the camera on shutdown

CabinetLinkSystem — pointer wiring

a real pointerdown on the canvas walks the player over
ignores non-primary buttons — right-click is not a walk
stops listening once the system is removed

CabinetLinkSystem — locating the cabinet

falls back to a MeshPrimitive cabinet’s position
falls back to the pick point when the cabinet has no mesh component
a launch for a cabinet that vanished mid-gesture is a no-op

Last run 2026-10-08

CabinetLink.test.ts

// @vitest-environment jsdom
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { EventBus, MockRendererAdapter, World } from '@babylonjsmarket/ecs';
import { CabinetLinkEvents } from './CabinetLink.events';
import { FirstPersonCameraEvents } from '../FirstPersonCamera/FirstPersonCamera.events';
import { CabinetLinkComponent, CabinetLinkSystem } from './CabinetLink';
import { MeshComponent } from '../Mesh/Mesh.defs';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';

describe('CabinetLinkComponent', () => {
  it('derives its route from the game key', () => {
    expect(new CabinetLinkComponent({ game: 'frogger' }).route).toBe('/games/frogger/');
  });

  it('lets an explicit route win over the derived one', () => {
    const c = new CabinetLinkComponent({ game: 'frogger', route: '/arcade/frog' });
    expect(c.route).toBe('/arcade/frog');
  });

  it('has no route when it fronts no game', () => {
    expect(new CabinetLinkComponent().route).toBe('');
  });

  describe('approachFrom', () => {
    it('stands the player in front of a cabinet facing +Z, looking back at it', () => {
      const c = new CabinetLinkComponent({ game: 'g', facing: 0, standoff: 1.2 });
      const spot = c.approachFrom([3, 0, -5]);
      // Facing +Z means "in front" is +Z of the cabinet.
      expect(spot.x).toBeCloseTo(3, 5);
      expect(spot.z).toBeCloseTo(-3.8, 5);
      // And the player turns 180° to look back at the machine.
      expect(spot.yaw).toBeCloseTo(Math.PI, 5);
    });

    it('follows the cabinet’s facing when it is turned', () => {
      const c = new CabinetLinkComponent({ game: 'g', facing: Math.PI / 2, standoff: 2 });
      const spot = c.approachFrom([0, 0, 0]);
      // Facing +X now, so the stand point is +X of the cabinet.
      expect(spot.x).toBeCloseTo(2, 5);
      expect(spot.z).toBeCloseTo(0, 5);
    });

    it('an explicit standPoint overrides the computed one but still faces the cabinet', () => {
      const c = new CabinetLinkComponent({ game: 'g', facing: 0, standPoint: [9, 9] });
      const spot = c.approachFrom([0, 0, 0]);
      expect([spot.x, spot.z]).toEqual([9, 9]);
      expect(spot.yaw).toBeCloseTo(Math.PI, 5);
    });
  });

  it('serialize round-trips', () => {
    const c = new CabinetLinkComponent({ game: 'pacman', facing: 1, standoff: 2, title: 'Pac-Man' });
    expect(new CabinetLinkComponent(c.serialize()).serialize()).toEqual(c.serialize());
  });

  it('launchDistance defaults to no gate (Infinity) and stays out of the serialized form', () => {
    const c = new CabinetLinkComponent({ game: 'g' });
    expect(c.launchDistance).toBe(Infinity);
    expect('launchDistance' in c.serialize()).toBe(false);
    // …so the JSON round-trip cannot turn it into null.
    const json = JSON.parse(JSON.stringify(c.serialize()));
    expect(new CabinetLinkComponent(json).launchDistance).toBe(Infinity);
  });

  it('a finite launchDistance round-trips', () => {
    const c = new CabinetLinkComponent({ game: 'g', launchDistance: 1.5 });
    expect(c.serialize().launchDistance).toBe(1.5);
    expect(new CabinetLinkComponent(c.serialize()).launchDistance).toBe(1.5);
  });
});

describe('CabinetLinkSystem', () => {
  let eventBus: EventBus;
  let world: World;
  let renderer: MockRendererAdapter;
  let system: CabinetLinkSystem;
  let clock: number;

  beforeEach(() => {
    clock = 1000;
    eventBus = new EventBus();
    renderer = new MockRendererAdapter();
    world = new World({ eventBus, renderer, detectRaces: false });
    system = new CabinetLinkSystem(eventBus);
    system.now = () => clock;
    world.addSystem(system);
    world.initialize();
  });

  /** A cabinet at `x` on the back wall, facing the player (+Z). */
  const cabinet = (game: string, x: number) => {
    const e = world.createEntity();
    e.add(new MeshComponent({ src: '/cab.glb', position: [x, 0, -4], autoLoad: false }));
    e.add(new CabinetLinkComponent({ game, facing: 0, standoff: 1.2 }));
    world.update(1 / 60);
    return e;
  };

  /** Make the next pick resolve to `meshId`. */
  const pickReturns = (meshId: string) => {
    vi.spyOn(renderer, 'pickAtScreenPoint').mockReturnValue({ x: 0, y: 1, z: -4, meshId });
  };

  it('a single click walks the player to the front of that cabinet', () => {
    const e = cabinet('frogger', 2);
    const goto = vi.fn();
    eventBus.on(FirstPersonCameraEvents.GOTO, goto);
    pickReturns(e.id);
    system.handleClick(100, 100);

    expect(goto).toHaveBeenCalledTimes(1);
    const spot = goto.mock.calls[0][0];
    expect(spot.x).toBeCloseTo(2, 5);
    expect(spot.z).toBeCloseTo(-2.8, 5); // 1.2 m out from z = -4
    expect(spot.yaw).toBeCloseTo(Math.PI, 5);
  });

  it('resolves a click on a CHILD mesh back to its cabinet', () => {
    // Instanced clones name their parts `<entityId>_<part>`; a click on the
    // side art must still count as clicking that machine.
    const e = cabinet('galaga', -3);
    const focused = vi.fn();
    eventBus.on(CabinetLinkEvents.FOCUSED, focused);
    pickReturns(`${e.id}_Side_Art_primitive0`);
    system.handleClick(10, 10);
    expect(focused).toHaveBeenCalledTimes(1);
    expect(focused.mock.calls[0][0].game).toBe('galaga');
  });

  it('a single click does NOT launch', () => {
    const e = cabinet('frogger', 0);
    const launch = vi.fn();
    eventBus.on(CabinetLinkEvents.LAUNCH, launch);
    pickReturns(e.id);
    system.handleClick(1, 1);
    expect(launch).not.toHaveBeenCalled();
  });

  it('a second click on the same cabinet, in time, launches its game', () => {
    const e = cabinet('frogger', 0);
    const launch = vi.fn();
    eventBus.on(CabinetLinkEvents.LAUNCH, launch);
    pickReturns(e.id);
    system.handleClick(1, 1);
    clock += 200;
    system.handleClick(1, 1);

    expect(launch).toHaveBeenCalledTimes(1);
    expect(launch.mock.calls[0][0]).toMatchObject({
      game: 'frogger',
      route: '/games/frogger/',
    });
  });

  it('a slow second click is two separate walks, not a launch', () => {
    const e = cabinet('frogger', 0);
    const launch = vi.fn();
    const goto = vi.fn();
    eventBus.on(CabinetLinkEvents.LAUNCH, launch);
    eventBus.on(FirstPersonCameraEvents.GOTO, goto);
    pickReturns(e.id);
    system.handleClick(1, 1);
    clock += 5000;
    system.handleClick(1, 1);

    expect(launch).not.toHaveBeenCalled();
    expect(goto).toHaveBeenCalledTimes(2);
  });

  it('clicking a DIFFERENT cabinet quickly is not a double-click', () => {
    // Two machines side by side; a fast click on each is two approaches, and
    // must not launch whichever you happened to touch second.
    const a = cabinet('galaga', -2);
    const b = cabinet('pacman', 2);
    const launch = vi.fn();
    eventBus.on(CabinetLinkEvents.LAUNCH, launch);
    pickReturns(a.id);
    system.handleClick(1, 1);
    clock += 100;
    pickReturns(b.id);
    system.handleClick(1, 1);
    expect(launch).not.toHaveBeenCalled();
  });

  it('a third click starts a fresh pair rather than launching again', () => {
    const e = cabinet('frogger', 0);
    const launch = vi.fn();
    eventBus.on(CabinetLinkEvents.LAUNCH, launch);
    pickReturns(e.id);
    system.handleClick(1, 1);
    clock += 100;
    system.handleClick(1, 1); // launch
    clock += 100;
    system.handleClick(1, 1); // must NOT launch again
    expect(launch).toHaveBeenCalledTimes(1);
  });

  it('a second click still launches even after the walk moved the view off the cabinet', () => {
    // The regression this whole gesture design exists for: click one starts the
    // player walking, so click two lands on a wall instead of the machine.
    const e = cabinet('frogger', 0);
    const launch = vi.fn();
    eventBus.on(CabinetLinkEvents.LAUNCH, launch);
    pickReturns(e.id);
    system.handleClick(1, 1);
    clock += 150;
    pickReturns('Wall_W_box'); // camera moved; same pixel now hits the wall
    system.handleClick(1, 1);
    expect(launch).toHaveBeenCalledTimes(1);
    expect(launch.mock.calls[0][0].game).toBe('frogger');
  });

  it('a second click on a DIFFERENT cabinet retargets instead of launching', () => {
    const a = cabinet('galaga', -2);
    const b = cabinet('pacman', 2);
    const launch = vi.fn();
    const goto = vi.fn();
    eventBus.on(CabinetLinkEvents.LAUNCH, launch);
    eventBus.on(FirstPersonCameraEvents.GOTO, goto);
    pickReturns(a.id);
    system.handleClick(1, 1);
    clock += 120;
    pickReturns(b.id);
    system.handleClick(1, 1);
    expect(launch).not.toHaveBeenCalled();
    expect(goto).toHaveBeenCalledTimes(2);
  });

  it('a click on nothing arms nothing — the next click is not a launch', () => {
    const e = cabinet('frogger', 0);
    const launch = vi.fn();
    eventBus.on(CabinetLinkEvents.LAUNCH, launch);
    vi.spyOn(renderer, 'pickAtScreenPoint').mockReturnValue(null);
    system.handleClick(1, 1);
    clock += 100;
    pickReturns(e.id);
    system.handleClick(1, 1);
    expect(launch).not.toHaveBeenCalled();
  });

  it('ignores clicks that hit nothing', () => {
    cabinet('frogger', 0);
    const goto = vi.fn();
    eventBus.on(FirstPersonCameraEvents.GOTO, goto);
    vi.spyOn(renderer, 'pickAtScreenPoint').mockReturnValue(null);
    system.handleClick(1, 1);
    expect(goto).not.toHaveBeenCalled();
  });

  it('ignores clicks on meshes that belong to no cabinet', () => {
    cabinet('frogger', 0);
    const goto = vi.fn();
    eventBus.on(FirstPersonCameraEvents.GOTO, goto);
    pickReturns('Floor');
    system.handleClick(1, 1);
    expect(goto).not.toHaveBeenCalled();
  });

  describe('launchDistance — the proximity gate', () => {
    /** Announce a walking camera standing at (x, z), the way FirstPersonCamera does. */
    const cameraAt = (x: number, z: number) => {
      const handle = renderer.createPerspectiveCamera('firstPerson', {
        fov: 1.1,
        near: 0.1,
        far: 100,
        position: [x, 1.6, z],
      });
      eventBus.emit(FirstPersonCameraEvents.CREATED, { entityId: 'Player', handle });
      return handle;
    };
    const doubleClick = (id: string) => {
      pickReturns(id);
      system.handleClick(1, 1);
      clock += 150;
      system.handleClick(1, 1);
    };

    it('launches when the player is within reach', () => {
      const e = cabinet('frogger', 0); // at z = -4
      cameraAt(0, -3); // 1 m away
      const launch = vi.fn();
      eventBus.on(CabinetLinkEvents.LAUNCH, launch);
      e.get(CabinetLinkComponent)!.launchDistance = 1.5;
      doubleClick(e.id);
      expect(launch).toHaveBeenCalledTimes(1);
    });

    it('too far: reports OUT_OF_RANGE with the distances, does not launch, leaves the walk running', () => {
      const e = cabinet('frogger', 0); // at z = -4
      cameraAt(0, 4); // 8 m away
      const launch = vi.fn();
      const outOfRange = vi.fn();
      const goto = vi.fn();
      eventBus.on(CabinetLinkEvents.LAUNCH, launch);
      eventBus.on(CabinetLinkEvents.OUT_OF_RANGE, outOfRange);
      eventBus.on(FirstPersonCameraEvents.GOTO, goto);
      e.get(CabinetLinkComponent)!.launchDistance = 1.5;
      doubleClick(e.id);
      expect(launch).not.toHaveBeenCalled();
      expect(outOfRange).toHaveBeenCalledTimes(1);
      expect(outOfRange.mock.calls[0][0]).toMatchObject({
        entityId: e.id,
        game: 'frogger',
        title: 'frogger',
        launchDistance: 1.5,
      });
      expect(outOfRange.mock.calls[0][0].distance).toBeCloseTo(8, 5);
      // Exactly one GOTO — the first click's — and nothing cancelled it.
      expect(goto).toHaveBeenCalledTimes(1);
    });

    it('measures from the PLAYER, not from the click point', () => {
      const e = cabinet('frogger', 0); // at z = -4
      cameraAt(0, 4); // player is 8 m away…
      const launch = vi.fn();
      eventBus.on(CabinetLinkEvents.LAUNCH, launch);
      e.get(CabinetLinkComponent)!.launchDistance = 1.5;
      // …even though the pick itself lands right on the machine.
      vi.spyOn(renderer, 'pickAtScreenPoint').mockReturnValue({ x: 0, y: 1, z: -3.9, meshId: e.id });
      system.handleClick(1, 1);
      clock += 100;
      system.handleClick(1, 1);
      expect(launch).not.toHaveBeenCalled();
    });

    it('after the walk brings the player close, the next double-click launches', () => {
      const e = cabinet('frogger', 0);
      const handle = cameraAt(0, 4);
      const launch = vi.fn();
      eventBus.on(CabinetLinkEvents.LAUNCH, launch);
      e.get(CabinetLinkComponent)!.launchDistance = 1.5;
      doubleClick(e.id);
      expect(launch).not.toHaveBeenCalled();
      // The camera walked over (FirstPersonCamera poses it each frame).
      renderer.setCameraPose(handle, [0, 1.6, -2.8], { x: 0, y: 1, z: 0, w: 0 });
      clock += 5000; // a fresh pair
      doubleClick(e.id);
      expect(launch).toHaveBeenCalledTimes(1);
    });

    it('with no launchDistance the gate is open from anywhere (today’s behaviour)', () => {
      const e = cabinet('frogger', 0);
      cameraAt(50, 50);
      const launch = vi.fn();
      eventBus.on(CabinetLinkEvents.LAUNCH, launch);
      doubleClick(e.id);
      expect(launch).toHaveBeenCalledTimes(1);
    });

    it('with no walking camera announced there is nothing to measure from, so it launches', () => {
      const e = cabinet('frogger', 0);
      const launch = vi.fn();
      eventBus.on(CabinetLinkEvents.LAUNCH, launch);
      e.get(CabinetLinkComponent)!.launchDistance = 0.1;
      doubleClick(e.id);
      expect(launch).toHaveBeenCalledTimes(1);
    });

    it('a CREATED without a handle is ignored', () => {
      const e = cabinet('frogger', 0);
      eventBus.emit(FirstPersonCameraEvents.CREATED, { entityId: 'Player' });
      const launch = vi.fn();
      eventBus.on(CabinetLinkEvents.LAUNCH, launch);
      e.get(CabinetLinkComponent)!.launchDistance = 0.1;
      doubleClick(e.id);
      expect(launch).toHaveBeenCalledTimes(1);
    });

    it('a cabinet with no mesh at all is measured from the first click’s pick point', () => {
      const e = world.createEntity();
      e.add(new CabinetLinkComponent({ game: 'g', launchDistance: 1 }));
      world.update(1 / 60);
      cameraAt(0, 0);
      const outOfRange = vi.fn();
      eventBus.on(CabinetLinkEvents.OUT_OF_RANGE, outOfRange);
      vi.spyOn(renderer, 'pickAtScreenPoint').mockReturnValue({ x: 3, y: 1, z: 4, meshId: e.id });
      system.handleClick(1, 1);
      clock += 100;
      system.handleClick(1, 1);
      expect(outOfRange.mock.calls[0][0].distance).toBeCloseTo(5, 5);
    });

    it('forgets the camera on shutdown', () => {
      const e = cabinet('frogger', 0);
      cameraAt(0, 40);
      e.get(CabinetLinkComponent)!.launchDistance = 1;
      world.removeSystem(system);
      const fresh = new CabinetLinkSystem(eventBus);
      fresh.now = () => clock;
      world.addSystem(fresh);
      const launch = vi.fn();
      eventBus.on(CabinetLinkEvents.LAUNCH, launch);
      pickReturns(e.id);
      fresh.handleClick(1, 1);
      clock += 100;
      fresh.handleClick(1, 1);
      expect(launch).toHaveBeenCalledTimes(1); // no camera known → gate open
    });
  });

  it('a non-interactive cabinet is scenery you can still walk up to', () => {
    // `interactive: false` means "no game behind it", not "ignores you". Most
    // machines in a room are scenery, and a click that does nothing at all
    // reads as a broken page rather than as an empty cabinet.
    const e = world.createEntity();
    e.add(new MeshComponent({ src: '/cab.glb', position: [0, 0, -4], autoLoad: false }));
    e.add(new CabinetLinkComponent({ game: 'frogger', interactive: false }));
    world.update(1 / 60);
    const goto = vi.fn();
    const launch = vi.fn();
    eventBus.on(FirstPersonCameraEvents.GOTO, goto);
    eventBus.on(CabinetLinkEvents.LAUNCH, launch);
    pickReturns(e.id);

    system.handleClick(1, 1);
    expect(goto).toHaveBeenCalledTimes(1); // walks you over

    system.handleClick(1, 1); // and the confirming click does nothing
    expect(launch).not.toHaveBeenCalled();
  });
});

// @vitest-environment jsdom
describe('CabinetLinkSystem — pointer wiring', () => {
  let eventBus: EventBus;
  let world: World;
  let renderer: MockRendererAdapter;
  let system: CabinetLinkSystem;
  let canvas: HTMLCanvasElement;

  const clickCanvas = (button = 0) =>
    canvas.dispatchEvent(
      new MouseEvent('pointerdown', { clientX: 50, clientY: 60, button, bubbles: true }),
    );

  beforeEach(async () => {
    eventBus = new EventBus();
    renderer = new MockRendererAdapter();
    canvas = document.createElement('canvas');
    document.body.appendChild(canvas);
    await renderer.init(canvas);
    world = new World({ eventBus, renderer, detectRaces: false });
    system = new CabinetLinkSystem(eventBus);
    world.addSystem(system);
    world.initialize();

    const e = world.createEntity();
    e.add(new MeshComponent({ src: '/cab.glb', position: [0, 0, -4], autoLoad: false }));
    e.add(new CabinetLinkComponent({ game: 'frogger', facing: 0 }));
    world.update(1 / 60);
    vi.spyOn(renderer, 'pickAtScreenPoint').mockReturnValue({ x: 0, y: 1, z: -4, meshId: e.id });
  });

  afterEach(() => {
    canvas.remove();
  });

  it('a real pointerdown on the canvas walks the player over', () => {
    const goto = vi.fn();
    eventBus.on(FirstPersonCameraEvents.GOTO, goto);
    clickCanvas();
    expect(goto).toHaveBeenCalledTimes(1);
  });

  it('ignores non-primary buttons — right-click is not a walk', () => {
    const goto = vi.fn();
    eventBus.on(FirstPersonCameraEvents.GOTO, goto);
    clickCanvas(2);
    expect(goto).not.toHaveBeenCalled();
  });

  it('stops listening once the system is removed', () => {
    world.removeSystem(system);
    const goto = vi.fn();
    eventBus.on(FirstPersonCameraEvents.GOTO, goto);
    clickCanvas();
    expect(goto).not.toHaveBeenCalled();
  });
});

describe('CabinetLinkSystem — locating the cabinet', () => {
  let eventBus: EventBus;
  let world: World;
  let renderer: MockRendererAdapter;
  let system: CabinetLinkSystem;

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

  it('falls back to a MeshPrimitive cabinet’s position', () => {
    const e = world.createEntity();
    e.add(new MeshPrimitiveComponent({ primitive: 'box', position: [5, 0, -2] }));
    e.add(new CabinetLinkComponent({ game: 'g', facing: 0, standoff: 1 }));
    world.update(1 / 60);
    vi.spyOn(renderer, 'pickAtScreenPoint').mockReturnValue({ x: 9, y: 9, z: 9, meshId: e.id });
    const goto = vi.fn();
    eventBus.on(FirstPersonCameraEvents.GOTO, goto);
    system.handleClick(1, 1);
    expect(goto.mock.calls[0][0].x).toBeCloseTo(5, 5);
    expect(goto.mock.calls[0][0].z).toBeCloseTo(-1, 5);
  });

  it('falls back to the pick point when the cabinet has no mesh component', () => {
    const e = world.createEntity();
    e.add(new CabinetLinkComponent({ game: 'g', facing: 0, standoff: 1 }));
    world.update(1 / 60);
    vi.spyOn(renderer, 'pickAtScreenPoint').mockReturnValue({ x: 2, y: 1, z: 3, meshId: e.id });
    const goto = vi.fn();
    eventBus.on(FirstPersonCameraEvents.GOTO, goto);
    system.handleClick(1, 1);
    expect(goto.mock.calls[0][0].x).toBeCloseTo(2, 5);
    expect(goto.mock.calls[0][0].z).toBeCloseTo(4, 5);
  });

  it('a launch for a cabinet that vanished mid-gesture is a no-op', () => {
    const e = world.createEntity();
    e.add(new CabinetLinkComponent({ game: 'g' }));
    world.update(1 / 60);
    vi.spyOn(renderer, 'pickAtScreenPoint').mockReturnValue({ x: 0, y: 0, z: 0, meshId: e.id });
    const launch = vi.fn();
    eventBus.on(CabinetLinkEvents.LAUNCH, launch);
    system.handleClick(1, 1);
    world.removeEntity(e.id); // scene swapped out from under the gesture
    world.update(1 / 60);
    expect(() => system.handleClick(1, 1)).not.toThrow();
    expect(launch).not.toHaveBeenCalled();
  });
});