@realnation/builder-shared-sdk 2.5.1 → 2.7.0

package/dist/gamepad/signals.js

@@ -0,0 +1,117 @@
+import { AXIS_CONTROLS, BUTTON_CONTROLS } from './controls.js';
+/**
+ * Steering was tuned on the real wheel (PF 2026-09-22): at 0.35 of full lock
+ * it had to be dragged round too far before a lane change registered, 0.2
+ * lands where a player expects it. Release sits at half of press, so the wheel
+ * has to come most of the way back before the next turn counts.
+ *
+ * Pedals sit where they are because timing games score the instant of the
+ * press, and a pedal that only registers when floored feels late. That they
+ * now read higher than steering is not a contradiction: a fifth of full lock
+ * is a real turn of the wheel, a quarter of pedal travel is a light touch.
+ *
+ * A profile may override any of these: a 900-degree wheel needs a much lower
+ * steering line than a 270-degree one to feel the same.
+ */
+export const DEFAULT_THRESHOLDS = {
+    steeringPress: 0.2,
+    steeringRelease: 0.1,
+    pedalPress: 0.25,
+    pedalRelease: 0.12,
+    buttonPress: 0.5,
+    buttonRelease: 0.4,
+};
+export function resolveThresholds(overrides) {
+    return { ...DEFAULT_THRESHOLDS, ...overrides };
+}
+export const EMPTY_SIGNAL_STATE = {};
+export function emptyReading() {
+    return { steering: 0, throttle: 0, brake: 0, clutch: 0, buttons: {} };
+}
+function pedalReading(reading, control) {
+    switch (control) {
+        case 'throttle':
+            return reading.throttle;
+        case 'brake':
+            return reading.brake;
+        case 'clutch':
+            return reading.clutch;
+        default:
+            return 0;
+    }
+}
+/**
+ * How far one control is engaged, 0..1.
+ *
+ * The two steering directions read off the same signed axis, each seeing only
+ * its own side. That is what makes them mutually exclusive for free: turning
+ * left drives `wheel-right` to zero, which releases it.
+ */
+function engagement(reading, control) {
+    switch (control) {
+        case 'wheel-left':
+            return Math.max(0, -reading.steering);
+        case 'wheel-right':
+            return Math.max(0, reading.steering);
+        case 'throttle':
+        case 'brake':
+        case 'clutch':
+            return pedalReading(reading, control);
+        default:
+            return reading.buttons[control] ?? 0;
+    }
+}
+function linesFor(control, thresholds) {
+    switch (control) {
+        case 'wheel-left':
+        case 'wheel-right':
+            return [thresholds.steeringPress, thresholds.steeringRelease];
+        case 'throttle':
+        case 'brake':
+        case 'clutch':
+            return [thresholds.pedalPress, thresholds.pedalRelease];
+        default:
+            return [thresholds.buttonPress, thresholds.buttonRelease];
+    }
+}
+const ALL_CONTROLS = [...AXIS_CONTROLS, ...BUTTON_CONTROLS];
+/**
+ * Advances the state machine by one frame.
+ *
+ * Only controls that changed produce events, so a held pedal emits exactly one
+ * press however long it is held. That is what keeps the runner's `e.repeat`
+ * contract intact for the timing games.
+ */
+export function stepSignals(previous, reading, thresholds = DEFAULT_THRESHOLDS) {
+    const next = { ...previous };
+    const events = [];
+    for (const control of ALL_CONTROLS) {
+        const [press, release] = linesFor(control, thresholds);
+        const value = engagement(reading, control);
+        const wasDown = previous[control] === true;
+        if (!wasDown && value >= press) {
+            next[control] = true;
+            events.push({ control, pressed: true });
+        }
+        else if (wasDown && value <= release) {
+            next[control] = false;
+            events.push({ control, pressed: false });
+        }
+    }
+    return { state: next, events };
+}
+/**
+ * Releases everything currently held.
+ *
+ * Called whenever polling is about to stop or the device goes away: a page
+ * hidden mid-corner stops its animation frames, and a press with no matching
+ * release leaves hold-style modules (Video Player) stuck playing forever.
+ */
+export function releaseAll(previous) {
+    const events = [];
+    for (const control of ALL_CONTROLS) {
+        if (previous[control] === true)
+            events.push({ control, pressed: false });
+    }
+    return { state: EMPTY_SIGNAL_STATE, events };
+}

package/dist/gamepad/source.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Where device snapshots come from.
+ *
+ * The session never touches `navigator` directly: it polls a source. The live
+ * source reads the Gamepad API on animation frames; the mock source replays a
+ * script. Tests and machines without a wheel drive the same session code the
+ * hardware does, which is the point (same principle as the runtime mock: it
+ * may be stricter than the real thing, never looser).
+ */
+import type { GamepadLike } from './normalize.js';
+export interface GamepadSource {
+    /** Starts delivering snapshots. Called once when the session connects. */
+    start(onFrame: (pads: readonly GamepadLike[]) => void): void;
+    /** Stops delivering. Must be safe to call when never started. */
+    stop(): void;
+    /** One snapshot on demand, for the connect-time device probe. */
+    read(): readonly GamepadLike[];
+    /** True when this environment can report gamepads at all. */
+    readonly supported: boolean;
+}
+/**
+ * Reads the browser's Gamepad API.
+ *
+ * Polling is the only option the API offers: there are no per-frame events,
+ * and Chrome hands out a fresh snapshot object on every call. `getGamepads()`
+ * returns a sparse array whose holes are disconnected slots, hence the filter.
+ */
+export declare class LiveGamepadSource implements GamepadSource {
+    private readonly requestFrame;
+    private readonly cancelFrame;
+    private handle;
+    private onFrame;
+    readonly supported: boolean;
+    constructor(requestFrame?: (cb: () => void) => number, cancelFrame?: (handle: number) => void);
+    read(): readonly GamepadLike[];
+    start(onFrame: (pads: readonly GamepadLike[]) => void): void;
+    stop(): void;
+}
+export interface MockGamepadOptions {
+    /** The device to report. Absent means "nothing plugged in". */
+    pad?: GamepadLike | null;
+    /** Leaves frame delivery to `step()` instead of a timer. For tests. */
+    manual?: boolean;
+    /** Frame interval when not manual. */
+    intervalMs?: number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+/**
+ * A scripted device.
+ *
+ * Mutate `pad` between frames to drive a turn or a pedal. In manual mode the
+ * caller decides when a frame happens, so a test can assert on exactly the
+ * sequence it wrote rather than on whatever a timer produced.
+ */
+export declare class MockGamepadSource implements GamepadSource {
+    readonly supported = true;
+    private onFrame;
+    private timer;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private readonly intervalMs;
+    private readonly manual;
+    pad: GamepadLike | null;
+    constructor(options?: MockGamepadOptions);
+    read(): readonly GamepadLike[];
+    start(onFrame: (pads: readonly GamepadLike[]) => void): void;
+    stop(): void;
+    /** Delivers one frame. The only way frames happen in manual mode. */
+    step(): void;
+}
+/** Builds a mock device with every axis at rest and every button up. */
+export declare function mockPad(id: string, axisCount: number, buttonCount: number, overrides?: {
+    axes?: number[];
+    buttons?: number[];
+    index?: number;
+}): GamepadLike;
+//# sourceMappingURL=source.d.ts.map

package/dist/gamepad/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/gamepad/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,KAAK,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC7D,iEAAiE;IACjE,IAAI,IAAI,IAAI,CAAC;IACb,iEAAiE;IACjE,IAAI,IAAI,SAAS,WAAW,EAAE,CAAC;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IAOnD,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAP9B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,OAAO,CAAyD;IAExE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAGT,YAAY,GAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,MAA0C,EAC5E,WAAW,GAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAqC;IAKzF,IAAI,IAAI,SAAS,WAAW,EAAE;IAO9B,KAAK,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,KAAK,IAAI,GAAG,IAAI;IAU5D,IAAI,IAAI,IAAI;CAKb;AAED,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,GAAG,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACzB,uEAAuE;IACvE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACnD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACxC;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,QAAQ,CAAC,SAAS,QAAQ;IAE1B,OAAO,CAAC,OAAO,CAAyD;IACxE,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA4B;IACvD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IAEjC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;gBAEZ,OAAO,GAAE,kBAAuB;IAQ5C,IAAI,IAAI,SAAS,WAAW,EAAE;IAI9B,KAAK,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,KAAK,IAAI,GAAG,IAAI;IAM5D,IAAI,IAAI,IAAI;IAMZ,qEAAqE;IACrE,IAAI,IAAI,IAAI;CAGb;AAED,wEAAwE;AACxE,wBAAgB,OAAO,CACrB,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,SAAS,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACtE,WAAW,CAOb"}

package/dist/gamepad/source.js

@@ -0,0 +1,92 @@
+/**
+ * Reads the browser's Gamepad API.
+ *
+ * Polling is the only option the API offers: there are no per-frame events,
+ * and Chrome hands out a fresh snapshot object on every call. `getGamepads()`
+ * returns a sparse array whose holes are disconnected slots, hence the filter.
+ */
+export class LiveGamepadSource {
+    requestFrame;
+    cancelFrame;
+    handle = null;
+    onFrame = null;
+    supported;
+    constructor(requestFrame = (cb) => requestAnimationFrame(cb), cancelFrame = (h) => cancelAnimationFrame(h)) {
+        this.requestFrame = requestFrame;
+        this.cancelFrame = cancelFrame;
+        this.supported = typeof navigator !== 'undefined' && typeof navigator.getGamepads === 'function';
+    }
+    read() {
+        if (!this.supported)
+            return [];
+        return Array.from(navigator.getGamepads()).filter((pad) => Boolean(pad?.connected));
+    }
+    start(onFrame) {
+        this.onFrame = onFrame;
+        if (!this.supported || this.handle !== null)
+            return;
+        const tick = () => {
+            this.handle = this.requestFrame(tick);
+            this.onFrame?.(this.read());
+        };
+        this.handle = this.requestFrame(tick);
+    }
+    stop() {
+        if (this.handle !== null)
+            this.cancelFrame(this.handle);
+        this.handle = null;
+        this.onFrame = null;
+    }
+}
+/**
+ * A scripted device.
+ *
+ * Mutate `pad` between frames to drive a turn or a pedal. In manual mode the
+ * caller decides when a frame happens, so a test can assert on exactly the
+ * sequence it wrote rather than on whatever a timer produced.
+ */
+export class MockGamepadSource {
+    supported = true;
+    onFrame = null;
+    timer = null;
+    setTimer;
+    clearTimer;
+    intervalMs;
+    manual;
+    pad;
+    constructor(options = {}) {
+        this.pad = options.pad ?? null;
+        this.manual = options.manual ?? false;
+        this.intervalMs = options.intervalMs ?? 16;
+        this.setTimer = options.setTimer ?? ((fn, ms) => setInterval(fn, ms));
+        this.clearTimer = options.clearTimer ?? ((h) => clearInterval(h));
+    }
+    read() {
+        return this.pad?.connected ? [this.pad] : [];
+    }
+    start(onFrame) {
+        this.onFrame = onFrame;
+        if (this.manual || this.timer !== null)
+            return;
+        this.timer = this.setTimer(() => this.step(), this.intervalMs);
+    }
+    stop() {
+        if (this.timer !== null)
+            this.clearTimer(this.timer);
+        this.timer = null;
+        this.onFrame = null;
+    }
+    /** Delivers one frame. The only way frames happen in manual mode. */
+    step() {
+        this.onFrame?.(this.read());
+    }
+}
+/** Builds a mock device with every axis at rest and every button up. */
+export function mockPad(id, axisCount, buttonCount, overrides = {}) {
+    const axes = Array.from({ length: axisCount }, (_, i) => overrides.axes?.[i] ?? 0);
+    const buttons = Array.from({ length: buttonCount }, (_, i) => {
+        const value = overrides.buttons?.[i] ?? 0;
+        return { value, pressed: value > 0.5 };
+    });
+    return { id, index: overrides.index ?? 0, connected: true, mapping: '', axes, buttons };
+}

package/package.json

@@ -1,64 +1,68 @@
-{
-  "name": "@realnation/builder-shared-sdk",
-  "version": "2.5.1",
-  "type": "module",
-  "private": false,
-  "exports": {
-    "./package.json": "./package.json",
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./runtime": {
-      "types": "./dist/runtime/index.d.ts",
-      "import": "./dist/runtime/index.js"
-    },
-    "./runtime/vue": {
-      "types": "./dist/runtime/vue/index.d.ts",
-      "import": "./dist/runtime/vue/index.js"
-    },
-    "./interaction": {
-      "types": "./dist/interaction/index.d.ts",
-      "import": "./dist/interaction/index.js"
-    },
-    "./interaction/vue": {
-      "types": "./dist/interaction/vue.d.ts",
-      "import": "./dist/interaction/vue.js"
-    },
-    "./souvenir": {
-      "types": "./dist/souvenir/index.d.ts",
-      "import": "./dist/souvenir/index.js"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "clean": "rimraf dist",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "npm run clean && npm run test && npm run build",
-    "prepare": "npm run clean && npm run build"
-  },
-  "dependencies": {
-    "ali-oss": "^6.23.0",
-    "axios": "^1.7.7"
-  },
-  "peerDependencies": {
-    "vue": "^3.4.0"
-  },
-  "peerDependenciesMeta": {
-    "vue": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@types/ali-oss": "^6.16.11",
-    "@types/node": "^26.1.2",
-    "rimraf": "^5.0.5",
-    "typescript": "^5.4.5",
-    "vitest": "^2.1.0",
-    "vue": "^3.4.0"
-  }
-}
+{
+  "name": "@realnation/builder-shared-sdk",
+  "version": "2.7.0",
+  "type": "module",
+  "private": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./runtime/vue": {
+      "types": "./dist/runtime/vue/index.d.ts",
+      "import": "./dist/runtime/vue/index.js"
+    },
+    "./interaction": {
+      "types": "./dist/interaction/index.d.ts",
+      "import": "./dist/interaction/index.js"
+    },
+    "./interaction/vue": {
+      "types": "./dist/interaction/vue.d.ts",
+      "import": "./dist/interaction/vue.js"
+    },
+    "./souvenir": {
+      "types": "./dist/souvenir/index.d.ts",
+      "import": "./dist/souvenir/index.js"
+    },
+    "./gamepad": {
+      "types": "./dist/gamepad/index.d.ts",
+      "import": "./dist/gamepad/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run clean && npm run test && npm run build",
+    "prepare": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "ali-oss": "^6.23.0",
+    "axios": "^1.7.7"
+  },
+  "peerDependencies": {
+    "vue": "^3.4.0"
+  },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/ali-oss": "^6.16.11",
+    "@types/node": "^26.1.2",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.4.5",
+    "vitest": "^2.1.0",
+    "vue": "^3.4.0"
+  }
+}