@jgengine/shell 0.34.0 → 0.36.0

package/CHANGELOG.md

@@ -26,6 +26,65 @@ 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.36.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.36.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.33.0`; `@jgengine/github` is `0.23.0`.
+
+### Added
+
+- `createAgentSystem` (`@jgengine/core/agents/system`) takes a game's needs, options, mood weights, members and
+  schedules once and returns a running cast: one `tick(dt)` for everyone, one target selector for the whole system,
+  a fallback declared once, and a plain-JSON `save()`/`load()` that rides the game's own save.
+- `--quick` on `bun run shoot` and `bun run drive` is the 960x540 iteration preset: one settled frame (a 2s settle window in drive), no video, no perf pass, written as `<name>-quick.png` and timed on its own line. It refuses a 1600x900 pixel claim, a frame-time claim, a non-desktop device and a recording flag by name instead of producing weaker evidence; full stays the default for PR shots. On a warm daemon a two-shot `drive` of ember-command went 9.3s to 8.2s and 4316KB to 1383KB of PNG.
+- `createPlayScript` / `runPlayScript` (`@jgengine/shell/play`) play a real `PlayableGame` headlessly from a tick-based script: `move`, `aim`, `fire`, `use`, `wait` and `command` steps plus `setup`/`onTick` hooks, `expect` assertions read after setup and on their own tick, a tick timeline, and an FNV digest for replay comparison. It replays the shell's own frame pipeline — held movement through the walk controller, a bound action resolving to its command on press and repeat, interact prompts, hotbar — so a script proves the same code path a player's hands do. No browser, no wall clock, fixed `dt`.
+- `bun run simulate <game> <script>` runs a committed `<game>/scripts/*.play.ts` against a game under `./Games`, prints the timeline, names a failed assertion and exits 1. It merges the game's own tsconfig `paths` with this checkout's source packages, so the game imports and the engine under test are one module graph.
+- `HeadlessRunner.aim()` steers the walk controller mid-run; `HeadlessRunnerOptions` gains `seed` (deterministic `ctx.rng`) and `collision` (the shell's voxel config, previously dropped on the headless path).
+
+Play scripts prove play in seconds instead of minutes of browser play, and the three proofs land beside their games: Scrap Signal (an enemy takes damage and closes in), Beacon Bastion (a composed wave is reached, its bounty scales, a boss phase flips) and Harbor Heat (heat is witness-gated, the search area is set, a courier is swept).
+
+### Changed
+
+- The graphics quality tier now costs what it claims on the render path. A tier's post chain renders at its own resolution scale (`low` 0.7, `medium` 0.85, `high`/`ultra` native) instead of always at the canvas size, and a game's authored `shadowMapSize` and `cascades` are a ceiling the tier caps rather than a value it ignored — every reference game authored 3 cascades and 1024/2048, so no tier changed a shadow before this. `low` and `medium` also stretch the far cascades' refresh interval, and the smallest caster worth a depth draw grows as the map shrinks. `high` and `ultra` keep native resolution, the authored shadow sizes and the measured cadence, so their frames are unchanged.
+- Measured uncapped at 1600x900: whole-frame draws at `low` fell 53% in harbor-heat (515 → 242) and 63% in drift-foundry (1,098 → 408), with the shadow pass there down from 911 ms to 344 ms over a 6 s window; `high` and `ultra` held their draw counts.
+
+### Fixed
+
+- Terrain build no longer scans every road and path segment for every vertex. A baked path corridor, a draped road and a painted polyline region each answer "how far is this point?" from a precomputed segment grid, so Scrap Signal's world build drops from 16.6 s to 0.51 s on the same machine and its longest boot stall from 11.6–18.4 s to 1.2 s. Sampled heights and palettes are bit-identical to the previous full scan, and `withPathProfiles` still composes profiles in order.
+- Load-time shader warmup compiles against the render state the first frame actually draws with. A scene whose post chain renders into its own buffer was linking two programs per material, one linear untone-mapped set the frame draws and one canvas set nothing ever drew; the cover no longer waits for the second set. Harbor Heat links 84 programs to 58 and Scrap Signal 124 to 83 before the cover lifts, with no visual change.
+
+### Performance
+
+- `createTerrainPaletteSampler` (`@jgengine/core/world/terrain`) tests only the material regions whose painted core or blend ring covers a sample, so a world with hundreds of authored regions no longer pays for all of them at every vertex.
+
+## 0.35.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.35.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.32.0`; `@jgengine/github` is `0.22.0`.
+
+### Added
+
+- `ModelLodConfig.crowdCapacity` declares how many characters of one model a batch draws (default 128). A character past the cap keeps its own rig at its distance tier instead of disappearing.
+- `ModelLodConfig.crowdDistance` accepts `0`, which batches a character at every distance instead of only past 25 m. A game with a near crowd or a close-quarters army sets it to batch members in front of the camera too.
+- `characterRigTier` (`@jgengine/shell/render/characterLod`) resolves the distance tier a character poses its own rig on, which is the fallback for an over-cap crowd.
+- `audio.zones` (`@jgengine/core/game/playableGame`): a scene declares world-space ambience zones, one looping bed per zone. The shell crossfades bed levels from the listener position on each sound's own bus, so entering, leaving and walking between zones hand over instead of cutting.
+- `audio.occlusion` (`@jgengine/core/audio/occlusion`): budgeted geometry occlusion for retained positional loops. A blocked line attenuates the loop and darkens it through a low-pass; the per-tick test budget and interval bound the cost, and a loop that cannot be tested stays on distance-only.
+- `SoundDef.duck`: a cue can lower named buses for its own duration. `AudioEngine.duck` returns a release, and the player's own gain is restored exactly even when they move the slider mid-duck.
+- `AudioEngine.ambience()`, `AudioEngine.occlusionStats()` and `window.__jgengineAudio` report the zone mix, the newest occlusion test and the measured per-test cost for capture and diagnostics.
+
+### Changed
+
+- The character batch path now covers every drawable character model, not only skinned locomotion rigs: a node-transform character (rotating limbs, no skin) rides the node a clip moves, and a model with no clips at all batches as a static geometry. Both still bake to one geometry per material, so a crowd draws once per model and material.
+- Batched characters are pickable: the batch carries the entity ids of the instances it drew, so `worldHit().entity` and a click on a batched character resolve to the character instead of falling through to the ground.
+
+### Fixed
+
+- Load-time shader warmup compiles what the first frame can reach, reveals as soon as those programs are linked, and finishes the rest in background rounds, so a scene no longer holds the loading cover for its whole model stream and no longer drops a compile onto a frame that is already showing. The loading cover names the shader count, the seconds waited and the work left for the background.
+- A crowd batch silently dropped members past its fixed 128 instances while their markers still hid them, so a full scene lost characters. Members past the declared capacity now keep their own rigs.
+- A crowd batch's clock now follows the game clock when one is bound, so a paused game no longer keeps its crowd walking.
+
 ## 0.34.0
 
 ### Migrate
@@ -34,6 +93,7 @@ At publish, rename this heading to the new version and mirror the entries into
 
 ### Added
 
+- `PaceBand` on `DriverGoal` (`paceBand` + caller-measured `paceGap`) gives catch-up pacing an owner in `@jgengine/core/ai/driver`: a dead zone around `margin` (`tolerance`), `ease` shedding pace for a car ahead over `easeAt`, `push` adding it for a car behind over `pushAt`, and `scale` as the per-car share. `paceBandFactor(band, gap)` exposes the rule on its own. Deterministic scalar math, no allocation per step; the push never outdrives `DriverTuning.maxSpeed`. First adopter: Drift Foundry's rival field, which deletes its own `paceBand`; second: Harbor Heat's interceptors.
 - `createRunLoop` (`@jgengine/core/run/runLoop`) holds a run's at-risk haul, banks it scaled by the line or loses it on a failure, and draws one authored change for each next run from a seeded table, so the same seed and run history replay the same sequence. State round-trips through `snapshot`/`restore`; the money stays in `progression/careerBank`.
 
 ## 0.33.0

package/dist/GamePlayerShell.js

@@ -225,6 +225,8 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
         buses: resolvePlayableAudio(playable).buses,
         music: playable.audio?.music,
         musicBus: playable.audio?.musicBus,
+        zones: playable.audio?.zones,
+        occlusion: playable.audio?.occlusion,
     }), [playable]);
     useEffect(() => () => audioEngine.dispose(), [audioEngine]);
     useEffect(() => {

package/dist/Shell3dPresentation.js

@@ -412,7 +412,7 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
                                                     catch (error) {
                                                         reportRuntimeError(error, "tick");
                                                     }
-                                                }, seatsActive: () => !gateRef.current && playControlsActive(ctx) }), _jsx(DevtoolsRendererProbe, {}), devtoolsEnabled ? (_jsx(FrameTelemetry, { game: playable.game.name, quality: graphics.quality === "low" ? "draft" : "full" })) : null, splitScreen ? (_jsx(SplitScreenRenderer, { ctx: ctx, viewports: seatViewports, config: playable.viewports, mainCamera: playable.camera })) : null, !splitScreen && resolvedLook.postProcessing !== undefined && resolvedLook.postProcessing.enabled !== false ? (_jsx(PostProcessing, { config: resolvedLook.postProcessing, quality: graphics.quality, stages: graphics.profile.postStages })) : null, poster ? null : _jsx(SceneWarmupGate, { onState: setWarmup })] }) }), _jsx(SceneWarmupCover, { state: warmup }), graphics.showFps && !poster ? _jsx(FpsCounter, { tally: frameTally }) : null, !poster &&
+                                                }, seatsActive: () => !gateRef.current && playControlsActive(ctx) }), _jsx(DevtoolsRendererProbe, {}), devtoolsEnabled ? (_jsx(FrameTelemetry, { game: playable.game.name, quality: graphics.quality === "low" ? "draft" : "full" })) : null, splitScreen ? (_jsx(SplitScreenRenderer, { ctx: ctx, viewports: seatViewports, config: playable.viewports, mainCamera: playable.camera })) : null, !splitScreen && resolvedLook.postProcessing !== undefined && resolvedLook.postProcessing.enabled !== false ? (_jsx(PostProcessing, { config: resolvedLook.postProcessing, quality: graphics.quality, stages: graphics.profile.postStages })) : null, poster ? null : (_jsx(SceneWarmupGate, { onState: setWarmup, sceneDrawsToTarget: !splitScreen && resolvedLook.postProcessing !== undefined && resolvedLook.postProcessing.enabled !== false }))] }) }), _jsx(SceneWarmupCover, { state: warmup }), graphics.showFps && !poster ? _jsx(FpsCounter, { tally: frameTally }) : null, !poster &&
                                     !orientationGate &&
                                     coarsePointer &&
                                     controlsActive &&

package/dist/audio/AudioComponents.js

@@ -2,14 +2,21 @@ import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
 import { Quaternion, Vector3 } from "three";
 import { useGameContext } from "@jgengine/react/provider";
+import { installAudioProbe } from "./audioProbe.js";
 import { createEmitterTracker } from "./emitterTracking.js";
 import { groundFocusListener } from "./listenerAnchor.js";
 import { createListenerVelocityTrack, stepListenerVelocity } from "./loopParams.js";
+import { sceneLineBlocked } from "./occlusion.js";
 export function AudioListener({ engine, anchor = "camera" }) {
     const camera = useThree((state) => state.camera);
     const ctx = useGameContext();
     const trackRef = useRef(createListenerVelocityTrack());
     const scratchRef = useRef({ direction: new Vector3(), up: new Vector3(), quaternion: new Quaternion() });
+    useEffect(() => {
+        engine.setOcclusionSource((from, to) => sceneLineBlocked(ctx.scene, from, to));
+        return () => engine.setOcclusionSource(null);
+    }, [engine, ctx]);
+    useEffect(() => installAudioProbe(engine), [engine]);
     useFrame((_, dt) => {
         const { direction, up, quaternion } = scratchRef.current;
         camera.getWorldDirection(direction);

package/dist/audio/audioEngine.d.ts

@@ -1,4 +1,6 @@
+import { type AmbienceZoneDef } from "@jgengine/core/audio/ambience";
 import { type AudioBusDef, type SoundDef } from "@jgengine/core/audio/audioFalloff";
+import { type AudioOcclusionConfig } from "@jgengine/core/audio/occlusion";
 import type { MusicTheme } from "@jgengine/core/audio/music";
 import { type VoiceAllocator, type VoiceAllocatorConfig } from "@jgengine/core/audio/voiceAllocator";
 import { type CrossfadeOptions } from "./musicDirector.js";
@@ -28,6 +30,10 @@ export interface AudioSceneConfig {
     music?: Record<string, MusicTheme>;
     /** Bus id the procedural music director mixes through. Default "music". */
     musicBus?: string;
+    /** World-space ambience zones; each becomes one retained looping bed driven by the listener position. */
+    zones?: readonly AmbienceZoneDef[];
+    /** Geometry occlusion budget/policy for retained positional loops. Unset keeps the defaults; `false` keeps distance-only. */
+    occlusion?: AudioOcclusionConfig | false;
 }
 export interface AudioEmitterHandle {
     /** Whether playback is reserved or playing; false after stop, stealing, failed load, or natural end. Optional for legacy hosts. */
@@ -43,8 +49,46 @@ export interface AudioEmitterHandle {
     setHighpass(hz: number): void;
     /** Emitter world velocity for doppler; ignored unless the sound declares `doppler`. */
     setVelocity(velocity: Vec3): void;
+    /** Geometry occlusion, 0 (clear line) to 1 (fully blocked): scales the loop's gain and darkens it, composed with the game's own gain and filter. */
+    setOcclusion(amount: number): void;
     stop(): void;
 }
+/** How long and how far to duck buses for {@link AudioEngine.duck}. */
+export interface DuckOptions {
+    /** How far to lower the buses, 0..1. Default 0.6. */
+    amount?: number;
+    /** Seconds to hold the duck; omit to hold until the returned release runs. */
+    seconds?: number;
+    /** Fade time constant in seconds. Default 0.03. */
+    fadeSeconds?: number;
+}
+/** Measured geometry-occlusion work, cumulative since the engine was created. */
+export interface AudioOcclusionStats {
+    /** Geometry tests run. */
+    tests: number;
+    /** Tests that found blocking geometry. */
+    blocked: number;
+    /** Total time spent inside the injected geometry test, milliseconds. */
+    testMs: number;
+    /** Mean milliseconds per test, or 0 before the first test. */
+    perTestMs: number;
+    /** Endpoints and result of the newest test, for a probe explaining what the engine actually asked. */
+    lastTest: {
+        from: Vec3;
+        to: Vec3;
+        blocked: boolean;
+    } | null;
+}
+/** Current ambience mix, by zone id. */
+export interface AudioAmbienceState {
+    /** Loudest zone, or null when the listener is outside every zone. */
+    zone: string | null;
+    /** Non-silent zone beds with their smoothed target level (`0..1`). */
+    levels: readonly {
+        id: string;
+        level: number;
+    }[];
+}
 export interface AudioEngine {
     /** Full listener orientation, or a legacy position using forward -Z and up +Y. */
     setListenerPose(pose: ListenerPose | Vec3): void;
@@ -60,6 +104,21 @@ export interface AudioEngine {
     playLoop(soundId: string, position?: Vec3): AudioEmitterHandle | null;
     /** Crossfade the procedural soundtrack to `themeId` (null fades out). No-op when no `music` catalog is configured. */
     playMusic(themeId: string | null, options?: CrossfadeOptions): void;
+    /**
+     * Install the scene's blocking-geometry test (`from` listener, `to` emitter), or null to stop
+     * testing. The engine owns the per-tick budget; tests never run outside it.
+     */
+    setOcclusionSource(blocked: ((from: Vec3, to: Vec3) => boolean) | null): void;
+    /** Cumulative occlusion cost, for a capture probe or a perf readout. */
+    occlusionStats(): AudioOcclusionStats;
+    /** Current zone mix, for a capture probe or a HUD readout. */
+    ambience(): AudioAmbienceState;
+    /**
+     * Lower one bus for its duration and restore exactly the player's own level, even if they move
+     * the slider while it is ducked. Returns an idempotent release.
+     * @capability audio-ducking a cue with a `duck` policy lowers the music or ambience bus for its duration and restores the player's own gain exactly, even when the slider moves mid-duck.
+     */
+    duck(busId: string, options?: DuckOptions): () => void;
     setBusGain(busId: string, gain: number): void;
     /** Mute one bus without losing its gain: unmuting restores exactly the volume the player set. */
     setBusMute(busId: string, muted: boolean): void;