@jgengine/core 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -26,6 +26,116 @@ 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.24.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.24.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.21.0`; `@jgengine/github` is `0.11.0`.
+
+### Added
+
+- `buildGroundCoverageMask`, `createGroundEdgeFade` and `applyGroundEdgeFade` (`@jgengine/shell/terrain`) fade any ground material out at the outer edge of a merged mesh footprint, leaving seams between layers inside it crisp.
+
+### Changed
+
+- City studio ground (roads, junctions, block land, sidewalks, medians, drives, parks, crops, curbs, markings) now fades into the terrain where the town's ground ends instead of stopping at a hard edge. `meta.edgeFade: false` on the city volume keeps the old hard edge.
+
+## 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/audio/uiCues.d.ts

@@ -0,0 +1,26 @@
+import type { AudioBusDef, SoundDef } from "./audioFalloff.js";
+import type { NoticeTone } from "../game/notices.js";
+/** Interface sound cues every game gets: press, hover, panel open/close, confirm, refusal, notification. */
+export type UiCue = "click" | "hover" | "open" | "close" | "confirm" | "deny" | "notify";
+/** Every {@link UiCue}, in a stable order. */
+export declare const UI_CUES: readonly UiCue[];
+/** Bus the default UI cues mix through; the settings menu shows its volume. */
+export declare const UI_CUE_BUS = "ui";
+/** Catalog id a cue plays under: `ui.click`, `ui.deny`, ... A game sound with that id replaces the default. */
+export declare function uiCueSoundId(cue: UiCue): string;
+/** The cue a notice of each tone plays when it appears. */
+export declare const NOTICE_TONE_CUES: Readonly<Record<NoticeTone, UiCue>>;
+/** Short, soft procedural patches: no samples to load, quiet enough to sit under game audio. */
+export declare const DEFAULT_UI_CUE_SOUNDS: Readonly<Record<UiCue, SoundDef>>;
+/** Per-cue override: a replacement sound, or `false` to silence that cue. `false` for the whole map silences all. */
+export type UiCueOverrides = false | Partial<Record<UiCue, SoundDef | false>>;
+/**
+ * Merge the default UI cue patches into a game's sound catalog. A game sound already named `ui.<cue>` wins,
+ * then `overrides`, then the default. Adds the `ui` bus (gain 0.8) when the game did not declare one.
+ *
+ * @capability ui-sound-cues default procedural click/hover/open/close/confirm/deny/notify cues on a "ui" bus, overridable per game
+ */
+export declare function withUiCueSounds(sounds: Readonly<Record<string, SoundDef>> | undefined, buses: Readonly<Record<string, AudioBusDef>> | undefined, overrides?: UiCueOverrides): {
+    sounds: Record<string, SoundDef>;
+    buses: Record<string, AudioBusDef> | undefined;
+};

package/dist/audio/uiCues.js

@@ -0,0 +1,118 @@
+/** Every {@link UiCue}, in a stable order. */
+export const UI_CUES = ["click", "hover", "open", "close", "confirm", "deny", "notify"];
+/** Bus the default UI cues mix through; the settings menu shows its volume. */
+export const UI_CUE_BUS = "ui";
+/** Catalog id a cue plays under: `ui.click`, `ui.deny`, ... A game sound with that id replaces the default. */
+export function uiCueSoundId(cue) {
+    return `ui.${cue}`;
+}
+/** The cue a notice of each tone plays when it appears. */
+export const NOTICE_TONE_CUES = {
+    info: "notify",
+    success: "confirm",
+    warn: "notify",
+    deny: "deny",
+};
+function uiSound(cue, def) {
+    return { id: uiCueSoundId(cue), bus: UI_CUE_BUS, positional: false, priority: 2, ...def };
+}
+/** Short, soft procedural patches: no samples to load, quiet enough to sit under game audio. */
+export const DEFAULT_UI_CUE_SOUNDS = {
+    click: uiSound("click", {
+        gain: 0.5,
+        maxVoices: 2,
+        synth: {
+            voices: [
+                { kind: "tone", wave: "triangle", freq: 1560, slideTo: 1120, duration: 0.05, gain: 0.32, attack: 0.002 },
+                { kind: "noise", filterType: "highpass", filterFreq: 4200, duration: 0.018, gain: 0.08 },
+            ],
+        },
+    }),
+    hover: uiSound("hover", {
+        gain: 0.35,
+        maxVoices: 1,
+        synth: { voices: [{ kind: "tone", wave: "sine", freq: 2240, duration: 0.03, gain: 0.12, attack: 0.002 }] },
+    }),
+    open: uiSound("open", {
+        gain: 0.5,
+        maxVoices: 2,
+        synth: {
+            voices: [
+                { kind: "tone", wave: "triangle", freq: 523, duration: 0.09, gain: 0.26 },
+                { kind: "tone", wave: "triangle", freq: 784, duration: 0.12, gain: 0.24, delay: 0.045 },
+                { kind: "noise", filterType: "bandpass", filterFreq: 2400, duration: 0.08, gain: 0.04 },
+            ],
+        },
+    }),
+    close: uiSound("close", {
+        gain: 0.5,
+        maxVoices: 2,
+        synth: {
+            voices: [
+                { kind: "tone", wave: "triangle", freq: 784, duration: 0.08, gain: 0.22 },
+                { kind: "tone", wave: "triangle", freq: 523, duration: 0.11, gain: 0.22, delay: 0.04 },
+            ],
+        },
+    }),
+    confirm: uiSound("confirm", {
+        gain: 0.5,
+        maxVoices: 2,
+        synth: {
+            voices: [
+                { kind: "tone", wave: "sine", freq: 659, duration: 0.12, gain: 0.26 },
+                { kind: "tone", wave: "sine", freq: 831, duration: 0.12, gain: 0.24, delay: 0.06 },
+                { kind: "tone", wave: "sine", freq: 988, duration: 0.22, gain: 0.24, delay: 0.12 },
+            ],
+        },
+    }),
+    deny: uiSound("deny", {
+        gain: 0.55,
+        maxVoices: 1,
+        synth: {
+            voices: [
+                { kind: "tone", wave: "triangle", freq: 233, slideTo: 207, duration: 0.09, gain: 0.34, attack: 0.004 },
+                { kind: "tone", wave: "triangle", freq: 185, slideTo: 164, duration: 0.15, gain: 0.34, delay: 0.085, attack: 0.004 },
+                { kind: "noise", filterType: "lowpass", filterFreq: 900, duration: 0.05, gain: 0.08 },
+            ],
+        },
+    }),
+    notify: uiSound("notify", {
+        gain: 0.45,
+        maxVoices: 1,
+        synth: {
+            voices: [
+                { kind: "tone", wave: "sine", freq: 1319, duration: 0.32, gain: 0.22 },
+                { kind: "tone", wave: "sine", freq: 1976, duration: 0.24, gain: 0.08 },
+                { kind: "tone", wave: "sine", freq: 1760, duration: 0.36, gain: 0.16, delay: 0.07 },
+            ],
+        },
+    }),
+};
+/**
+ * Merge the default UI cue patches into a game's sound catalog. A game sound already named `ui.<cue>` wins,
+ * then `overrides`, then the default. Adds the `ui` bus (gain 0.8) when the game did not declare one.
+ *
+ * @capability ui-sound-cues default procedural click/hover/open/close/confirm/deny/notify cues on a "ui" bus, overridable per game
+ */
+export function withUiCueSounds(sounds, buses, overrides) {
+    if (overrides === false)
+        return { sounds: { ...sounds }, buses: buses === undefined ? undefined : { ...buses } };
+    const merged = {};
+    let usesUiBus = false;
+    for (const cue of UI_CUES) {
+        const id = uiCueSoundId(cue);
+        if (sounds?.[id] !== undefined)
+            continue;
+        const override = overrides?.[cue];
+        if (override === false)
+            continue;
+        const def = override ?? DEFAULT_UI_CUE_SOUNDS[cue];
+        merged[id] = { ...def, id };
+        if (def.bus === UI_CUE_BUS)
+            usesUiBus = true;
+    }
+    const nextBuses = usesUiBus && buses?.[UI_CUE_BUS] === undefined
+        ? { ...buses, [UI_CUE_BUS]: { id: UI_CUE_BUS, gain: 0.8 } }
+        : buses;
+    return { sounds: { ...merged, ...sounds }, buses: nextBuses };
+}

package/dist/commands/commandRegistry.d.ts

@@ -1,5 +1,8 @@
+/** Why a command refused: `reason` is a stable machine code; `message`, when set, is shown to the player. */
 export interface CommandRejection {
     reason: string;
+    /** Player-facing text ("Needs 40 more gold"). The shell shows it in the notice feed with the deny cue. */
+    message?: string;
 }
 export type CommandDecodeResult<TInput> = {
     ok: true;
@@ -22,6 +25,7 @@ export type CommandResult<TState> = {
 } | {
     status: "rejected";
     reason: string;
+    message?: string;
 } | {
     status: "unknown-command";
 };

package/dist/commands/commandRegistry.js

@@ -25,8 +25,11 @@ export function createCommandRegistry() {
                 decoded = result.value;
             }
             const rejection = definition.validate?.(state, decoded) ?? null;
-            if (rejection)
-                return { status: "rejected", reason: rejection.reason };
+            if (rejection) {
+                return rejection.message === undefined
+                    ? { status: "rejected", reason: rejection.reason }
+                    : { status: "rejected", reason: rejection.reason, message: rejection.message };
+            }
             const next = definition.apply(state, decoded);
             return { status: "applied", state: next === undefined ? state : next };
         },

package/dist/game/events.d.ts

@@ -248,6 +248,17 @@ export interface AudioLoopSetEvent {
     /** Highpass cutoff in Hz. */
     highpass?: number;
 }
+/**
+ * A command run through `ctx.game.commands` (or a bound host) was refused. `reason` is the machine code;
+ * `message` is the player-facing text the command's `validate` returned, when it gave one.
+ */
+export interface CommandRefusedEvent {
+    command: string;
+    reason: string;
+    message?: string;
+    /** `runAs` actor, or null for a plain `run`. */
+    actor: string | null;
+}
 /** Stop and dispose the retained loop `id`; an unknown `id` is ignored (#1051). */
 export interface AudioLoopStopEvent {
     id: string;
@@ -287,6 +298,7 @@ export interface GameEventMap {
     "audio.loopStop": AudioLoopStopEvent;
     "entity.animation": EntityAnimationEvent;
     "animation.event": AnimationClipEvent;
+    "command.refused": CommandRefusedEvent;
 }
 export type GameEventHandler<TPayload> = (payload: TPayload) => void;
 export interface GameEvents<TMap extends GameEventMap = GameEventMap> {

package/dist/game/notices.d.ts

@@ -0,0 +1,85 @@
+import type { GameEvents } from "./events.js";
+/** How a notice reads: neutral info, a win, a caution, or a refused action. */
+export type NoticeTone = "info" | "success" | "warn" | "deny";
+/** What a caller pushes: plain text, or text with a tone, a dedupe key and a lifetime. */
+export interface NoticeInput {
+    text: string;
+    /** Default "info". */
+    tone?: NoticeTone;
+    /** Live notices with the same key stack into one (count +1, lifetime refreshed). Default `${tone}:${text}`. */
+    key?: string;
+    /** Lifetime in ms. Defaults to the feed's `ttlMs`, or `denyTtlMs` for deny. */
+    ttlMs?: number;
+}
+/** A live notice as the HUD renders it. */
+export interface Notice {
+    id: string;
+    text: string;
+    tone: NoticeTone;
+    key: string;
+    /** How many pushes stacked into this notice; render "×N" when above 1. */
+    count: number;
+    /** Clock time (ms) of the latest push. */
+    at: number;
+    expiresAt: number;
+}
+/** Plain JSON state of a {@link NoticeFeed}. */
+export interface NoticeFeedState {
+    notices: Notice[];
+    counter: number;
+}
+/** Tunables for {@link createNoticeFeed}; all retunable at runtime. */
+export interface NoticeFeedConfig {
+    /** Maximum live notices; the oldest falls off. Default 4. */
+    cap?: number;
+    /** Default lifetime in ms. Default 3200. */
+    ttlMs?: number;
+    /** Lifetime for deny notices, which are short reactions. Default 2400. */
+    denyTtlMs?: number;
+}
+/** A capped, self-expiring, deduping notice list every game reaches through `ctx.game.notices`. */
+export interface NoticeFeed {
+    /** Raise a notice (or stack it onto a live one with the same key); returns the live entry. */
+    push(input: NoticeInput | string): Notice;
+    /** Remove one notice early. */
+    dismiss(id: string): void;
+    /** Drop expired notices as of the feed clock. */
+    prune(): void;
+    /** Live notices, oldest first. Stable reference until the next change. */
+    list(): readonly Notice[];
+    clear(): void;
+    /** Called after every change. */
+    subscribe(listener: () => void): () => void;
+    /** Called once per push; `stacked` is true when it merged into a live notice. */
+    onPush(listener: (notice: Notice, stacked: boolean) => void): () => void;
+    retune(config: NoticeFeedConfig): void;
+    snapshot(): NoticeFeedState;
+    restore(next: NoticeFeedState): void;
+}
+/**
+ * Player-facing notice feed: info/success/warn/deny messages with stacking dedupe and TTL. Pure state with
+ * an injected clock, so it runs headless; the shell renders it and plays a UI cue per push.
+ *
+ * @capability notice-feed push toned, deduped, self-expiring player notices from game logic via ctx.game.notices
+ */
+export declare function createNoticeFeed(config?: NoticeFeedConfig & {
+    now?: () => number;
+}): NoticeFeed;
+/** Options for {@link attachRefusalNotices}. */
+export interface RefusalNoticeOptions {
+    /** Which actors' refusals to show. Default: commands run without an actor or by `localUserId`. */
+    accept?: (refusal: {
+        command: string;
+        reason: string;
+        actor: string | null;
+    }) => boolean;
+    /** The local player's id, used by the default `accept`. */
+    localUserId?: () => string;
+}
+/**
+ * Show every player-facing command refusal (`validate` returned `{ reason, message }`) as a deny notice.
+ * Refusals without a `message` stay silent: `reason` is a machine string. Returns the detach function.
+ *
+ * @capability refusal-feedback surface a refused command's player-facing message in the notice feed automatically
+ */
+export declare function attachRefusalNotices(events: Pick<GameEvents, "on">, notices: Pick<NoticeFeed, "push">, options?: RefusalNoticeOptions): () => void;

package/dist/game/notices.js

@@ -0,0 +1,105 @@
+const DEFAULT_CAP = 4;
+const DEFAULT_TTL_MS = 3200;
+const DEFAULT_DENY_TTL_MS = 2400;
+/**
+ * Player-facing notice feed: info/success/warn/deny messages with stacking dedupe and TTL. Pure state with
+ * an injected clock, so it runs headless; the shell renders it and plays a UI cue per push.
+ *
+ * @capability notice-feed push toned, deduped, self-expiring player notices from game logic via ctx.game.notices
+ */
+export function createNoticeFeed(config = {}) {
+    const now = config.now ?? Date.now;
+    let cap = config.cap ?? DEFAULT_CAP;
+    let ttlMs = config.ttlMs ?? DEFAULT_TTL_MS;
+    let denyTtlMs = config.denyTtlMs ?? DEFAULT_DENY_TTL_MS;
+    let notices = [];
+    let counter = 0;
+    const listeners = new Set();
+    const pushListeners = new Set();
+    function set(next) {
+        if (next === notices)
+            return;
+        notices = next;
+        for (const listener of [...listeners])
+            listener();
+    }
+    function prunedAt(time) {
+        return notices.every((notice) => notice.expiresAt > time) ? notices : notices.filter((notice) => notice.expiresAt > time);
+    }
+    return {
+        push(raw) {
+            const input = typeof raw === "string" ? { text: raw } : raw;
+            const tone = input.tone ?? "info";
+            const key = input.key ?? `${tone}:${input.text}`;
+            const time = now();
+            const life = input.ttlMs ?? (tone === "deny" ? denyTtlMs : ttlMs);
+            const live = prunedAt(time);
+            const index = live.findIndex((notice) => notice.key === key);
+            let notice;
+            if (index >= 0) {
+                const previous = live[index];
+                notice = { ...previous, text: input.text, tone, count: previous.count + 1, at: time, expiresAt: time + life };
+                const next = [...live];
+                next[index] = notice;
+                set(next);
+            }
+            else {
+                notice = { id: `notice-${counter}`, text: input.text, tone, key, count: 1, at: time, expiresAt: time + life };
+                counter += 1;
+                const next = [...live, notice];
+                set(cap > 0 && next.length > cap ? next.slice(next.length - cap) : next);
+            }
+            for (const listener of [...pushListeners])
+                listener(notice, index >= 0);
+            return notice;
+        },
+        dismiss(id) {
+            if (notices.some((notice) => notice.id === id))
+                set(notices.filter((notice) => notice.id !== id));
+        },
+        prune() {
+            set(prunedAt(now()));
+        },
+        list: () => notices,
+        clear() {
+            if (notices.length > 0)
+                set([]);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        onPush(listener) {
+            pushListeners.add(listener);
+            return () => pushListeners.delete(listener);
+        },
+        retune(next) {
+            cap = next.cap ?? cap;
+            ttlMs = next.ttlMs ?? ttlMs;
+            denyTtlMs = next.denyTtlMs ?? denyTtlMs;
+            if (cap > 0 && notices.length > cap)
+                set(notices.slice(notices.length - cap));
+        },
+        snapshot: () => ({ notices: notices.map((notice) => ({ ...notice })), counter }),
+        restore(next) {
+            counter = next.counter;
+            set(next.notices.map((notice) => ({ ...notice })));
+        },
+    };
+}
+/**
+ * Show every player-facing command refusal (`validate` returned `{ reason, message }`) as a deny notice.
+ * Refusals without a `message` stay silent: `reason` is a machine string. Returns the detach function.
+ *
+ * @capability refusal-feedback surface a refused command's player-facing message in the notice feed automatically
+ */
+export function attachRefusalNotices(events, notices, options = {}) {
+    const accept = options.accept ?? ((refusal) => refusal.actor === null || options.localUserId === undefined || refusal.actor === options.localUserId());
+    return events.on("command.refused", (refusal) => {
+        if (refusal.message === undefined || refusal.message === "")
+            return;
+        if (!accept(refusal))
+            return;
+        notices.push({ text: refusal.message, tone: "deny", key: `refusal:${refusal.command}:${refusal.message}` });
+    });
+}

package/dist/game/playableGame.d.ts

@@ -1,6 +1,8 @@
 import type { AnimGraph } from "../anim/animGraph.js";
 import type { AudioBusDef, SoundDef } from "../audio/audioFalloff.js";
 import type { MusicTheme } from "../audio/music.js";
+import type { UiCueOverrides } from "../audio/uiCues.js";
+import type { NoticeFeedConfig } from "./notices.js";
 import type { MaterialAsset, MaterialAssignment, MaterialSurfaceParameters, MaterialTextureRole } from "../material/materialAsset.js";
 import type { EditorCatalogDefinition, EditorDocument } from "../editor/types.js";
 import type { PostProcessingConfig } from "../render/postProcessing.js";
@@ -29,6 +31,17 @@ import type { GameCameraConfig } from "./cameraConfig.js";
 import type { ViewportsConfig } from "./viewports.js";
 import type { LootFilterRule } from "./lootFilter.js";
 import type { RarityStyle } from "./worldItem.js";
+/** How the shell presents `ctx.game.notices`; every field is optional. */
+export interface NoticePresentationConfig extends NoticeFeedConfig {
+    /** Screen band for the feed. "top" sits below top-edge HUD bars, "center" over the play area, "bottom" above action bars. Default "top". */
+    placement?: "top" | "center" | "bottom";
+    /** Keep the feed and cues but render nothing (the game draws `ctx.game.notices` itself). Default false. */
+    hidden?: boolean;
+    /** Show refused commands' `message` as deny notices. Default true. */
+    refusals?: boolean;
+    /** Play a UI cue per new notice (deny → deny, success → confirm, else notify). Default true. */
+    cues?: boolean;
+}
 export type { CameraFollowState, CameraKeyframe, CameraProjection, CameraRigKind, CameraWeaponView, CameraShakeConfig, ChaseCameraConfig, ChaseView, CinematicCameraConfig, FirstPersonCameraConfig, GameCameraConfig, InspectionCameraConfig, InspectionZoomAnchor, LockOnCameraConfig, ObserverCameraConfig, PlayerFovConfig, RtsCameraConfig, ShoulderCameraConfig, SideScrollCameraConfig, TopDownCameraConfig, TurntableCameraConfig, } from "./cameraConfig.js";
 export { CAMERA_FRUSTUM_DEFAULTS } from "./cameraConfig.js";
 /**
@@ -229,6 +242,8 @@ export interface ModelConfig {
     collisionMesh?: CollisionMeshData;
     /** Per-entity PBR tint/finish override (#151.3); cloned onto each `MeshStandardMaterial` in the model so shared GLTF caches stay untouched. */
     material?: ModelMaterialOverride;
+    /** `false` keeps this model's exported material params and skips the engine's default painted surface detail. Default true. */
+    surfaceDetail?: boolean;
     /** Reusable authored surfaces available to this model's named slot assignments. */
     materialAssets?: readonly MaterialAsset[];
     /** Sparse per-slot assignments; unselected imported materials keep their original appearance. */
@@ -310,6 +325,8 @@ export interface DirectionalLightingConfig {
     shadowBias?: number;
     /** Shadow normal bias to fight peter-panning. Default 0.02. */
     shadowNormalBias?: number;
+    /** PCF penumbra width in shadow-map texels; 0 is a hard edge. Default 1.25. */
+    shadowRadius?: number;
 }
 export interface HemisphereLightingConfig {
     skyColor?: string;
@@ -340,6 +357,16 @@ export interface LightingConfig {
     /** Maximum dynamic point + spot lights mounted by the shell. Default 8. */
     maxDynamicLights?: number;
     hemisphere?: HemisphereLightingConfig;
+    /**
+     * Multiplier on `ambient` intensity while image-based light is on (every look but `"flat"`), so the
+     * shaped sky light carries the fill instead of a flat wash. Default 0.5; 1 keeps the authored value.
+     */
+    iblAmbientScale?: number;
+    /**
+     * With no `directional` entry, the shell adds a soft shadowless key light so forms still get a lit
+     * and a shaded side. Default true; `false` keeps the scene lit by ambient/hemisphere/IBL alone.
+     */
+    fallbackKey?: boolean;
 }
 export interface BackdropFogConfig {
     color?: string;
@@ -610,6 +637,8 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     shadows?: boolean;
     /** Per-quality renderer budgets; omitted tiers use {@link DEFAULT_GRAPHICS_PROFILES}. */
     graphics?: Partial<Record<"low" | "medium" | "high", Partial<GraphicsProfile>>>;
+    /** Default painted finish on loaded models (normalized glTF params plus procedural mottling, wear and micro-normal, scaled by the graphics tier's `surfaceDetail`). Default true; `false` renders every model with its exported material. */
+    surfaceDetail?: boolean;
     /** Pointer-driven input: click-to-move, box-select, right-click verbs, cursor aim (#22/#30/#31). */
     pointer?: PointerConfig;
     /** Touch controls on coarse-pointer devices. Unset derives a scheme from `input` (virtual joystick for movement actions, on-screen buttons for the rest); a config refines it with gestures and curated buttons; `false` opts out. */
@@ -679,6 +708,8 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
         buses?: Record<string, AudioBusDef>;
         music?: Record<string, MusicTheme>;
         musicBus?: string;
+        /** Default UI cues (`ui.click`, `ui.deny`, ...) on a "ui" bus. A sound named `ui.<cue>` in `sounds` replaces one; a map entry replaces or (`false`) silences one; `false` silences all. */
+        uiCues?: UiCueOverrides;
     };
     /** Continuous positional emitter keyed by entity kind name: while a matching entity exists, the shell plays and repositions the mapped `audio.sounds` id (looping engine hum, campfire crackle, footstep loop) with listener-distance falloff. */
     entitySounds?: Record<string, string>;
@@ -702,6 +733,12 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     postProcessing?: PostProcessingConfig;
     /** F2+D debug overlay (frame/sim timing, logs, backend latency, keybinds, live tunables). On for every game by default; `false` disables the toggle. */
     devtools?: boolean;
+    /**
+     * Shell-mounted notice feed for `ctx.game.notices`: toned, stacked, self-expiring messages with a UI cue
+     * per push, plus automatic deny notices for refused commands that return a `message`. On by default;
+     * `false` removes the renderer, the cues and the refusal hookup (the feed itself stays on ctx).
+     */
+    notices?: NoticePresentationConfig | false;
     /** Player settings menu. Auto-mounted for every game (Sound / Graphics / Gameplay / Controls); unset uses the defaults, `false` opts out. Add game-specific rows via `extra`, switch overlay/full-page via `mode`, or swap the gear for compact on-screen buttons via `surface: "quick"`. */
     settings?: GameSettingsConfig | false;
     /** Automatic camera frustum + distance culling and asset streaming. On by default with conservative margins; unset uses engine defaults, `{ enabled: false }` opts out. Override bounds/distance/pins per entity kind or object catalog id. */

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.22.0";
+export declare const VERSION = "0.24.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];