@driftengine/core 3.61.0

package/src/input/inputHarness.ts

@@ -0,0 +1,226 @@
+import {
+  AXIS_INDEX,
+  BUTTON_INDEX,
+  type GamepadAxis,
+  type GamepadButton,
+} from './gamepadMapping.ts';
+
+/**
+ * A browser with a controller in it, for tests that need `InputSource` and not a machine.
+ *
+ * **Not a `.test.ts` file, and that is the point.** Vitest registers a test when the file
+ * declaring it is imported, so a second test file importing this from beside its own tests would
+ * re-run every test in that file as well. Split out for the same reason `rendererHarness.ts` is.
+ *
+ * **This character has no DOM at all** — the vitest environment is `node`, because what this
+ * repository tests is simulation rather than pages. `input.test.ts` already stubbed `window` and
+ * `document` on `globalThis` by hand; this generalises that and adds a `navigator` with a pad
+ * behind it.
+ *
+ * **`requestAnimationFrame` is a queue this drives rather than a clock.** The poll runs on a frame
+ * callback, and a test that waited for a real one would be slow and would sometimes fail. `frame()`
+ * runs exactly one, so a test states how many frames happened instead of hoping.
+ *
+ * `restore()` puts back whatever was there, and a test must call it in a `finally`: leaking a fake
+ * `window` into the next file is a failure that reads as the next file's bug.
+ */
+
+interface FakeButton {
+  pressed: boolean;
+  value: number;
+}
+
+export function fakeBrowser(id = 'Xbox 360 Controller (XInput STANDARD GAMEPAD)') {
+  const buttons: FakeButton[] = Array.from({ length: 17 }, () => ({ pressed: false, value: 0 }));
+  const axes: number[] = [0, 0, 0, 0];
+  let connected = false;
+  let mapping = 'standard';
+  let padId = id;
+
+  /**
+   * A fresh array every call, and fresh button objects behind it — **because the real one does
+   * that too**, and the poll's whole design rests on it. A harness that handed back the same array
+   * would let a renderer read it many times a frame and never show the cost.
+   */
+  const calls = { getGamepads: 0 };
+
+  /**
+   * The rumble half, recorded rather than felt.
+   *
+   * **A haptic effect has no observable result in a test**, which is exactly why the surface answers
+   * a boolean rather than nothing: what can be asserted is whether the platform took the call and
+   * what it was handed. So the effects are recorded here and the tests read them.
+   *
+   * `hasActuator` is a switch rather than a fixture, because the capability under test is largely
+   * the *refusal*: most pads on most browsers cannot rumble, and a settings screen has to know.
+   */
+  const effects: { type: string; params: Record<string, number> }[] = [];
+  let resets = 0;
+  let hasActuator = true;
+  let hasReset = true;
+  let failEffect = false;
+
+  const actuator = {
+    playEffect: (type: string, params: Record<string, number>): Promise<string> => {
+      effects.push({ type, params: { ...params } });
+      return failEffect
+        ? Promise.reject(new Error('the pad went away'))
+        : Promise.resolve('complete');
+    },
+    reset: (): Promise<string> => {
+      resets += 1;
+      return Promise.resolve('complete');
+    },
+  };
+
+  const getGamepads = (): (object | null)[] => {
+    calls.getGamepads += 1;
+    if (!connected) return [null];
+    return [
+      {
+        id: padId,
+        index: 0,
+        mapping,
+        connected: true,
+        buttons: buttons.map((b) => ({ pressed: b.pressed, value: b.value })),
+        axes: axes.slice(),
+        vibrationActuator: hasActuator
+          ? hasReset
+            ? actuator
+            : { playEffect: actuator.playEffect }
+          : null,
+      },
+    ];
+  };
+
+  const frameCallbacks: ((time: number) => void)[] = [];
+  let nextFrameHandle = 1;
+
+  const target = {
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    requestPointerLock: () => undefined,
+    getBoundingClientRect: () => ({ left: 0, top: 0, width: 640, height: 480 }),
+  } as unknown as HTMLElement;
+
+  const globals = globalThis as unknown as Record<string, unknown>;
+  const had: Record<string, { present: boolean; value: unknown }> = {};
+  const install = (name: string, value: unknown): void => {
+    had[name] = { present: name in globals, value: globals[name] };
+    /* `defineProperty` rather than assignment: `navigator` is a getter on the Node global and
+       assigning to it is silently ignored, which would leave the poll reading the real one. */
+    Object.defineProperty(globals, name, { value, configurable: true, writable: true });
+  };
+
+  /** Window listeners this harness can fire, so a key is a statement rather than a real event. */
+  const windowListeners = new Map<string, ((event: unknown) => void)[]>();
+  install('window', {
+    matchMedia: () => ({ matches: false }),
+    addEventListener: (type: string, fn: (event: unknown) => void) => {
+      const existing = windowListeners.get(type);
+      if (existing === undefined) windowListeners.set(type, [fn]);
+      else existing.push(fn);
+    },
+    removeEventListener: (type: string, fn: (event: unknown) => void) => {
+      const existing = windowListeners.get(type);
+      if (existing === undefined) return;
+      const at = existing.indexOf(fn);
+      if (at >= 0) existing.splice(at, 1);
+    },
+  });
+  install('document', {
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    pointerLockElement: null,
+    visibilityState: 'visible',
+  });
+  install('navigator', { getGamepads });
+  install('requestAnimationFrame', (fn: (time: number) => void) => {
+    frameCallbacks.push(fn);
+    return nextFrameHandle++;
+  });
+  install('cancelAnimationFrame', () => {});
+
+  const indexOfButton = (button: GamepadButton): number => BUTTON_INDEX[button];
+
+  return {
+    target,
+    /**
+     * How many times the poll asked the browser for pads.
+     *
+     * The number the once-a-frame rule is asserted on: `getGamepads` allocates an array and the
+     * objects behind it, so a read that called it again would multiply that by however many
+     * buttons a frame looks at.
+     */
+    calls,
+    /** Every effect the poll's pad was asked to play, in order, with the parameters it was given. */
+    effects,
+    /** How many times the actuator was reset, which is what stopping a rumble does. */
+    get resets(): number {
+      return resets;
+    },
+    /**
+     * Whether this pad carries an actuator, and whether that actuator carries `reset`.
+     *
+     * Both are real states a browser produces: a keyboard-shaped pad has no actuator at all, and an
+     * older Chromium's actuator has `playEffect` without `reset`.
+     */
+    rumbleSupport(present: boolean, options: { reset?: boolean; fail?: boolean } = {}): void {
+      hasActuator = present;
+      hasReset = options.reset ?? true;
+      failEffect = options.fail ?? false;
+    },
+    connect(nextId = padId, nextMapping = 'standard'): void {
+      padId = nextId;
+      mapping = nextMapping;
+      connected = true;
+    },
+    disconnect(): void {
+      connected = false;
+    },
+    press(button: GamepadButton): void {
+      const at = buttons[indexOfButton(button)];
+      if (at !== undefined) {
+        at.pressed = true;
+        at.value = 1;
+      }
+    },
+    release(button: GamepadButton): void {
+      const at = buttons[indexOfButton(button)];
+      if (at !== undefined) {
+        at.pressed = false;
+        at.value = 0;
+      }
+    },
+    axis(axis: GamepadAxis, value: number): void {
+      axes[AXIS_INDEX[axis]] = value;
+    },
+    /** Press a key, as the window would deliver it. `target` is nothing a game is typing into. */
+    keyDown(code: string): void {
+      for (const fn of windowListeners.get('keydown') ?? []) {
+        fn({ code, repeat: false, target: null, preventDefault: () => {} });
+      }
+    },
+    keyUp(code: string): void {
+      for (const fn of windowListeners.get('keyup') ?? []) fn({ code });
+    },
+    /** Run exactly one animation frame, which is what a poll rides on. */
+    frame(): void {
+      const pending = frameCallbacks.splice(0, frameCallbacks.length);
+      for (const fn of pending) fn(0);
+    },
+    restore(): void {
+      for (const [name, before] of Object.entries(had)) {
+        if (before.present) {
+          Object.defineProperty(globals, name, {
+            value: before.value,
+            configurable: true,
+            writable: true,
+          });
+        } else {
+          delete globals[name];
+        }
+      }
+    },
+  };
+}

package/src/input/rightGesture.ts

@@ -0,0 +1,76 @@
+/**
+ * What a drag on the look zone turns out to be.
+ *
+ * Separated from `TouchControls` because it is the one part of touch handling
+ * with a right answer that can be checked without a device: everything else is
+ * DOM plumbing, but this is a classification, and getting it wrong silently
+ * removes a control rather than breaking one visibly.
+ */
+export type RightGesture = 'pending' | 'look' | 'secondary';
+
+export interface RightGestureOptions {
+  /** Travel before a drag is classified at all, pixels. */
+  gestureMovePx: number;
+  /** A flick has to finish inside this to count as one, milliseconds. */
+  swipeMaxMs: number;
+  /** Vertical travel over horizontal required to read as a deliberate flick. */
+  swipeDominance: number;
+}
+
+/**
+ * Classify a drag from its travel and duration.
+ *
+ * The bias is deliberate and one-way: **when in doubt, it is a look.** Looking
+ * is continuous and constant, the secondary flick is occasional, and the two
+ * failure modes are not equal — a missed flick costs one slide, while a look
+ * wrongly eaten costs the camera for the whole gesture, which is felt as the
+ * controls being broken rather than as a missed input.
+ *
+ * That asymmetry is exactly what went wrong: any quick downward drag was read
+ * as a flick, so trying to look *down* quickly did not move the camera at all.
+ * Looking left and right stayed fine, because no gesture competes for it.
+ */
+export function classifyRightGesture(
+  dx: number,
+  dy: number,
+  elapsedMs: number,
+  options: RightGestureOptions,
+): RightGesture {
+  if (Math.hypot(dx, dy) < options.gestureMovePx) return 'pending';
+  const quick = elapsedMs < options.swipeMaxMs;
+  // Downward only, and steeply so: dy is positive toward the bottom of the
+  // screen, and a flick that is merely mostly-down is far likelier to be
+  // somebody looking at the ground.
+  if (quick && dy > 0 && dy > options.swipeDominance * Math.abs(dx)) return 'secondary';
+  return 'look';
+}
+
+/**
+ * Whether a released touch was a tap, and therefore fires the primary.
+ *
+ * Stated as its own rule because getting it wrong is how the primary went
+ * missing. The press used to be queued only for a touch still *unresolved* at
+ * release — but a motionless touch is promoted to the held form after
+ * `holdResolveMs`, which the caller runs on a frame clock, so every tap longer
+ * than that resolve was discarded. On a phone that is most of them: a
+ * comfortable tap is 80 to 150 ms against a 90 ms resolve, which is exactly the
+ * shape of *"sometimes the jump is missed."*
+ *
+ * So a tap is defined by what it *did*, not by which state it happened to be
+ * parked in: it stayed inside `gestureMovePx` of where it landed and it was
+ * short. A touch that travelled further has already been read as a look or a
+ * flick and did its work there; firing a press on its release as well would put
+ * a jump on the end of every camera drag, which is the complaint this scheme
+ * was built to fix.
+ *
+ * `travelPx` is the *greatest* distance reached from the start, not the
+ * distance at release: a thumb that swings out and returns is not a tap, and
+ * measuring only the final point cannot tell the two apart.
+ */
+export function isTapRelease(
+  travelPx: number,
+  durationMs: number,
+  options: { gestureMovePx: number; tapMaxMs: number },
+): boolean {
+  return travelPx <= options.gestureMovePx && durationMs < options.tapMaxMs;
+}

package/src/input/rumble.ts

@@ -0,0 +1,138 @@
+/**
+ * Driving a controller's motors, and saying so when the platform cannot.
+ *
+ * **The refusal is half the capability.** Most pads on most browsers have no actuator at all, and a
+ * settings screen that offers a rumble slider a player's hardware ignores is worse than one that
+ * greys it out. So every verb here answers a boolean — the same rule the host seam keeps for a
+ * window mode a shell cannot enter — rather than accepting the call and doing nothing quietly.
+ *
+ * **The engine takes durations and magnitudes, and nothing else.** A magnitude is a fraction of a
+ * motor and a duration is milliseconds; what a rumble *means* is the consumer's. There is no
+ * pattern language, no named effect and no curve, because every one of those would be a decision
+ * about what a game does with the hardware.
+ *
+ * ## What this reaches, and what it does not
+ *
+ * `GamepadHapticActuator.playEffect('dual-rumble', …)` and nothing else. Two motors of different
+ * masses, which is what a standard pad has: `strong` is the low-frequency one and `weak` the
+ * high-frequency one.
+ *
+ * **`hapticActuators[].pulse` is not used, on purpose.** It is a non-standard surface with a
+ * different model — one magnitude where this has two — so serving it would mean either dropping
+ * the weak motor or averaging the pair, and both are a silent lie about what the caller asked for.
+ * A platform with only `pulse` answers `false` and is greyed out, which is true rather than
+ * convenient. **What would make that wrong** is a measurement on a browser a consumer actually
+ * ships to where `pulse` exists and `vibrationActuator` does not.
+ *
+ * **Trigger rumble is not reached either.** `'trigger-rumble'` drives two more motors that only
+ * some pads have, so it needs its own capability answer beside `canRumble` rather than riding this
+ * one; it is a row of its own the day somebody wants it.
+ */
+
+/**
+ * The actuator, named here so this file does not depend on lib.dom's version of it.
+ *
+ * `reset` is optional because an older Chromium ships `playEffect` without it, and a pad that can
+ * play an effect can always be stopped by a zero one — which is what `stopRumble` falls back to.
+ */
+export interface RawHapticActuator {
+  playEffect(type: string, params: Readonly<Record<string, number>>): Promise<string>;
+  reset?(): Promise<string>;
+}
+
+/**
+ * The specification's ceiling on one effect, in milliseconds.
+ *
+ * Clamped here rather than left to the platform, because a longer request is not an error the
+ * caller can see: the promise resolves with a word nobody reads, and browsers differ on whether
+ * they clamp it or drop it. A caller wanting a longer rumble re-issues, which it has to anyway —
+ * any effect can be preempted by the next one.
+ */
+export const MAX_RUMBLE_MS = 5000;
+
+/**
+ * The parameters, claimed once.
+ *
+ * `playEffect` converts this to a dictionary synchronously at the call, so one object rewritten in
+ * place is safe and is what the hot-path rule asks for even though a rumble is an event rather
+ * than a frame.
+ */
+const params: Record<string, number> = {
+  duration: 0,
+  startDelay: 0,
+  strongMagnitude: 0,
+  weakMagnitude: 0,
+};
+
+function clamp01(value: number): number {
+  if (!(value > 0)) return 0;
+  return value > 1 ? 1 : value;
+}
+
+/**
+ * Play one dual-rumble effect. Answers whether the platform took it.
+ *
+ * `false` means the caller should stop offering the control, and it is answered for three separate
+ * states that are one thing to a player: no actuator, an actuator this browser cannot drive, and a
+ * duration there is nothing to play for.
+ *
+ * A rejection is swallowed and reported through `onFailure`, once per pad. `playEffect` rejects
+ * when the pad goes away mid-effect, which is a thing a player does with a cable; an unhandled
+ * rejection is a stack trace nobody can act on, and silence leaves a player whose pad stopped
+ * rumbling with nothing to read. **This never throws**, because it is reachable from a frame.
+ */
+export function playRumble(
+  actuator: RawHapticActuator | null,
+  durationMs: number,
+  strong: number,
+  weak: number,
+  onFailure: () => void,
+): boolean {
+  if (actuator === null || typeof actuator.playEffect !== 'function') return false;
+  if (!(durationMs > 0)) return false;
+
+  params.duration = durationMs > MAX_RUMBLE_MS ? MAX_RUMBLE_MS : durationMs;
+  params.strongMagnitude = clamp01(strong);
+  params.weakMagnitude = clamp01(weak);
+  return dispatch(actuator, onFailure);
+}
+
+/**
+ * Stop whatever is playing. Answers whether the platform took it.
+ *
+ * `reset` where the actuator has one, and a zero effect where it does not — a zero-magnitude,
+ * zero-duration effect preempts the one in flight, which is the same result by the specification's
+ * own rule about preemption. Answering `false` for a missing `reset` would grey out a control the
+ * hardware can honour.
+ */
+export function stopRumble(actuator: RawHapticActuator | null, onFailure: () => void): boolean {
+  if (actuator === null || typeof actuator.playEffect !== 'function') return false;
+  if (typeof actuator.reset === 'function') {
+    swallow(actuator.reset(), onFailure);
+    return true;
+  }
+  params.duration = 0;
+  params.strongMagnitude = 0;
+  params.weakMagnitude = 0;
+  return dispatch(actuator, onFailure);
+}
+
+function dispatch(actuator: RawHapticActuator, onFailure: () => void): boolean {
+  /*
+   * The call itself is guarded, not only its promise. A browser that rejects the *arguments* throws
+   * synchronously rather than rejecting, and this is reachable from a frame — where the house rule
+   * is that nothing throws.
+   */
+  try {
+    swallow(actuator.playEffect('dual-rumble', params), onFailure);
+  } catch {
+    onFailure();
+    return false;
+  }
+  return true;
+}
+
+function swallow(result: Promise<string> | undefined, onFailure: () => void): void {
+  if (result === undefined || typeof result.then !== 'function') return;
+  void result.then(undefined, onFailure);
+}