@jgengine/shell 0.17.0 → 0.18.1

package/dist/audio/audioEngine.js

@@ -30,6 +30,35 @@ function resolveOfflineAudioContextCtor() {
     return (window.OfflineAudioContext ??
         window.webkitOfflineAudioContext);
 }
+function setAudioParam(param, value) {
+    if (param === undefined)
+        return;
+    param.value = value;
+}
+function setPannerPosition(panner, position) {
+    setAudioParam(panner.positionX, position.x);
+    setAudioParam(panner.positionY, position.y);
+    setAudioParam(panner.positionZ, position.z);
+}
+function createPanner(context, spatial, position) {
+    const panner = context.createPanner();
+    panner.panningModel = spatial.panning === "hrtf" ? "HRTF" : "equalpower";
+    panner.distanceModel = "inverse";
+    if (spatial.refDistance !== undefined)
+        panner.refDistance = spatial.refDistance;
+    if (spatial.maxDistance !== undefined)
+        panner.maxDistance = spatial.maxDistance;
+    if (spatial.rolloff !== undefined)
+        panner.rolloffFactor = spatial.rolloff;
+    if (spatial.coneInner !== undefined)
+        panner.coneInnerAngle = spatial.coneInner;
+    if (spatial.coneOuter !== undefined)
+        panner.coneOuterAngle = spatial.coneOuter;
+    if (spatial.coneOuterGain !== undefined)
+        panner.coneOuterGain = spatial.coneOuterGain;
+    setPannerPosition(panner, position);
+    return panner;
+}
 export function createAudioEngine(config = {}) {
     const sounds = config.sounds ?? {};
     const busDefs = config.buses ?? {};
@@ -128,8 +157,17 @@ export function createAudioEngine(config = {}) {
         // A one-shot synth cue realises its decaying voices live and is fire-and-forget.
         if (sound.synth !== undefined && !loop) {
             const cueGain = context.createGain();
-            cueGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
-            cueGain.connect(bus);
+            cueGain.gain.value = sound.spatial === undefined
+                ? resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1)
+                : sound.gain ?? 1;
+            if (sound.spatial !== undefined) {
+                const panner = createPanner(context, sound.spatial, currentPosition);
+                cueGain.connect(panner);
+                panner.connect(bus);
+            }
+            else {
+                cueGain.connect(bus);
+            }
             realizeSynthPatch(context, cueGain, sharedNoiseBuffer(), sound.synth);
             return NOOP_HANDLE;
         }
@@ -152,10 +190,13 @@ export function createAudioEngine(config = {}) {
         let sourceNode = null;
         let userGainNode = null;
         let falloffGain = null;
+        let pannerNode = null;
         function updateFalloff() {
-            if (falloffGain !== null) {
+            if (falloffGain !== null && sound.spatial === undefined) {
                 falloffGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
             }
+            if (pannerNode !== null)
+                setPannerPosition(pannerNode, currentPosition);
         }
         void bufferPromise.then((buffer) => {
             if (buffer === null)
@@ -171,7 +212,16 @@ export function createAudioEngine(config = {}) {
             fGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
             src.connect(uGain);
             uGain.connect(fGain);
-            fGain.connect(bus);
+            if (sound.spatial !== undefined) {
+                const panner = createPanner(context, sound.spatial, currentPosition);
+                fGain.gain.value = 1;
+                fGain.connect(panner);
+                panner.connect(bus);
+                pannerNode = panner;
+            }
+            else {
+                fGain.connect(bus);
+            }
             src.start();
             sourceNode = src;
             userGainNode = uGain;
@@ -185,6 +235,7 @@ export function createAudioEngine(config = {}) {
                 src.disconnect();
                 uGain.disconnect();
                 fGain.disconnect();
+                pannerNode?.disconnect();
                 sourceNode = null;
                 userGainNode = null;
                 falloffGain = null;
@@ -219,7 +270,18 @@ export function createAudioEngine(config = {}) {
     }
     return {
         setListenerPose(position) {
-            listenerPosition = position;
+            const pose = "position" in position ? position : { position, forward: { x: 0, y: 0, z: -1 }, up: { x: 0, y: 1, z: 0 } };
+            listenerPosition = pose.position;
+            const listener = context.listener;
+            setAudioParam(listener.positionX, pose.position.x);
+            setAudioParam(listener.positionY, pose.position.y);
+            setAudioParam(listener.positionZ, pose.position.z);
+            setAudioParam(listener.forwardX, pose.forward.x);
+            setAudioParam(listener.forwardY, pose.forward.y);
+            setAudioParam(listener.forwardZ, pose.forward.z);
+            setAudioParam(listener.upX, pose.up.x);
+            setAudioParam(listener.upY, pose.up.y);
+            setAudioParam(listener.upZ, pose.up.z);
             for (const updateGain of activeSpatialUpdaters)
                 updateGain();
         },

package/dist/camera/cameraRigs.js

@@ -1,6 +1,7 @@
 import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useMemo, useRef } from "react";
 import { PerspectiveCamera, Quaternion, Vector3 } from "three";
+import { snapPixelPerfectPosition } from "@jgengine/core/game/pixelPerfect";
 import { usePlayer } from "@jgengine/react/hooks";
 import { useGameContext } from "@jgengine/react/provider";
 import { ORBIT_CAMERA_FRAME_PRIORITY } from "./orbitCameraMath.js";
@@ -162,6 +163,12 @@ export function SideScrollRig(props) {
         };
         followRef.current = follow;
         const pose = resolveSideScrollPose(follow, resolved, config?.fov ?? currentFov(camera));
+        const pixelPerfect = props.config?.projection === "orthographic" ? props.config.pixelPerfect : undefined;
+        if (pixelPerfect !== undefined) {
+            const snapped = snapPixelPerfectPosition(pose.position, pixelPerfect.pixelsPerUnit);
+            pose.position = snapped;
+            pose.lookAt = snapPixelPerfectPosition(pose.lookAt, pixelPerfect.pixelsPerUnit);
+        }
         commit(pose, dt);
     }, CAMERA_RIG_FRAME_PRIORITY);
     return null;

package/dist/defineGame.js

@@ -3,6 +3,8 @@ import { useMemo } from "react";
 import { defineGameDefinition as defineEngineGame, } from "@jgengine/core/game/defineGame";
 import { syncLifecyclePhase } from "@jgengine/core/game/gamePhase";
 import { offline } from "@jgengine/core/runtime/adapter";
+import { lightingFromDocument } from "@jgengine/core/editor/environment";
+import { resolveGameLook } from "@jgengine/core/render/lookPreset";
 import { EnvironmentScene } from "./environment.js";
 import { terrainGroundColorSampler } from "./environment/terrainGroundColor.js";
 import { AuthoredScene } from "./scene/AuthoredScene.js";
@@ -12,6 +14,9 @@ function worldBackdrop(feature) {
         return _jsx(EnvironmentScene, { feature: feature });
     };
 }
+function isEnvironmentSource(value) {
+    return typeof value === "object" && value !== null && "kind" in value && ["gradient", "hdri", "cube"].includes(value.kind);
+}
 function authoredSceneOverlay(document, placement, scatterModels, assets, world, Vfx) {
     const terrain = world !== undefined && world.kind === "environment" ? world.terrain : undefined;
     return function AuthoredSceneOverlay(props) {
@@ -28,12 +33,19 @@ const emptyUi = () => null;
  * @capability define-game single public game-authoring path — compose systems, world, presentation, and authored scene in one definition
  */
 export function defineGame(config) {
-    const { content, loop, GameUI, environment, camera, multiplayer, editorLayers, editorCatalogs, scenePlacement, sceneScatterModels, WorldOverlay, viewmodel, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, orientation, worldHealthBars, nameplates, presentationEffects, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting, backdrop, postProcessing, shadows, presentation, objectStyles, devtools, capture, platforms, hudFit, ...engineFields } = config;
+    const { content, loop, GameUI, environment, camera, multiplayer, editorLayers, editorCatalogs, scenePlacement, sceneScatterModels, WorldOverlay, viewmodel, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, orientation, worldHealthBars, nameplates, presentationEffects, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting: authoredLighting, environmentSource, backdrop, look, postProcessing, shadows, graphics, presentation, objectStyles, devtools, capture, platforms, hudFit, ...engineFields } = config;
     const game = defineEngineGame({
         ...engineFields,
         multiplayer: multiplayer ?? offline(),
         loop,
     });
+    const resolvedLook = resolveGameLook({
+        look,
+        lighting: authoredLighting,
+        backdrop,
+        postProcessing,
+        hasWorldSky: editorLayers?.environment?.preset !== undefined,
+    });
     function withPhaseSync(inner) {
         return (ctx, ...args) => {
             inner?.(ctx, ...args);
@@ -53,8 +65,9 @@ export function defineGame(config) {
             onDispose: composed?.onDispose?.bind(composed) ?? noop,
         },
         GameUI: GameUI ?? emptyUi,
-        environment: environment ??
-            (game.world?.kind === "environment" ? worldBackdrop(game.world) : undefined),
+        environment: isEnvironmentSource(environment) ? undefined :
+            environment ??
+                (game.world?.kind === "environment" ? worldBackdrop(game.world) : undefined),
         camera: camera ?? { perspective: "third" },
         editorLayers,
         editorCatalogs,
@@ -81,10 +94,12 @@ export function defineGame(config) {
         worldItem,
         collision,
         movement,
-        lighting,
-        backdrop,
-        postProcessing,
+        lighting: resolvedLook.lighting ?? (editorLayers === undefined ? undefined : lightingFromDocument(editorLayers) ?? (editorLayers.environment?.pointLights === undefined ? undefined : { point: editorLayers.environment.pointLights })),
+        environmentSource: environmentSource ?? (isEnvironmentSource(environment) ? environment : undefined),
+        backdrop: resolvedLook.backdrop,
+        postProcessing: resolvedLook.postProcessing,
         shadows,
+        graphics,
         presentation,
         objectStyles,
         devtools,

package/dist/devtools/KeysPanel.js

@@ -2,15 +2,15 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { bindingLabel } from "@jgengine/core/input/actionBindings";
 function flattenCodes(codes) {
     if (Array.isArray(codes)) {
-        return [{ codes: codes.map(bindingLabel).join(" / "), mode: "press" }];
+        return [{ codes: codes.map((code) => bindingLabel(code)).join(" / "), mode: "press" }];
     }
     const modes = codes;
     const result = [];
     if (modes.hold !== undefined && modes.hold.length > 0) {
-        result.push({ codes: modes.hold.map(bindingLabel).join(" / "), mode: "hold" });
+        result.push({ codes: modes.hold.map((code) => bindingLabel(code)).join(" / "), mode: "hold" });
     }
     if (modes.toggle !== undefined && modes.toggle.length > 0) {
-        result.push({ codes: modes.toggle.map(bindingLabel).join(" / "), mode: "toggle" });
+        result.push({ codes: modes.toggle.map((code) => bindingLabel(code)).join(" / "), mode: "toggle" });
     }
     return result;
 }

package/dist/drivers/FrameDriver.d.ts

@@ -4,8 +4,9 @@ import type { ActionStateTracker } from "@jgengine/core/input/actionBindings";
 import type { PointerService } from "../pointer/pointerService.js";
 import type { ShellMultiplayer } from "../multiplayer.js";
 import type { PlayableGame } from "../registry.js";
+import type { AuthoritativeFrameHandler } from "../worldSync.js";
 export declare const POSTER_SETTLE_SECONDS = 1.6;
-export declare function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryClickRef, pointerAxisRef, analogRef, gateRef, onRuntimeError, multiplayer, serverIdRef, pointerService, pointerAim, pingCommand, poster, onPosterSettled, }: {
+export declare function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryClickRef, pointerAxisRef, analogRef, gateRef, onRuntimeError, multiplayer, serverIdRef, pointerService, pointerAim, pingCommand, poster, onPosterSettled, authoritativeFrameRef, }: {
     ctx: GameContext;
     playable: PlayableGame;
     tracker: ActionStateTracker<string>;
@@ -37,4 +38,7 @@ export declare function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef,
     pingCommand: string | undefined;
     poster: boolean;
     onPosterSettled: () => void;
+    authoritativeFrameRef: {
+        current: AuthoritativeFrameHandler | null;
+    };
 }): null;

package/dist/drivers/FrameDriver.js

@@ -17,9 +17,10 @@ import { devtools } from "@jgengine/core/devtools/devtools";
 import { collisionDebug } from "../devtools/collisionDebug.js";
 import { GAME_SIM_FRAME_PRIORITY } from "../camera/index.js";
 import { NO_ACTIONS } from "../shellConstants.js";
+import { createPredictionBuffer } from "@jgengine/core/runtime/prediction";
 const TURN_SPEED = 2.4;
 export const POSTER_SETTLE_SECONDS = 1.6;
-export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryClickRef, pointerAxisRef, analogRef, gateRef, onRuntimeError, multiplayer, serverIdRef, pointerService, pointerAim, pingCommand, poster, onPosterSettled, }) {
+export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryClickRef, pointerAxisRef, analogRef, gateRef, onRuntimeError, multiplayer, serverIdRef, pointerService, pointerAim, pingCommand, poster, onPosterSettled, authoritativeFrameRef, }) {
     const posterElapsedRef = useRef(0);
     const posterDoneRef = useRef(false);
     const hasReportedTickError = useRef(false);
@@ -57,6 +58,26 @@ export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryC
     }), [multiplayer, serverAuthoritative, serverIdRef]);
     const lastSentInputRef = useRef(null);
     const inputActions = useMemo(() => Object.keys(playable.game.input ?? {}), [playable]);
+    const predictionRef = useRef(createPredictionBuffer({
+        initial: [0, 0, 0],
+        maxTicks: 120,
+        step: (state) => state,
+        snapThreshold: 0.1,
+    }));
+    const predictionHandler = useMemo(() => (_revision) => {
+        const playerId = ctx.player.possession.active(ctx.player.userId);
+        const player = ctx.scene.entity.get(playerId);
+        if (player === null)
+            return;
+        const prediction = predictionRef.current;
+        const current = player.position;
+        const snapshot = prediction.snapshot();
+        const tick = snapshot.records.at(-1)?.tick ?? snapshot.confirmedTick;
+        const result = prediction.reconcile(tick, current);
+        if (result.snapped)
+            ctx.scene.entity.setPose(playerId, { position: current });
+    }, [ctx]);
+    authoritativeFrameRef.current = serverAuthoritative ? predictionHandler : null;
     useFrame((_state, rawDt) => {
         if (poster) {
             if (posterDoneRef.current)
@@ -71,7 +92,12 @@ export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryC
         const sendInput = () => {
             if (!serverAuthoritative)
                 return;
-            const frame = { held: ctx.input.held(), pointer: ctx.input.pointer(), analog: ctx.input.analog() };
+            const frame = {
+                held: ctx.input.held(),
+                pointer: ctx.input.pointer(),
+                analog: ctx.input.analog(),
+                tick: ctx.sim.tick(),
+            };
             const last = lastSentInputRef.current;
             if (last !== null && inputFramesEqual(last, frame))
                 return;
@@ -88,7 +114,6 @@ export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryC
         try {
             let endPhase = devtools.profile.begin("time+input");
             const dt = Math.min(rawDt, 0.05);
-            const gameDt = ctx.time.advance(dt);
             ctx.input.publish(heldActionsFor(tracker, inputActions));
             ctx.input.publishPointer(pointerAxisRef.current);
             ctx.input.publishAnalog(analogRef.current);
@@ -98,28 +123,40 @@ export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryC
                 yawRef.current = steerYaw(yawRef.current, turnInput, TURN_SPEED, dt);
             endPhase();
             const playerId = ctx.player.possession.active(ctx.player.userId);
-            const player = ctx.scene.entity.get(playerId);
-            if (player !== null && drivesPose && !serverAuthoritative) {
-                endPhase = devtools.profile.begin("pose");
-                stepPlayerMovement(ctx, ctx.player.userId, { held: ctx.input.held(), pointer: ctx.input.pointer(), analog: ctx.input.analog() }, rawDt, movementTuning, yawRef.current);
-                endPhase();
-            }
-            if (autoPickupRadius !== null && !serverAuthoritative) {
-                endPhase = devtools.profile.begin("pickup");
-                const self = ctx.scene.entity.get(playerId);
-                if (self !== null) {
-                    const nearest = ctx.scene.worldItem.nearestInRadius(self.position, autoPickupRadius);
-                    if (nearest !== null)
-                        ctx.scene.worldItem.pickup(nearest, ctx.player.userId);
+            ctx.sim.advance(dt, (stepDt) => {
+                const gameDt = ctx.time.advance(stepDt);
+                ctx.sim.runStages("beforeMovement", stepDt);
+                const player = ctx.scene.entity.get(playerId);
+                // Server-authoritative sessions still run the deterministic local step as a prediction; the
+                // replicated pose is the confirmation that the transport reconciles on the next world diff.
+                if (player !== null && drivesPose) {
+                    const endPose = devtools.profile.begin("pose");
+                    stepPlayerMovement(ctx, ctx.player.userId, { held: ctx.input.held(), pointer: ctx.input.pointer(), analog: ctx.input.analog() }, stepDt, movementTuning, yawRef.current, pitchRef.current);
+                    const predicted = ctx.scene.entity.get(playerId);
+                    if (predicted !== null) {
+                        predictionRef.current.record({ held: ctx.input.held(), pointer: ctx.input.pointer(), analog: ctx.input.analog(), tick: ctx.sim.tick() }, stepDt, predicted.position);
+                    }
+                    endPose();
                 }
-                endPhase();
-            }
-            if (!serverAuthoritative) {
-                devtools.profile.measure("onTick", () => {
-                    playable.loop.onTick(ctx, gameDt);
-                });
-                advanceBehaviors(ctx, gameDt);
-            }
+                ctx.sim.runStages("afterMovement", stepDt);
+                if (autoPickupRadius !== null && !serverAuthoritative) {
+                    const endPickup = devtools.profile.begin("pickup");
+                    const self = ctx.scene.entity.get(playerId);
+                    if (self !== null) {
+                        const nearest = ctx.scene.worldItem.nearestInRadius(self.position, autoPickupRadius);
+                        if (nearest !== null)
+                            ctx.scene.worldItem.pickup(nearest, ctx.player.userId);
+                    }
+                    endPickup();
+                }
+                if (!serverAuthoritative) {
+                    devtools.profile.measure("onTick", () => {
+                        playable.loop.onTick(ctx, gameDt);
+                    });
+                    advanceBehaviors(ctx, gameDt);
+                }
+                ctx.sim.runStages("afterTick", stepDt);
+            });
             endPhase = devtools.profile.begin("actions");
             if (tracker.wasPressed("tabTarget")) {
                 if (ctx.game.commands.has("target.cycle"))

package/dist/drivers/HudOnlyDriver.js

@@ -26,14 +26,19 @@ export function HudOnlyDriver({ ctx, playable, tracker, pointerAxisRef, gateRef,
             try {
                 let endPhase = devtools.profile.begin("time+input");
                 const dt = Math.min(rawDt, 0.05);
-                const gameDt = ctx.time.advance(dt);
                 ctx.input.publish(heldActionsFor(tracker, inputActions));
                 ctx.input.publishPointer(pointerAxisRef.current);
                 endPhase();
-                devtools.profile.measure("onTick", () => {
-                    playable.loop.onTick(ctx, gameDt);
+                ctx.sim.advance(dt, (stepDt) => {
+                    const gameDt = ctx.time.advance(stepDt);
+                    ctx.sim.runStages("beforeMovement", stepDt);
+                    ctx.sim.runStages("afterMovement", stepDt);
+                    devtools.profile.measure("onTick", () => {
+                        playable.loop.onTick(ctx, gameDt);
+                    });
+                    advanceBehaviors(ctx, gameDt);
+                    ctx.sim.runStages("afterTick", stepDt);
                 });
-                advanceBehaviors(ctx, gameDt);
                 endPhase = devtools.profile.begin("actions");
                 const nowMs = performance.now();
                 for (const action of inputActions) {

package/dist/environment/EnvironmentScene.js

@@ -85,7 +85,7 @@ function Vegetation({ grass, field, groundColor, }) {
     const wind = useMemo(() => ({ strength: grass.windStrength }), [grass.windStrength]);
     const colorBase = grass.colors[0];
     const colorTip = grass.colors[grass.colors.length - 1];
-    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(GrassField, { area: area, count: Math.max(1500, Math.min(250000, Math.ceil(grass.density * grass.area.w * grass.area.d))), density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, colorGround: groundColor, wind: wind, edgeFeather: Math.min(8, Math.max(1.5, Math.min(grass.area.w, grass.area.d) * 0.12)), frustumCulled: true }) }));
+    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(GrassField, { area: area, count: Math.max(1500, Math.min(250000, Math.ceil(grass.density * grass.area.w * grass.area.d))), density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, bladeBend: grass.bladeBend, tuftRadius: grass.tuftRadius, colorVariation: grass.colorVariation, normalLift: grass.normalLift, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, colorGround: groundColor, wind: wind, edgeFeather: Math.min(8, Math.max(1.5, Math.min(grass.area.w, grass.area.d) * 0.12)), frustumCulled: true }) }));
 }
 /** Terrain color under a grass patch center — so blade roots blend into the ground they stand on. */
 function vegetationGroundColor(terrain, field, grass) {

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/gamepadSource.d.ts

@@ -0,0 +1,12 @@
+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, }: {
+    tracker: ActionStateTracker<string>;
+    bindings: ActionCodesMap;
+    analogRef: {
+        current: Readonly<Record<string, number>> | null;
+    };
+    input: InputSnapshot;
+}): null;

package/dist/input/gamepadSource.js

@@ -0,0 +1,107 @@
+import { useEffect, useRef } from "react";
+import { useFrame } from "@react-three/fiber";
+import { resolveGamepadFrame, } from "@jgengine/core/input/gamepadModel";
+import { mergeGamepadInput } from "./gamepadMerge.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,
+    };
+}
+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 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 syntheticSnapshot() {
+    if (typeof window === "undefined" || !new URLSearchParams(window.location.search).has("gamepad"))
+        return null;
+    return { id: "Synthetic Gamepad", axes: [0, 0], buttons: [{ pressed: true, value: 1 }], 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());
+    const padBindings = useRef(gamepadCodes(bindings));
+    useEffect(() => {
+        padBindings.current = gamepadCodes(bindings);
+        previousHeld.current.clear();
+        previousAnalog.current.clear();
+        tracker.reset();
+    }, [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)
+                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]);
+    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 },
+                }));
+            }
+        }
+        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/materialOverride.d.ts

@@ -2,7 +2,7 @@ import * as THREE from "three";
 import type { ModelMaterialOverride } from "@jgengine/core/game/playableGame";
 export interface MaterialOverrideOptions {
     clone?: boolean;
-    /** Loaded PBR textures matching `ModelMaterialOverride.maps`' roles, applied onto each `MeshStandardMaterial` alongside the tint override. The caller (a React component, via `useTexture`) owns loading; this function never fetches a URL. */
+    /** Loaded PBR textures matching `ModelMaterialOverride.maps`' roles, applied onto each standard or physical material alongside the tint override. The caller (a React component, via `useTexture`) owns loading; this function never fetches a URL. */
     textures?: MaterialOverrideTextures;
 }
 /** Loaded PBR textures for `applyMaterialOverride`'s `textures` option — matches `ModelMaterialMaps`' roles. */
@@ -11,6 +11,9 @@ export interface MaterialOverrideTextures {
     normal?: THREE.Texture;
     roughness?: THREE.Texture;
     ao?: THREE.Texture;
+    metalness?: THREE.Texture;
+    emissive?: THREE.Texture;
+    height?: THREE.Texture;
 }
 /** @internal */
 export declare function applyMaterialOverride(root: THREE.Object3D, override: ModelMaterialOverride, options?: MaterialOverrideOptions): void;

package/dist/materialOverride.js

@@ -13,7 +13,7 @@ export function applyMaterialOverride(root, override, options) {
     });
 }
 function overrideOne(material, override, clone, textures) {
-    if (!(material instanceof THREE.MeshStandardMaterial))
+    if (!isStandardOrPhysicalMaterial(material))
         return material;
     const target = clone ? material.clone() : material;
     if (override.color !== undefined)
@@ -34,12 +34,21 @@ function overrideOne(material, override, clone, textures) {
         target.roughnessMap = textures.roughness;
     if (textures?.ao !== undefined)
         target.aoMap = textures.ao;
+    if (textures?.metalness !== undefined)
+        target.metalnessMap = textures.metalness;
+    if (textures?.emissive !== undefined)
+        target.emissiveMap = textures.emissive;
+    if (textures?.height !== undefined)
+        target.displacementMap = textures.height;
     if (textures !== undefined)
         target.needsUpdate = true;
     if (override.rim !== undefined)
         applyRimLight(target, override.rim);
     return target;
 }
+function isStandardOrPhysicalMaterial(material) {
+    return material.isMeshStandardMaterial === true;
+}
 /**
  * Adds a fresnel rim term to a standard material's outgoing light. Patched through
  * `onBeforeCompile` rather than as a second pass so the rim shadows, fogs, and tonemaps with the

package/dist/postfx/PostProcessing.d.ts

@@ -6,14 +6,17 @@ import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
  * post chain: RenderPass → GTAO → UnrealBloom → SMAA → OutputPass → Grade. Rendered only
  * when `PlayableGame.postProcessing` is set, so games without it draw unchanged.
  *
- * `quality` (the player's graphics-quality setting) gates the passes whose cost
- * scales with scene geometry or resolution beyond the dpr cap: GTAO re-renders
- * the whole scene for depth/normals and runs a multi-sample full-screen pass,
- * and Bokeh DOF renders scene depth again — both run on "high" only. Bloom,
- * SMAA, tone mapping, and grade stay on every tier (SMAA is the cheap edge fix
- * for alpha-tested foliage that MSAA samples alone leave crawling).
+ * `stages` (resolved from the player's graphics profile) controls expensive passes
+ * independently. Medium keeps AO and DOF with reduced AO sampling; low can disable
+ * them while retaining cheaper bloom, SMAA, tone mapping, and grade stages.
  */
-export declare function PostProcessing({ config, quality }: {
+export declare function PostProcessing({ config, quality, stages }: {
     config: PostProcessingConfig;
     quality?: GraphicsQuality;
+    stages?: {
+        ao: boolean;
+        bloom: boolean;
+        dof: boolean;
+        smaa: boolean;
+    };
 }): null;