MouseInput

MouseInput.core.ts

MouseInput.core.ts — pure data for the global mouse → EventBus bridge.

Marks the singleton "input source" entity, the pointer sibling of KeyboardInput. The MouseInputSystem (next door in MouseInput.ts) attaches DOM pointer listeners and republishes them as the canonical mouse.* bus events, so gameplay systems read the mouse off the bus rather than touching the DOM.

Deltas go out in RAW device pixels. Scaling them into intent is the consumer's job, not this component's — a flight stick wants ~400px per full deflection (PlayerFlightInput.mouseSensitivity) while a turret or a cursor wants something else entirely, and each should be able to say so without renegotiating with the shared input source.

requirePointerLock gates accumulation on actually holding the pointer. Left on (the default), motion is ignored until the canvas captures the cursor, so dragging the mouse toward a browser tab doesn't roll the ship; clickToLock makes the first click request that capture instead of counting as a shot.

Zero imports from @babylonjs, three, solid-js, or the DOM.

MouseInput.core.ts

import { Component } from '@babylonjsmarket/ecs';

export interface MouseInputInput {
  /** Ignore motion until the pointer is locked to the canvas. */
  requirePointerLock?: boolean;
  /** First click requests pointer lock instead of counting as a button press. */
  clickToLock?: boolean;
}

export const DEFAULT_MOUSE_INPUT_PARAMS: Required<MouseInputInput> = {
  requirePointerLock: true,
  clickToLock: true,
};

export class MouseInputComponent extends Component {
  requirePointerLock: boolean;
  clickToLock: boolean;

  constructor(data: MouseInputInput = {}) {
    super();
    const p = { ...DEFAULT_MOUSE_INPUT_PARAMS, ...data };
    this.requirePointerLock = p.requirePointerLock;
    this.clickToLock = p.clickToLock;
  }

  serialize(): MouseInputInput {
    return {
      requirePointerLock: this.requirePointerLock,
      clickToLock: this.clickToLock,
    };
  }
}

MouseInput.ts

MouseInput.ts — renderer-agnostic System bridging the DOM mouse onto the EventBus. The pointer half of the input contract KeyboardInput owns for keys.

On init it attaches window pointer listeners (guarded by a window check so it stays inert under SSR / node tests) and republishes each one as the canonical bus events — imported from inputEvents, never hardcoded:

DOM mousemove → emit MouseInputEvents.MOVE { dx, dy } DOM mousedown → emit MouseInputEvents.DOWN { button } DOM mouseup → emit MouseInputEvents.UP { button } DOM pointerlockchange → emit MouseInputEvents.LOCK_CHANGED { locked }

Motion is read from movementX/Y — a relative delta, the only thing that means anything once the cursor is locked and has no on-screen position. It is forwarded in RAW device pixels; consumers scale it (see PlayerFlightInput.mouseSensitivity).

Two details are load-bearing, both inherited from the reference game's input bridge:

While requirePointerLock is set, motion before capture is DROPPED rather than queued. Otherwise the mouse travel that a player uses to go click the canvas arrives as one enormous first delta and snaps the ship around. - Losing the lock (Esc, tab-away) synthesises an UP for every button still held. The DOM does not send mouseup once the pointer is gone, so without this the guns keep firing after the player has left.

The canvas comes from renderer.getRenderingCanvas() — the adapter's own accessor, so no engine type crosses the boundary and pointer lock still targets the surface being drawn into.

DOM listeners are non-event resources, so they're torn down in onShutdown. Not pauseable — an input source keeps bridging while paused so a pause menu still receives the mouse. Zero @babylonjs / three imports; constructor takes (eventBus) only.

MouseInput.ts

import { System } from '@babylonjsmarket/ecs';
import type { EventBus } from '@babylonjsmarket/ecs';
import { MouseInputComponent } from './MouseInput.core';
import { MouseInputEvents } from '../../inputEvents';

export class MouseInputSystem extends System {
  protected query = { required: [MouseInputComponent] };

  private moveHandler: ((e: MouseEvent) => void) | null = null;
  private downHandler: ((e: MouseEvent) => void) | null = null;
  private upHandler: ((e: MouseEvent) => void) | null = null;
  private lockChangeHandler: (() => void) | null = null;

  /** Buttons currently held, so a lost pointer lock can release them. */
  private heldButtons = new Set<number>();
  private pointerLocked = false;

  constructor(eventBus: EventBus) {
    super(eventBus);
    // Input source: keep bridging the mouse even while the world is paused.
    this._pauseable = false;
  }

  protected onInitialize(): void {
    this.moveHandler = (e: MouseEvent) => {
      if (this.requiresLock() && !this.pointerLocked) return;
      const dx = e.movementX ?? 0;
      const dy = e.movementY ?? 0;
      // A still mouse fires no-op moves on some platforms; don't wake listeners.
      if (dx === 0 && dy === 0) return;
      this.eventBus.emit(MouseInputEvents.MOVE, { dx, dy });
    };

    this.downHandler = (e: MouseEvent) => {
      // First click buys the pointer, it doesn't pull the trigger.
      if (this.clicksToLock() && !this.pointerLocked) {
        this.requestPointerLock();
        return;
      }
      this.heldButtons.add(e.button);
      this.eventBus.emit(MouseInputEvents.DOWN, { button: e.button });
    };

    this.upHandler = (e: MouseEvent) => {
      this.heldButtons.delete(e.button);
      this.eventBus.emit(MouseInputEvents.UP, { button: e.button });
    };

    this.lockChangeHandler = () => {
      this.pointerLocked = this.isCanvasLocked();
      if (!this.pointerLocked) this.releaseHeldButtons();
      this.eventBus.emit(MouseInputEvents.LOCK_CHANGED, { locked: this.pointerLocked });
    };

    if (typeof window !== 'undefined') {
      window.addEventListener('mousemove', this.moveHandler);
      window.addEventListener('mousedown', this.downHandler);
      window.addEventListener('mouseup', this.upHandler);
    }
    if (typeof document !== 'undefined') {
      document.addEventListener('pointerlockchange', this.lockChangeHandler);
    }

    // Adopt the lock that already exists rather than assuming there isn't one.
    // A round reset rebuilds the game around the SAME canvas, so the pointer is
    // very often still captured — and since no pointerlockchange fires for a lock
    // that never changed, starting at `false` would silently drop every mouse
    // delta until the player pressed Esc and clicked again.
    this.pointerLocked = this.isCanvasLocked();
  }

  protected onShutdown(): void {
    if (typeof window !== 'undefined') {
      if (this.moveHandler) window.removeEventListener('mousemove', this.moveHandler);
      if (this.downHandler) window.removeEventListener('mousedown', this.downHandler);
      if (this.upHandler) window.removeEventListener('mouseup', this.upHandler);
    }
    if (typeof document !== 'undefined' && this.lockChangeHandler) {
      document.removeEventListener('pointerlockchange', this.lockChangeHandler);
    }
    this.moveHandler = null;
    this.downHandler = null;
    this.upHandler = null;
    this.lockChangeHandler = null;
    this.heldButtons.clear();
    this.pointerLocked = false;
  }

  protected onUpdate(_dt: number): void {
    // DOM-driven: every event is emitted from a handler attached in
    // onInitialize, so there is no per-frame work.
  }

  /** True if any matched MouseInput source demands pointer lock before motion. */
  private requiresLock(): boolean {
    for (const entity of this.entities) {
      if (entity.get(MouseInputComponent)!.requirePointerLock) return true;
    }
    return false;
  }

  /** True if any matched MouseInput source spends the first click on capture. */
  private clicksToLock(): boolean {
    for (const entity of this.entities) {
      if (entity.get(MouseInputComponent)!.clickToLock) return true;
    }
    return false;
  }

  private getCanvas(): HTMLCanvasElement | null {
    return this.world?.renderer?.getRenderingCanvas() ?? null;
  }

  /** True if the DOM currently has the pointer locked to our own canvas. */
  private isCanvasLocked(): boolean {
    if (typeof document === 'undefined') return false;
    const canvas = this.getCanvas();
    return canvas !== null && document.pointerLockElement === canvas;
  }

  private requestPointerLock(): void {
    this.getCanvas()?.requestPointerLock?.();
  }

  /**
   * Tell listeners every held button came up. Called when the pointer lock is
   * lost, because the DOM will not send those mouseups itself.
   */
  private releaseHeldButtons(): void {
    for (const button of this.heldButtons) {
      this.eventBus.emit(MouseInputEvents.UP, { button });
    }
    this.heldButtons.clear();
  }
}

export {
  MouseInputComponent,
  DEFAULT_MOUSE_INPUT_PARAMS,
  type MouseInputInput,
} from './MouseInput.core';

MouseInput.contract.test.ts

// @vitest-environment jsdom
import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import { MouseInputComponent, MouseInputSystem } from './MouseInput';

// jsdom: MouseInputSystem attaches window/document pointer listeners in
// onInitialize, which the contract battery runs.
runMechanicContract({
  name: 'MouseInput',
  componentClass: MouseInputComponent,
  // A standalone input source, exactly like KeyboardInput: it only needs its own
  // marker component to match, and it emits its `mouse.*` events from DOM
  // handlers rather than during onUpdate — so no companions and no declared
  // events here. The emitted names are covered by MouseInput.test.ts, which can
  // dispatch real pointer events; the contract's output check only watches
  // update ticks and would always see zero.
  systemClass: MouseInputSystem,
  sampleInput: { requirePointerLock: false },
});

MouseInput.core.test.ts

import { describe, expect, it } from 'vitest';
import { MouseInputComponent, DEFAULT_MOUSE_INPUT_PARAMS } from './MouseInput.core';

describe('MouseInputComponent', () => {
  it('demands pointer lock by default', () => {
    expect(DEFAULT_MOUSE_INPUT_PARAMS.requirePointerLock).toBe(true);
    expect(new MouseInputComponent().requirePointerLock).toBe(true);
  });

  it('spends the first click on capture by default', () => {
    expect(DEFAULT_MOUSE_INPUT_PARAMS.clickToLock).toBe(true);
    expect(new MouseInputComponent().clickToLock).toBe(true);
  });

  it('accepts both knobs turned off', () => {
    const c = new MouseInputComponent({ requirePointerLock: false, clickToLock: false });
    expect(c.requirePointerLock).toBe(false);
    expect(c.clickToLock).toBe(false);
  });

  it('serialize() round-trips into an equivalent component', () => {
    const c = new MouseInputComponent({ requirePointerLock: false, clickToLock: true });
    const copy = new MouseInputComponent(c.serialize());
    expect(copy.serialize()).toEqual({ requirePointerLock: false, clickToLock: true });
  });
});

MouseInput.test.ts

import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { EventBus, World, MockRendererAdapter } from '@babylonjsmarket/ecs';
import { MouseInputComponent, MouseInputSystem } from './MouseInput';
import { MouseInputEvents } from '../../inputEvents';

/** A mousemove carrying a relative delta, the way a locked pointer reports. */
function mousemove(dx: number, dy: number): void {
  const e = new MouseEvent('mousemove');
  // movementX/Y are read-only accessors on the prototype; jsdom doesn't
  // synthesise them from the constructor, so define them on the instance.
  Object.defineProperty(e, 'movementX', { value: dx });
  Object.defineProperty(e, 'movementY', { value: dy });
  window.dispatchEvent(e);
}

const mousedown = (button = 0) => window.dispatchEvent(new MouseEvent('mousedown', { button }));
const mouseup = (button = 0) => window.dispatchEvent(new MouseEvent('mouseup', { button }));

/** Point document.pointerLockElement at `el` and fire the change event. */
function setPointerLock(el: Element | null): void {
  Object.defineProperty(document, 'pointerLockElement', {
    value: el,
    configurable: true,
  });
  document.dispatchEvent(new Event('pointerlockchange'));
}

describe('MouseInputSystem', () => {
  let eventBus: EventBus;
  let world: World;
  let system: MouseInputSystem;
  let renderer: MockRendererAdapter;
  let canvas: HTMLCanvasElement;
  let seen: Array<{ type: string; data: unknown }>;

  beforeEach(async () => {
    canvas = document.createElement('canvas');
    document.body.appendChild(canvas);
    renderer = new MockRendererAdapter();
    await renderer.init(canvas);

    eventBus = new EventBus();
    world = new World({ eventBus, renderer });
    system = new MouseInputSystem(eventBus);
    world.addSystem(system);
    world.createEntity().add(new MouseInputComponent());
    world.initialize();

    seen = [];
    for (const type of Object.values(MouseInputEvents)) {
      eventBus.on(type, (data: unknown) => seen.push({ type, data }));
    }
  });

  afterEach(() => {
    world.shutdown();
    canvas.remove();
    setPointerLock(null);
  });

  const moves = () => seen.filter((e) => e.type === MouseInputEvents.MOVE).map((e) => e.data);
  const ups = () => seen.filter((e) => e.type === MouseInputEvents.UP).map((e) => e.data);
  const downs = () => seen.filter((e) => e.type === MouseInputEvents.DOWN).map((e) => e.data);

  it('re-exports the component for the registry', () => {
    expect(typeof MouseInputComponent).toBe('function');
    expect(new MouseInputComponent()).toBeInstanceOf(MouseInputComponent);
  });

  it('is not pauseable — the mouse still reaches a pause menu', () => {
    expect(system.pauseable).toBe(false);
  });

  it('does no per-frame work', () => {
    expect(() => world.update(1 / 60)).not.toThrow();
    expect(seen).toHaveLength(0);
  });

  // The whole reason requirePointerLock defaults on: the travel a player spends
  // reaching for the canvas must not arrive as one enormous first delta.
  it('drops motion until the pointer is locked', () => {
    mousemove(50, 50);
    expect(moves()).toHaveLength(0);

    setPointerLock(canvas);
    mousemove(50, 50);
    expect(moves()).toEqual([{ dx: 50, dy: 50 }]);
  });

  it('forwards raw device pixels, unscaled', () => {
    setPointerLock(canvas);
    mousemove(-13, 7);
    expect(moves()).toEqual([{ dx: -13, dy: 7 }]);
  });

  it('ignores a no-op move', () => {
    setPointerLock(canvas);
    mousemove(0, 0);
    expect(moves()).toHaveLength(0);
  });

  it('reports motion straight away when pointer lock is not required', async () => {
    world.shutdown();
    const bus = new EventBus();
    const w = new World({ eventBus: bus, renderer });
    w.addSystem(new MouseInputSystem(bus));
    w.createEntity().add(new MouseInputComponent({ requirePointerLock: false }));
    w.initialize();

    const got: unknown[] = [];
    bus.on(MouseInputEvents.MOVE, (d: unknown) => got.push(d));
    mousemove(4, 5);

    expect(got).toEqual([{ dx: 4, dy: 5 }]);
    w.shutdown();
  });

  it('spends the first click on capture instead of the trigger', () => {
    const request = vi.fn();
    canvas.requestPointerLock = request;

    mousedown(0);

    expect(request).toHaveBeenCalledTimes(1);
    expect(downs()).toHaveLength(0);
  });

  it('reports button presses once the pointer is held', () => {
    setPointerLock(canvas);

    mousedown(0);
    expect(downs()).toEqual([{ button: 0 }]);

    mouseup(0);
    expect(ups()).toEqual([{ button: 0 }]);
  });

  it('passes the button index through', () => {
    setPointerLock(canvas);
    mousedown(2);
    expect(downs()).toEqual([{ button: 2 }]);
  });

  it('clicks straight through when clickToLock is off', async () => {
    world.shutdown();
    const bus = new EventBus();
    const w = new World({ eventBus: bus, renderer });
    w.addSystem(new MouseInputSystem(bus));
    w.createEntity().add(new MouseInputComponent({ clickToLock: false }));
    w.initialize();

    const got: unknown[] = [];
    bus.on(MouseInputEvents.DOWN, (d: unknown) => got.push(d));
    mousedown(0);

    expect(got).toEqual([{ button: 0 }]);
    w.shutdown();
  });

  it('announces the lock being taken and released', () => {
    setPointerLock(canvas);
    setPointerLock(null);

    expect(seen.filter((e) => e.type === MouseInputEvents.LOCK_CHANGED).map((e) => e.data)).toEqual([
      { locked: true },
      { locked: false },
    ]);
  });

  it('is not locked when some other element holds the pointer', () => {
    const other = document.createElement('div');
    setPointerLock(other);

    expect(seen.filter((e) => e.type === MouseInputEvents.LOCK_CHANGED).map((e) => e.data)).toEqual([
      { locked: false },
    ]);
  });

  // The DOM sends no mouseup once the pointer is gone, so without this the guns
  // keep firing after the player has hit Esc.
  it('releases held buttons when the lock is lost', () => {
    setPointerLock(canvas);
    mousedown(0);
    mousedown(2);
    seen.length = 0;

    setPointerLock(null);

    expect(ups()).toEqual([{ button: 0 }, { button: 2 }]);
  });

  it('does not re-release a button that already came up', () => {
    setPointerLock(canvas);
    mousedown(0);
    mouseup(0);
    seen.length = 0;

    setPointerLock(null);

    expect(ups()).toHaveLength(0);
  });

  it('stops listening after shutdown', () => {
    setPointerLock(canvas);
    world.shutdown();
    seen.length = 0;

    mousemove(20, 20);
    mousedown(0);

    expect(seen).toHaveLength(0);
  });

  // A round reset rebuilds the game around the same canvas, so the pointer is
  // usually still captured — and no pointerlockchange fires for a lock that never
  // changed. Starting at `false` would drop every delta until the player pressed
  // Esc and clicked again.
  it('adopts a pointer lock that was already held at startup', () => {
    setPointerLock(canvas);
    world.shutdown();

    const bus = new EventBus();
    const w = new World({ eventBus: bus, renderer });
    w.addSystem(new MouseInputSystem(bus));
    w.createEntity().add(new MouseInputComponent());
    w.initialize();

    const got: unknown[] = [];
    bus.on(MouseInputEvents.MOVE, (d: unknown) => got.push(d));
    mousemove(9, 9);

    expect(got).toEqual([{ dx: 9, dy: 9 }]);
    w.shutdown();
  });

  it('does not adopt a lock held by some other element at startup', () => {
    setPointerLock(document.createElement('div'));
    world.shutdown();

    const bus = new EventBus();
    const w = new World({ eventBus: bus, renderer });
    w.addSystem(new MouseInputSystem(bus));
    w.createEntity().add(new MouseInputComponent());
    w.initialize();

    const got: unknown[] = [];
    bus.on(MouseInputEvents.MOVE, (d: unknown) => got.push(d));
    mousemove(9, 9);

    expect(got).toHaveLength(0);
    w.shutdown();
  });

  it('survives having no canvas to lock', () => {
    const bus = new EventBus();
    const w = new World({ eventBus: bus }); // no renderer at all
    w.addSystem(new MouseInputSystem(bus));
    w.createEntity().add(new MouseInputComponent());
    w.initialize();

    expect(() => mousedown(0)).not.toThrow();
    w.shutdown();
  });
});