@vgai/engine 0.5.22 → 0.5.23

package/src/input/host-pointer.ts

@@ -0,0 +1,230 @@
+/**
+ * The host POINTER stream, in the game's own coordinate space — the DOM edge
+ * `InputManager`'s touch backends (`setTouchButton` / `setTouchStick`) and any
+ * pointer-position read need, and which the manager itself deliberately does
+ * not own.
+ *
+ * `InputManager` listens on `window` for keyboard, mouse and focus, in CLIENT
+ * pixels, because an action map is surface-agnostic. A pointer is not: a tap is
+ * only meaningful relative to the surface it landed on, and a game's own
+ * coordinate space is usually NOT that surface's CSS pixels — a fixed design
+ * resolution presented by uniformly scaling and letterboxing is the common
+ * case, and a hit-test against a UI rect authored in design pixels has to
+ * happen in one space with the pointer. That mapping needs a surface and a
+ * design size the manager has no way to know, so it lives here, beside it.
+ *
+ * What this owns, and nothing more:
+ *
+ * - **Position** — the last pointer position over the surface, mapped into the
+ *   design space. `setPosition` is the headless door (a harness or a game
+ *   command driving the game with no DOM), the same shape as
+ *   `InputManager.addMouseDelta`: inject through the accumulator the reader
+ *   already reads, never a synthetic `pointermove`.
+ * - **Touches** — a per-frame queue of {@link HostPointerTouch} records with
+ *   DENSE finger indices, drained by the game's own frame. `pointerId` is the
+ *   browser's opaque, monotonically growing handle; a touch API that reports
+ *   "finger 0 and finger 1" wants the lowest free slot, reused the moment a
+ *   finger lifts, which is what {@link HostPointerTouch.index} is.
+ * - **Cursor** — the CSS cursor applied to the surface, because the surface is
+ *   resolved here and nowhere else.
+ *
+ * **Gating.** Every listener returns early unless
+ * `InputManager.isInputActive()` — the SAME predicate the manager's own
+ * `keydown`/`mousemove` listeners pass, so play-mode isolation and window
+ * blur suppress pointer position and touches exactly as they suppress a key.
+ * The predicate is read from the manager rather than recomposed here
+ * (`isEnabled() && isFocused()` written out a second time is how a looser gate
+ * drifts in: a blurred or typing tab kept updating a pointer position under
+ * exactly that duplication). Text-entry focus is deliberately NOT part of it,
+ * matching `onMouseMove` rather than `onKeyDown` — moving a finger is not
+ * typing.
+ *
+ * **Ownership.** Owns its four pointer listeners on the resolved owner, the
+ * touch queue and the finger-index table. Shares the `InputManager`, which is
+ * the game's and is never mutated here — this reports; what a control DOES
+ * with a finger (which rect owns it, whether that becomes a `setTouchButton`)
+ * belongs to the UI that draws the control. Teardown is {@link
+ * HostPointer.dispose}, and only that: `InputManager.dispose` does not reach
+ * these listeners.
+ *
+ * Headless (no `window`): construction succeeds and binds nothing. Position is
+ * whatever {@link HostPointer.setPosition} last wrote, and the touch queue
+ * stays empty.
+ */
+
+import type { InputManager } from './input-manager';
+import type { Vector2 } from './input-types';
+
+/**
+ * Cap on the undrained touch queue. A game that drains every frame cannot
+ * reach it — this is the bound for one that never drains at all (a project
+ * that reads no touches, on a device that has them), so the queue is a RING:
+ * the newest records win and the oldest are dropped.
+ */
+const TOUCH_QUEUE_MAX = 256;
+
+/** One finger edge the host pointer stream produced. */
+export interface HostPointerTouch {
+  /**
+   * `'start'` when the finger went down on the surface, `'move'` while it
+   * drags, `'end'` when it lifted or the browser cancelled it. A cancel is an
+   * end: the finger is gone either way, and a control that treats them
+   * differently is holding a button nothing will ever release.
+   */
+  readonly phase: 'start' | 'move' | 'end';
+  /**
+   * DENSE finger index — the lowest slot free when this finger went down, and
+   * free again the moment it lifts. NOT the browser's `pointerId`, which never
+   * reuses a value and is therefore useless as "which finger is this".
+   */
+  readonly index: number;
+  /** Position in the design space (see {@link HostPointerOptions.designSize}). */
+  readonly position: Vector2;
+}
+
+/** What {@link createHostPointer} needs. */
+export interface HostPointerOptions {
+  /** The game's own manager — read for its gate, never written. */
+  readonly input: InputManager;
+  /**
+   * The render surface pointer positions are relative to.
+   *
+   * A GETTER rather than an element because a renderer usually mints its
+   * canvas after the game's services exist. Absent (or returning `null`) falls
+   * back to the event's own target element, and listening falls back to
+   * `window` — which is what makes a finger that starts on the canvas and
+   * drags over a DOM overlay keep reporting.
+   */
+  readonly surface?: (() => HTMLElement | null) | undefined;
+  /**
+   * The game's own logical resolution, if it has one. Surface CSS pixels are
+   * mapped into it, so a pointer and a UI rect authored at this size share one
+   * space regardless of how the host scaled and letterboxed the surface.
+   *
+   * Absent: positions are reported in the surface's own CSS pixels, and the
+   * position before any event is `{x: 0, y: 0}`. Present: the position before
+   * any event is the CENTRE of the design space — a pointer that has never
+   * moved is better described as the middle of the view than as a corner it
+   * was never at.
+   */
+  readonly designSize?: Vector2 | undefined;
+}
+
+/** The host pointer stream bound to one surface. One per mounted game. */
+export interface HostPointer {
+  /** The last pointer position, in the design space. */
+  getPosition(): Vector2;
+  /** Headless / harness door onto {@link getPosition}'s value. */
+  setPosition(position: Vector2): void;
+  /**
+   * Drain the touch records queued since the last call. Returns them in
+   * arrival order and empties the queue, so a frame that drains sees each
+   * finger edge exactly once.
+   */
+  takeTouches(): readonly HostPointerTouch[];
+  /**
+   * Set the CSS `cursor` applied to the surface. Applied on the next pointer
+   * move over it, which is also when the surface is known.
+   */
+  setCursor(cursor: string): void;
+  /** Remove the listeners this owns. */
+  dispose(): void;
+}
+
+export function createHostPointer(options: HostPointerOptions): HostPointer {
+  const { input, surface: surfaceOf, designSize } = options;
+  let position: Vector2 = designSize
+    ? { x: designSize.x / 2, y: designSize.y / 2 }
+    : { x: 0, y: 0 };
+  let cursor = 'default';
+
+  const touches: HostPointerTouch[] = [];
+  /** Browser `pointerId` -> dense finger index, for fingers currently down. */
+  const fingerOfPointer = new Map<number, number>();
+  const freeFinger = (): number => {
+    const taken = new Set(fingerOfPointer.values());
+    let index = 0;
+    while (taken.has(index)) index += 1;
+    return index;
+  };
+  const queue = (touch: HostPointerTouch): void => {
+    touches.push(touch);
+    if (touches.length > TOUCH_QUEUE_MAX) touches.shift();
+  };
+
+  const queueTouch = (event: PointerEvent, point: Vector2): void => {
+    if (event.type === 'pointerdown') {
+      const index = freeFinger();
+      fingerOfPointer.set(event.pointerId, index);
+      queue({ phase: 'start', index, position: point });
+      return;
+    }
+    // A move or a release from a pointer that never went down on this surface
+    // is not one of our fingers.
+    const index = fingerOfPointer.get(event.pointerId);
+    if (index === undefined) return;
+    if (event.type === 'pointerup' || event.type === 'pointercancel') {
+      fingerOfPointer.delete(event.pointerId);
+      queue({ phase: 'end', index, position: point });
+      return;
+    }
+    queue({ phase: 'move', index, position: point });
+  };
+
+  /** A client-space event as a point in the design space, via the surface rect
+   *  the host actually presented it at. */
+  const toDesignSpace = (event: PointerEvent, rect: DOMRect): Vector2 => {
+    const x = event.clientX - rect.left;
+    const y = event.clientY - rect.top;
+    if (!designSize) return { x, y };
+    return { x: (x * designSize.x) / rect.width, y: (y * designSize.y) / rect.height };
+  };
+
+  const onPointer = (event: PointerEvent): void => {
+    // The manager's own gate, read from the manager. See this module's header
+    // for why it is not recomposed here.
+    if (!input.isInputActive()) return;
+    const surface = surfaceOf?.() ?? (event.target instanceof HTMLElement ? event.target : null);
+    if (surface === null) return;
+    const rect = surface.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0) return;
+    const point = toDesignSpace(event, rect);
+
+    if (event.type === 'pointermove') {
+      // Every pointer type moves the position — a stylus and a dragging finger
+      // are as much "where the pointer is" as a mouse. Only the TOUCH queue is
+      // touch-only.
+      position = point;
+      surface.style.cursor = cursor;
+    }
+    // A mouse or a pen is not a finger. A control that answered them here would
+    // steal the clicks of a player who cannot see it.
+    if (event.pointerType === 'touch') queueTouch(event, point);
+  };
+
+  const KINDS = ['pointerdown', 'pointermove', 'pointerup', 'pointercancel'] as const;
+  const owner: EventTarget | null =
+    typeof window === 'undefined' ? null : (surfaceOf?.() ?? window);
+  if (owner !== null) {
+    for (const kind of KINDS) owner.addEventListener(kind, onPointer as EventListener);
+  }
+
+  return {
+    getPosition(): Vector2 {
+      return position;
+    },
+    setPosition(next): void {
+      position = { x: next.x, y: next.y };
+    },
+    takeTouches(): readonly HostPointerTouch[] {
+      return touches.splice(0, touches.length);
+    },
+    setCursor(next): void {
+      cursor = next;
+    },
+    dispose(): void {
+      if (owner === null) return;
+      for (const kind of KINDS) owner.removeEventListener(kind, onPointer as EventListener);
+    },
+  };
+}

package/src/input/input-manager.ts

@@ -184,10 +184,16 @@ const INPUT_TRACE_CAP = 2000;
  *     controls. `setTouchButton(sourceId, pressed)` feeds a digital action
  *     (edge-tracked like `mouse_button`); `setTouchStick(sourceId, value)`
  *     feeds a vector2 action (deadzone-rescaled like a gamepad stick). These
- *     are the injectable entry points a real on-screen touch UI's own
- *     touchstart/touchmove/touchend handlers would call — that DOM wiring is
- *     a thin adapter at the edge (browser-verified separately, e.g. F4/e2e);
- *     the mapping logic here is unit-tested headlessly with no DOM.
+ *     are the injectable entry points an on-screen touch UI calls, and they
+ *     are the UPPER half of the touch story. The LOWER half — the DOM
+ *     pointer stream itself, as dense finger indices mapped into the game's
+ *     own design space and gated on `isInputActive()` — is
+ *     `input/host-pointer.ts` (`createHostPointer`), beside this file; a
+ *     control drains its `takeTouches()` and calls the setters above.
+ *     What is deliberately still NOT here is the control layer in between:
+ *     which rect owns which finger, and how a knob's offset becomes a stick
+ *     vector, is the shape of the UI drawing the control, so it belongs to
+ *     that UI and there is no first-party one to generalize from yet.
  *   - Focus gating — `blur`/`focus` on `window` (guarded, real DOM only) now
  *     drop input the same way `setEnabled(false)` does (flushing held
  *     key/mouse/touch-button state) without touching the `enabled` flag the
@@ -428,7 +434,7 @@ export class InputManager {
   // caller never tells `poll()` which tick it's servicing (every existing
   // bare/headless caller — tests, a mount with no `Game` shell behind it —
   // keeps this exact pre-existing behavior, zero regression). The REAL
-  // per-world wiring (`setup-three-root-adapter.ts`) instead passes the
+  // per-world wiring (`world3d-react/r3f-root-factory.tsx`) instead passes the
   // shared `Game`-level tick counter into every `poll(tick)` call — this is
   // deliberate: an InputManager-local counter drifts from the actual game
   // tick for a paused/frozen world (its `poll()` isn't called every game
@@ -461,7 +467,7 @@ export class InputManager {
    *  action}`) emitted whenever a scheduled entry is discarded because its
    *  target tick's input phase never ran. Wired by whoever constructs this
    *  `InputManager` with access to a `DebugRegistry`
-   *  (`setup-three-root-adapter.ts`, the same seed spot as
+   *  (`world3d-react/r3f-root-factory.tsx`, the same seed spot as
    *  `setVirtualInputTarget`/`setInputActionsSource`) — `null` (the
    *  default) for a bare/headless `InputManager`, in which case a drop
    *  stays silent (matching pre-D15/T-D15.5 behavior). */
@@ -787,8 +793,8 @@ export class InputManager {
     }
   }
 
-  /** The names of all registered actions (r3f `world-context` enumerates these
-   *  for its input-binding projection). */
+  /** The names of all registered actions (the `game.input.actions` debug seam
+   *  enumerates these — `runtime/game-input-seams.ts`). */
   actionNames(): string[] {
     return [...this.actions.keys()];
   }
@@ -797,7 +803,7 @@ export class InputManager {
    * Poll gamepads and virtual look stick (call at start of frame).
    *
    * `tick` (D15/T-D15.3/.5) — the GAME tick this call services. Pass the
-   * live, shared `Game` tick counter here (`setup-three-root-adapter.ts` does,
+   * live, shared `Game` tick counter here (`world3d-react/r3f-root-factory.tsx` does,
    * via `DebugRegistry.getGameTick()`) so `scheduleActionAtTick`'s numbering
    * never drifts from the actual game tick — the bug an earlier revision of
    * this feature had: an InputManager-LOCAL counter, incremented once per
@@ -1691,6 +1697,22 @@ export class InputManager {
     return this.focused;
   }
 
+  /**
+   * The gate every REAL-DEVICE listener here passes: {@link isEnabled} AND
+   * {@link isFocused}. Public because the DOM edge this class deliberately
+   * does not own — `host-pointer.ts`, the pointer stream behind the touch
+   * backends — must pass the SAME gate, and a caller writing
+   * `isEnabled() && isFocused()` out for itself is how a looser one drifts in
+   * (a pointer adapter that checked only `isEnabled` kept updating position
+   * for a blurred tab). Read it; do not recompose it.
+   *
+   * Machine input (`setVirtualAction` and the tick-scheduled actuations) is
+   * deliberately NOT this gate — see `machineInputActive`.
+   */
+  isInputActive(): boolean {
+    return this.inputActive;
+  }
+
   /** Whether the pointer is currently locked to {@link requestPointerLock}'s
    *  element (F2, spec §12 "pointer lock") — tracked via the real
    *  `pointerlockchange` event. */
@@ -2167,12 +2189,11 @@ export class InputManager {
   }
 
   // ==========================================================================
-  // Task 1.4 — action-level virtual input for a synthetic player. Promoted from
-  // hollowstone's proven `VirtualInput` (`bot/virtual-input.ts`): a bot drives
+  // Action-level virtual input for a synthetic player: a bot drives
   // NAMED ACTIONS (not raw devices), and its contributions join action
   // resolution at exactly the same points binding contributions do (see
   // isPressed/isJustPressed and collectScalarContributions/
-  // collectVector2Contributions above). #144 split the gates: virtual input
+  // collectVector2Contributions above). The gates are split: virtual input
   // passes `machineInputActive` (the editor's `enabled` flag only), while
   // human input keeps the full `inputActive` (enabled AND focused) gate — a
   // synthetic player must keep playing the shared editor tab while the
@@ -2380,7 +2401,7 @@ export class InputManager {
    *  `'input.schedule.dropped'` (`{tick, action}`) whenever it discards a
    *  scheduled entry for a tick whose input phase never ran. Called once by
    *  whoever constructs this `InputManager` with a `DebugRegistry` behind it
-   *  (`setup-three-root-adapter.ts`), the same seed spot as
+   *  (`world3d-react/r3f-root-factory.tsx`), the same seed spot as
    *  `setVirtualInputTarget`/`setInputActionsSource` — never called directly
    *  by gameplay code. */
   setDebugEmit(fn: ((event: string, detail?: unknown) => void) | null): void {

package/src/input/input-types.ts

@@ -128,7 +128,7 @@ export interface InputMapFile {
 // types. See input-manager.ts's class doc comment for the full design note;
 // these are the plain data shapes shared between `InputManager`'s rebinding
 // API, the framework-free `RebindController` (rebind-controller.ts), and any
-// UI (e.g. the template's `RebindPanel.tsx`) that surfaces them.
+// UI that surfaces them.
 // =============================================================================
 
 /**

package/src/input/rebind-controller.ts

@@ -1,11 +1,9 @@
-// F3 (spec §12 "Add Rebinding and Prompts") — a framework-free rebinding
-// STATE MACHINE over an `InputManager`. Deliberately has no dependency on
-// React (or any UI library): "listen for the next input, surface a conflict,
-// let the caller decide" is the same flow whether the caller is the
-// template's `RebindPanel.tsx` (ordinary React, see that file) or any other
-// UI/CLI. Keeping the logic here means it's unit-testable with no DOM/JSX at
-// all, and the React component becomes a thin, mechanically-verifiable
-// wrapper (see the template component's own doc comment).
+// A framework-free rebinding STATE MACHINE over an `InputManager`.
+// Deliberately has no dependency on React (or any UI library): "listen for the
+// next input, surface a conflict, let the caller decide" is the same flow
+// whether the caller is a React panel or a CLI. Keeping the logic here makes
+// it unit-testable with no DOM/JSX at all, and leaves any UI a thin,
+// mechanically-verifiable wrapper.
 //
 // Flow: `listen(actionName)` -> caller captures the next raw input event
 // itself (a keydown, a gamepad poll, a touch tap — capture is inherently