@vgai/engine 0.2.0 → 0.3.0

package/src/input/input-types.ts

@@ -1,14 +1,116 @@
-/** A single binding for an action */
+/**
+ * A single binding for an action.
+ *
+ * F2 (spec §12 "Complete Device Backends") un-rejects `mouse_move` and
+ * `gamepad_axis_pair` — both now have real `InputManager` readers (see that
+ * file's `collectPointerDeltaContributions`/`collectVector2Contributions`):
+ *  - `mouse_move` feeds a `'pointerDelta'`-valueType action with the raw
+ *    accumulated mouse delta (no deadzone — deltas are not deadzoned, same
+ *    rule as `test_pointer_delta`), and can ALSO feed a `'vector2'`-valueType
+ *    action (the same delta, radial-deadzoned + unit-circle-clamped via
+ *    `deadzone`) — e.g. an alternative look control. It does not feed a
+ *    `'scalar'` action (no natural single-axis-select field is defined; add
+ *    one if a real use case needs it).
+ *  - `gamepad_axis_pair` feeds a `'vector2'`-valueType action with the
+ *    coupled `(xAxis, yAxis)` reading, radial-deadzoned the same way a real
+ *    analog stick is (default deadzone 0.15, matching `gamepad_axis`).
+ *
+ * F2 also adds `touch_button`/`touch_stick` below — the touch/virtual-control
+ * backend. Both are driven by `InputManager.setTouchButton`/`setTouchStick`
+ * (the injectable entry points a touch-control UI's own touchstart/
+ * touchmove/touchend handlers call — that DOM wiring is a thin adapter at
+ * the edge, browser-verified separately; the MAPPING here is unit-tested
+ * headlessly with no DOM). `sourceId` names the virtual control (a zone/
+ * knob id chosen by the touch UI), reusing the same field `test_*` bindings
+ * use for their named source — not a real device index.
+ */
 export type InputBinding =
   | { type: 'key'; code: string }
   | { type: 'mouse_button'; button: number }
-  | { type: 'mouse_move' }
+  | { type: 'mouse_move'; deadzone?: number }
   | { type: 'gamepad_button'; button: number }
   | { type: 'gamepad_axis'; axis: number; direction: 'positive' | 'negative'; deadzone?: number }
-  | { type: 'gamepad_axis_pair'; xAxis: number; yAxis: number; deadzone?: number };
+  | { type: 'gamepad_axis_pair'; xAxis: number; yAxis: number; deadzone?: number }
+  // F1 (spec §12) — the "injected test input" backend named in F2's acceptance criteria,
+  // built here as the typed value model's testable source (see input-manager.ts's
+  // injectAxis/injectVector2/injectPointerDelta/injectPointerPosition). Each is keyed by a
+  // caller-chosen `sourceId` (not a real device index) so tests can push synthetic raw values
+  // through the exact same aggregation/deadzone/combine path real device backends will use.
+  | { type: 'test_axis'; sourceId: string; deadzone?: number }
+  | { type: 'test_vector2'; sourceId: string; deadzone?: number }
+  | { type: 'test_pointer_delta'; sourceId: string }
+  | { type: 'test_pointer_position'; sourceId: string }
+  // F2 (spec §12) — touch/virtual controls. `touch_button` is digital (edge-
+  // tracked just like `mouse_button`); `touch_stick` is a `'vector2'`-valueType
+  // analog control (radial-deadzoned like a gamepad stick). See input-manager.ts's
+  // setTouchButton/setTouchStick.
+  | { type: 'touch_button'; sourceId: string }
+  | { type: 'touch_stick'; sourceId: string; deadzone?: number };
+
+/**
+ * The value shape an action carries (F1, spec §12 "Define Typed Action Values"):
+ *  - `'digital'` — boolean, with pressed/justPressed/justReleased edges (InputManager.isPressed
+ *    et al.). The default when an action omits `valueType` — every action authored before F1
+ *    is a digital action, so this stays backward compatible.
+ *  - `'scalar'` — a single float axis (InputManager.getScalar), e.g. a throttle or a single
+ *    thumbstick axis.
+ *  - `'vector2'` — a {x,y} axis pair (InputManager.getVector2), e.g. movement/look.
+ *  - `'pointerDelta'` — a {x,y} per-frame movement delta (InputManager.getPointerDelta),
+ *    summed across contributing sources, cleared every frame (mirrors the existing
+ *    mouseDeltaX/Y accumulator's per-frame-reset shape).
+ *  - `'pointerPosition'` — a {x,y} absolute position (InputManager.getPointerPosition),
+ *    last-write-wins across contributing sources (position isn't additive).
+ */
+export type ActionValueType = 'digital' | 'scalar' | 'vector2' | 'pointerDelta' | 'pointerPosition';
+
+/** A plain 2D vector — the shared shape for Vector2 axis pairs, pointer delta, and pointer
+ *  position action values (F1). */
+export interface Vector2 {
+  x: number;
+  y: number;
+}
+
+/**
+ * Maps an `ActionValueType` to its TS read type. This is the "no `any`" backbone behind
+ * `InputManager.readAction` (and, informally, behind each dedicated typed getter returning a
+ * concrete, non-`any` type): given a value type known at the call site (a literal, or a type
+ * parameter inferred from a caller's own action-value-type map), the return type is exact.
+ */
+export type ActionValueOf<T extends ActionValueType> = T extends 'digital'
+  ? boolean
+  : T extends 'scalar'
+    ? number
+    : T extends 'vector2' | 'pointerDelta' | 'pointerPosition'
+      ? Vector2
+      : never;
+
+/**
+ * Device/source metadata (F1 AC): which binding — and, for gamepad bindings, which connected
+ * gamepad, or for injected test bindings, which named source — produced an action's current
+ * value. Returned by the `*Source` sibling of each typed getter (e.g. `getScalarSource`).
+ */
+export interface ActionValueSource {
+  /** The binding kind that produced the current value. */
+  bindingType: InputBinding['type'];
+  /** Present for `test_axis`/`test_vector2`/`test_pointer_delta`/`test_pointer_position`/
+   *  `touch_button`/`touch_stick` bindings — the caller-chosen source id passed to the
+   *  matching `inject*`/`setTouch*` call (F2 reuses this same field for named touch zones,
+   *  not a real device index). */
+  sourceId?: string;
+  /** Present for `gamepad_button`/`gamepad_axis`/`gamepad_axis_pair` (F2) bindings — the
+   *  index into `navigator.getGamepads()` of the gamepad that produced the value. */
+  gamepadIndex?: number;
+  /** F2 — present alongside `gamepadIndex` for `gamepad_button`/`gamepad_axis`/
+   *  `gamepad_axis_pair` bindings: the connected gamepad's `Gamepad.id` (device identity,
+   *  spec §12 F2 "expose device identity"), e.g. a vendor/product string. */
+  gamepadId?: string;
+}
 
 /** An action has a name and one or more bindings */
 export interface InputAction {
+  /** Declares this action's value shape (F1). Optional — defaults to `'digital'`, matching
+   *  every action authored before F1. See `ActionValueType` for the full set. */
+  valueType?: ActionValueType;
   bindings: InputBinding[];
 }
 
@@ -17,3 +119,53 @@ export interface InputMapFile {
   version: number;
   actions: Record<string, InputAction>;
 }
+
+// =============================================================================
+// F3 (spec §12 "Add Rebinding and Prompts") — rebinding + conflict + prompt
+// 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.
+// =============================================================================
+
+/**
+ * A structural conflict returned by `InputManager.findConflicts` (F3 AC
+ * "Conflicts are detected and returned structurally"): a proposed binding
+ * would collide with an EXISTING binding already registered on a different
+ * action. Never thrown — always a plain data array the caller (typically a
+ * rebinding UI) inspects and decides what to do with (block, warn, or let the
+ * user override).
+ */
+export interface BindingConflict {
+  /** The other action whose existing binding collides with the proposed one. */
+  actionName: string;
+  /** That action's bindings-array index the collision was found at (stable
+   *  enough to pass straight to `removeBinding`/`replaceBinding` if the UI
+   *  offers "steal this binding"). */
+  bindingIndex: number;
+  /** The colliding binding itself. */
+  binding: InputBinding;
+}
+
+/**
+ * The coarse input-device family a prompt is being requested for (F3 AC "a
+ * current-device prompt API"). Keyboard and mouse are kept distinct — a
+ * binding list frequently carries one of each (e.g. `key` for movement,
+ * `mouse_button` for fire) and a prompt UI usually wants to show whichever
+ * one is bound, not conflate the two.
+ */
+export type PromptDevice = 'keyboard' | 'mouse' | 'gamepad' | 'touch';
+
+/**
+ * The resolved display prompt for one action's binding on a given device
+ * family (F3 AC: "resolves labels/icons such as `Space`, `A`, or a touch
+ * control"). `icon` is a short glyph/name a UI can look up in its own icon
+ * set (for keyboard it's the same short label; for gamepad it's the
+ * canonical button/glyph name, e.g. `'A'`; the UI decides how to render it).
+ */
+export interface BindingPrompt {
+  device: PromptDevice;
+  bindingType: InputBinding['type'];
+  label: string;
+  icon: string;
+}

package/src/input/prompt-labels.ts

@@ -0,0 +1,122 @@
+// F3 (spec §12 "Add Rebinding and Prompts") — the device->label map behind
+// `InputManager.getPrompt`. Pure data + pure functions, no InputManager
+// dependency, so it's independently unit-testable and reusable by a
+// rebinding UI that wants to render a label without going through a live
+// InputManager instance (e.g. previewing a not-yet-applied binding).
+//
+// Labels intentionally favor short, conventional display strings over exact
+// spec names (`'Ctrl'` not `'ControlLeft'`, `'A'` not `'button-0'`) — this is
+// what a HUD prompt or rebinding list actually renders.
+
+import type { InputBinding, PromptDevice } from './input-types';
+
+/** `KeyboardEvent.code` values with a friendlier display label than the raw
+ *  code string. Anything not listed here falls through to `keyLabel`'s
+ *  `Key*`/`Digit*` stripping, or the raw code as a last resort. */
+const KEY_LABELS: Record<string, string> = {
+  Space: 'Space',
+  Escape: 'Esc',
+  Enter: 'Enter',
+  NumpadEnter: 'Enter',
+  Tab: 'Tab',
+  Backspace: 'Backspace',
+  CapsLock: 'Caps Lock',
+  ArrowUp: '↑',
+  ArrowDown: '↓',
+  ArrowLeft: '←',
+  ArrowRight: '→',
+  ShiftLeft: 'Shift',
+  ShiftRight: 'Shift',
+  ControlLeft: 'Ctrl',
+  ControlRight: 'Ctrl',
+  AltLeft: 'Alt',
+  AltRight: 'Alt',
+  MetaLeft: 'Meta',
+  MetaRight: 'Meta',
+};
+
+/** Display label for a `KeyboardEvent.code` (F3 AC example: `'Space'`). */
+export function keyLabel(code: string): string {
+  const known = KEY_LABELS[code];
+  if (known) return known;
+  if (code.startsWith('Key') && code.length === 4) return code.slice(3); // KeyW -> W
+  if (code.startsWith('Digit') && code.length === 6) return code.slice(5); // Digit1 -> 1
+  if (code.startsWith('Numpad')) return `Num ${code.slice(6)}`;
+  if (code.startsWith('F') && /^F\d+$/.test(code)) return code; // F1..F12 already short
+  return code;
+}
+
+const MOUSE_BUTTON_LABELS: Record<number, string> = {
+  0: 'Left Click',
+  1: 'Middle Click',
+  2: 'Right Click',
+  3: 'Mouse 4',
+  4: 'Mouse 5',
+};
+
+/** Display label for a `MouseEvent.button` index. */
+export function mouseButtonLabel(button: number): string {
+  return MOUSE_BUTTON_LABELS[button] ?? `Mouse ${button}`;
+}
+
+/** W3C Standard Gamepad button-index -> conventional face-button glyph name
+ *  (F3 AC example: `'A'`). Only meaningful when `Gamepad.mapping === 'standard'`
+ *  — see `InputManager.getPrompt`, which falls back to a raw index label when
+ *  the connected pad doesn't report the standard mapping. */
+export const STANDARD_GAMEPAD_BUTTON_LABELS: Record<number, string> = {
+  0: 'A',
+  1: 'B',
+  2: 'X',
+  3: 'Y',
+  4: 'LB',
+  5: 'RB',
+  6: 'LT',
+  7: 'RT',
+  8: 'Back',
+  9: 'Start',
+  10: 'L3',
+  11: 'R3',
+  12: 'D-Up',
+  13: 'D-Down',
+  14: 'D-Left',
+  15: 'D-Right',
+  16: 'Home',
+};
+
+/** Display label for a single standard-mapping gamepad axis (a `gamepad_axis`
+ *  binding — one half of a stick, or a trigger). */
+export function gamepadAxisLabel(axis: number): string {
+  if (axis === 0 || axis === 1) return 'Left Stick';
+  if (axis === 2 || axis === 3) return 'Right Stick';
+  return `Axis ${axis}`;
+}
+
+/** Display label for a coupled `gamepad_axis_pair` binding. */
+export function gamepadAxisPairLabel(xAxis: number, yAxis: number): string {
+  if (xAxis === 0 && yAxis === 1) return 'Left Stick';
+  if (xAxis === 2 && yAxis === 3) return 'Right Stick';
+  return `Axis ${xAxis}/${yAxis}`;
+}
+
+/** Which `PromptDevice` family a binding kind belongs to, or `null` for a
+ *  binding kind with no real physical device (the synthetic `test_*` kinds —
+ *  they're an injected-test-input source, never something to prompt a player
+ *  about). */
+export function bindingDeviceFamily(type: InputBinding['type']): PromptDevice | null {
+  switch (type) {
+    case 'key':
+      return 'keyboard';
+    case 'mouse_button':
+    case 'mouse_move':
+      return 'mouse';
+    case 'gamepad_button':
+    case 'gamepad_axis':
+    case 'gamepad_axis_pair':
+      return 'gamepad';
+    case 'touch_button':
+    case 'touch_stick':
+      return 'touch';
+    default:
+      return null;
+  }
+}

package/src/input/rebind-controller.ts

@@ -0,0 +1,105 @@
+// 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).
+//
+// Flow: `listen(actionName)` -> caller captures the next raw input event
+// itself (a keydown, a gamepad poll, a touch tap — capture is inherently
+// device-specific and NOT this class's job) and turns it into an
+// `InputBinding`, then calls `capture(binding)`. If the proposed binding is
+// free, it's applied immediately and the state becomes `'applied'`. If it
+// collides with another action's existing binding (per
+// `InputManager.findConflicts`), the state becomes `'conflict'`, carrying the
+// structured conflict list for the UI to show — the caller then calls either
+// `resolveOverride()` (apply anyway) or `cancel()`.
+
+import type { InputManager } from './input-manager';
+import type { BindingConflict, InputBinding } from './input-types';
+
+/** How a captured binding is applied once accepted. */
+export type RebindMode = 'replace' | 'add';
+
+export type RebindState =
+  | { status: 'idle' }
+  | { status: 'listening'; actionName: string; mode: RebindMode; index: number }
+  | {
+      status: 'conflict';
+      actionName: string;
+      mode: RebindMode;
+      index: number;
+      proposed: InputBinding;
+      conflicts: BindingConflict[];
+    }
+  | { status: 'applied'; actionName: string; binding: InputBinding };
+
+export class RebindController {
+  private state: RebindState = { status: 'idle' };
+
+  constructor(private readonly input: InputManager) {}
+
+  getState(): RebindState {
+    return this.state;
+  }
+
+  /**
+   * Enter listening mode for `actionName`. `mode: 'replace'` (default)
+   * rebinds the slot at `index` (default 0 — the action's first/primary
+   * binding); `mode: 'add'` appends a new binding alongside the existing
+   * ones instead (`index` is ignored for `'add'`).
+   */
+  listen(actionName: string, mode: RebindMode = 'replace', index = 0): void {
+    this.state = { status: 'listening', actionName, mode, index };
+  }
+
+  /** Abandon listening/a pending conflict with no changes applied. */
+  cancel(): void {
+    this.state = { status: 'idle' };
+  }
+
+  /**
+   * Feed a captured raw `InputBinding` while in the `'listening'` state
+   * (a no-op returning the current state unchanged otherwise — e.g. a stray
+   * keypress arriving after the UI already cancelled). Checks
+   * `InputManager.findConflicts` first: a free binding is applied
+   * immediately (-> `'applied'`); a colliding one transitions to
+   * `'conflict'` instead of applying, so the UI can surface it before
+   * anything changes.
+   */
+  capture(binding: InputBinding): RebindState {
+    if (this.state.status !== 'listening') return this.state;
+    const { actionName, mode, index } = this.state;
+    const conflicts = this.input.findConflicts(binding, actionName);
+    if (conflicts.length > 0) {
+      this.state = { status: 'conflict', actionName, mode, index, proposed: binding, conflicts };
+      return this.state;
+    }
+    this.apply(actionName, mode, index, binding);
+    this.state = { status: 'applied', actionName, binding };
+    return this.state;
+  }
+
+  /**
+   * From a `'conflict'` state, apply the pending proposed binding anyway
+   * (the UI decided the collision is acceptable, e.g. "steal this binding").
+   * Does NOT remove the colliding binding from the other action — that is a
+   * separate, explicit `InputManager.removeBinding` call the UI can make
+   * first if it wants a true swap. A no-op (returns current state) unless a
+   * conflict is pending.
+   */
+  resolveOverride(): RebindState {
+    if (this.state.status !== 'conflict') return this.state;
+    const { actionName, mode, index, proposed } = this.state;
+    this.apply(actionName, mode, index, proposed);
+    this.state = { status: 'applied', actionName, binding: proposed };
+    return this.state;
+  }
+
+  private apply(actionName: string, mode: RebindMode, index: number, binding: InputBinding): void {
+    if (mode === 'add') this.input.addBinding(actionName, binding);
+    else this.input.replaceBinding(actionName, index, binding);
+  }
+}