@jgengine/core 0.18.1 → 0.21.0

package/dist/input/actionContexts.d.ts

@@ -1,21 +1,45 @@
 import type { ActionCodesMap } from "./actionBindings.js";
+import type { AxisBinding } from "./axisInput.js";
+import type { AxisShapeConfig } from "./axisShaper.js";
+/** Serializable axis shaping a context may carry: {@link AxisShapeConfig} without the `scale` callback. */
+export type ActionContextAxisShape = Omit<AxisShapeConfig, "scale">;
 /** Named action-binding layer that may optionally expose lower layers. */
 export interface ActionContext {
     id: string;
     codes: ActionCodesMap;
     passthrough: boolean;
+    /** Axis bindings (by action name) this context brings, e.g. `steer` while driving; read with `activeAxes()`. */
+    axes?: Record<string, AxisBinding>;
+    /** Per-axis shaping this context brings; feed it to `createAxisShaper(...).retune` when the stack changes. */
+    shaping?: Record<string, ActionContextAxisShape>;
 }
 /** Serializable state for an action-context stack. */
 export interface ActionContextStackSnapshot {
     contexts: ActionContext[];
 }
+/** Axis bindings and shaping merged across the active contexts. */
+export interface ActiveContextAxes {
+    bindings: Record<string, AxisBinding>;
+    shaping: Record<string, ActionContextAxisShape>;
+}
 /** Mutable layered action-map stack with snapshot and restore support. */
 export interface ActionContextStack {
     push(context: ActionContext): void;
     pop(id: string): boolean;
     active(): ActionCodesMap;
+    /** Axis bindings and shaping of the active contexts, merged top-down like {@link active}. */
+    activeAxes(): ActiveContextAxes;
+    /** Ids of the stacked contexts, bottom first. */
+    ids(): readonly string[];
+    /** Bumps on every push, pop and restore; cheap change detection for per-frame readers. */
+    version(): number;
+    /** Called after every push, pop and restore; returns an unsubscribe. The shell rebinds live input here. */
+    subscribe(listener: () => void): () => void;
     snapshot(): ActionContextStackSnapshot;
     restore(snapshot: ActionContextStackSnapshot): void;
 }
-/** Creates a serializable stack of layered action maps for menus and gameplay modes. */
+/**
+ * Creates a serializable stack of layered action maps for menus and gameplay modes.
+ * @capability action-contexts Swap bindings live for on-foot, driving, menu or build modes by pushing and popping layered action maps.
+ */
 export declare function createActionContextStack(): ActionContextStack;

package/dist/input/actionContexts.js

@@ -12,45 +12,102 @@ function cloneCodes(codes) {
     }
     return result;
 }
-/** Creates a serializable stack of layered action maps for menus and gameplay modes. */
+function cloneAxes(axes) {
+    const result = {};
+    for (const [axis, binding] of Object.entries(axes)) {
+        result[axis] = {
+            ...binding,
+            positive: [...binding.positive],
+            ...(binding.negative === undefined ? {} : { negative: [...binding.negative] }),
+        };
+    }
+    return result;
+}
+function cloneShaping(shaping) {
+    const result = {};
+    for (const [axis, shape] of Object.entries(shaping)) {
+        result[axis] = {
+            ...(shape.digital === undefined ? {} : { digital: { ...shape.digital } }),
+            ...(shape.analog === undefined ? {} : { analog: { ...shape.analog } }),
+            ...(shape.range === undefined ? {} : { range: { ...shape.range } }),
+        };
+    }
+    return result;
+}
+function cloneContext(context) {
+    return {
+        id: context.id,
+        codes: cloneCodes(context.codes),
+        passthrough: context.passthrough,
+        ...(context.axes === undefined ? {} : { axes: cloneAxes(context.axes) }),
+        ...(context.shaping === undefined ? {} : { shaping: cloneShaping(context.shaping) }),
+    };
+}
+function mergeTopDown(contexts, pick) {
+    const merged = {};
+    for (let index = contexts.length - 1; index >= 0; index -= 1) {
+        const context = contexts[index];
+        const layer = pick(context);
+        if (layer !== undefined) {
+            for (const [key, value] of Object.entries(layer)) {
+                if (merged[key] === undefined)
+                    merged[key] = value;
+            }
+        }
+        if (!context.passthrough)
+            break;
+    }
+    return merged;
+}
+/**
+ * Creates a serializable stack of layered action maps for menus and gameplay modes.
+ * @capability action-contexts Swap bindings live for on-foot, driving, menu or build modes by pushing and popping layered action maps.
+ */
 export function createActionContextStack() {
     let contexts = [];
+    let version = 0;
+    const listeners = new Set();
+    const changed = () => {
+        version += 1;
+        for (const listener of [...listeners])
+            listener();
+    };
     return {
         push(context) {
-            contexts = [...contexts.filter((current) => current.id !== context.id), {
-                    id: context.id,
-                    codes: cloneCodes(context.codes),
-                    passthrough: context.passthrough,
-                }];
+            contexts = [...contexts.filter((current) => current.id !== context.id), cloneContext(context)];
+            changed();
         },
         pop(id) {
             const next = contexts.filter((context) => context.id !== id);
-            const changed = next.length !== contexts.length;
+            const removed = next.length !== contexts.length;
             contexts = next;
-            return changed;
+            if (removed)
+                changed();
+            return removed;
         },
         active() {
-            const merged = {};
-            for (let index = contexts.length - 1; index >= 0; index -= 1) {
-                const context = contexts[index];
-                for (const [action, codes] of Object.entries(context.codes)) {
-                    if (merged[action] === undefined)
-                        merged[action] = codes;
-                }
-                if (!context.passthrough)
-                    break;
-            }
-            return merged;
+            return mergeTopDown(contexts, (context) => context.codes);
+        },
+        activeAxes() {
+            return {
+                bindings: mergeTopDown(contexts, (context) => context.axes),
+                shaping: mergeTopDown(contexts, (context) => context.shaping),
+            };
+        },
+        ids: () => contexts.map((context) => context.id),
+        version: () => version,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
         },
         snapshot() {
-            return { contexts: contexts.map((context) => ({ ...context, codes: cloneCodes(context.codes) })) };
+            return { contexts: contexts.map(cloneContext) };
         },
         restore(snapshot) {
-            contexts = snapshot.contexts.map((context) => ({
-                id: context.id,
-                codes: cloneCodes(context.codes),
-                passthrough: context.passthrough,
-            }));
+            contexts = snapshot.contexts.map(cloneContext);
+            changed();
         },
     };
 }

package/dist/input/axisInput.d.ts

@@ -47,6 +47,10 @@ export declare class AxisChannel {
     get value(): AxisInput;
     sample(dt: number, isDown: (code: string) => boolean, pointer?: PointerAxisState | null): AxisInput;
 }
+/**
+ * Car axes bound to raw key codes, for an {@link AxisChannel} sampled with a key-code `isDown`. `ctx.input.axis`
+ * samples action names instead, so bind it to the game's input actions (e.g. `moveForward`), not this map.
+ */
 export declare const DRIVE_AXIS_BINDINGS: AxisBindingMap;
 export interface GenericAxisConfig<TAxes extends string> {
     bindings: Record<TAxes, AxisBinding>;

package/dist/input/axisInput.js

@@ -86,6 +86,10 @@ export class AxisChannel {
         return this.current;
     }
 }
+/**
+ * Car axes bound to raw key codes, for an {@link AxisChannel} sampled with a key-code `isDown`. `ctx.input.axis`
+ * samples action names instead, so bind it to the game's input actions (e.g. `moveForward`), not this map.
+ */
 export const DRIVE_AXIS_BINDINGS = {
     throttle: { positive: ["KeyW", "ArrowUp"] },
     brake: { positive: ["KeyS", "ArrowDown"] },

package/dist/input/axisShaper.d.ts

@@ -0,0 +1,73 @@
+import type { AxisBinding, AxisRange } from "./axisInput.js";
+/**
+ * How one axis responds to one kind of source. Keys want ramps (a held key should feel like a pedal
+ * being pressed, not a switch); sticks want deadzone and curve but no lag.
+ */
+export interface AxisShapeProfile {
+    /** Inner deadzone `0..1`; the remaining travel is rescaled so output still starts at 0 (default `0`). */
+    deadzone?: number;
+    /** Raw magnitude at which output reaches full scale, `0..1` (default `1`). */
+    saturation?: number;
+    /** Response exponent applied after the deadzone: `1` linear, `>1` finer near centre (default `1`). */
+    curve?: number;
+    /** Units/s the output may move away from zero (default `Infinity`: no ramp). */
+    riseRate?: number;
+    /** Units/s the output may move back toward zero while the input keeps its sign (default `riseRate`). */
+    fallRate?: number;
+    /** Units/s the output moves when the input is released or reversed — self-centring (default `fallRate`). */
+    returnRate?: number;
+}
+/** Shaping for one named axis. */
+export interface AxisShapeConfig {
+    /** Profile for keys and buttons (default: pass through). */
+    digital?: AxisShapeProfile;
+    /** Profile for sticks, triggers and other continuous sources (default: pass through). */
+    analog?: AxisShapeProfile;
+    /** Output range (default `[-1, 1]`; use `{ min: 0, max: 1 }` for pedals). */
+    range?: AxisRange;
+    /**
+     * Multiplier from a caller-supplied signal, applied to the target before ramping — speed-sensitive
+     * steering (`speed => 1 / (1 + speed / 30)`), weapon-sway-by-stamina, and similar. Default `1`.
+     */
+    scale?: (signal: number) => number;
+}
+/** Config for {@link createAxisShaper}: one entry per axis. */
+export interface AxisShaperConfig<TAxes extends string> {
+    axes: Record<TAxes, AxisShapeConfig>;
+}
+/** Per-sample options for {@link AxisShaper.shape}. */
+export interface AxisShapeSample<TAxes extends string> {
+    /** Axes whose raw value came from an analog source this frame; unlisted axes use the digital profile. */
+    analog?: Partial<Record<TAxes, boolean>> | ReadonlySet<TAxes>;
+    /** Signal passed to each axis's `scale` callback (speed, stamina, zoom). */
+    signal?: number;
+}
+/** Shaped axis output, one number per axis. */
+export type AxisValues<TAxes extends string> = Record<TAxes, number>;
+/** Stateful per-axis response shaping between raw input and a sim. */
+export interface AxisShaper<TAxes extends string> {
+    /** Shape one frame of raw axis values (as returned by `ctx.input.axis`) and return the shaped output. */
+    shape(dt: number, raw: Readonly<Record<TAxes, number>>, sample?: AxisShapeSample<TAxes>): AxisValues<TAxes>;
+    /** The last shaped output. */
+    value(): Readonly<AxisValues<TAxes>>;
+    /** Replace the shaping config (settings screen, per-vehicle feel) without resetting the current output. */
+    retune(next: AxisShaperConfig<TAxes>): void;
+    snapshot(): AxisValues<TAxes>;
+    restore(state: Readonly<AxisValues<TAxes>>): void;
+    /** Zero every axis. */
+    reset(): void;
+}
+/** Deadzone, saturation and curve applied to one raw value; sign is preserved. */
+export declare function shapeAxisValue(raw: number, profile: AxisShapeProfile | undefined): number;
+/**
+ * Creates an {@link AxisShaper}: deadzone, curve and ramp rates per axis, chosen per frame by whether the
+ * source was a key or a stick. It sits between `ctx.input.axis(...)` and any sim (a vehicle, an aircraft,
+ * aim), so a held key eases in and self-centres while a stick stays direct. Deterministic and serializable.
+ * @capability axis-shaping shape raw input per axis — deadzone, response curve, keyboard ramp, self-centring, speed-sensitive scaling
+ */
+export declare function createAxisShaper<TAxes extends string>(initial: AxisShaperConfig<TAxes>): AxisShaper<TAxes>;
+/**
+ * Which axes an analog source is driving this frame: an axis counts as analog when any action bound to it
+ * has a published analog magnitude (`ctx.input.analog()`). Feed the result to {@link AxisShaper.shape}.
+ */
+export declare function analogAxes<TAxes extends string>(bindings: Readonly<Record<TAxes, AxisBinding>>, analog: Readonly<Record<string, number>> | null): Set<TAxes>;

package/dist/input/axisShaper.js

@@ -0,0 +1,105 @@
+const FULL_RANGE = { min: -1, max: 1 };
+function clampTo(value, range) {
+    return value < range.min ? range.min : value > range.max ? range.max : value;
+}
+/** Deadzone, saturation and curve applied to one raw value; sign is preserved. */
+export function shapeAxisValue(raw, profile) {
+    if (profile === undefined)
+        return raw;
+    const deadzone = Math.min(0.99, Math.max(0, profile.deadzone ?? 0));
+    const saturation = Math.max(deadzone + 0.01, Math.min(1, profile.saturation ?? 1));
+    const magnitude = Math.abs(raw);
+    if (magnitude <= deadzone)
+        return 0;
+    const normalized = Math.min(1, (magnitude - deadzone) / (saturation - deadzone));
+    const curved = normalized ** Math.max(0.1, profile.curve ?? 1);
+    return Math.sign(raw) * curved;
+}
+function rateFor(current, target, profile) {
+    const rise = profile?.riseRate ?? Number.POSITIVE_INFINITY;
+    const fall = profile?.fallRate ?? rise;
+    const back = profile?.returnRate ?? fall;
+    if (target === 0 || (current !== 0 && Math.sign(target) !== Math.sign(current)))
+        return back;
+    return Math.abs(target) >= Math.abs(current) ? rise : fall;
+}
+function isAnalog(axis, analog) {
+    if (analog === undefined)
+        return false;
+    if (analog instanceof Set)
+        return analog.has(axis);
+    return analog[axis] === true;
+}
+/**
+ * Creates an {@link AxisShaper}: deadzone, curve and ramp rates per axis, chosen per frame by whether the
+ * source was a key or a stick. It sits between `ctx.input.axis(...)` and any sim (a vehicle, an aircraft,
+ * aim), so a held key eases in and self-centres while a stick stays direct. Deterministic and serializable.
+ * @capability axis-shaping shape raw input per axis — deadzone, response curve, keyboard ramp, self-centring, speed-sensitive scaling
+ */
+export function createAxisShaper(initial) {
+    let config = initial;
+    const names = Object.keys(config.axes);
+    const current = {};
+    for (const name of names)
+        current[name] = 0;
+    return {
+        shape(dt, raw, sample) {
+            const step = Math.max(0, dt);
+            for (const name of Object.keys(config.axes)) {
+                const axis = config.axes[name];
+                const range = axis.range ?? FULL_RANGE;
+                const profile = isAnalog(name, sample?.analog) ? axis.analog : axis.digital;
+                const scale = axis.scale === undefined ? 1 : axis.scale(sample?.signal ?? 0);
+                const target = clampTo(shapeAxisValue(raw[name] ?? 0, profile) * scale, range);
+                const from = current[name] ?? 0;
+                const rate = rateFor(from, target, profile);
+                let next;
+                if (!Number.isFinite(rate))
+                    next = target;
+                else if (target !== 0 && from !== 0 && Math.sign(target) !== Math.sign(from)) {
+                    // A reversal returns to centre at the return rate, then builds the other way at the rise rate.
+                    const toZero = Math.min(Math.abs(from), rate * step);
+                    const left = step - toZero / Math.max(rate, 1e-9);
+                    next = Math.abs(from) > toZero ? from - Math.sign(from) * toZero : Math.sign(target) * Math.min(Math.abs(target), (profile?.riseRate ?? Number.POSITIVE_INFINITY) * left);
+                }
+                else {
+                    const delta = target - from;
+                    const move = rate * step;
+                    next = Math.abs(delta) <= move ? target : from + Math.sign(delta) * move;
+                }
+                current[name] = clampTo(next, range);
+            }
+            return current;
+        },
+        value: () => current,
+        retune(next) {
+            config = next;
+            for (const name of Object.keys(next.axes))
+                current[name] ??= 0;
+        },
+        snapshot: () => ({ ...current }),
+        restore(state) {
+            Object.assign(current, state);
+        },
+        reset() {
+            for (const name of Object.keys(current))
+                current[name] = 0;
+        },
+    };
+}
+/**
+ * Which axes an analog source is driving this frame: an axis counts as analog when any action bound to it
+ * has a published analog magnitude (`ctx.input.analog()`). Feed the result to {@link AxisShaper.shape}.
+ */
+export function analogAxes(bindings, analog) {
+    const out = new Set();
+    if (analog === null)
+        return out;
+    for (const name of Object.keys(bindings)) {
+        const binding = bindings[name];
+        const codes = binding.negative === undefined ? binding.positive : [...binding.positive, ...binding.negative];
+        if (codes.some((code) => analog[code] !== undefined))
+            out.add(name);
+    }
+    return out;
+}

package/dist/input/gamepadModel.d.ts

@@ -29,17 +29,51 @@ export interface GamepadDeadzone {
     inner: number;
     outer: number;
 }
+/**
+ * Read-only view of one sampled gamepad. The browser `Gamepad` satisfies it structurally, so a poll
+ * loop can resolve `navigator.getGamepads()` entries without copying them.
+ */
+export interface GamepadSample {
+    readonly axes: ArrayLike<number>;
+    readonly buttons: ArrayLike<{
+        readonly pressed: boolean;
+        readonly value: number;
+    }>;
+    readonly connected: boolean;
+}
 /** Options for resolving one gamepad snapshot into action state. */
 export interface ResolveGamepadFrameOptions {
     deadzone: GamepadDeadzone;
+    /** Response exponent for sticks and analog buttons: `1` linear, `>1` finer near rest (default `1`). */
+    curve?: number;
+    /** Inner deadzone `0..1` for analog button values (triggers); below it the button reads 0 and is not held (default `0`). */
+    triggerDeadzone?: number;
+}
+/**
+ * Game-level pad feel read by the shell's gamepad poll. A number `deadzone` is the axial inner
+ * deadzone with a `0.95` outer edge.
+ */
+export interface GamepadFeelConfig {
+    /** Stick deadzone (default axial `0.12` inner, `0.95` outer). */
+    deadzone?: number | GamepadDeadzone;
+    /** Response exponent shared by sticks and triggers (default `1`). */
     curve?: number;
+    /** Trigger inner deadzone `0..1` (default `0`). */
+    triggerDeadzone?: number;
 }
+/** Shell default stick deadzone. */
+export declare const DEFAULT_GAMEPAD_DEADZONE: GamepadDeadzone;
+/** Resolve a {@link GamepadFeelConfig} into the options {@link resolveGamepadFrame} takes. */
+export declare function gamepadFeelOptions(config: GamepadFeelConfig | undefined): ResolveGamepadFrameOptions;
 /** The digital and analog action state produced by a gamepad frame. */
 export interface GamepadFrame {
     held: string[];
     analog: Record<string, number>;
 }
-/** Resolve one sampled gamepad into held actions and shaped analog action values.
+/**
+ * Resolve one sampled gamepad into held actions and shaped analog action values. Sticks go through
+ * the deadzone and curve; analog buttons (triggers) through `triggerDeadzone` and the same curve.
+ * Pass `out` to reuse a frame across polls; it is cleared and returned.
  * @capability gamepad-input Resolve sampled gamepad input into actions with deadzones and response curves.
  */
-export declare function resolveGamepadFrame(snapshot: GamepadSnapshot, bindings: GamepadBindings, options: ResolveGamepadFrameOptions): GamepadFrame;
+export declare function resolveGamepadFrame(snapshot: GamepadSample, bindings: GamepadBindings, options: ResolveGamepadFrameOptions, out?: GamepadFrame): GamepadFrame;

package/dist/input/gamepadModel.js

@@ -7,63 +7,102 @@ export const GAMEPAD_GLYPH_SETS = {
 };
 /** Lowercase alias for consumers that prefer data-oriented naming. */
 export const gamepadGlyphSets = GAMEPAD_GLYPH_SETS;
+/** Shell default stick deadzone. */
+export const DEFAULT_GAMEPAD_DEADZONE = { kind: "axial", inner: 0.12, outer: 0.95 };
+/** Resolve a {@link GamepadFeelConfig} into the options {@link resolveGamepadFrame} takes. */
+export function gamepadFeelOptions(config) {
+    const deadzone = config?.deadzone;
+    return {
+        deadzone: deadzone === undefined
+            ? DEFAULT_GAMEPAD_DEADZONE
+            : typeof deadzone === "number"
+                ? { kind: "axial", inner: deadzone, outer: DEFAULT_GAMEPAD_DEADZONE.outer }
+                : deadzone,
+        curve: config?.curve ?? 1,
+        triggerDeadzone: config?.triggerDeadzone ?? 0,
+    };
+}
 function bindingCodes(codes) {
     if (Array.isArray(codes))
         return codes;
     const modes = codes;
     return [...(modes.hold ?? []), ...(modes.toggle ?? [])];
 }
-function shape(value, deadzone, curve) {
-    const magnitude = Math.abs(value);
-    if (magnitude <= deadzone.inner)
+function clampUnit(value) {
+    return Number.isFinite(value) ? (value < -1 ? -1 : value > 1 ? 1 : value) : 0;
+}
+function rescale(magnitude, inner, outer, curve) {
+    if (magnitude <= inner)
         return 0;
-    const normalized = magnitude >= deadzone.outer ? 1 : (magnitude - deadzone.inner) / (deadzone.outer - deadzone.inner);
-    return Math.sign(value) * Math.pow(normalized, curve);
+    const normalized = magnitude >= outer ? 1 : (magnitude - inner) / (outer - inner);
+    return curve === 1 ? normalized : Math.pow(normalized, curve);
 }
+const axisCodes = new Map();
 function readAxis(code) {
-    const match = /^padaxis:(\d+)([+-])$/.exec(code);
-    return match === null ? null : { index: Number(match[1]), sign: match[2] === "+" ? 1 : -1 };
+    let parsed = axisCodes.get(code);
+    if (parsed === undefined) {
+        const match = /^padaxis:(\d+)([+-])$/.exec(code);
+        parsed = match === null ? null : { index: Number(match[1]), sign: match[2] === "+" ? 1 : -1 };
+        axisCodes.set(code, parsed);
+    }
+    return parsed;
 }
-/** Resolve one sampled gamepad into held actions and shaped analog action values.
+/**
+ * Resolve one sampled gamepad into held actions and shaped analog action values. Sticks go through
+ * the deadzone and curve; analog buttons (triggers) through `triggerDeadzone` and the same curve.
+ * Pass `out` to reuse a frame across polls; it is cleared and returned.
  * @capability gamepad-input Resolve sampled gamepad input into actions with deadzones and response curves.
  */
-export function resolveGamepadFrame(snapshot, bindings, options) {
+export function resolveGamepadFrame(snapshot, bindings, options, out = { held: [], analog: {} }) {
+    out.held.length = 0;
+    for (const key in out.analog)
+        delete out.analog[key];
     if (!snapshot.connected)
-        return { held: [], analog: {} };
+        return out;
     const inner = Math.max(0, options.deadzone.inner);
     const outer = Math.max(inner + Number.EPSILON, options.deadzone.outer);
     const curve = options.curve === undefined ? 1 : Math.max(Number.EPSILON, options.curve);
-    const rawAxes = snapshot.axes.map((value) => (Number.isFinite(value) ? Math.max(-1, Math.min(1, value)) : 0));
-    const axes = rawAxes.map((value) => shape(value, { ...options.deadzone, inner, outer }, curve));
-    if (options.deadzone.kind === "radial") {
-        const magnitude = Math.hypot(...rawAxes);
-        const radial = magnitude <= inner ? 0 : Math.min(1, (magnitude - inner) / (outer - inner));
-        const factor = magnitude === 0 ? 0 : (radial * Math.pow(radial, curve - 1)) / magnitude;
-        for (let index = 0; index < axes.length; index += 1)
-            axes[index] = rawAxes[index] * factor;
+    const triggerInner = Math.min(0.99, Math.max(0, options.triggerDeadzone ?? 0));
+    const radial = options.deadzone.kind === "radial";
+    let radialFactor = 0;
+    if (radial) {
+        let sumSquares = 0;
+        for (let index = 0; index < snapshot.axes.length; index += 1) {
+            const value = clampUnit(snapshot.axes[index]);
+            sumSquares += value * value;
+        }
+        const magnitude = Math.sqrt(sumSquares);
+        radialFactor = magnitude === 0 ? 0 : rescale(Math.min(1, magnitude), inner, outer, curve) / magnitude;
     }
-    const held = [];
-    const analog = {};
-    for (const action of Object.keys(bindings)) {
+    for (const action in bindings) {
         let actionAnalog = 0;
         let isHeld = false;
         for (const code of bindingCodes(bindings[action])) {
             if (code.startsWith("pad:")) {
-                const index = Number(code.slice(4));
-                const button = snapshot.buttons[index];
-                if (button?.pressed === true)
+                const button = snapshot.buttons[Number(code.slice(4))];
+                if (button === undefined)
+                    continue;
+                const raw = Number.isFinite(button.value) ? Math.max(0, Math.min(1, button.value)) : 0;
+                const value = rescale(raw, triggerInner, 1, curve);
+                if (button.pressed && (value > 0 || raw === 0))
                     isHeld = true;
-                actionAnalog = Math.max(actionAnalog, button?.value ?? 0);
+                if (value > actionAnalog)
+                    actionAnalog = value;
                 continue;
             }
             const axis = readAxis(code);
-            if (axis !== null)
-                actionAnalog = Math.max(actionAnalog, Math.max(0, axes[axis.index] * axis.sign));
+            if (axis === null)
+                continue;
+            const raw = clampUnit(snapshot.axes[axis.index] ?? 0);
+            const shaped = radial ? raw * radialFactor : Math.sign(raw) * rescale(Math.abs(raw), inner, outer, curve);
+            const value = shaped * axis.sign;
+            if (value > actionAnalog)
+                actionAnalog = value;
         }
         if (isHeld || actionAnalog > 0)
-            held.push(action);
+            out.held.push(action);
         if (actionAnalog !== 0)
-            analog[action] = actionAnalog;
+            out.analog[action] = actionAnalog;
     }
-    return { held, analog };
+    return out;
 }

package/dist/input/haptics.d.ts

@@ -0,0 +1,50 @@
+/** Motor intensities, each `0..1`: `strong` is the low-frequency motor, `weak` the high-frequency one. */
+export interface HapticLevel {
+    strong: number;
+    weak: number;
+}
+/** A decaying one-shot on a channel: starts at `strong`/`weak` and fades to zero over `ms`. */
+export interface HapticPulse extends HapticLevel {
+    ms: number;
+}
+/** Options for {@link createHapticChannels}. */
+export interface HapticChannelsOptions {
+    /** Scale applied to channels below the highest active priority (default `0.4`), so an impact cuts through the engine hum. */
+    duck?: number;
+}
+/** Serializable channel state. */
+export interface HapticChannelsSnapshot {
+    duck: number;
+    channels: {
+        name: string;
+        strong: number;
+        weak: number;
+        priority: number;
+        remainingMs: number | null;
+        totalMs: number | null;
+    }[];
+}
+/**
+ * Named continuous rumble channels for one player, mixed by priority each frame. Game code sets
+ * levels from its own telemetry (engine rpm, road surface, impacts); the shell mixes and drives the pad.
+ */
+export interface HapticChannels {
+    /** Hold a channel at a level until changed; `0`/`0` silences it. Higher `priority` (default `0`) ducks lower channels. */
+    set(channel: string, level: HapticLevel, priority?: number): void;
+    /** Start a fading one-shot on a channel, replacing what it held. */
+    pulse(channel: string, pulse: HapticPulse, priority?: number): void;
+    /** Silence one channel, or all of them. */
+    clear(channel?: string): void;
+    /** Advance pulses by `dt` seconds and return the mixed level. */
+    mix(dt: number): HapticLevel;
+    /** The last mixed level. */
+    level(): HapticLevel;
+    retune(options: HapticChannelsOptions): void;
+    snapshot(): HapticChannelsSnapshot;
+    restore(snapshot: HapticChannelsSnapshot): void;
+}
+/**
+ * Per-player haptic channels mixed by priority.
+ * @capability haptics Continuous gamepad rumble from named channels (engine, road, impact) mixed by priority, plus fading pulses.
+ */
+export declare function createHapticChannels(options?: HapticChannelsOptions): HapticChannels;