@jgengine/shell 0.18.0 → 0.19.0

package/dist/environment/daylightCycle.d.ts

@@ -1,8 +1,11 @@
+import type { SkySunConfig } from "@jgengine/core/world/features";
 export interface DaylightCycleConfig {
     horizonColor?: string;
     zenithColor?: string;
     sunIntensity?: number;
     ambientIntensity?: number;
+    /** Fixed sun placement, or the noon placement the day arc swings around. Unset keeps the engine arc. */
+    sun?: SkySunConfig;
 }
 export interface DaylightState {
     sunPosition: [number, number, number];
@@ -16,6 +19,23 @@ export declare const DEFAULT_DAY_SUN_INTENSITY = 1;
 export declare const DEFAULT_DAY_AMBIENT_INTENSITY = 0.6;
 export declare const DEFAULT_DAY_SKY_TOP = "#3fa4f2";
 export declare const DEFAULT_DAY_SKY_BOTTOM = "#e3f4ff";
+/** The engine arc's noon height: `atan(1 / SUN_DEPTH_RATIO)`, ~68 degrees. */
+export declare const DEFAULT_SUN_ELEVATION_DEG: number;
+/**
+ * Unit direction toward a sun at compass `azimuth` (0 = -Z, 90 = +X) and `elevation` above the
+ * horizon, both in degrees. Shared by the dome glow, the sky-owned sun light, and the editor.
+ * @internal
+ */
+export declare function sunDirectionFromBearing(azimuth: number, elevation: number): [number, number, number];
+/**
+ * Inverse of {@link sunDirectionFromBearing}: the bearing/elevation (degrees) of a world-space
+ * direction such as an authored directional light's position. A zero vector reads as overhead.
+ * @internal
+ */
+export declare function bearingFromDirection(direction: readonly [number, number, number]): {
+    azimuth: number;
+    elevation: number;
+};
 export declare const SKY_PRESET_DAY_FRACTION: Record<"day" | "dusk" | "night", number>;
 /** @internal */
 export declare function lerpHexColor(a: string, b: string, t: number): string;

package/dist/environment/daylightCycle.js

@@ -16,6 +16,34 @@ export const DEFAULT_DAY_SKY_TOP = "#3fa4f2";
 export const DEFAULT_DAY_SKY_BOTTOM = "#e3f4ff";
 const SUN_DISTANCE = 200;
 const SUN_DEPTH_RATIO = 0.4;
+const DEG = Math.PI / 180;
+/** The engine arc's noon height: `atan(1 / SUN_DEPTH_RATIO)`, ~68 degrees. */
+export const DEFAULT_SUN_ELEVATION_DEG = Math.atan2(1, SUN_DEPTH_RATIO) / DEG;
+/**
+ * Unit direction toward a sun at compass `azimuth` (0 = -Z, 90 = +X) and `elevation` above the
+ * horizon, both in degrees. Shared by the dome glow, the sky-owned sun light, and the editor.
+ * @internal
+ */
+export function sunDirectionFromBearing(azimuth, elevation) {
+    const az = azimuth * DEG;
+    const el = elevation * DEG;
+    const flat = Math.cos(el);
+    return [Math.sin(az) * flat, Math.sin(el), -Math.cos(az) * flat];
+}
+/**
+ * Inverse of {@link sunDirectionFromBearing}: the bearing/elevation (degrees) of a world-space
+ * direction such as an authored directional light's position. A zero vector reads as overhead.
+ * @internal
+ */
+export function bearingFromDirection(direction) {
+    const [x, y, z] = direction;
+    const length = Math.hypot(x, y, z);
+    if (length === 0)
+        return { azimuth: 0, elevation: 90 };
+    const azimuth = ((Math.atan2(x, -z) / DEG) + 360) % 360;
+    const elevation = Math.asin(Math.max(-1, Math.min(1, y / length))) / DEG;
+    return { azimuth, elevation };
+}
 export const SKY_PRESET_DAY_FRACTION = {
     night: 0,
     day: 0.5,
@@ -106,13 +134,37 @@ export function daylightStateAt(dayFraction, config = {}) {
     const ambientIntensity = lerp(from.ambientIntensity, to.ambientIntensity, localT);
     const skyTop = lerpHexColor(from.skyTop, to.skyTop, localT);
     const skyBottom = lerpHexColor(from.skyBottom, to.skyBottom, localT);
+    const sunPosition = sunPositionAt(wrapped, config.sun);
+    return { sunPosition, sunIntensity, ambientIntensity, skyTop, skyBottom, background: skyBottom };
+}
+/**
+ * Sun position for a wrapped day fraction. Without `sun`, the legacy arc: east at dawn, ~68 degrees
+ * up at noon, west at dusk, tilted 0.4 toward +Z. With `sun`, the arc is rotated so noon lands
+ * exactly on the authored bearing and elevation and the sun still rises 90 degrees before it and
+ * sets 90 degrees after it, so a fixed preset (noon, dusk, night fractions) samples the same arc.
+ */
+function sunPositionAt(wrapped, sun) {
     const angle = (wrapped - 0.25) * 2 * Math.PI;
-    const elevation = Math.sin(angle);
-    const azimuth = Math.cos(angle);
-    const sunPosition = [
-        azimuth * SUN_DISTANCE,
-        elevation * SUN_DISTANCE,
-        SUN_DISTANCE * SUN_DEPTH_RATIO,
+    const along = Math.cos(angle);
+    const up = Math.sin(angle);
+    if (sun === undefined) {
+        return [along * SUN_DISTANCE, up * SUN_DISTANCE, SUN_DISTANCE * SUN_DEPTH_RATIO];
+    }
+    const noon = sunDirectionFromBearing(sun.azimuth ?? 0, sun.elevation ?? DEFAULT_SUN_ELEVATION_DEG);
+    const horizon = normalize([noon[0], 0, noon[2]], [0, 0, -1]);
+    const east = [-horizon[2], 0, horizon[0]];
+    const zenith = normalize(cross(east, noon), [0, 1, 0]);
+    const rise = normalize(cross(noon, zenith), east);
+    return [
+        (rise[0] * along + noon[0] * up) * SUN_DISTANCE,
+        (rise[1] * along + noon[1] * up) * SUN_DISTANCE,
+        (rise[2] * along + noon[2] * up) * SUN_DISTANCE,
     ];
-    return { sunPosition, sunIntensity, ambientIntensity, skyTop, skyBottom, background: skyBottom };
+}
+function cross(a, b) {
+    return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+function normalize(v, fallback) {
+    const length = Math.hypot(v[0], v[1], v[2]);
+    return length < 1e-6 ? [fallback[0], fallback[1], fallback[2]] : [v[0] / length, v[1] / length, v[2] / length];
 }

package/dist/environment/sunShadowMath.d.ts

@@ -0,0 +1,45 @@
+/**
+ * One shadow map for an outdoor sun: 2048 texels over a 70 m box that leads the camera, so the
+ * ground the player looks at gets ~3.4 cm texels and a PCF radius wide enough to hide the
+ * stair-step. A 180 m box centered on the camera wasted half its texels behind the view.
+ * @internal
+ */
+export declare const SUN_SHADOW: {
+    readonly mapSize: 2048;
+    readonly halfExtent: 35;
+    readonly lead: 22;
+    readonly radius: 6;
+    readonly distance: 220;
+    readonly near: 10;
+    readonly far: 520;
+    readonly bias: -0.0004;
+    readonly normalBias: 0.02;
+};
+/**
+ * Where the sun's shadow box centers this frame: `lead` meters ahead of the camera along its
+ * horizontal view, snapped to whole shadow texels so edges hold still while the camera moves.
+ * Looking straight down (no horizontal view) centers on the camera.
+ * @internal
+ */
+export declare function sunShadowFocus(camera: {
+    x: number;
+    z: number;
+}, forward: {
+    x: number;
+    z: number;
+}, out?: {
+    x: number;
+    z: number;
+}): {
+    x: number;
+    z: number;
+};
+/**
+ * The sun light's world position for a focus point: `distance` meters back along the sun
+ * direction, so near/far cover the box whatever magnitude the sky's sun vector carries.
+ * @internal
+ */
+export declare function sunLightPosition(focus: {
+    x: number;
+    z: number;
+}, sun: readonly [number, number, number], out?: [number, number, number]): [number, number, number];

package/dist/environment/sunShadowMath.js

@@ -0,0 +1,50 @@
+/**
+ * One shadow map for an outdoor sun: 2048 texels over a 70 m box that leads the camera, so the
+ * ground the player looks at gets ~3.4 cm texels and a PCF radius wide enough to hide the
+ * stair-step. A 180 m box centered on the camera wasted half its texels behind the view.
+ * @internal
+ */
+export const SUN_SHADOW = {
+    mapSize: 2048,
+    halfExtent: 35,
+    lead: 22,
+    radius: 6,
+    distance: 220,
+    near: 10,
+    far: 520,
+    bias: -0.0004,
+    normalBias: 0.02,
+};
+/**
+ * Where the sun's shadow box centers this frame: `lead` meters ahead of the camera along its
+ * horizontal view, snapped to whole shadow texels so edges hold still while the camera moves.
+ * Looking straight down (no horizontal view) centers on the camera.
+ * @internal
+ */
+export function sunShadowFocus(camera, forward, out = { x: 0, z: 0 }) {
+    const length = Math.hypot(forward.x, forward.z);
+    const lead = length < 1e-6 ? 0 : SUN_SHADOW.lead / length;
+    const texel = (SUN_SHADOW.halfExtent * 2) / SUN_SHADOW.mapSize;
+    out.x = Math.round((camera.x + forward.x * lead) / texel) * texel;
+    out.z = Math.round((camera.z + forward.z * lead) / texel) * texel;
+    return out;
+}
+/**
+ * The sun light's world position for a focus point: `distance` meters back along the sun
+ * direction, so near/far cover the box whatever magnitude the sky's sun vector carries.
+ * @internal
+ */
+export function sunLightPosition(focus, sun, out = [0, 0, 0]) {
+    const length = Math.hypot(sun[0], sun[1], sun[2]);
+    if (length < 1e-6) {
+        out[0] = focus.x;
+        out[1] = SUN_SHADOW.distance;
+        out[2] = focus.z;
+        return out;
+    }
+    const scale = SUN_SHADOW.distance / length;
+    out[0] = focus.x + sun[0] * scale;
+    out[1] = sun[1] * scale;
+    out[2] = focus.z + sun[2] * scale;
+    return out;
+}

package/dist/input/gamepadMerge.d.ts

@@ -0,0 +1,10 @@
+import type { GamepadFrame } from "@jgengine/core/input/gamepadModel";
+/** Per-frame gamepad actions and analog values ready to merge with another input source. */
+export interface GamepadInputFrame {
+    held: readonly string[];
+    analog: Readonly<Record<string, number>>;
+}
+/** Merge one resolved gamepad frame with another input source's semantic state. */
+export declare function mergeGamepadFrame(base: GamepadInputFrame, gamepad: GamepadFrame): GamepadInputFrame;
+/** Pure reducer used by the shell and synthetic gamepad tests. */
+export declare function mergeGamepadInput(frames: readonly GamepadFrame[], base?: GamepadInputFrame): GamepadInputFrame;

package/dist/input/gamepadMerge.js

@@ -0,0 +1,12 @@
+/** Merge one resolved gamepad frame with another input source's semantic state. */
+export function mergeGamepadFrame(base, gamepad) {
+    const held = [...new Set([...base.held, ...gamepad.held])];
+    const analog = { ...base.analog };
+    for (const [action, value] of Object.entries(gamepad.analog))
+        analog[action] = Math.max(analog[action] ?? 0, value);
+    return { held, analog };
+}
+/** Pure reducer used by the shell and synthetic gamepad tests. */
+export function mergeGamepadInput(frames, base = { held: [], analog: {} }) {
+    return frames.reduce(mergeGamepadFrame, base);
+}

package/dist/input/gamepadPoll.d.ts

@@ -0,0 +1,47 @@
+import { type GamepadBindings, type GamepadFrame, type GamepadSample, type ResolveGamepadFrameOptions } from "@jgengine/core/input/gamepadModel";
+import type { ActionCodesMap, ActionStateTracker } from "@jgengine/core/input/actionBindings";
+import type { LocalPlayerSlot, LocalPlayers } from "@jgengine/core/runtime/localPlayers";
+/** Buffers one shell gamepad poll reuses across frames. */
+export interface GamepadPoll {
+    held: Set<string>;
+    nextHeld: Set<string>;
+    frame: GamepadFrame;
+    merged: Record<string, number>;
+    base: Readonly<Record<string, number>> | null;
+}
+/** Fresh buffers for {@link stepGamepadPoll}. */
+export declare function emptyGamepadPoll(): GamepadPoll;
+/** The pad-only slice of an action binding map, in the shape {@link resolveGamepadFrame} reads. */
+export declare function gamepadCodes(bindings: ActionCodesMap): GamepadBindings;
+/**
+ * Swap the pad bindings mid-game (a context push) without touching keyboard state: release the codes
+ * of pad-held actions whose pad codes changed (the next poll presses them under the new map), and
+ * keep the rest held.
+ */
+export declare function rebindGamepadPoll(poll: GamepadPoll, previous: GamepadBindings, next: GamepadBindings, tracker: ActionStateTracker<string>): void;
+/**
+ * One poll: resolve every connected pad, press/release tracker codes for actions whose pad state
+ * changed, and return the analog map to publish (pad values max-merged over the other source's).
+ * Allocation-free after the first frame.
+ */
+export declare function stepGamepadPoll(poll: GamepadPoll, pads: ArrayLike<GamepadSample | null | undefined>, bindings: GamepadBindings, options: ResolveGamepadFrameOptions, tracker: ActionStateTracker<string>, analogIn: Readonly<Record<string, number>> | null): Readonly<Record<string, number>> | null;
+/** Where each connected pad's input goes this frame; buffers are reused across frames. */
+export interface GamepadRoute {
+    /** Pads driving the primary player, by pad index (`null` for pads routed elsewhere). */
+    primary: (GamepadSample | null)[];
+    /** Pads driving another local seat; entries past `seatCount` are stale pooled slots. */
+    seats: {
+        slotId: string;
+        pad: GamepadSample;
+    }[];
+    seatCount: number;
+    /** Seats opened this frame. */
+    joined: LocalPlayerSlot[];
+}
+/** Fresh buffers for {@link routeGamepads}. */
+export declare function emptyGamepadRoute(): GamepadRoute;
+/**
+ * Route pads to local seats: a claimed pad goes to its seat, an unclaimed pad hot-joins on a button
+ * press (stick drift never opens a seat), and with one seat every pad drives the primary player.
+ */
+export declare function routeGamepads(pads: ArrayLike<GamepadSample | null | undefined>, seats: Pick<LocalPlayers, "assign" | "slotForDevice" | "config">, route: GamepadRoute): GamepadRoute;

package/dist/input/gamepadPoll.js

@@ -0,0 +1,142 @@
+import { resolveGamepadFrame, } from "@jgengine/core/input/gamepadModel";
+/** Fresh buffers for {@link stepGamepadPoll}. */
+export function emptyGamepadPoll() {
+    return { held: new Set(), nextHeld: new Set(), frame: { held: [], analog: {} }, merged: {}, base: null };
+}
+/** The pad-only slice of an action binding map, in the shape {@link resolveGamepadFrame} reads. */
+export function gamepadCodes(bindings) {
+    const result = {};
+    for (const [action, config] of Object.entries(bindings)) {
+        const codes = Array.isArray(config)
+            ? config
+            : [...(config.hold ?? []), ...(config.toggle ?? [])];
+        const padCodes = codes.filter((code) => code.startsWith("pad:") || code.startsWith("padaxis:"));
+        if (padCodes.length > 0)
+            result[action] = padCodes;
+    }
+    return result;
+}
+function syncTracker(tracker, bindings, previous, next) {
+    for (const action in bindings) {
+        const wasDown = previous.has(action);
+        const isDown = next.has(action);
+        if (isDown === wasDown)
+            continue;
+        for (const code of bindings[action]) {
+            if (isDown)
+                tracker.handleDown(code);
+            else
+                tracker.handleUp(code);
+        }
+    }
+}
+/**
+ * Swap the pad bindings mid-game (a context push) without touching keyboard state: release the codes
+ * of pad-held actions whose pad codes changed (the next poll presses them under the new map), and
+ * keep the rest held.
+ */
+export function rebindGamepadPoll(poll, previous, next, tracker) {
+    for (const action of poll.held) {
+        const before = (previous[action] ?? []);
+        const after = next[action];
+        if (after !== undefined && after.length === before.length && after.every((code, index) => code === before[index]))
+            continue;
+        for (const code of before)
+            tracker.handleUp(code);
+        poll.held.delete(action);
+    }
+}
+/**
+ * One poll: resolve every connected pad, press/release tracker codes for actions whose pad state
+ * changed, and return the analog map to publish (pad values max-merged over the other source's).
+ * Allocation-free after the first frame.
+ */
+export function stepGamepadPoll(poll, pads, bindings, options, tracker, analogIn) {
+    // The analog slot is shared with the touch dock: anything other than our own merged record is a
+    // fresh touch publish (or null) and becomes the base the pad values merge over.
+    if (analogIn !== poll.merged)
+        poll.base = analogIn;
+    const merged = poll.merged;
+    for (const key in merged)
+        delete merged[key];
+    let any = false;
+    if (poll.base !== null) {
+        for (const action in poll.base) {
+            merged[action] = poll.base[action];
+            any = true;
+        }
+    }
+    const nextHeld = poll.nextHeld;
+    nextHeld.clear();
+    for (let index = 0; index < pads.length; index += 1) {
+        const pad = pads[index];
+        if (pad === null || pad === undefined)
+            continue;
+        const frame = resolveGamepadFrame(pad, bindings, options, poll.frame);
+        for (const action of frame.held)
+            nextHeld.add(action);
+        for (const action in frame.analog) {
+            const value = frame.analog[action];
+            if (value > (merged[action] ?? 0)) {
+                merged[action] = value;
+                any = true;
+            }
+        }
+    }
+    syncTracker(tracker, bindings, poll.held, nextHeld);
+    poll.nextHeld = poll.held;
+    poll.held = nextHeld;
+    return any ? merged : null;
+}
+/** Fresh buffers for {@link routeGamepads}. */
+export function emptyGamepadRoute() {
+    return { primary: [], seats: [], seatCount: 0, joined: [] };
+}
+function anyButtonPressed(pad) {
+    for (let index = 0; index < pad.buttons.length; index += 1) {
+        if (pad.buttons[index]?.pressed === true)
+            return true;
+    }
+    return false;
+}
+/**
+ * Route pads to local seats: a claimed pad goes to its seat, an unclaimed pad hot-joins on a button
+ * press (stick drift never opens a seat), and with one seat every pad drives the primary player.
+ */
+export function routeGamepads(pads, seats, route) {
+    route.primary.length = pads.length;
+    route.seatCount = 0;
+    route.joined.length = 0;
+    const single = seats.config().maxSlots === 1;
+    for (let index = 0; index < pads.length; index += 1) {
+        route.primary[index] = null;
+        const pad = pads[index];
+        if (pad === null || pad === undefined || !pad.connected)
+            continue;
+        const deviceId = `gamepad:${index}`;
+        let slot = seats.slotForDevice(deviceId);
+        if (slot === null && (single || anyButtonPressed(pad))) {
+            const assigned = seats.assign(deviceId);
+            if (assigned !== null) {
+                slot = assigned.slot;
+                if (assigned.joined)
+                    route.joined.push(slot);
+            }
+        }
+        if (slot === null)
+            continue;
+        if (slot.index === 0)
+            route.primary[index] = pad;
+        else {
+            const entry = route.seats[route.seatCount];
+            if (entry === undefined)
+                route.seats.push({ slotId: slot.slotId, pad });
+            else {
+                entry.slotId = slot.slotId;
+                entry.pad = pad;
+            }
+            route.seatCount += 1;
+        }
+    }
+    return route;
+}

package/dist/input/gamepadSource.d.ts

@@ -0,0 +1,22 @@
+import { type GamepadFeelConfig } from "@jgengine/core/input/gamepadModel";
+import type { LocalPlayerSlot, LocalPlayers } from "@jgengine/core/runtime/localPlayers";
+import type { ActionCodesMap, ActionStateTracker } from "@jgengine/core/input/actionBindings";
+import type { InputSnapshot } from "@jgengine/core/runtime/inputSnapshot";
+export { mergeGamepadFrame, mergeGamepadInput } from "./gamepadMerge.js";
+/** Poll browser gamepads and feed semantic actions into the shell tracker. */
+export declare function GamepadSource({ tracker, bindings, analogRef, input, feel, seats, onSeatJoin, seatsActive, }: {
+    tracker: ActionStateTracker<string>;
+    bindings: ActionCodesMap;
+    analogRef: {
+        current: Readonly<Record<string, number>> | null;
+    };
+    input: InputSnapshot;
+    /** Game-level pad feel (`defineGame({ gamepad })`); unset keeps the shell defaults. */
+    feel?: GamepadFeelConfig;
+    /** Local seats; pads claimed by a seat other than the primary publish to that seat's input. */
+    seats?: LocalPlayers;
+    /** A pad just opened a new seat; the shell spawns its player here. */
+    onSeatJoin?: (slot: LocalPlayerSlot) => void;
+    /** False while play controls are gated (menus, orientation lock): seats publish nothing held. */
+    seatsActive?: () => boolean;
+}): null;

package/dist/input/gamepadSource.js

@@ -0,0 +1,153 @@
+import { useEffect, useMemo, useRef } from "react";
+import { useFrame } from "@react-three/fiber";
+import { gamepadFeelOptions, resolveGamepadFrame, } from "@jgengine/core/input/gamepadModel";
+import { emptyGamepadPoll, emptyGamepadRoute, gamepadCodes, rebindGamepadPoll, routeGamepads, stepGamepadPoll, } from "./gamepadPoll.js";
+import { PAD_HAPTIC_EFFECT_MS, emptyPadHapticState, stepPadHaptics } from "./padHaptics.js";
+export { mergeGamepadFrame, mergeGamepadInput } from "./gamepadMerge.js";
+const NO_PADS = [];
+function browserPads() {
+    return typeof navigator === "undefined" || navigator.getGamepads === undefined ? NO_PADS : navigator.getGamepads();
+}
+function actuatorOf(pad) {
+    return pad === null || pad === undefined || !("vibrationActuator" in pad) ? null : (pad.vibrationActuator ?? null);
+}
+function ignore() { }
+/** Pad index a user's rumble goes to: their seat's pad, else the first connected pad for the primary seat. */
+function padIndexForUser(userId, seats, pads) {
+    const legacy = /^gamepad:(\d+)$/.exec(userId)?.[1];
+    if (legacy !== undefined)
+        return Number(legacy);
+    const slot = seats?.slots().find((candidate) => candidate.userId === userId);
+    const claimed = slot?.deviceId === null || slot?.deviceId === undefined ? undefined : /^gamepad:(\d+)$/.exec(slot.deviceId)?.[1];
+    if (claimed !== undefined)
+        return Number(claimed);
+    if (slot !== undefined && slot.index !== 0)
+        return -1;
+    for (let index = 0; index < pads.length; index += 1) {
+        if (pads[index]?.connected === true)
+            return index;
+    }
+    return -1;
+}
+const NO_HELD = [];
+function hasAnalog(analog) {
+    for (const _ in analog)
+        return true;
+    return false;
+}
+// `?gamepad` (or `?gamepad=N` for N pads) injects synthetic pads holding Start (button 9), since
+// headless browsers cannot attach a real one; N > 1 hot-joins local seats.
+function syntheticPads() {
+    if (typeof window === "undefined")
+        return null;
+    const param = new URLSearchParams(window.location.search).get("gamepad");
+    if (param === null)
+        return null;
+    const count = Math.max(1, Math.min(4, Number(param) || 1));
+    const buttons = Array.from({ length: 10 }, (_, index) => ({ pressed: index === 9, value: index === 9 ? 1 : 0 }));
+    return Array.from({ length: count }, () => ({ axes: [0, 0, 0, 0], buttons, connected: true }));
+}
+/** Poll browser gamepads and feed semantic actions into the shell tracker. */
+export function GamepadSource({ tracker, bindings, analogRef, input, feel, seats, onSeatJoin, seatsActive, }) {
+    const poll = useRef(emptyGamepadPoll());
+    const padBindings = useRef(gamepadCodes(bindings));
+    const options = useMemo(() => gamepadFeelOptions(feel), [feel]);
+    const synthetic = useMemo(syntheticPads, []);
+    useEffect(() => {
+        const next = gamepadCodes(bindings);
+        rebindGamepadPoll(poll.current, padBindings.current, next, tracker);
+        padBindings.current = next;
+    }, [bindings, tracker]);
+    useEffect(() => {
+        const inputWithRumble = input;
+        inputWithRumble.rumble = async (userId, options) => {
+            const pads = browserPads();
+            const actuator = actuatorOf(pads[padIndexForUser(userId, seats, pads)]);
+            if (actuator === null)
+                return false;
+            try {
+                await actuator.playEffect("dual-rumble", {
+                    duration: options.ms,
+                    strongMagnitude: options.strong,
+                    weakMagnitude: options.weak,
+                });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        return () => {
+            delete inputWithRumble.rumble;
+        };
+    }, [input, seats]);
+    const hapticStates = useRef(new Map());
+    const driveHaptics = (dt, pads) => {
+        if (seats === undefined)
+            return;
+        const nowMs = performance.now();
+        const slots = seats.slots();
+        for (let index = 0; index < slots.length; index += 1) {
+            const level = input.haptics(slots[index].userId).mix(dt);
+            const padIndex = padIndexForUser(slots[index].userId, seats, pads);
+            const actuator = actuatorOf(pads[padIndex]);
+            if (actuator === null)
+                continue;
+            let state = hapticStates.current.get(padIndex);
+            if (state === undefined) {
+                state = emptyPadHapticState();
+                hapticStates.current.set(padIndex, state);
+            }
+            const command = stepPadHaptics(state, level, nowMs);
+            if (command === "play") {
+                actuator
+                    .playEffect("dual-rumble", { duration: PAD_HAPTIC_EFFECT_MS, strongMagnitude: level.strong, weakMagnitude: level.weak })
+                    .catch(ignore);
+            }
+            else if (command === "reset") {
+                actuator.reset?.().catch(ignore);
+            }
+        }
+    };
+    const route = useRef(emptyGamepadRoute());
+    const seatFrame = useRef({ held: [], analog: {} });
+    const seatsPublished = useRef(new Set());
+    useFrame((_state, dt) => {
+        const pads = synthetic ?? browserPads();
+        driveHaptics(dt, pads);
+        if (seats === undefined) {
+            analogRef.current = stepGamepadPoll(poll.current, pads, padBindings.current, options, tracker, analogRef.current);
+            return;
+        }
+        const routed = routeGamepads(pads, seats, route.current);
+        for (const slot of routed.joined)
+            onSeatJoin?.(slot);
+        analogRef.current = stepGamepadPoll(poll.current, routed.primary, padBindings.current, options, tracker, analogRef.current);
+        const active = seatsActive?.() ?? true;
+        const published = seatsPublished.current;
+        for (const slotId of published) {
+            let routedNow = false;
+            for (let index = 0; index < routed.seatCount; index += 1)
+                routedNow ||= routed.seats[index].slotId === slotId;
+            if (routedNow && active)
+                continue;
+            const seat = seats.local(slotId);
+            seat?.input.publish(NO_HELD);
+            seat?.input.publishAnalog(null);
+            published.delete(slotId);
+        }
+        if (!active)
+            return;
+        for (let index = 0; index < routed.seatCount; index += 1) {
+            const { slotId, pad } = routed.seats[index];
+            const seat = seats.local(slotId);
+            if (seat === null)
+                continue;
+            const frame = resolveGamepadFrame(pad, padBindings.current, options, seatFrame.current);
+            seat.input.publish(frame.held);
+            seat.input.publishAnalog(hasAnalog(frame.analog) ? frame.analog : null);
+            published.add(slotId);
+        }
+    });
+    return null;
+}

package/dist/input/mouseLook.js

@@ -1,3 +1,4 @@
+import { requestRawPointerLock } from "./pointerLock.js";
 export function createMouseLookTracker(element, options = {}) {
     const sensitivity = options.sensitivity ?? 0.0024;
     const maxPitch = options.maxPitch ?? 1.15;
@@ -10,7 +11,7 @@ export function createMouseLookTracker(element, options = {}) {
         if (window.matchMedia?.("(pointer: coarse)").matches)
             return;
         if (document.pointerLockElement !== element)
-            void element.requestPointerLock?.();
+            requestRawPointerLock(element);
     };
     const onMove = (event) => {
         if (pointerLock && document.pointerLockElement !== element)

package/dist/input/padHaptics.d.ts

@@ -0,0 +1,17 @@
+import type { HapticLevel } from "@jgengine/core/input/haptics";
+/** How long each rumble command lasts; refreshed before it runs out so a held level feels continuous. */
+export declare const PAD_HAPTIC_EFFECT_MS = 120;
+/** Last command sent to one pad. */
+export interface PadHapticState {
+    strong: number;
+    weak: number;
+    sentAtMs: number;
+    active: boolean;
+}
+/** Fresh state for {@link stepPadHaptics}. */
+export declare function emptyPadHapticState(): PadHapticState;
+/**
+ * Decide what to send a pad this frame for a mixed level: `"play"` when the level changed or the
+ * last effect is about to run out, `"reset"` when it fell silent, `null` otherwise.
+ */
+export declare function stepPadHaptics(state: PadHapticState, level: HapticLevel, nowMs: number): "play" | "reset" | null;

package/dist/input/padHaptics.js

@@ -0,0 +1,32 @@
+/** How long each rumble command lasts; refreshed before it runs out so a held level feels continuous. */
+export const PAD_HAPTIC_EFFECT_MS = 120;
+const REFRESH_MS = 80;
+const CHANGE = 0.03;
+const SILENT = 0.01;
+/** Fresh state for {@link stepPadHaptics}. */
+export function emptyPadHapticState() {
+    return { strong: 0, weak: 0, sentAtMs: -Infinity, active: false };
+}
+/**
+ * Decide what to send a pad this frame for a mixed level: `"play"` when the level changed or the
+ * last effect is about to run out, `"reset"` when it fell silent, `null` otherwise.
+ */
+export function stepPadHaptics(state, level, nowMs) {
+    const silent = level.strong < SILENT && level.weak < SILENT;
+    if (silent) {
+        if (!state.active)
+            return null;
+        state.active = false;
+        state.strong = 0;
+        state.weak = 0;
+        return "reset";
+    }
+    const changed = Math.abs(level.strong - state.strong) > CHANGE || Math.abs(level.weak - state.weak) > CHANGE;
+    if (state.active && !changed && nowMs - state.sentAtMs < REFRESH_MS)
+        return null;
+    state.active = true;
+    state.strong = level.strong;
+    state.weak = level.weak;
+    state.sentAtMs = nowMs;
+    return "play";
+}