@jgengine/core 0.18.1 → 0.19.0

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;

package/dist/input/haptics.js

@@ -0,0 +1,74 @@
+const clamp01 = (value) => (Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0);
+/**
+ * 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 function createHapticChannels(options = {}) {
+    let duck = clamp01(options.duck ?? 0.4);
+    const channels = new Map();
+    const last = { strong: 0, weak: 0 };
+    const write = (name, channel) => {
+        if (channel.strong === 0 && channel.weak === 0)
+            channels.delete(name);
+        else
+            channels.set(name, channel);
+    };
+    return {
+        set(name, level, priority = 0) {
+            write(name, { strong: clamp01(level.strong), weak: clamp01(level.weak), priority, remainingMs: null, totalMs: null });
+        },
+        pulse(name, pulse, priority = 0) {
+            const ms = Math.max(0, pulse.ms);
+            if (ms === 0) {
+                channels.delete(name);
+                return;
+            }
+            write(name, { strong: clamp01(pulse.strong), weak: clamp01(pulse.weak), priority, remainingMs: ms, totalMs: ms });
+        },
+        clear(name) {
+            if (name === undefined)
+                channels.clear();
+            else
+                channels.delete(name);
+        },
+        mix(dt) {
+            const stepMs = Math.max(0, dt) * 1000;
+            let top = -Infinity;
+            for (const [name, channel] of channels) {
+                if (channel.remainingMs !== null) {
+                    channel.remainingMs -= stepMs;
+                    if (channel.remainingMs <= 0) {
+                        channels.delete(name);
+                        continue;
+                    }
+                }
+                if (channel.priority > top)
+                    top = channel.priority;
+            }
+            let strong = 0;
+            let weak = 0;
+            for (const channel of channels.values()) {
+                const fade = channel.remainingMs === null || channel.totalMs === null ? 1 : channel.remainingMs / channel.totalMs;
+                const scale = (channel.priority >= top ? 1 : duck) * fade;
+                strong = Math.max(strong, channel.strong * scale);
+                weak = Math.max(weak, channel.weak * scale);
+            }
+            last.strong = strong;
+            last.weak = weak;
+            return last;
+        },
+        level: () => last,
+        retune(next) {
+            duck = clamp01(next.duck ?? duck);
+        },
+        snapshot() {
+            return { duck, channels: [...channels].map(([name, channel]) => ({ name, ...channel })) };
+        },
+        restore(snapshot) {
+            duck = clamp01(snapshot.duck);
+            channels.clear();
+            for (const { name, ...channel } of snapshot.channels)
+                channels.set(name, { ...channel });
+        },
+    };
+}

package/dist/input/inputBuffer.d.ts

@@ -0,0 +1,40 @@
+/** One action's press history inside an {@link InputBuffer}. */
+export interface BufferedAction {
+    pressedAt: number;
+    previousPressAt: number | null;
+    releasedAt: number | null;
+    consumed: boolean;
+}
+/** Serializable state for an {@link InputBuffer}. */
+export interface InputBufferSnapshot {
+    windowMs: number;
+    actions: Record<string, BufferedAction>;
+}
+/** Remembers recent action presses so a press slightly early (a jump before landing) still counts. Times are caller-supplied ms, so it runs the same on a client, a host or in a replay. */
+export interface InputBuffer {
+    /** Record a press edge. */
+    press(action: string, nowMs: number): void;
+    /** Record a release edge; {@link InputBuffer.hold} stops growing. */
+    release(action: string, nowMs: number): void;
+    /** `true` once for a press no older than `windowMs` (default: the buffer's window), then the press is spent. */
+    consume(action: string, nowMs: number, windowMs?: number): boolean;
+    /** `true` while `nowMs` is within `windowMs` of `groundedAtMs` — late-jump grace after leaving a ledge. `null` never qualifies. */
+    coyote(groundedAtMs: number | null, nowMs: number, windowMs: number): boolean;
+    /** How long the action has been held, ms; `0` when released or never pressed. */
+    hold(action: string, nowMs: number): number;
+    /** `true` when the last two presses were at most `gapMs` apart and the latest is no older than `gapMs`. */
+    doubleTap(action: string, nowMs: number, gapMs: number): boolean;
+    /** Change the default buffer window. */
+    retune(next: {
+        windowMs: number;
+    }): void;
+    snapshot(): InputBufferSnapshot;
+    restore(snapshot: InputBufferSnapshot): void;
+}
+/**
+ * Creates an input buffer for jump buffering, coyote time, hold duration and double taps.
+ * @capability input-buffer buffer early presses, coyote time, hold duration and double tap for responsive controls
+ */
+export declare function createInputBuffer(options: {
+    windowMs: number;
+}): InputBuffer;

package/dist/input/inputBuffer.js

@@ -0,0 +1,59 @@
+/**
+ * Creates an input buffer for jump buffering, coyote time, hold duration and double taps.
+ * @capability input-buffer buffer early presses, coyote time, hold duration and double tap for responsive controls
+ */
+export function createInputBuffer(options) {
+    let windowMs = options.windowMs;
+    let actions = new Map();
+    return {
+        press(action, nowMs) {
+            const previous = actions.get(action);
+            actions.set(action, {
+                pressedAt: nowMs,
+                previousPressAt: previous === undefined ? null : previous.pressedAt,
+                releasedAt: null,
+                consumed: false,
+            });
+        },
+        release(action, nowMs) {
+            const entry = actions.get(action);
+            if (entry !== undefined && entry.releasedAt === null)
+                entry.releasedAt = nowMs;
+        },
+        consume(action, nowMs, window = windowMs) {
+            const entry = actions.get(action);
+            if (entry === undefined || entry.consumed || nowMs - entry.pressedAt > window)
+                return false;
+            entry.consumed = true;
+            return true;
+        },
+        coyote(groundedAtMs, nowMs, window) {
+            return groundedAtMs !== null && nowMs - groundedAtMs <= window;
+        },
+        hold(action, nowMs) {
+            const entry = actions.get(action);
+            if (entry === undefined || entry.releasedAt !== null)
+                return 0;
+            return Math.max(0, nowMs - entry.pressedAt);
+        },
+        doubleTap(action, nowMs, gapMs) {
+            const entry = actions.get(action);
+            if (entry === undefined || entry.previousPressAt === null)
+                return false;
+            return entry.pressedAt - entry.previousPressAt <= gapMs && nowMs - entry.pressedAt <= gapMs;
+        },
+        retune(next) {
+            windowMs = next.windowMs;
+        },
+        snapshot() {
+            const copy = {};
+            for (const [action, entry] of actions)
+                copy[action] = { ...entry };
+            return { windowMs, actions: copy };
+        },
+        restore(snapshot) {
+            windowMs = snapshot.windowMs;
+            actions = new Map(Object.entries(snapshot.actions).map(([action, entry]) => [action, { ...entry }]));
+        },
+    };
+}

package/dist/input/lookChannel.d.ts

@@ -9,6 +9,14 @@ export interface LookDeltas {
     yaw: number;
     pitch: number;
 }
+/** Plain JSON state of a {@link LookChannel}: the pending pixel deltas and the committed pose. */
+export interface LookChannelState {
+    deltaX: number;
+    deltaY: number;
+    yaw: number;
+    pitch: number;
+    verticalOffset: number;
+}
 export interface LookChannel {
     accumulate(dx: number, dy: number): void;
     /** Yaw/pitch deltas (radians) for this frame; clears the accumulator. */
@@ -19,6 +27,8 @@ export interface LookChannel {
     readPitch(): number;
     setVerticalOffset(offset: number): void;
     readVerticalOffset(): number;
+    snapshot(): LookChannelState;
+    restore(next: LookChannelState): void;
 }
 export interface LookChannelOptions {
     /** Radians of rotation per pixel of pointer travel. */

package/dist/input/lookChannel.js

@@ -40,5 +40,11 @@ export function createLookChannel({ sensitivity, maxVerticalOffset = Infinity })
         readVerticalOffset() {
             return verticalOffset;
         },
+        snapshot() {
+            return { deltaX, deltaY, yaw, pitch, verticalOffset };
+        },
+        restore(next) {
+            ({ deltaX, deltaY, yaw, pitch, verticalOffset } = next);
+        },
     };
 }

package/dist/input/pointer.d.ts

@@ -65,5 +65,7 @@ export interface DragCapture {
     cancel(): void;
     /** The current drag state, or `null` when idle. */
     state(): DragState | null;
+    /** Resumes the drag a {@link DragCapture.state} described (its `origin` and `current`), or goes idle on `null`. */
+    restore(next: DragState | null): void;
 }
 export declare function createDragCapture(config?: DragCaptureConfig): DragCapture;

package/dist/input/pointer.js

@@ -61,5 +61,9 @@ export function createDragCapture(config = {}) {
             current = null;
         },
         state: snapshot,
+        restore(next) {
+            origin = next === null ? null : [next.origin[0], next.origin[1], next.origin[2]];
+            current = next === null ? null : [next.current[0], next.current[1], next.current[2]];
+        },
     };
 }

package/dist/item/affix.d.ts

@@ -51,4 +51,10 @@ export interface AffixRoller {
     roll(base: ItemBaseDef, rarityId: string, rng: () => number): RolledItem;
     rollRandom(base: ItemBaseDef, rng: () => number): RolledItem;
 }
+/**
+ * Rolls randomized gear from a base item: a weighted rarity tier scales base stats and picks
+ * prefix/suffix affixes that name and modify the item. Deterministic for a given `rng`.
+ *
+ * @capability affix-roller roll randomized gear (guns, armor, loot) with rarity tiers, stat scaling and prefix/suffix affixes from a seed
+ */
 export declare function createAffixRoller(config: RollerConfig): AffixRoller;

package/dist/item/affix.js

@@ -20,6 +20,12 @@ function assertConfig(config) {
             throw new Error(`rarity "${tier.id}" weight must be positive`);
     }
 }
+/**
+ * Rolls randomized gear from a base item: a weighted rarity tier scales base stats and picks
+ * prefix/suffix affixes that name and modify the item. Deterministic for a given `rng`.
+ *
+ * @capability affix-roller roll randomized gear (guns, armor, loot) with rarity tiers, stat scaling and prefix/suffix affixes from a seed
+ */
 export function createAffixRoller(config) {
     assertConfig(config);
     const poolById = new Map(config.pools.map((p) => [p.id, p]));

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.18.1";
+export declare const VERSION = "0.19.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];