@jgengine/shell 0.34.0 → 0.35.0

package/CHANGELOG.md

@@ -26,6 +26,33 @@ 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.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 +61,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;