@jgengine/shell 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -26,6 +26,102 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.23.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.23.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.20.0`; `@jgengine/github` is `0.10.0`.
+
+### Added
+
+- `player_pose` agent-bridge verb (`@jgengine/shell`, `window.__jgengineAgent`, `drive --rpc '{"method":"player_pose"}'`) returns the local player's position and heading, and `debug_snapshot` carries the same `player` field, so a drive can prove movement from position deltas instead of screenshots.
+- `sim_advance` agent-bridge verb (`@jgengine/shell`, `drive --rpc '{"method":"sim_advance","seconds":30}'`) steps the mounted sim driver — input, movement, `onTick`, behaviors, bound actions — in 0.05 s frames without rendering, so a headless drive can reach waves, shifts and timers that never arrive at software-rendered frame rates. Capped at 120 s per call.
+- `time_scale` agent-bridge verb sets the game clock's timescale and reports `{ timescale, now }`.
+- `GameContextObjectEntry.scenery` (`@jgengine/core`): an object kind placed once and left alone. Its runtime placements now render through the shared instanced static-object batches that editor-authored props already used.
+- `BUILDING_STYLE_PROBABILITIES` and `resolveBuildingProbabilities` (`@jgengine/core/world/buildings`): each `BuildingStyle` now carries facade-part probabilities, so an industrial yard shows few windows and roof plant, a ruin loses awnings and clotheslines, coastal fronts gain awnings. `building({ probabilities })` overrides any part.
+- `debug_summary` agent-bridge verb and `debug_snapshot` `detail: "summary"`: fps, frame/sim ms, draw calls, triangles, entities, warnings and top culprit in about 1 KB. `drive --rpc '{"method":"debug_snapshot"}'` prints the summary; `"detail":"full"` keeps the full snapshot.
+- `modelLoadStarts()` (`@jgengine/shell/render/modelLoad`) counts model streaming bursts for capture quiescence checks.
+- `jgengine` warns when it is not the CLI the caller meant: a global install run inside a jgengine checkout, a project-local `jgengine` shadowed, or a CLI built for an older SDK than the project installs. Harness runs print the CLI version and harness revision.
+- `withGraphicsQualityOverride` and `parseGraphicsQuality` (`@jgengine/core/settings/graphicsSettings`) pin a graphics tier for one session without persisting it.
+- The player shell reads `?quality=<tier>` and pins that tier for the page. `bun run shoot`/`drive --quality draft` use it (low tier, half size) for fast iteration shots; `--quality full` stays the default for PR evidence.
+- `jgengine doctor` flags a silent game: one that neither declares `defineGame({ audio })` cues nor calls `ctx.game.audio.play`/`loop`. Four reference games shipped without a single sound; the fix text points at procedural `SoundDef` synth patches, which need no asset files.
+- `drive --key mouse0:<ms>` (also `mouse1`, `mouse2`) holds that mouse button over the play canvas, matching the shell's pointer binding codes, so hold-to-fire weapons can be driven headlessly. Keyboard codes are unchanged.
+- `drive --right-click-at x,y` sends a native right click in CSS viewport pixels, so RTS move/attack/gather orders and context actions can be driven headlessly; `--click-at` stays a left click.
+- `ctx.scene.entity.selection` (`@jgengine/core`): the player's selected entities as a reactive `SelectionSet`. The shell pointer (`pointer.select` click / marquee) now writes it instead of private component state, so game HUDs can show the selected unit's card or a "3 units selected" summary and can set the selection themselves (select-all, control groups); the selection ring follows either way. Despawned ids drop out.
+- `LightingConfig.iblAmbientScale` (default 0.5) and `LightingConfig.fallbackKey` (default true); `balanceLightingForIbl` in `@jgengine/core/render/lightingBalance` applies them.
+- `DirectionalLightingConfig.shadowRadius` (PCF penumbra in texels, default 1.25).
+- `DEFAULT_AO` in `@jgengine/core/render/postProcessing` and `mergePostProcessing` in `@jgengine/core/render/lookPreset`.
+- Loaded GLB models get a default painted finish: flat-colour, vertex-colour and palette-atlas materials have their exported roughness/metalness/`envMapIntensity` normalized and compile with one shared object-space detail shader (mottling, wear, roughness break-up, micro-normal, cavity). Normal-mapped, cutout and transparent materials are untouched.
+- `GraphicsProfile.surfaceDetail` (`"off" | "lite" | "full"`, `@jgengine/core/settings/graphicsProfile`): `"lite"` on low, `"full"` on medium and up.
+- `ModelConfig.surfaceDetail: false` opts one model out; `defineGame({ surfaceDetail: false })` opts a game out.
+- `createSurfaceRibbonMaterial`, `ribbonSurfaceFrame`, `resolvePathSurface` and `useSurfaceRibbonMaterial` (`@jgengine/shell/terrain`) shade ground ribbons with the terrain's procedural surface functions, plus wear and a noise-warped soft edge.
+- `road({ surface })` (`@jgengine/core/world/features`) picks the carriageway surface; `false` keeps flat colour.
+- `AuthoredScene`/`AuthoredPaths` `pathSurfaceDetail`/`surfaceDetail` props and path `meta.surface`, `meta.edgeSoftness`, `meta.wear`, `meta.surfaceDetail`.
+- `EditableTerrain.gridBounds` (`@jgengine/core/world/terraform`) exposes the world extent of the paint/height cell grid.
+- Painted terrain renders each layer's `surface` as its own procedural ground (grass, dirt, gravel, rock, sand, mud, snow, road) with albedo variation, roughness and micro-normals, blended along noise-warped, height-aware edges, in play and in the editor viewport. No game config or assets needed.
+- `TerrainDetailConfig.surfaceStrength` (0..1, default 1) scales the per-surface response; `detail: false` opts a terrain out to the flat vertex-colour ground.
+- `@jgengine/shell/terrain` exports `packTerrainPaintWeights`, `createTerrainPaintTextures`, `terrainSurfaceClass`, `createTerrainDetailMaterial` and `TerrainQualityContext`/`useTerrainQuality`.
+- `ctx.game.notices` (`@jgengine/core/game/notices`, `createNoticeFeed`): a player-facing notice feed with info/success/warn/deny tones, stacking dedupe (repeats show ×N and refresh their lifetime), a cap, TTL, `onPush`, `retune` and `snapshot`/`restore`. Pure state on the context clock, so headless and hosted runs are unaffected.
+- The shell mounts `NoticeStack` (`@jgengine/react/notices`) for every game: animated toned cards below top HUD bars, 14px text on `--jg-*` vars with fallbacks, no pointer capture. Configure with `notices: { placement, hidden, refusals, cues, cap, ttlMs }` or remove with `notices: false`.
+- Refusal feedback: `validate` may return `{ reason, message }`. `reason` stays the machine code; a `message` is shown automatically as a deduped deny notice with the deny cue when the local player's command is refused, locally or from a host. `ctx.game.commands` emits a `command.refused` event for every refusal; `attachRefusalNotices` is the headless hookup.
+- UI sound cues: `useUiCue()` / `playUiCue` (`@jgengine/react/uiCues`) play `click`, `hover`, `open`, `close`, `confirm`, `deny`, `notify`. Soft procedural defaults (`@jgengine/core/audio/uiCues`) mix on a new "ui" bus with a "UI volume" setting under master volume. A game sound named `ui.<cue>` replaces one; `audio.uiCues` overrides or silences cues (`false` for all).
+- `notice_push` and `run_command` agent-bridge verbs for `drive --rpc`.
+- `ui-feedback` dev probe (apps/dev) exercising refusals, the feed and cues.
+- `HudTheme` gains a type scale with a 12px floor, spacing, motion (durations and easings), elevation (layered shadows and a lit top rim), and hover/press/focus/disabled state tokens; `hudThemeVars` emits them as `--jg-type-*`, `--jg-space-*`, `--jg-motion-*`, `--jg-ease*`, `--jg-elevation-*`, `--jg-highlight`, `--jg-hover-*`, `--jg-press-*`, `--jg-focus-ring`, and `--jg-disabled-opacity`. `@jgengine/react/hudTokens` reads them in inline styles (`hudType`, `hudSpace`, `hudTransition`, `hudElevation`, `hudFont`, `HUD_FOCUS_RING`).
+- Engine stylesheet `@jgengine/react/styles.css` (also `ENGINE_STYLESHEET` / `useEngineStyles` in `@jgengine/react/engineStyles`): every `jg-*` keyframe the shared blocks and registry use, `[data-jg-*]` interaction states, quiet hover/press/focus defaults for plain HUD buttons, and reduced-motion handling for `prefers-reduced-motion` and `[data-reduced-motion="true"]`. The `jgengine create` template imports it.
+- `HudThemeRoot`: the shell wraps every `GameUI` in it, applying `defaultHudTheme` and the stylesheet. `defineGame({ hudTheme })` swaps the root theme; `hudTheme: false` opts out.
+- Primitives `HudButton`, `HudPanel` (open/close transition via `usePresence`), and `TweenNumber` / `useTweenedValue` with an up/down delta flash; `useReducedMotion` in `@jgengine/react/accessibility`.
+- `HudInteractProvider` / `useHudInteract`, plus `cue` and `onInteract` on the primitives, windows, modals, and `ActionButton`: one seam for a UI sound system.
+
+### Changed
+
+- Static-object batches group same-model props per 64 m cell from 3 placements (was 24 m cells and more than 8), so sparse city dressing such as palms, lamps and benches shares draws. Harbor Heat's opening drops from 5,310 to 4,650 draw calls.
+- `building()` districts with a non-generic `style` generate a different facade mix than before (previously a style changed colours only). `generic` is unchanged.
+- `bun run shoot/drive` and the scaffolded/bundled `shoot.mjs`/`drive.mjs` parse one shared flag table: `--click-at`, `--right-click-at`, `--width`, `--height`, `--port`, `--size`, `--settle`, `--param`, `--probe`, `--reload`, key chords and mouse holds work in both; unknown flags fail instead of being ignored or taken as a game id; dev-runner-only flags are refused by name in the portable harness.
+- Play-mode capture readiness waits until staged `--state`/`--run` commands have ticked, their entities mounted and model streaming stopped, and never declares ready over "Loading game view…". A rejected staged command fails the capture.
+- Play-mode captures of a game with a start menu and no `capture.play` click its start action and report what they clicked.
+- Monorepo tests, type-checks and `bun run gen` resolve `@jgengine/*` to package source through the `paths` in `tsconfig.base.json` (`bun run gen:source-paths` keeps every workspace tsconfig in sync), so a fresh checkout or worktree is testable with no build. Published packages are unchanged: `exports` still point at `dist`, and the built output is byte-identical.
+- The export manifest is computed from the files each package's build emits, not from `dist` on disk, so it can no longer drift with a stale or partial build. `bun run ship:preflight` now fails with the fix (`bun run gen`) when any generated artifact is stale.
+- `bun run agent:worktree -- <name>` produces a clean, ready worktree locally and in cloud sessions: it links dependencies, `Games` and the dev runner's ignored assets from the main checkout instead of installing and building. `agent:bootstrap` only installs; pass `--build` to also build dist.
+- The procedural IBL probe has a zenith/horizon/ground gradient and an HDR sun disc plus a broad lobe, with the horizon leaning toward the ambient colour, at intensity 0.45 (was a 2-colour gradient at 0.35), so forms get a lit and a shaded side from IBL alone.
+- Under IBL (every look but `"flat"`), authored ambient is halved, and lighting with no directional light gets a soft shadowless key light (intensity 0.6, tinted by the ambient colour).
+- A post chain that omits `ao` now runs `DEFAULT_AO` on medium tier and above; `ao: false` still opts out. `NEUTRAL_POST_PROCESSING` no longer sets `ao: false`.
+- Styled look presets deep-merge their post stages under a partial game `postProcessing` instead of being dropped whole.
+- Shadows use `PCFShadowMap` instead of `PCFSoftShadowMap`, which three r182 compiles as unfiltered basic shadows (stair-stepped edges), with a default radius of 1.25 texels on configured and cascaded lights.
+- GTAO samples are tiered: 8 on medium, 12 on high (was 16), 16 on ultra.
+- A model `material.rim` override now chains the material's live program cache key instead of a snapshot.
+- Authored paths now render as dirt (or their `meta.surface`/kind) with wheel ruts and edges that fade into the terrain, instead of flat-colour ribbons with hard cut edges.
+- `road()` carriageways, curbs, sidewalks and welded junctions, and city studio ground (streets, block land, sidewalks, drives, parks), shade with matching procedural asphalt, gravel, concrete and dirt. City volumes opt out with `meta.surfaceDetail: false`.
+- Terrain noise and micro-normal GLSL moved to shared exports in `terrainSurfaceShader.ts` so terrain and ribbons compile the same code.
+- A terrain without `detail` now renders with default procedural detail instead of flat vertex colour.
+- Slope rock no longer fades with `detail.strength`; it follows `surfaceStrength`.
+- The textured terrain path's normal map is applied in view space (it was added to the view-space normal as a world-space offset).
+- The `low` graphics tier takes a cheap terrain surface path without micro-normals.
+- The shell plays UI cues for every engine HUD primitive (`HudButton`, `HudPanel`, `Window`, `ModalHost`, `ActionButton`): activate → `click` (or the primitive's `cue` when it names a cue, e.g. `cue="confirm"`), button/action hover → `hover`, panel open/close → `open`/`close`. Off with `notices: false` or `notices.cues: false`; `audio.uiCues` silences single cues. `uiCueForInteraction` (`@jgengine/react/uiCues`) exposes the mapping.
+- `CommandRejection`, `CommandValidationError`, `CommandResult`, `RunCommandResult` and `TransportRunCommandResult` carry an optional `message`; the ws hosts forward it. Results without one are unchanged.
+- `defaultHudTheme` is the engine's default look: a system UI font stack led by Inter, layered translucent panels with a lit rim and hairline borders, and gradient slots.
+- `Window` / `PanelHost` render on `HudPanel` with enter and exit transitions and a `HudButton` close; `ModalHost` fades its backdrop and lifts its dialog, with an exit; `ConfirmDialog` / `PauseMenu` use `HudPanel` and `HudButton`; `HudFrame` and `ActionButton` read the font, elevation, focus, and motion tokens.
+- Text under 12px in `@jgengine/react` and `registry/jgengine` now uses the type scale's `xs` step (12px floor).
+
+### Fixed
+
+- Games on the `rts` and `topDown` camera rigs hear positional sound again. The spatial-audio listener sat at the camera, 35–50 m above the ground, so the default 24 m falloff silenced every ground event even at screen centre; for these rigs it now sits where the camera looks at the ground. Chase, first-person and other rigs keep the camera-anchored listener.
+- The bundled `jgengine drive` and `jgengine shoot` harnesses let Chrome pick a free debug port instead of guessing one from the clock, so they no longer attach to another Chrome that holds the same port. An interrupted drive or shoot (SIGINT/SIGTERM) now closes its Chrome instead of leaving it running.
+- `jgengine doctor` flags component folders reached through a `tsconfig` path alias (such as a shared `@/components/ui/*` registry) that game code imports but `src/index.css` never scans with `@source`. Their Tailwind classes were silently not generated, so those HUD blocks rendered tiny and unstyled; the fix text names the exact `@source` line to add.
+- `jgengine doctor` now flags a 3D game that sets neither a `look` preset nor `postProcessing`; such a game renders the unstyled `"neutral"` look with no tone-map grade, AO or bloom. Its fix text no longer claims cinematic is the default. Write `look: "neutral"` when unstyled output is deliberate.
+- `jgengine create` scaffolds name `look: "cinematic"` explicitly, so a new 3D game starts graded instead of on the unstyled default.
+- Generated city districts (`@jgengine/shell` `CityRenderer`) fade their developed ground to transparent over its outer 9 m, so it melts into the terrain or authored paint beyond it instead of ending in a hard, stair-stepped green rim.
+- City districts (`@jgengine/shell` `CityRenderer`) draw a crossing of gravel lanes as gravel instead of a dark asphalt slab; a crossing that touches any paved street stays asphalt.
+- The published CLI and scaffold browser driver restore game keyboard focus before key holds and wait for a rendered frame under the held key. Menu clicks and slow headless rendering no longer silently swallow movement inputs; failed frame sampling releases held keys.
+- After a click on a control that then unmounts (a start screen's "Play", a menu's last button), `@jgengine/shell` returns focus to the play surface instead of leaving it on `<body>`, so gameplay keys work without an extra click on the canvas.
+- `sim_advance` (`@jgengine/shell` agent bridge) yields to the browser every ten simulated seconds, so models for entities spawned mid-advance mount as in play; a 30 s advance through Beacon Bastion's first wave previously left every raider with health bars but no model.
+- Generated city districts no longer lay a checkerboard over their ground. The developed-ground fabric drew one flat quad per 2.5 m cell with a per-cell random roll that flipped neighbours between zone bands; it is now one shared-vertex sheet coloured from smooth noise, so yards and lots blend.
+- Authored terrain paint (paths, clearings, painted layers) now blends smoothly between neighbouring cells in the runtime ground and the editor sculpt view, instead of snapping each vertex to its 2 m cell and drawing grid-aligned stair-step edges. Unpainted cells blend toward the caller's base ground color, so painted edges fade into the terrain palette.
+- A terrain detail `material` no longer overrides the ground's authored roughness with its roughness map. The map now varies roughness around the authored value, so scanned ground maps (roughness near 0.45) stop giving dry terrain a wet specular sheen; games no longer need to lower `material.strength` to stay matte.
+- A terrain without a `waterLevel` no longer paints the detail shader's beach sand band. Previously the band defaulted to water at height 0, so any flat terrain near 0 (a park, a meadow) rendered as beach; six reference games set `detail.waterLevel` far below the world only to avoid it. Set `waterLevel` on the terrain or `detail.waterLevel` to keep a shoreline.
+- Atomic vitals bars (`HealthBar`, `ManaBar`, … in `@jgengine/react`) cap their frame at a quarter of the bar height, so thin bars (e.g. `height: "4px"`) show their fill instead of only the two 2px frame lines.
+- Built-in world health bars (`worldHealthBars`, `@jgengine/shell`) span about 1.4 m at the entity's on-screen scale (28–112 px) instead of a fixed 112 px, so top-down and RTS cameras no longer paint bars ten times wider than the units under them.
+
 ## 0.22.0
 
 ### Migrate

package/dist/GamePlayerShell.js

@@ -11,6 +11,7 @@ import { actionContextStack, activeActionCodes } from "@jgengine/core/game/contr
 import { useDisplayProfile } from "@jgengine/react/display";
 import { RotateDeviceScreen } from "@jgengine/react/rotateDevice";
 import { createSettingsStore } from "@jgengine/core/settings/settingsModel";
+import { parseGraphicsQuality, withGraphicsQualityOverride } from "@jgengine/core/settings/graphicsSettings";
 import { applyBindingOverrides, clearBindingOverride, loadBindingOverrides, saveBindingOverride, } from "@jgengine/core/input/bindingOverrides";
 import { orientationGateActive, orientationHintActive, resolveOrientationRequirement, } from "@jgengine/core/ui/orientation";
 import { devtools } from "@jgengine/core/devtools/devtools";
@@ -19,11 +20,13 @@ import { armTextureErrors } from "@jgengine/core/devtools/textureErrors";
 import { readUrlFlag, subscribeUrlChange, writeUrlParam } from "@jgengine/core/devtools/urlFlags";
 import { createAudioEngine } from "./audio/audioEngine.js";
 import { attachAudioEventWire } from "./audio/audioWire.js";
+import { resolvePlayableAudio } from "./audio/playableAudio.js";
 import { installAgentBridge } from "./devtools/agentBridge.js";
 import { attachPlaytestProbe } from "./devtools/playtestProbe.js";
 import { withDevtoolsLatency } from "./devtools/latencyInstrumentation.js";
 import { resolveRigKind } from "./camera/rigResolve.js";
 import { contextModels } from "./render/resolveModel.js";
+import { configureModelSurface } from "./render/modelSurface.js";
 import { OrientationHint } from "./touch/OrientationHint.js";
 import { useTouchStyle, useTouchJoystickVariant, useGraphicsSettings } from "./settings/appliedSettings.js";
 import { logRuntimeError, } from "./diagnostics/RuntimeDiagnostics.js";
@@ -38,6 +41,7 @@ import { observableShellTracker, attachShellInputPublication } from "./shellInpu
 import { attachShellControlSuspension } from "./shellControlSuspension.js";
 import { LazyShell3dPresentation } from "./lazyShell3dPresentation.js";
 import { createPresentationDiagnosticOwnership, createPlaySurfaceFocusOwnership, PresentationRecovery } from "./presentationRecovery.js";
+import { installPlayFocusReclaim } from "./playSurfaceFocus.js";
 const DEV_USER_ID = "dev-player";
 /** The query param that mirrors the devtools overlay into the URL — present = open. */
 const DEBUG_PARAM = "debug";
@@ -76,15 +80,20 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
         devtoolsEnabled,
         isDevtoolsOpen: () => devtoolsOpenRef.current,
         setDevtoolsOpen,
+        getContext: () => ctxRef.current,
     }), [playable, devtoolsEnabled]);
     const [posterFrozen, setPosterFrozen] = useState(false);
     const posterSettledRef = useRef(false);
     const [ctx, setCtx] = useState(null);
+    const ctxRef = useRef(null);
+    ctxRef.current = ctx;
     const [diagnostics, setDiagnostics] = useState([]);
     const diagnosticSequence = useRef(0);
     const presentationDiagnostics = useRef(createPresentationDiagnosticOwnership());
     const [remotePlayers, setRemotePlayers] = useState([]);
     const wrapperRef = useRef(null);
+    // A start/menu button that unmounts on click drops focus to <body>, where gameplay keys never arrive.
+    useEffect(() => (poster ? undefined : installPlayFocusReclaim(document, () => wrapperRef.current)), [poster]);
     const recoveredFocus = useRef(createPlaySurfaceFocusOwnership());
     const yawRef = useRef(0);
     const pitchRef = useRef(0);
@@ -93,7 +102,12 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
     const primaryClickRef = useRef(false);
     const pointerAxisRef = useRef(null);
     const f2HeldRef = useRef(false);
-    const settingsStore = useMemo(() => createSettingsStore(), []);
+    const settingsStore = useMemo(() => {
+        const store = createSettingsStore();
+        // `?quality=<tier>` pins the graphics tier for this page only (capture draft shots); never persisted.
+        const pinned = typeof window === "undefined" ? null : parseGraphicsQuality(new URLSearchParams(window.location.search).get("quality"));
+        return pinned === null ? store : withGraphicsQualityOverride(store, pinned, playable.graphics);
+    }, []);
     const [bindingOverrides, setBindingOverrides] = useState(() => loadBindingOverrides(playable.game.name));
     // Render-time reset (no stale-keybinds frame): reload persisted overrides once per playable change.
     const [overridesPlayable, setOverridesPlayable] = useState(playable);
@@ -118,6 +132,7 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
         tracker.rebind(activeBindingMap);
     }
     const graphics = useGraphicsSettings(settingsStore, playable.shadows ?? true, playable.graphics);
+    useLayoutEffect(() => configureModelSurface(playable.surfaceDetail !== false, graphics.profile.surfaceDetail), [playable.surfaceDetail, graphics.profile.surfaceDetail]);
     const trackPointerAxis = (event) => {
         const rect = wrapperRef.current?.getBoundingClientRect();
         if (rect === undefined)
@@ -184,10 +199,10 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
     gateRef.current = orientationGate;
     const orientationGateEl = orientationGate ? (_jsx(RotateDeviceScreen, { requiredOrientation: orientationRequirement.required ?? "landscape", title: orientationRequirement.required === "portrait" ? "Turn your phone upright" : "Turn your phone sideways", description: `${playable.game.name} is built for ${orientationRequirement.required ?? "landscape"} play.` })) : orientationHint && orientationRequirement.preferred !== null ? (_jsx(OrientationHint, { wanted: orientationRequirement.preferred })) : null;
     const audioEngine = useMemo(() => createAudioEngine({
-        sounds: playable.audio?.sounds,
+        sounds: resolvePlayableAudio(playable).sounds,
         maxVoices: playable.audio?.maxVoices,
         voiceOverflow: playable.audio?.voiceOverflow,
-        buses: playable.audio?.buses,
+        buses: resolvePlayableAudio(playable).buses,
         music: playable.audio?.music,
         musicBus: playable.audio?.musicBus,
     }), [playable]);

package/dist/GameUiPreview.js

@@ -2,6 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useState } from "react";
 import { createGameContext } from "@jgengine/core/runtime/gameContext";
 import { GameProvider } from "@jgengine/react/provider";
+import { HudThemeRoot } from "@jgengine/react/hudThemeRoot";
 import { HudViewportProvider } from "@jgengine/react/hudViewport";
 import { contextModels } from "./render/resolveModel.js";
 const PREVIEW_USER_ID = "ui-preview";
@@ -61,5 +62,5 @@ export function GameUiPreview({ playable, scenario = defaultUiScenario, }) {
     if (ctx === null)
         return _jsx("div", { className: "h-full w-full bg-neutral-900" });
     const GameUI = playable.GameUI;
-    return (_jsx("div", { "data-ui-preview-ready": true, className: "relative h-full w-full overflow-hidden", style: { background: "linear-gradient(180deg, #2a3d33 0%, #1a2320 55%, #141b18 100%)" }, children: _jsx(GameProvider, { context: ctx, children: _jsx(HudViewportProvider, { platforms: playable.platforms, config: playable.hudFit, children: _jsx(GameUI, {}) }) }) }));
+    return (_jsx("div", { "data-ui-preview-ready": true, className: "relative h-full w-full overflow-hidden", style: { background: "linear-gradient(180deg, #2a3d33 0%, #1a2320 55%, #141b18 100%)" }, children: _jsx(GameProvider, { context: ctx, children: _jsx(HudViewportProvider, { platforms: playable.platforms, config: playable.hudFit, children: _jsx(HudThemeRoot, { theme: playable.hudTheme, children: _jsx(GameUI, {}) }) }) }) }));
 }

package/dist/Shell3dPresentation.js

@@ -3,7 +3,7 @@ import { Canvas } from "@react-three/fiber";
 import { useMemo, useEffect, useRef, useState, useSyncExternalStore, } 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 { 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";
@@ -11,6 +11,7 @@ import { BUILT_IN_SETTING_CATEGORIES, } from "@jgengine/core/settings/settingsMo
 import { playControlsActive } from "@jgengine/core/game/controlGate";
 import { sky as resolveSkyDescriptor } from "@jgengine/core/world/features";
 import { resolveGameLook } from "@jgengine/core/render/lookPreset";
+import { balanceLightingForIbl } from "@jgengine/core/render/lightingBalance";
 import { GameViewportProvider } from "@jgengine/react/gameViewport";
 import { GameProvider } from "@jgengine/react/provider";
 import { SettingsProvider } from "@jgengine/react/settings";
@@ -40,6 +41,7 @@ import { WorldItems } from "./world/WorldItems.js";
 import { TouchControlsDock, TouchPlaySurface, touchDockClearance } from "./touch/TouchControlsOverlay.js";
 import { SettingsRuntime } from "./settings/SettingsRuntime.js";
 import { SettingsChrome } from "./settings/SettingsChrome.js";
+import { resolvePlayableAudio } from "./audio/playableAudio.js";
 import { AudioSettingsBridge } from "./settings/appliedSettings.js";
 import { TextureFiltering } from "./render/TextureFiltering.js";
 import { FrameRateLimiter } from "./drivers/FrameRateLimiter.js";
@@ -53,6 +55,7 @@ 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 { TerrainQualityContext } from "./terrain/terrainQuality.js";
 import { detectKtx2Support } from "./render/modelLoad.js";
 import { resolvePresentationEffects, resolveWorldOverlayBars, } from "./presentationResolve.js";
 const PRIMARY_CLICK_MOVE_THRESHOLD_PX = 6;
@@ -82,7 +85,8 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
     const frameTally = useRef({ frames: 0 }).current;
     const WorldOverlay = playable.WorldOverlay;
     const pointerService = useMemo(() => createPointerService(), []);
-    const selection = useMemo(() => createSelectionSet(), [playable]);
+    // The player's entity selection lives on ctx so game HUDs can read (and write) it.
+    const selection = ctx.scene.entity.selection;
     const controlledEntityId = ctx.player.possession.active(ctx.player.userId);
     const cameraOverride = useSyncExternalStore(ctx.camera.subscribe, ctx.camera.rig, ctx.camera.rig);
     const configuredCamera = playable.camera?.followEntityId !== undefined
@@ -124,6 +128,7 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
     const authoredSky = backdropSky ?? worldSky;
     const lighting = resolvedLook.lighting;
     const sunFromLighting = lighting?.directional?.[0]?.position;
+    const sceneLighting = useMemo(() => (cinematicLook ? balanceLightingForIbl(lighting) : lighting), [cinematicLook, lighting]);
     const effectiveSky = useMemo(() => authoredSky === undefined || authoredSky.sun !== undefined || authoredSky.timeOfDay || sunFromLighting === undefined
         ? authoredSky
         : { ...authoredSky, sun: bearingFromDirection(sunFromLighting) }, [authoredSky, sunFromLighting]);
@@ -132,7 +137,8 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
     const pointerDownRef = useRef(null);
     const marqueeStartRef = useRef(null);
     const [marquee, setMarquee] = useState(null);
-    const [selectedIds, setSelectedIds] = useState(() => new Set());
+    const selectionKey = useSyncExternalStore(ctx.subscribe, () => selection.list().join("\n"), () => selection.list().join("\n"));
+    const selectedIds = useMemo(() => new Set(selectionKey === "" ? [] : selectionKey.split("\n")), [selectionKey]);
     const [contextMenu, setContextMenu] = useState(null);
     const localXY = (event) => {
         const rect = wrapperRef.current?.getBoundingClientRect();
@@ -142,7 +148,6 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
     };
     const commitSelection = (ids) => {
         selection.replace(ids);
-        setSelectedIds(new Set(ids));
     };
     const finishMarquee = (rect) => {
         const candidates = [];
@@ -344,7 +349,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, graphics: playable.graphics, 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: resolvePlayableAudio(playable).buses }), _jsx(SettingsRuntime, { variant: settingsVariant, surface: settingsSurface, actions: settingsActions, input: playable.game.input ?? {}, buses: resolvePlayableAudio(playable).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`,
@@ -373,9 +378,9 @@ 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, 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 }), _jsx(GameProvider, { context: ctx, children: _jsxs(BuildingRenderBudget, { drawDistance: graphics.profile.drawDistance, visibility: playable.visibility, cullingDisabled: splitScreen, children: [_jsxs(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, editorLayers: playable.editorLayers }), bars !== null ? (_jsx(WorldEntityBars, { statId: bars.statId, roles: bars.roles, resolveRole: resolveEntityRole, ...(bars.maxSamples === undefined ? {} : { maxSamples: bars.maxSamples }), ...(bars.tickMs === undefined ? {} : { tickMs: bars.tickMs }), ...(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.maxSamples === undefined ? {} : { maxSamples: nameplates.maxSamples }), ...(nameplates.tickMs === undefined ? {} : { tickMs: nameplates.tickMs }), ...(nameplates.maxDistance === undefined ? {} : { maxDistance: nameplates.maxDistance }), occlude: nameplates.occlude, ...(nameplates.resolveName === undefined ? {} : { resolveName: nameplates.resolveName }), ...(nameplates.showHealth === undefined ? {} : { showHealth: nameplates.showHealth }) })) : null, WorldOverlay !== undefined ? (_jsx("group", { userData: CAMERA_TRANSPARENT_USERDATA, children: _jsx(WorldOverlay, { ctx: ctx }) })) : null] }), _jsx(WorldItems, { config: playable.worldItem }), _jsx(WorldParticles, { quality: graphics.quality, particleCap: graphics.profile.particleCap, diagnostics: devtoolsEnabled }), _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, authoritativeFrameRef: authoritativeFrameRef }), _jsx(GamepadSource, { tracker: tracker, bindings: inputBindings ?? {}, analogRef: analogRef, input: ctx.input, feel: playable.gamepad, seats: localPlayers(ctx), onSeatJoin: (slot) => {
+                                        }, shadows: graphics.shadows ? "percentage" : false, 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: sceneLighting?.hemisphere?.skyColor ?? "#87b5e0", groundColor: sceneLighting?.hemisphere?.groundColor ?? "#3d4a38", horizonTint: sceneLighting?.ambient?.color, sunDirection: sceneLighting?.directional?.[0]?.position, sunColor: sceneLighting?.directional?.[0]?.color ?? "#fff2d6" })) : null, sceneLighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: sceneLighting, profile: graphics.profile })) : effectiveSky === undefined ? (_jsxs(_Fragment, { children: [_jsx("ambientLight", { intensity: cinematicLook ? 0.3 : 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 }), _jsx(GameProvider, { context: ctx, children: _jsx(TerrainQualityContext.Provider, { value: graphics.quality, children: _jsxs(BuildingRenderBudget, { drawDistance: graphics.profile.drawDistance, visibility: playable.visibility, cullingDisabled: splitScreen, children: [_jsxs(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, editorLayers: playable.editorLayers }), bars !== null ? (_jsx(WorldEntityBars, { statId: bars.statId, roles: bars.roles, resolveRole: resolveEntityRole, ...(bars.maxSamples === undefined ? {} : { maxSamples: bars.maxSamples }), ...(bars.tickMs === undefined ? {} : { tickMs: bars.tickMs }), ...(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.maxSamples === undefined ? {} : { maxSamples: nameplates.maxSamples }), ...(nameplates.tickMs === undefined ? {} : { tickMs: nameplates.tickMs }), ...(nameplates.maxDistance === undefined ? {} : { maxDistance: nameplates.maxDistance }), occlude: nameplates.occlude, ...(nameplates.resolveName === undefined ? {} : { resolveName: nameplates.resolveName }), ...(nameplates.showHealth === undefined ? {} : { showHealth: nameplates.showHealth }) })) : null, WorldOverlay !== undefined ? (_jsx("group", { userData: CAMERA_TRANSPARENT_USERDATA, children: _jsx(WorldOverlay, { ctx: ctx }) })) : null] }), _jsx(WorldItems, { config: playable.worldItem }), _jsx(WorldParticles, { quality: graphics.quality, particleCap: graphics.profile.particleCap, diagnostics: devtoolsEnabled }), _jsx(CombatPresentation, { effects: effects }), devtoolsEnabled ? _jsx(CollisionDebugWorld, {}) : null, _jsx(AudioListener, { engine: audioEngine, anchor: playable.camera?.rig === "rts" || playable.camera?.rig === "topDown" ? "ground" : "camera" }), _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, 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 });
                                                 }

package/dist/ShellChrome.d.ts

@@ -3,7 +3,7 @@ import type { GameContext } from "@jgengine/core/runtime/gameContext";
 import { type RuntimeDiagnostic } from "./diagnostics/RuntimeDiagnostics.js";
 import type { ShellMultiplayer } from "./multiplayer.js";
 import type { PlayableGame } from "./registry.js";
-/** Shared GameUI mount: error boundary → GameProvider → phase stamp → HudViewport. @internal */
+/** Shared GameUI mount: error boundary → GameProvider → phase stamp → HudViewport → HUD theme root. @internal */
 export declare function ShellGameUiChrome({ ctx, playable, GameUI, uiScale, orientationGate, onRuntimeError, }: {
     ctx: GameContext;
     playable: PlayableGame;

package/dist/ShellChrome.js

@@ -1,15 +1,17 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { lazy, Suspense, useEffect, useState } from "react";
+import { HudThemeRoot } from "@jgengine/react/hudThemeRoot";
 import { HudViewportProvider } from "@jgengine/react/hudViewport";
 import { GameProvider } from "@jgengine/react/provider";
 import { DiagnosticOverlay, GameUiErrorBoundary, } from "./diagnostics/RuntimeDiagnostics.js";
 import { DevtoolsRuntime } from "./devtools/DevtoolsRuntime.js";
 import { GamePhaseStamp } from "./GamePhaseStamp.js";
+import { ShellNotices, ShellUiCues } from "./ShellNotices.js";
 import { SettingsPlayControlGate } from "./settings/SettingsRuntime.js";
 const DevtoolsOverlay = lazy(() => import("./devtools/DevtoolsOverlay.js").then((module) => ({ default: module.DevtoolsOverlay })));
-/** Shared GameUI mount: error boundary → GameProvider → phase stamp → HudViewport. @internal */
+/** Shared GameUI mount: error boundary → GameProvider → phase stamp → HudViewport → HUD theme root. @internal */
 export function ShellGameUiChrome({ ctx, playable, GameUI, uiScale, orientationGate, onRuntimeError, }) {
-    return (_jsx(GameUiErrorBoundary, { onRuntimeError: onRuntimeError, children: _jsxs(GameProvider, { context: ctx, children: [_jsx(SettingsPlayControlGate, { ctx: ctx }), _jsx(GamePhaseStamp, {}), _jsx(HudViewportProvider, { platforms: playable.platforms, config: playable.hudFit, userScale: uiScale, children: orientationGate ? null : _jsx(GameUI, {}) })] }) }));
+    return (_jsx(GameUiErrorBoundary, { onRuntimeError: onRuntimeError, children: _jsxs(GameProvider, { context: ctx, children: [_jsx(SettingsPlayControlGate, { ctx: ctx }), _jsx(GamePhaseStamp, {}), _jsx(HudViewportProvider, { platforms: playable.platforms, config: playable.hudFit, userScale: uiScale, children: orientationGate ? null : (_jsx(ShellUiCues, { ctx: ctx, enabled: playable.notices !== false && playable.notices?.cues !== false, children: _jsx(HudThemeRoot, { theme: playable.hudTheme, children: _jsx(GameUI, {}) }) })) }), orientationGate ? null : _jsx(ShellNotices, { ctx: ctx, config: playable.notices, scale: uiScale })] }) }));
 }
 /** Devtools + diagnostic overlays shared by HUD and 3D presentation paths. @internal */
 export function ShellDebugOverlays({ ctx, playable, multiplayer, diagnostics, devtoolsEnabled, devtoolsOpen, hideDiagnostics = false, }) {

package/dist/ShellHudPresentation.js

@@ -6,6 +6,7 @@ import { SettingsProvider } from "@jgengine/react/settings";
 import { GameViewportProvider } from "@jgengine/react/gameViewport";
 import { HudOnlyDriver } from "./drivers/HudOnlyDriver.js";
 import { createShellKeyHandlers, ShellDebugOverlays, ShellGameUiChrome } from "./ShellChrome.js";
+import { resolvePlayableAudio } from "./audio/playableAudio.js";
 import { AudioSettingsBridge } from "./settings/appliedSettings.js";
 import { SettingsRuntime } from "./settings/SettingsRuntime.js";
 import { SettingsChrome } from "./settings/SettingsChrome.js";
@@ -49,7 +50,7 @@ export function ShellHudPresentation({ playable, ctx, multiplayer, serverIdRef,
         description: action.description,
         run: () => action.run(ctx),
     }));
-    return (_jsxs(SettingsProvider, { store: settingsStore, children: [_jsx(AudioSettingsBridge, { store: settingsStore, engine: audioEngine, buses: playable.audio?.buses }), _jsx(SettingsRuntime, { variant: settingsConfig.variant ?? "panel", surface: settingsDisabled ? false : settingsConfig.surface ?? false, actions: settingsActions, input: playable.game.input ?? {}, buses: playable.audio?.buses, extra: settingsConfig.extra ?? [], categories: settingsConfig.categories ?? [], hide: settingsDisabled ? BUILT_IN_SETTING_CATEGORIES : settingsConfig.hide ?? [], fovEnabled: false, 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, className: "relative h-full w-full bg-neutral-950 outline-none", onKeyDown: keys.onKeyDown, onKeyUp: keys.onKeyUp, onBlur: keys.onBlur, onPointerDown: onPointerResumeAudio, onPointerMove: trackPointerAxis, onPointerLeave: deactivatePointerAxis, onPointerCancel: deactivatePointerAxis, children: _jsxs(GameViewportProvider, { platforms: playable.platforms, children: [_jsx(HudOnlyDriver, { ctx: ctx, multiplayer: multiplayer, serverIdRef: serverIdRef, playable: playable, tracker: tracker, pointerAxisRef: pointerAxisRef, gateRef: gateRef, onRuntimeError: reportRuntimeError }), !orientationGate &&
+    return (_jsxs(SettingsProvider, { store: settingsStore, children: [_jsx(AudioSettingsBridge, { store: settingsStore, engine: audioEngine, buses: resolvePlayableAudio(playable).buses }), _jsx(SettingsRuntime, { variant: settingsConfig.variant ?? "panel", surface: settingsDisabled ? false : settingsConfig.surface ?? false, actions: settingsActions, input: playable.game.input ?? {}, buses: resolvePlayableAudio(playable).buses, extra: settingsConfig.extra ?? [], categories: settingsConfig.categories ?? [], hide: settingsDisabled ? BUILT_IN_SETTING_CATEGORIES : settingsConfig.hide ?? [], fovEnabled: false, 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, className: "relative h-full w-full bg-neutral-950 outline-none", onKeyDown: keys.onKeyDown, onKeyUp: keys.onKeyUp, onBlur: keys.onBlur, onPointerDown: onPointerResumeAudio, onPointerMove: trackPointerAxis, onPointerLeave: deactivatePointerAxis, onPointerCancel: deactivatePointerAxis, children: _jsxs(GameViewportProvider, { platforms: playable.platforms, children: [_jsx(HudOnlyDriver, { ctx: ctx, multiplayer: multiplayer, serverIdRef: serverIdRef, playable: playable, tracker: tracker, pointerAxisRef: pointerAxisRef, gateRef: gateRef, onRuntimeError: reportRuntimeError }), !orientationGate &&
                                 coarsePointer &&
                                 touchScheme !== null &&
                                 touchScheme.gestures !== null &&

package/dist/ShellNotices.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from "react";
+import type { NoticePresentationConfig } from "@jgengine/core/game/playableGame";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+/**
+ * Wire `ctx.game.notices` for the player: refused commands with a `message` become deny notices, each new
+ * notice plays its tone's UI cue, and the default stack renders it. Returns the detach function.
+ * @internal
+ */
+export declare function attachShellNotices(ctx: GameContext, config?: NoticePresentationConfig): () => void;
+/** The shell-mounted notice feed; `playable.notices: false` removes it. @internal */
+export declare function ShellNotices({ ctx, config, scale, }: {
+    ctx: GameContext;
+    config: NoticePresentationConfig | false | undefined;
+    scale: number;
+}): import("react").JSX.Element | null;
+/**
+ * Plays the UI cue for every engine HUD primitive interaction below it (button activate/hover, panel
+ * open/close), so `HudButton`, `HudPanel`, windows and action slots sound without per-button wiring.
+ * Off with `playable.notices: false` or `notices.cues: false`; `audio.uiCues` silences individual cues.
+ * @internal
+ */
+export declare function ShellUiCues({ ctx, enabled, children }: {
+    ctx: GameContext;
+    enabled: boolean;
+    children?: ReactNode;
+}): import("react").JSX.Element;

package/dist/ShellNotices.js

@@ -0,0 +1,51 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect } from "react";
+import { NOTICE_TONE_CUES, uiCueSoundId } from "@jgengine/core/audio/uiCues";
+import { attachRefusalNotices } from "@jgengine/core/game/notices";
+import { HudInteractProvider } from "@jgengine/react/hudInteract";
+import { NoticeStack } from "@jgengine/react/notices";
+import { playUiCue, uiCueForInteraction } from "@jgengine/react/uiCues";
+/**
+ * Wire `ctx.game.notices` for the player: refused commands with a `message` become deny notices, each new
+ * notice plays its tone's UI cue, and the default stack renders it. Returns the detach function.
+ * @internal
+ */
+export function attachShellNotices(ctx, config = {}) {
+    const notices = ctx.game.notices;
+    notices.retune(config);
+    const detachRefusals = config.refusals === false
+        ? () => undefined
+        : attachRefusalNotices(ctx.game.events, notices, { localUserId: () => ctx.player.userId });
+    const detachCues = config.cues === false
+        ? () => undefined
+        : notices.onPush((notice) => ctx.game.audio.play(uiCueSoundId(NOTICE_TONE_CUES[notice.tone])));
+    return () => {
+        detachRefusals();
+        detachCues();
+    };
+}
+/** The shell-mounted notice feed; `playable.notices: false` removes it. @internal */
+export function ShellNotices({ ctx, config, scale, }) {
+    const enabled = config !== false;
+    const settings = config === false ? undefined : config;
+    useEffect(() => (enabled ? attachShellNotices(ctx, settings) : undefined), [ctx, enabled, settings]);
+    if (!enabled || settings?.hidden === true)
+        return null;
+    return _jsx(NoticeStack, { feed: ctx.game.notices, placement: settings?.placement ?? "top", scale: scale });
+}
+/**
+ * Plays the UI cue for every engine HUD primitive interaction below it (button activate/hover, panel
+ * open/close), so `HudButton`, `HudPanel`, windows and action slots sound without per-button wiring.
+ * Off with `playable.notices: false` or `notices.cues: false`; `audio.uiCues` silences individual cues.
+ * @internal
+ */
+export function ShellUiCues({ ctx, enabled, children }) {
+    const onInteract = useCallback((event) => {
+        const cue = uiCueForInteraction(event);
+        if (cue !== null)
+            playUiCue(ctx, cue);
+    }, [ctx]);
+    if (!enabled)
+        return _jsx(_Fragment, { children: children });
+    return _jsx(HudInteractProvider, { onInteract: onInteract, children: children });
+}

package/dist/audio/AudioComponents.d.ts

@@ -1,6 +1,8 @@
 import type { AudioEngine } from "./audioEngine.js";
-export declare function AudioListener({ engine }: {
+import { type ListenerAnchor } from "./listenerAnchor.js";
+export declare function AudioListener({ engine, anchor }: {
     engine: AudioEngine;
+    anchor?: ListenerAnchor;
 }): null;
 export declare function EntityAudioEmitters({ engine, entitySounds, }: {
     engine: AudioEngine;

package/dist/audio/AudioComponents.js

@@ -2,14 +2,17 @@ import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
 import { Quaternion, Vector3 } from "three";
 import { useGameContext } from "@jgengine/react/provider";
+import { groundFocusListener } from "./listenerAnchor.js";
 import { createListenerVelocityTrack, stepListenerVelocity } from "./loopParams.js";
-export function AudioListener({ engine }) {
+export function AudioListener({ engine, anchor = "camera" }) {
     const camera = useThree((state) => state.camera);
+    const ctx = useGameContext();
     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 };
+        const eye = { x: camera.position.x, y: camera.position.y, z: camera.position.z };
+        const position = anchor === "ground" ? groundFocusListener(eye, direction, ctx.world.groundHeightAt(eye.x, eye.z)) : eye;
         engine.setListenerPose({
             position,
             forward: { x: direction.x, y: direction.y, z: direction.z },

package/dist/audio/listenerAnchor.d.ts

@@ -0,0 +1,15 @@
+/** Where the spatial-audio listener sits: at the camera, or where an overhead camera looks at the ground. @internal */
+export type ListenerAnchor = "camera" | "ground";
+type Point = {
+    x: number;
+    y: number;
+    z: number;
+};
+/**
+ * The point an overhead camera looks at on the ground, lifted slightly, or the camera position when
+ * the view does not reach the ground. Overhead rigs sit tens of metres up, so a camera-anchored
+ * listener hears every ground event at the edge of (or past) its falloff even when it is centre-screen.
+ * @internal
+ */
+export declare function groundFocusListener(camera: Point, forward: Point, groundY: number): Point;
+export {};

package/dist/audio/listenerAnchor.js

@@ -0,0 +1,17 @@
+/** Furthest the listener moves from an overhead camera along its view ray. */
+const MAX_FOCUS_DISTANCE = 400;
+/** Listener height above the ground focus, so ground emitters are not exactly coincident with it. */
+const FOCUS_LIFT = 2;
+/**
+ * The point an overhead camera looks at on the ground, lifted slightly, or the camera position when
+ * the view does not reach the ground. Overhead rigs sit tens of metres up, so a camera-anchored
+ * listener hears every ground event at the edge of (or past) its falloff even when it is centre-screen.
+ * @internal
+ */
+export function groundFocusListener(camera, forward, groundY) {
+    const height = camera.y - groundY;
+    if (forward.y >= -0.05 || height <= 0)
+        return { ...camera };
+    const t = Math.min(MAX_FOCUS_DISTANCE, height / -forward.y);
+    return { x: camera.x + forward.x * t, y: groundY + FOCUS_LIFT, z: camera.z + forward.z * t };
+}

package/dist/audio/playableAudio.d.ts

@@ -0,0 +1,9 @@
+import type { AudioBusDef, SoundDef } from "@jgengine/core/audio/audioFalloff";
+import type { PlayableGame } from "../registry.js";
+/** A playable's sound catalog and buses with the default UI cues merged in. @internal */
+export interface ResolvedPlayableAudio {
+    sounds: Record<string, SoundDef>;
+    buses: Record<string, AudioBusDef> | undefined;
+}
+/** Resolve once per playable so the engine, the volume bridge and the settings rows share one bus list. @internal */
+export declare function resolvePlayableAudio(playable: PlayableGame): ResolvedPlayableAudio;

package/dist/audio/playableAudio.js

@@ -0,0 +1,11 @@
+import { withUiCueSounds } from "@jgengine/core/audio/uiCues";
+const cache = new WeakMap();
+/** Resolve once per playable so the engine, the volume bridge and the settings rows share one bus list. @internal */
+export function resolvePlayableAudio(playable) {
+    let resolved = cache.get(playable);
+    if (resolved === undefined) {
+        resolved = withUiCueSounds(playable.audio?.sounds, playable.audio?.buses, playable.audio?.uiCues);
+        cache.set(playable, resolved);
+    }
+    return resolved;
+}

package/dist/commandSink.d.ts

@@ -11,7 +11,7 @@ export declare function localCommandSink(ctx: GameContext): CommandSink;
 /** Sends commands to the authoritative host over the transport; the result replicates back through world sync.
  * @internal
  */
-export declare function remoteCommandSink(backend: Pick<LiveGameBackend, "transport">, serverId: string): CommandSink;
+export declare function remoteCommandSink(backend: Pick<LiveGameBackend, "transport">, serverId: string, events?: Pick<GameContext["game"]["events"], "emit">): CommandSink;
 /**
  * The sink a server-authoritative shell should dispatch gameplay commands through: remote when the game opts into
  * `authority: "server"` and a server is joined. Before join it discards commands rather than mutating a replica.

package/dist/commandSink.js

@@ -11,10 +11,15 @@ export function localCommandSink(ctx) {
 /** Sends commands to the authoritative host over the transport; the result replicates back through world sync.
  * @internal
  */
-export function remoteCommandSink(backend, serverId) {
+export function remoteCommandSink(backend, serverId, events) {
     return {
         run(name, input) {
-            void backend.transport.runCommand({ serverId, command: name, input }).catch(() => undefined);
+            void backend.transport.runCommand({ serverId, command: name, input }).then((result) => {
+                // Host refusals reach the local notice feed the same way local ones do.
+                if (!result.ok && result.message !== undefined) {
+                    events?.emit("command.refused", { command: name, reason: result.reason, message: result.message, actor: null });
+                }
+            }).catch(() => undefined);
         },
     };
 }
@@ -25,7 +30,7 @@ export function remoteCommandSink(backend, serverId) {
   */
 export function resolveCommandSink(ctx, opts) {
     if (opts.serverAuthoritative && opts.backend !== null && opts.serverId !== null) {
-        return remoteCommandSink(opts.backend, opts.serverId);
+        return remoteCommandSink(opts.backend, opts.serverId, ctx.game.events);
     }
     if (opts.serverAuthoritative)
         return { run() { } };