@jgengine/shell 0.18.0 → 0.19.0

package/dist/Shell3dPresentation.js

@@ -1,10 +1,12 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Canvas } from "@react-three/fiber";
 import { useMemo, useRef, useState, } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
 import { contextVerbInput, } from "@jgengine/core/interaction/contextMenu";
 import { createSelectionSet, isMarquee, screenRect, selectWithinRect, } from "@jgengine/core/scene/selection";
 import { DEFAULT_PICKUP_RADIUS } from "@jgengine/core/game/worldItem";
 import { CAMERA_FRUSTUM_DEFAULTS } from "@jgengine/core/game/playableGame";
+import { pixelPerfectFrustum, snapPixelPerfectPosition } from "@jgengine/core/game/pixelPerfect";
 import { BUILT_IN_SETTING_CATEGORIES, } from "@jgengine/core/settings/settingsModel";
 import { playControlsActive } from "@jgengine/core/game/controlGate";
 import { sky as resolveSkyDescriptor } from "@jgengine/core/world/features";
@@ -22,6 +24,7 @@ import { DevtoolsRendererProbe } from "./devtools/DevtoolsOverlay.js";
 import { CAMERA_TRANSPARENT_USERDATA, GameCameraRig, PlayerFovProvider, PlayerFovSlider, resolveRigKind, rtsPanKeysConflict, } from "./camera/index.js";
 import { CullingProvider } from "./visibility/CullingProvider.js";
 import { SkyDaylight, TimeOfDayDaylight } from "./environment.js";
+import { bearingFromDirection } from "./environment/daylightCycle.js";
 import { resolveSkyLightOwnership, skyEmitsLights } from "./environment/skyLightingPolicy.js";
 import { EnvironmentScene } from "./environment/EnvironmentScene.js";
 import { PointerProbe } from "./pointer/PointerProbe.js";
@@ -35,17 +38,45 @@ import { TouchControlsDock, TouchPlaySurface, touchDockClearance } from "./touch
 import { SettingsRuntime } from "./settings/SettingsRuntime.js";
 import { SettingsChrome } from "./settings/SettingsChrome.js";
 import { AudioSettingsBridge } from "./settings/appliedSettings.js";
+import { TextureFiltering } from "./render/TextureFiltering.js";
+import { FrameRateLimiter } from "./drivers/FrameRateLimiter.js";
+import { FpsCounter, FpsProbe } from "./diagnostics/FpsCounter.js";
 import { ConfiguredLighting, BackdropFog } from "./render/SceneLighting.js";
 import { WorldView, RemotePlayers } from "./world/WorldScene.js";
 import { FrameDriver } from "./drivers/FrameDriver.js";
+import { GamepadSource } from "./input/gamepadSource.js";
+import { SplitScreenRenderer, useSeatViewports } from "./camera/Viewports.js";
+import { localPlayers } from "@jgengine/core/runtime/localPlayers";
 import { createShellKeyHandlers, ShellDebugOverlays, ShellGameUiChrome } from "./ShellChrome.js";
 import { CombatPresentation } from "./CombatPresentation.js";
+import { WorldParticles } from "./world/WorldParticles.js";
+import { detectKtx2Support } from "./render/modelLoad.js";
 import { resolvePresentationEffects, resolveWorldOverlayBars, } from "./presentationResolve.js";
 const PRIMARY_CLICK_MOVE_THRESHOLD_PX = 6;
 const DEFAULT_BACKGROUND_COLOR = "#14161b";
+function PixelPerfectCamera({ pixelsPerUnit, integerScale }) {
+    const camera = useThree((state) => state.camera);
+    const size = useThree((state) => state.size);
+    useFrame(() => {
+        if (camera.isOrthographicCamera !== true)
+            return;
+        const frustum = pixelPerfectFrustum(size, pixelsPerUnit, integerScale === true);
+        camera.left = frustum.left;
+        camera.right = frustum.right;
+        camera.top = frustum.top;
+        camera.bottom = frustum.bottom;
+        camera.zoom = 1;
+        const snapped = snapPixelPerfectPosition(camera.position, pixelsPerUnit);
+        camera.position.set(snapped.x, snapped.y, snapped.z);
+        camera.updateProjectionMatrix();
+    }, 1);
+    return null;
+}
 /** 3D play surface: canvas, world overlays, and shared chrome. @internal */
-export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, pointerAxisRef, gateRef, wrapperRef, f2HeldRef, yawRef, pitchRef, primaryClickRef, cameraDraggingRef, serverIdRef, remotePlayers, touchScheme, touchSink, touchStyle, touchJoystickVariant, analogRef, orientationGate, orientationGateEl, coarsePointer, compact, graphics, settingsStore, bindingOverrides, rebindAction, resetActionBinding, diagnostics, devtoolsEnabled, devtoolsOpen, setDevtoolsOpen, reportRuntimeError, trackPointerAxis, deactivatePointerAxis, audioEngine, poster, posterFrozen, onPosterSettled, }) {
+export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, pointerAxisRef, gateRef, wrapperRef, f2HeldRef, yawRef, pitchRef, primaryClickRef, cameraDraggingRef, serverIdRef, remotePlayers, touchScheme, touchSink, touchStyle, touchJoystickVariant, analogRef, inputBindings, orientationGate, orientationGateEl, coarsePointer, compact, graphics, settingsStore, bindingOverrides, rebindAction, resetActionBinding, diagnostics, devtoolsEnabled, devtoolsOpen, setDevtoolsOpen, reportRuntimeError, trackPointerAxis, deactivatePointerAxis, audioEngine, poster, posterFrozen, onPosterSettled, authoritativeFrameRef, }) {
     const GameUI = playable.GameUI;
+    const ktx2SupportDetected = useRef(false);
+    const frameTally = useRef({ frames: 0 }).current;
     const WorldOverlay = playable.WorldOverlay;
     const pointerService = useMemo(() => createPointerService(), []);
     const selection = useMemo(() => createSelectionSet(), [playable]);
@@ -67,7 +98,7 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
     const worldSky = resolveWorldSky(playable.game.world);
     const world = playable.game.world;
     const biomeBands = world?.kind === "environment" ? world.terrain?.biomeBands : undefined;
-    const AutoEnvironment = playable.environment ??
+    const AutoEnvironment = (typeof playable.environment === "function" ? playable.environment : undefined) ??
         (world?.kind === "environment"
             ? () => _jsx(EnvironmentScene, { feature: world })
             : world?.kind === "place"
@@ -85,9 +116,13 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
     const cinematicLook = (playable.look ?? "cinematic") !== "flat";
     const backdrop = resolvedLook.backdrop;
     const backdropSky = backdrop?.sky !== undefined ? resolveSkyDescriptor(backdrop.sky) : undefined;
-    const effectiveSky = backdropSky ?? worldSky;
-    const backgroundColor = backdrop?.background ?? (effectiveSky === undefined ? DEFAULT_BACKGROUND_COLOR : undefined);
+    const authoredSky = backdropSky ?? worldSky;
     const lighting = resolvedLook.lighting;
+    const sunFromLighting = lighting?.directional?.[0]?.position;
+    const effectiveSky = useMemo(() => authoredSky === undefined || authoredSky.sun !== undefined || authoredSky.timeOfDay || sunFromLighting === undefined
+        ? authoredSky
+        : { ...authoredSky, sun: bearingFromDirection(sunFromLighting) }, [authoredSky, sunFromLighting]);
+    const backgroundColor = backdrop?.background ?? (effectiveSky === undefined ? DEFAULT_BACKGROUND_COLOR : undefined);
     const orthographic = playable.camera?.projection === "orthographic";
     const pointerDownRef = useRef(null);
     const marqueeStartRef = useRef(null);
@@ -234,6 +269,8 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
         }
     };
     const controlsActive = playControlsActive(ctx);
+    const seatViewports = useSeatViewports(ctx, playable.viewports);
+    const splitScreen = playable.viewports !== undefined && seatViewports.length > 1;
     const settingsDisabled = playable.settings === false;
     const settingsConfig = playable.settings === false || playable.settings === undefined ? {} : playable.settings;
     const settingsSurface = settingsDisabled ? false : settingsConfig.surface ?? false;
@@ -265,7 +302,7 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
         controlsActive: () => playControlsActive(ctx),
         exitPointerLockOnDevtools: true,
     });
-    return (_jsx(SettingsProvider, { store: settingsStore, children: _jsxs(PlayerFovProvider, { config: playable.camera, orthographic: orthographic, children: [_jsx(AudioSettingsBridge, { store: settingsStore, engine: audioEngine, buses: playable.audio?.buses }), _jsx(SettingsRuntime, { variant: settingsVariant, surface: settingsSurface, actions: settingsActions, input: playable.game.input ?? {}, buses: playable.audio?.buses, extra: settingsConfig.extra ?? [], categories: settingsConfig.categories ?? [], hide: hideCategories, fovEnabled: fovControlEnabled, hideBindings: settingsConfig.hideBindings ?? [], touchStyle: coarsePointer &&
+    return (_jsx(SettingsProvider, { store: settingsStore, children: _jsxs(PlayerFovProvider, { config: playable.camera, orthographic: orthographic, children: [_jsx(AudioSettingsBridge, { store: settingsStore, engine: audioEngine, buses: playable.audio?.buses }), _jsx(SettingsRuntime, { variant: settingsVariant, surface: settingsSurface, actions: settingsActions, input: playable.game.input ?? {}, buses: playable.audio?.buses, extra: settingsConfig.extra ?? [], categories: settingsConfig.categories ?? [], hide: hideCategories, fovEnabled: fovControlEnabled, graphics: playable.graphics, hideBindings: settingsConfig.hideBindings ?? [], touchStyle: coarsePointer &&
                         touchScheme !== null &&
                         (touchScheme.joystick !== null || touchScheme.buttons.length > 0), overrides: bindingOverrides, rebind: rebindAction, resetBinding: resetActionBinding, children: _jsx("div", { ref: wrapperRef, tabIndex: 0, ...(poster && posterFrozen ? { "data-poster-ready": "" } : {}), className: "relative h-full w-full bg-neutral-950 outline-none", style: {
                             "--jg-hud-dock-clearance": `${dockMounted ? touchDockClearance(touchScheme, touchScale) : 0}px`,
@@ -279,7 +316,12 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
                             else if (event.deltaY > 0 && ctx.game.commands.has("ui.hotbarScrollPrev")) {
                                 ctx.game.commands.run("ui.hotbarScrollPrev", {});
                             }
-                        }, children: _jsxs(GameViewportProvider, { platforms: playable.platforms, children: [_jsxs(Canvas, { frameloop: poster && posterFrozen ? "demand" : "always", orthographic: orthographic, camera: orthographic
+                        }, children: _jsxs(GameViewportProvider, { platforms: playable.platforms, children: [_jsxs(Canvas, { onCreated: ({ gl }) => {
+                                        if (ktx2SupportDetected.current)
+                                            return;
+                                        ktx2SupportDetected.current = true;
+                                        detectKtx2Support(gl);
+                                    }, frameloop: poster && posterFrozen ? "demand" : graphics.frameRateLimit > 0 && !poster ? "never" : "always", orthographic: orthographic, camera: orthographic
                                         ? {
                                             zoom: playable.camera?.frustum?.zoom ?? CAMERA_FRUSTUM_DEFAULTS.zoom,
                                             near: playable.camera?.frustum?.near ?? CAMERA_FRUSTUM_DEFAULTS.near,
@@ -289,9 +331,16 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
                                             fov: playable.camera?.frustum?.fov ?? CAMERA_FRUSTUM_DEFAULTS.fov,
                                             near: playable.camera?.frustum?.near ?? CAMERA_FRUSTUM_DEFAULTS.near,
                                             far: playable.camera?.frustum?.far ?? CAMERA_FRUSTUM_DEFAULTS.far,
-                                        }, shadows: graphics.shadows, dpr: [Math.min(1, graphics.dpr), graphics.dpr], gl: { preserveDrawingBuffer: true }, style: { touchAction: "none" }, children: [backgroundColor !== undefined ? _jsx("color", { attach: "background", args: [backgroundColor] }) : null, cinematicLook ? (_jsx(EnvironmentLighting, { skyColor: lighting?.hemisphere?.skyColor ?? "#87b5e0", groundColor: lighting?.hemisphere?.groundColor ?? "#3d4a38", sunDirection: lighting?.directional?.[0]?.position, sunColor: lighting?.directional?.[0]?.color ?? "#fff2d6" })) : null, lighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: lighting })) : effectiveSky === undefined ? (_jsxs(_Fragment, { children: [_jsx("ambientLight", { intensity: 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 })] })) : null, effectiveSky !== undefined ? (effectiveSky.timeOfDay ? (_jsx(TimeOfDayDaylight, { sky: effectiveSky, clock: ctx.time, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) })) : (_jsx(SkyDaylight, { sky: effectiveSky, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) }))) : null, _jsx(BackdropFog, { fog: backdrop?.fog }), _jsxs(GameProvider, { context: ctx, children: [_jsx(CullingProvider, { config: playable.visibility, children: _jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, objectStyles: playable.objectStyles, environment: AutoEnvironment, assets: playable.game.assets, renderEntity: playable.renderEntity, renderObject: playable.renderObject, selectedIds: selectedIds, hideLocalActor: firstPerson }) }), WorldOverlay !== undefined ? (_jsx("group", { userData: CAMERA_TRANSPARENT_USERDATA, children: _jsx(WorldOverlay, { ctx: ctx }) })) : null, bars !== null ? (_jsx(WorldEntityBars, { statId: bars.statId, roles: bars.roles, resolveRole: resolveEntityRole, ...(bars.maxDistance === undefined ? {} : { maxDistance: bars.maxDistance }), ...(bars.occlude === undefined ? {} : { occlude: bars.occlude }) })) : null, nameplates !== null ? (_jsx(WorldNameplates, { statId: nameplates.statId, roles: nameplates.roles, resolveRole: resolveEntityRole, ...(nameplates.maxDistance === undefined ? {} : { maxDistance: nameplates.maxDistance }), ...(nameplates.showHealth === undefined ? {} : { showHealth: nameplates.showHealth }) })) : null, _jsx(WorldItems, { config: playable.worldItem }), _jsx(CombatPresentation, { effects: effects }), devtoolsEnabled ? _jsx(CollisionDebugWorld, {}) : null, _jsx(AudioListener, { engine: audioEngine }), _jsx(EntityAudioEmitters, { engine: audioEngine, entitySounds: playable.entitySounds }), _jsx(ObjectAudioEmitters, { engine: audioEngine, objectSounds: playable.objectSounds }), _jsx(GameCameraRig, { yawRef: yawRef, pitchRef: pitchRef, config: cameraConfig, viewmodel: playable.viewmodel, pointerControls: pointerUsesLeft, panKeysEnabled: rtsPanKeysEnabled, director: ctx.camera, onDragChange: (dragging) => {
+                                        }, shadows: graphics.shadows, dpr: [Math.min(1, graphics.dpr), graphics.dpr], gl: { preserveDrawingBuffer: true, powerPreference: "high-performance" }, style: { touchAction: "none" }, children: [_jsx(TextureFiltering, { anisotropy: graphics.profile.anisotropy }), graphics.frameRateLimit > 0 && !poster ? _jsx(FrameRateLimiter, { fps: graphics.frameRateLimit }) : null, graphics.showFps ? _jsx(FpsProbe, { tally: frameTally }) : null, orthographic && playable.camera?.pixelPerfect !== undefined ? (_jsx(PixelPerfectCamera, { ...playable.camera.pixelPerfect })) : null, backgroundColor !== undefined ? _jsx("color", { attach: "background", args: [backgroundColor] }) : null, cinematicLook ? (_jsx(EnvironmentLighting, { source: playable.environmentSource, skyColor: lighting?.hemisphere?.skyColor ?? "#87b5e0", groundColor: lighting?.hemisphere?.groundColor ?? "#3d4a38", sunDirection: lighting?.directional?.[0]?.position, sunColor: lighting?.directional?.[0]?.color ?? "#fff2d6" })) : null, lighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: lighting, profile: graphics.profile })) : effectiveSky === undefined ? (_jsxs(_Fragment, { children: [_jsx("ambientLight", { intensity: 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 })] })) : null, effectiveSky !== undefined ? (effectiveSky.timeOfDay ? (_jsx(TimeOfDayDaylight, { sky: effectiveSky, clock: ctx.time, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) })) : (_jsx(SkyDaylight, { sky: effectiveSky, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) }))) : null, _jsx(BackdropFog, { fog: backdrop?.fog }), _jsxs(GameProvider, { context: ctx, children: [_jsx(CullingProvider, { config: playable.visibility, drawDistance: graphics.profile.drawDistance, children: _jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, objectStyles: playable.objectStyles, environment: AutoEnvironment, assets: playable.game.assets, renderEntity: playable.renderEntity, renderObject: playable.renderObject, selectedIds: selectedIds, hideLocalActor: firstPerson }) }), WorldOverlay !== undefined ? (_jsx("group", { userData: CAMERA_TRANSPARENT_USERDATA, children: _jsx(WorldOverlay, { ctx: ctx }) })) : null, bars !== null ? (_jsx(WorldEntityBars, { statId: bars.statId, roles: bars.roles, resolveRole: resolveEntityRole, ...(bars.maxDistance === undefined ? {} : { maxDistance: bars.maxDistance }), ...(bars.occlude === undefined ? {} : { occlude: bars.occlude }) })) : null, nameplates !== null ? (_jsx(WorldNameplates, { statId: nameplates.statId, roles: nameplates.roles, resolveRole: resolveEntityRole, ...(nameplates.maxDistance === undefined ? {} : { maxDistance: nameplates.maxDistance }), ...(nameplates.showHealth === undefined ? {} : { showHealth: nameplates.showHealth }) })) : null, _jsx(WorldItems, { config: playable.worldItem }), _jsx(WorldParticles, { quality: graphics.quality, particleCap: graphics.profile.particleCap }), _jsx(CombatPresentation, { effects: effects }), devtoolsEnabled ? _jsx(CollisionDebugWorld, {}) : null, _jsx(AudioListener, { engine: audioEngine }), _jsx(EntityAudioEmitters, { engine: audioEngine, entitySounds: playable.entitySounds }), _jsx(ObjectAudioEmitters, { engine: audioEngine, objectSounds: playable.objectSounds }), _jsx(GameCameraRig, { yawRef: yawRef, pitchRef: pitchRef, config: cameraConfig, viewmodel: playable.viewmodel, pointerControls: pointerUsesLeft, panKeysEnabled: rtsPanKeysEnabled, director: ctx.camera, onDragChange: (dragging) => {
                                                         cameraDraggingRef.current = dragging;
-                                                    } }), _jsx(PointerProbe, { service: pointerService })] }), _jsx(RemotePlayers, { rows: remotePlayers }), _jsx(FrameDriver, { ctx: ctx, playable: playable, tracker: tracker, yawRef: yawRef, pitchRef: pitchRef, primaryClickRef: primaryClickRef, pointerAxisRef: pointerAxisRef, analogRef: analogRef, gateRef: gateRef, onRuntimeError: reportRuntimeError, multiplayer: multiplayer, serverIdRef: serverIdRef, pointerService: pointerService, pointerAim: pointer?.aim === true, pingCommand: pointer?.pingCommand, poster: poster, onPosterSettled: onPosterSettled }), _jsx(DevtoolsRendererProbe, {}), resolvedLook.postProcessing !== undefined && resolvedLook.postProcessing.enabled !== false ? (_jsx(PostProcessing, { config: resolvedLook.postProcessing, quality: graphics.quality })) : null] }), !poster &&
+                                                    } }), _jsx(PointerProbe, { service: pointerService })] }), _jsx(RemotePlayers, { rows: remotePlayers }), _jsx(FrameDriver, { ctx: ctx, playable: playable, tracker: tracker, yawRef: yawRef, pitchRef: pitchRef, primaryClickRef: primaryClickRef, pointerAxisRef: pointerAxisRef, analogRef: analogRef, gateRef: gateRef, onRuntimeError: reportRuntimeError, multiplayer: multiplayer, serverIdRef: serverIdRef, pointerService: pointerService, pointerAim: pointer?.aim === true, pingCommand: pointer?.pingCommand, poster: poster, onPosterSettled: onPosterSettled, authoritativeFrameRef: authoritativeFrameRef }), _jsx(GamepadSource, { tracker: tracker, bindings: inputBindings ?? {}, analogRef: analogRef, input: ctx.input, feel: playable.gamepad, seats: localPlayers(ctx), onSeatJoin: (slot) => {
+                                                try {
+                                                    playable.loop.onNewPlayer(ctx, { userId: slot.userId, isNew: true });
+                                                }
+                                                catch (error) {
+                                                    reportRuntimeError(error, "tick");
+                                                }
+                                            }, seatsActive: () => !gateRef.current && playControlsActive(ctx) }), _jsx(DevtoolsRendererProbe, {}), splitScreen ? (_jsx(SplitScreenRenderer, { ctx: ctx, viewports: seatViewports, config: playable.viewports, mainCamera: playable.camera })) : null, !splitScreen && resolvedLook.postProcessing !== undefined && resolvedLook.postProcessing.enabled !== false ? (_jsx(PostProcessing, { config: resolvedLook.postProcessing, quality: graphics.quality, stages: graphics.profile.postStages })) : null] }), graphics.showFps && !poster ? _jsx(FpsCounter, { tally: frameTally }) : null, !poster &&
                                     !orientationGate &&
                                     coarsePointer &&
                                     controlsActive &&

package/dist/ShellChrome.d.ts

@@ -26,10 +26,12 @@ export declare function ShellDebugOverlays({ ctx, playable, multiplayer, diagnos
 export type ShellKeyHandlers = {
     onKeyDown: (event: {
         code: string;
+        target?: EventTarget | null;
         preventDefault: () => void;
     }) => void;
     onKeyUp: (event: {
         code: string;
+        target?: EventTarget | null;
     }) => void;
     onBlur: () => void;
 };

package/dist/ShellChrome.js

@@ -16,6 +16,12 @@ export function ShellDebugOverlays({ ctx, playable, multiplayer, diagnostics, de
 export function createShellKeyHandlers({ f2HeldRef, tracker, devtoolsEnabled, setDevtoolsOpen, controlsActive, exitPointerLockOnDevtools = false, }) {
     return {
         onKeyDown: (event) => {
+            const target = event.target;
+            if (target?.closest?.("input, textarea, select, [contenteditable]:not([contenteditable=false])")) {
+                f2HeldRef.current = false;
+                tracker.reset();
+                return;
+            }
             if (event.code === "F2") {
                 event.preventDefault();
                 f2HeldRef.current = true;

package/dist/ShellHudPresentation.d.ts

@@ -1,4 +1,4 @@
-import type { Dispatch, MutableRefObject, RefObject, SetStateAction } from "react";
+import { type Dispatch, type MutableRefObject, type RefObject, type SetStateAction } from "react";
 import type { PointerAxisState } from "@jgengine/core/input/pointerAxis";
 import type { ActionStateTracker } from "@jgengine/core/input/actionBindings";
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
@@ -6,6 +6,14 @@ import type { TouchScheme } from "@jgengine/core/input/touchScheme";
 import type { RuntimeDiagnostic } from "./diagnostics/RuntimeDiagnostics.js";
 import type { ShellMultiplayer } from "./multiplayer.js";
 import type { PlayableGame } from "./registry.js";
+/**
+ * Marks a HUD-only page ready for capture (`data-jg-capture="ready"`) unless a capture host already
+ * owns the flag. A HUD game has no `<canvas>`, so capture tools that wait for one would time out.
+ * @internal
+ */
+export declare function markHudCaptureReady(root: {
+    dataset: DOMStringMap;
+}): void;
 /** HUD-only play surface for non-3D shells. @internal */
 export declare function ShellHudPresentation({ playable, ctx, multiplayer, tracker, pointerAxisRef, gateRef, wrapperRef, f2HeldRef, yawRef, pitchRef, touchScheme, touchSink, orientationGate, orientationGateEl, coarsePointer, uiScale, diagnostics, devtoolsEnabled, devtoolsOpen, setDevtoolsOpen, reportRuntimeError, trackPointerAxis, deactivatePointerAxis, onPointerResumeAudio, }: {
     playable: PlayableGame;

package/dist/ShellHudPresentation.js

@@ -1,12 +1,33 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect } from "react";
 import { playControlsActive } from "@jgengine/core/game/controlGate";
 import { GameViewportProvider } from "@jgengine/react/gameViewport";
 import { HudOnlyDriver } from "./drivers/HudOnlyDriver.js";
 import { createShellKeyHandlers, ShellDebugOverlays, ShellGameUiChrome } from "./ShellChrome.js";
 import { TouchPlaySurface } from "./touch/TouchControlsOverlay.js";
+/**
+ * Marks a HUD-only page ready for capture (`data-jg-capture="ready"`) unless a capture host already
+ * owns the flag. A HUD game has no `<canvas>`, so capture tools that wait for one would time out.
+ * @internal
+ */
+export function markHudCaptureReady(root) {
+    if (root.dataset.jgCapture === undefined)
+        root.dataset.jgCapture = "ready";
+}
 /** HUD-only play surface for non-3D shells. @internal */
 export function ShellHudPresentation({ playable, ctx, multiplayer, tracker, pointerAxisRef, gateRef, wrapperRef, f2HeldRef, yawRef, pitchRef, touchScheme, touchSink, orientationGate, orientationGateEl, coarsePointer, uiScale, diagnostics, devtoolsEnabled, devtoolsOpen, setDevtoolsOpen, reportRuntimeError, trackPointerAxis, deactivatePointerAxis, onPointerResumeAudio, }) {
     const GameUI = playable.GameUI;
+    useEffect(() => {
+        // Two frames so the first GameUI paint has landed before tools capture.
+        let second = 0;
+        const first = requestAnimationFrame(() => {
+            second = requestAnimationFrame(() => markHudCaptureReady(document.documentElement));
+        });
+        return () => {
+            cancelAnimationFrame(first);
+            cancelAnimationFrame(second);
+        };
+    }, []);
     const keys = createShellKeyHandlers({
         f2HeldRef,
         tracker,

package/dist/TerritoryOverlay.d.ts

@@ -0,0 +1,21 @@
+import type { CSSProperties, ReactNode } from "react";
+/** A placement footprint cell and its authoritative preview status. */
+export type TerritoryPreviewCell = {
+    key: string;
+    x: number;
+    z: number;
+    status: "owned" | "claimable" | "blocked";
+};
+/**
+ * Placement footprint feedback with inline claim cost and affordability.
+ * @capability territory-overlay show footprint ownership, claim cost, and affordability
+ */
+export declare function TerritoryOverlay({ cells, cost, affordable, formatCost, renderCell, className, style }: {
+    cells: readonly TerritoryPreviewCell[];
+    cost: number;
+    affordable: boolean;
+    formatCost?: (cost: number) => ReactNode;
+    renderCell?: (cell: TerritoryPreviewCell) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;

package/dist/TerritoryOverlay.js

@@ -0,0 +1,9 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Placement footprint feedback with inline claim cost and affordability.
+ * @capability territory-overlay show footprint ownership, claim cost, and affordability
+ */
+export function TerritoryOverlay({ cells, cost, affordable, formatCost = String, renderCell, className, style }) {
+    const blocked = cells.some((cell) => cell.status === "blocked");
+    return _jsxs("div", { className: className, style: { pointerEvents: "none", ...style }, "data-territory-overlay": true, children: [_jsx("div", { style: { display: "flex", gap: 3 }, children: cells.map((cell) => _jsx("span", { "data-territory-cell": cell.status, title: `${cell.x}, ${cell.z}: ${cell.status}`, children: renderCell ? renderCell(cell) : _jsx("span", { "aria-label": cell.status, style: { display: "inline-block", width: 8, height: 8, borderRadius: 2, background: cell.status === "owned" ? "var(--jg-accent, #5fc2a8)" : cell.status === "claimable" ? "#d6a548" : "#d96969" } }) }, cell.key)) }), _jsx("output", { "aria-live": "polite", "data-affordable": affordable, "data-blocked": blocked, children: blocked ? "Land unavailable" : _jsxs(_Fragment, { children: ["Land: ", formatCost(cost), affordable ? "" : " — Insufficient funds"] }) })] });
+}

package/dist/audio/AudioComponents.js

@@ -1,10 +1,21 @@
 import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
+import { Quaternion, Vector3 } from "three";
 import { useGameContext } from "@jgengine/react/provider";
+import { createListenerVelocityTrack, stepListenerVelocity } from "./loopParams.js";
 export function AudioListener({ engine }) {
     const camera = useThree((state) => state.camera);
-    useFrame(() => {
-        engine.setListenerPose({ x: camera.position.x, y: camera.position.y, z: camera.position.z });
+    const trackRef = useRef(createListenerVelocityTrack());
+    useFrame((_, dt) => {
+        const direction = camera.getWorldDirection(new Vector3());
+        const up = camera.up.clone().applyQuaternion(camera.getWorldQuaternion(new Quaternion()));
+        const position = { x: camera.position.x, y: camera.position.y, z: camera.position.z };
+        engine.setListenerPose({
+            position,
+            forward: { x: direction.x, y: direction.y, z: direction.z },
+            up: { x: up.x, y: up.y, z: up.z },
+            velocity: stepListenerVelocity(trackRef.current, position, dt),
+        });
     });
     return null;
 }

package/dist/audio/audioEngine.d.ts

@@ -6,6 +6,14 @@ export interface Vec3 {
     y: number;
     z: number;
 }
+/** Position and orientation for a spatial-audio listener. */
+export interface ListenerPose {
+    position: Vec3;
+    forward: Vec3;
+    up: Vec3;
+    /** World velocity of the listener, for doppler on loops whose sound declares `doppler`. Default zero. */
+    velocity?: Vec3;
+}
 export interface AudioSceneConfig {
     sounds?: Record<string, SoundDef>;
     buses?: Record<string, AudioBusDef>;
@@ -20,10 +28,16 @@ export interface AudioEmitterHandle {
     setRate(rate: number): void;
     /** Live volume of a retained loop: `gain` scales the source (0–1), clamped and ramped ~20 ms (#1051). */
     setGain(gain: number): void;
+    /** Live lowpass cutoff of a retained loop in Hz, clamped and ramped like rate. */
+    setLowpass(hz: number): void;
+    /** Live highpass cutoff of a retained loop in Hz, clamped and ramped like rate. */
+    setHighpass(hz: number): void;
+    /** Emitter world velocity for doppler; ignored unless the sound declares `doppler`. */
+    setVelocity(velocity: Vec3): void;
     stop(): void;
 }
 export interface AudioEngine {
-    setListenerPose(position: Vec3): void;
+    setListenerPose(pose: ListenerPose | Vec3): void;
     playOneShot(soundId: string, position?: Vec3): void;
     playLoop(soundId: string, position?: Vec3): AudioEmitterHandle | null;
     /** Crossfade the procedural soundtrack to `themeId` (null fades out). No-op when no `music` catalog is configured. */

package/dist/audio/audioEngine.js

@@ -1,11 +1,13 @@
 import { distance3, resolveEmitterGain } from "@jgengine/core/audio/audioFalloff";
+import { dopplerRate } from "@jgengine/core/audio/doppler";
 import { patchDuration } from "@jgengine/core/audio/synth";
 import { createDisposer } from "@jgengine/core/game/defineGame";
-import { clampLoopGain, clampLoopRate } from "./loopParams.js";
+import { clampLoopCutoff, clampLoopGain, clampLoopRate, MIN_LOOP_CUTOFF, MAX_LOOP_CUTOFF } from "./loopParams.js";
 import { MusicDirector } from "./musicDirector.js";
 import { createNoiseBuffer, realizeSynthPatch } from "./synthEngine.js";
 /** setTargetAtTime time constant (~20 ms) for zipper-free live rate/gain ramps on retained loops (#1051). */
 const LOOP_PARAM_SMOOTH_TC = 0.02;
+const ZERO_VELOCITY = { x: 0, y: 0, z: 0 };
 function createNoopEngine() {
     return {
         setListenerPose: () => undefined,
@@ -30,6 +32,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 ?? {};
@@ -111,12 +142,17 @@ export function createAudioEngine(config = {}) {
         return pending;
     }
     let listenerPosition = { x: 0, y: 0, z: 0 };
+    let listenerVelocity = { x: 0, y: 0, z: 0 };
+    const nyquist = context.sampleRate / 2;
     const activeSpatialUpdaters = new Set();
     const activeLoops = new Set();
     const NOOP_HANDLE = {
         setPosition: () => undefined,
         setRate: () => undefined,
         setGain: () => undefined,
+        setLowpass: () => undefined,
+        setHighpass: () => undefined,
+        setVelocity: () => undefined,
         stop: () => undefined,
     };
     function playInternal(soundId, position, loop) {
@@ -128,8 +164,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;
         }
@@ -149,13 +194,34 @@ export function createAudioEngine(config = {}) {
         // Live control state, applied on source creation so updates that race the async buffer load stick.
         let currentRate = 1;
         let currentUserGain = 1;
+        let currentLowpass = MAX_LOOP_CUTOFF;
+        let currentHighpass = MIN_LOOP_CUTOFF;
+        let currentVelocity = { x: 0, y: 0, z: 0 };
+        const dopplerFactor = loop ? sound.doppler ?? 0 : 0;
         let sourceNode = null;
+        let lowpassNode = null;
+        let highpassNode = null;
         let userGainNode = null;
         let falloffGain = null;
+        let pannerNode = null;
+        function effectiveRate() {
+            if (dopplerFactor === 0)
+                return currentRate;
+            const shift = dopplerRate([listenerPosition.x, listenerPosition.y, listenerPosition.z], [listenerVelocity.x, listenerVelocity.y, listenerVelocity.z], [currentPosition.x, currentPosition.y, currentPosition.z], [currentVelocity.x, currentVelocity.y, currentVelocity.z], { factor: dopplerFactor });
+            return clampLoopRate(currentRate * shift);
+        }
+        function applyRate() {
+            if (sourceNode !== null)
+                sourceNode.playbackRate.setTargetAtTime(effectiveRate(), context.currentTime, LOOP_PARAM_SMOOTH_TC);
+        }
         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);
+            if (dopplerFactor !== 0)
+                applyRate();
         }
         void bufferPromise.then((buffer) => {
             if (buffer === null)
@@ -163,15 +229,39 @@ export function createAudioEngine(config = {}) {
             const src = context.createBufferSource();
             src.buffer = buffer;
             src.loop = loop || (sound.loop ?? false);
-            src.playbackRate.value = currentRate;
-            // source → per-loop user gain (setGain) → distance falloff → bus
+            src.playbackRate.value = effectiveRate();
+            // source → [lowpass → highpass, loops only] → per-loop user gain (setGain) → distance falloff → bus
             const uGain = context.createGain();
             uGain.gain.value = currentUserGain;
             const fGain = context.createGain();
             fGain.gain.value = resolveEmitterGain(distance3(currentPosition, listenerPosition), sound, 1);
-            src.connect(uGain);
+            if (loop) {
+                const lp = context.createBiquadFilter();
+                lp.type = "lowpass";
+                lp.frequency.value = clampLoopCutoff(currentLowpass, MAX_LOOP_CUTOFF, nyquist);
+                const hp = context.createBiquadFilter();
+                hp.type = "highpass";
+                hp.frequency.value = clampLoopCutoff(currentHighpass, MIN_LOOP_CUTOFF, nyquist);
+                src.connect(lp);
+                lp.connect(hp);
+                hp.connect(uGain);
+                lowpassNode = lp;
+                highpassNode = hp;
+            }
+            else {
+                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;
@@ -183,9 +273,14 @@ export function createAudioEngine(config = {}) {
                 catch {
                 }
                 src.disconnect();
+                lowpassNode?.disconnect();
+                highpassNode?.disconnect();
                 uGain.disconnect();
                 fGain.disconnect();
+                pannerNode?.disconnect();
                 sourceNode = null;
+                lowpassNode = null;
+                highpassNode = null;
                 userGainNode = null;
                 falloffGain = null;
             });
@@ -199,8 +294,22 @@ export function createAudioEngine(config = {}) {
             },
             setRate(rate) {
                 currentRate = clampLoopRate(rate);
-                if (sourceNode !== null)
-                    sourceNode.playbackRate.setTargetAtTime(currentRate, context.currentTime, LOOP_PARAM_SMOOTH_TC);
+                applyRate();
+            },
+            setLowpass(hz) {
+                currentLowpass = clampLoopCutoff(hz, MAX_LOOP_CUTOFF, nyquist);
+                if (lowpassNode !== null)
+                    lowpassNode.frequency.setTargetAtTime(currentLowpass, context.currentTime, LOOP_PARAM_SMOOTH_TC);
+            },
+            setHighpass(hz) {
+                currentHighpass = clampLoopCutoff(hz, MIN_LOOP_CUTOFF, nyquist);
+                if (highpassNode !== null)
+                    highpassNode.frequency.setTargetAtTime(currentHighpass, context.currentTime, LOOP_PARAM_SMOOTH_TC);
+            },
+            setVelocity(velocity) {
+                currentVelocity = velocity;
+                if (dopplerFactor !== 0)
+                    applyRate();
             },
             setGain(gain) {
                 currentUserGain = clampLoopGain(gain);
@@ -219,7 +328,19 @@ 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;
+            listenerVelocity = "velocity" in pose && pose.velocity !== undefined ? pose.velocity : ZERO_VELOCITY;
+            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/audio/audioWire.d.ts

@@ -17,6 +17,9 @@ type AudioLoopSetPayload = {
     rate?: number;
     gain?: number;
     at?: readonly [number, number, number];
+    velocity?: readonly [number, number, number];
+    lowpass?: number;
+    highpass?: number;
 };
 type AudioLoopStopPayload = {
     id: string;

package/dist/audio/audioWire.js

@@ -29,7 +29,7 @@ export function attachAudioEventWire(events, audioEngine) {
         if (handle !== null)
             loops.set(id, { sound, handle });
     });
-    const offLoopSet = events.on("audio.loopSet", ({ id, rate, gain, at }) => {
+    const offLoopSet = events.on("audio.loopSet", ({ id, rate, gain, at, velocity, lowpass, highpass }) => {
         const entry = loops.get(id);
         // Unknown id: a live update may race a stop — silently drop it.
         if (entry === undefined)
@@ -40,6 +40,12 @@ export function attachAudioEventWire(events, audioEngine) {
             entry.handle.setGain(gain);
         if (at !== undefined)
             entry.handle.setPosition({ x: at[0], y: at[1], z: at[2] });
+        if (velocity !== undefined)
+            entry.handle.setVelocity({ x: velocity[0], y: velocity[1], z: velocity[2] });
+        if (lowpass !== undefined)
+            entry.handle.setLowpass(lowpass);
+        if (highpass !== undefined)
+            entry.handle.setHighpass(highpass);
     });
     const offLoopStop = events.on("audio.loopStop", ({ id }) => {
         const entry = loops.get(id);

package/dist/audio/loopParams.d.ts

@@ -18,3 +18,42 @@ export declare function clampLoopRate(rate: number): number;
  * @internal — the audio engine applies this; game code sets gain through `ctx.game.audio.setLoop`.
  */
 export declare function clampLoopGain(gain: number): number;
+/** Lowest live filter cutoff, Hz. */
+export declare const MIN_LOOP_CUTOFF = 10;
+/** Highest live filter cutoff, Hz; the engine also caps it at the context's Nyquist frequency. */
+export declare const MAX_LOOP_CUTOFF = 22050;
+/**
+ * Clamp a loop filter cutoff into `MIN_LOOP_CUTOFF`–`min(MAX_LOOP_CUTOFF, nyquist)` Hz. Non-finite input
+ * falls back to `fallback` (the open, transparent end of that filter).
+ * @internal — the audio engine applies this; game code sets cutoffs through `ctx.game.audio.setLoop`.
+ */
+export declare function clampLoopCutoff(hz: number, fallback: number, nyquist?: number): number;
+/** Smoothed listener velocity estimate from per-frame camera positions. @internal */
+export interface ListenerVelocityTrack {
+    last: {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+    velocity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/** @internal */
+export declare function createListenerVelocityTrack(): ListenerVelocityTrack;
+/**
+ * Advance the listener velocity estimate by one frame: the position delta over `dt`, eased with a
+ * ~50 ms time constant so frame-time jitter does not warble doppler. A cut resets it to zero.
+ * @internal
+ */
+export declare function stepListenerVelocity(track: ListenerVelocityTrack, position: {
+    x: number;
+    y: number;
+    z: number;
+}, dt: number): {
+    x: number;
+    y: number;
+    z: number;
+};