@jgengine/shell 0.18.1 → 0.19.0

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/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

@@ -1,12 +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, }: {
+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

@@ -1,64 +1,69 @@
-import { useEffect, useRef } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import { useFrame } from "@react-three/fiber";
-import { resolveGamepadFrame, } from "@jgengine/core/input/gamepadModel";
-import { mergeGamepadInput } from "./gamepadMerge.js";
+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";
-function snapshotOf(gamepad) {
-    return {
-        id: gamepad.id,
-        axes: Array.from(gamepad.axes),
-        buttons: Array.from(gamepad.buttons, (button) => ({ pressed: button.pressed, value: button.value })),
-        connected: gamepad.connected,
-    };
+const NO_PADS = [];
+function browserPads() {
+    return typeof navigator === "undefined" || navigator.getGamepads === undefined ? NO_PADS : navigator.getGamepads();
 }
-function gamepadCodes(bindings) {
-    const result = new Map();
-    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.set(action, padCodes);
-    }
-    return result;
+function actuatorOf(pad) {
+    return pad === null || pad === undefined || !("vibrationActuator" in pad) ? null : (pad.vibrationActuator ?? null);
 }
-function syncTracker(tracker, bindings, previous, next) {
-    for (const [action, codes] of bindings) {
-        for (const code of codes) {
-            const wasDown = previous.has(action);
-            const isDown = next.has(action);
-            if (isDown && !wasDown)
-                tracker.handleDown(code);
-            if (!isDown && wasDown)
-                tracker.handleUp(code);
-        }
+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;
 }
-function syntheticSnapshot() {
-    if (typeof window === "undefined" || !new URLSearchParams(window.location.search).has("gamepad"))
+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;
-    return { id: "Synthetic Gamepad", axes: [0, 0], buttons: [{ pressed: true, value: 1 }], connected: true };
+    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, }) {
-    const previousHeld = useRef(new Set());
-    const previousAnalog = useRef(new Set());
+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(() => {
-        padBindings.current = gamepadCodes(bindings);
-        previousHeld.current.clear();
-        previousAnalog.current.clear();
-        tracker.reset();
+        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 = typeof navigator === "undefined" || navigator.getGamepads === undefined ? [] : navigator.getGamepads();
-            const requested = /^gamepad:(\d+)$/.exec(userId)?.[1];
-            const pad = (requested === undefined ? Array.from(pads).find((candidate) => candidate?.connected) : pads[Number(requested)]) ?? null;
-            const actuator = pad?.vibrationActuator;
-            if (actuator === undefined)
+            const pads = browserPads();
+            const actuator = actuatorOf(pads[padIndexForUser(userId, seats, pads)]);
+            if (actuator === null)
                 return false;
             try {
                 await actuator.playEffect("dual-rumble", {
@@ -75,33 +80,74 @@ export function GamepadSource({ tracker, bindings, analogRef, input, }) {
         return () => {
             delete inputWithRumble.rumble;
         };
-    }, [input]);
-    useFrame(() => {
-        const synthetic = syntheticSnapshot();
-        const pads = synthetic === null
-            ? (typeof navigator === "undefined" || navigator.getGamepads === undefined ? [] : navigator.getGamepads())
-            : [synthetic];
-        const frames = [];
-        for (let index = 0; index < pads.length; index += 1) {
-            const pad = pads[index];
-            if (pad !== null && pad !== undefined) {
-                frames.push(resolveGamepadFrame(snapshotOf(pad), padBindingsToGamepad(padBindings.current), {
-                    deadzone: { kind: "axial", inner: 0.12, outer: 0.95 },
-                }));
+    }, [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);
         }
-        const baseAnalog = { ...(analogRef.current ?? {}) };
-        for (const action of previousAnalog.current)
-            delete baseAnalog[action];
-        const merged = mergeGamepadInput(frames, { held: [], analog: baseAnalog });
-        const nextHeld = new Set(merged.held);
-        syncTracker(tracker, padBindings.current, previousHeld.current, nextHeld);
-        previousHeld.current = nextHeld;
-        analogRef.current = Object.keys(merged.analog).length === 0 ? null : merged.analog;
-        previousAnalog.current = new Set(Object.keys(mergeGamepadInput(frames).analog));
     });
     return null;
 }
-function padBindingsToGamepad(bindings) {
-    return Object.fromEntries(bindings.entries());
-}

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";
+}

package/dist/input/pointerLock.d.ts

@@ -0,0 +1,11 @@
+interface LockableElement {
+    requestPointerLock?: (options?: {
+        unadjustedMovement?: boolean;
+    }) => Promise<void> | void;
+}
+/**
+ * Request pointer lock with raw (unaccelerated) mouse deltas, falling back to a plain lock when
+ * the browser or OS rejects `unadjustedMovement`.
+ */
+export declare function requestRawPointerLock(element: LockableElement): void;
+export {};

package/dist/input/pointerLock.js

@@ -0,0 +1,19 @@
+/**
+ * Request pointer lock with raw (unaccelerated) mouse deltas, falling back to a plain lock when
+ * the browser or OS rejects `unadjustedMovement`.
+ */
+export function requestRawPointerLock(element) {
+    const request = element.requestPointerLock;
+    if (request === undefined)
+        return;
+    let pending;
+    try {
+        pending = request.call(element, { unadjustedMovement: true });
+    }
+    catch {
+        pending = request.call(element);
+    }
+    if (pending !== undefined && typeof pending.catch === "function") {
+        pending.catch(() => request.call(element)?.catch?.(() => undefined));
+    }
+}

package/dist/postfx/PostProcessing.d.ts

@@ -3,7 +3,7 @@ import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
- * post chain: RenderPass → GTAO → UnrealBloom → SMAA → OutputPass → Grade. Rendered only
+ * post chain: RenderPass → GTAO → UnrealBloom → SMAA → OutputPass → Stylize → Grade. Rendered only
  * when `PlayableGame.postProcessing` is set, so games without it draw unchanged.
  *
  * `stages` (resolved from the player's graphics profile) controls expensive passes

package/dist/postfx/PostProcessing.js

@@ -7,6 +7,7 @@ import { GTAOPass } from "three/examples/jsm/postprocessing/GTAOPass.js";
 import { BokehPass } from "three/examples/jsm/postprocessing/BokehPass.js";
 import { SMAAPass } from "three/examples/jsm/postprocessing/SMAAPass.js";
 import { createGradePass } from "./gradeShader.js";
+import { StylizePass } from "./stylizePass.js";
 import { hidePostfxOverlays, restorePostfxOverlays } from "./postfxOverlay.js";
 /**
  * GTAO renders the scene with an `overrideMaterial` normal/depth prepass, which stamps
@@ -60,7 +61,7 @@ function syncSize(built, width, height, pixelRatio) {
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
- * post chain: RenderPass → GTAO → UnrealBloom → SMAA → OutputPass → Grade. Rendered only
+ * post chain: RenderPass → GTAO → UnrealBloom → SMAA → OutputPass → Stylize → Grade. Rendered only
  * when `PlayableGame.postProcessing` is set, so games without it draw unchanged.
  *
  * `stages` (resolved from the player's graphics profile) controls expensive passes
@@ -116,6 +117,9 @@ export function PostProcessing({ config, quality = "high", stages }) {
             composer.addPass(new SMAAPass());
         }
         composer.addPass(new OutputPass());
+        if (config.stylize !== undefined && config.stylize !== false) {
+            composer.addPass(new StylizePass(scene, camera, config.stylize));
+        }
         let grade = null;
         if (config.grade !== false) {
             grade = createGradePass(config.grade ?? {});