@jgengine/shell 0.33.0 → 0.35.0

package/dist/render/shadowTiers.d.ts

@@ -0,0 +1,36 @@
+import type { GraphicsProfile } from "@jgengine/core/settings/graphicsProfile";
+/** Shadow map size when neither the game nor a profile names one. @internal */
+export declare const DEFAULT_SHADOW_MAP_SIZE = 1024;
+/** Cascades when neither the game nor a profile names a count. @internal */
+export declare const DEFAULT_CASCADES = 3;
+/**
+ * Shadow map size a tier will pay for. A game's authored size is a ceiling for its art, not a floor
+ * under the player's tier, so the profile caps it: a game built for 2048 renders 512 on `low`.
+ * @internal
+ */
+export declare function resolveShadowMapSize(profile?: GraphicsProfile, authored?: number): number;
+/**
+ * Cascades a tier will pay for, capped the same way. `low` asks for one, which the lighting tree
+ * mounts as a single shadow-casting light instead of a cascade rig.
+ * @internal
+ */
+export declare function resolveCascadeCount(profile?: GraphicsProfile, authored?: number): number;
+/**
+ * Multiplier on the far cascades' refresh interval, by shadow map size. A tier that halves its map
+ * also accepts a far cascade lagging a frame or two longer: at 1024 and below the depth pass is
+ * cheap per cascade but there are several of them, and a half-res silhouette moving is harder to
+ * see than a full-res one. `high` and `ultra` keep the cadence they had.
+ * @internal
+ */
+export declare const SHADOW_REFRESH_SCALE_BY_MAP_SIZE: Readonly<Record<number, number>>;
+/** Refresh-interval multiplier for a shadow map of `mapSize`. @internal */
+export declare function shadowRefreshScale(mapSize: number): number;
+/**
+ * Map size at which a caster's silhouette is still a few texels wide, the reference
+ * {@link MIN_SHADOW_CASTER_RADIUS} was measured at. A smaller map resolves less, so the smallest
+ * shadow worth a depth draw grows with it.
+ * @internal
+ */
+export declare const SHADOW_CASTER_RADIUS_REFERENCE_MAP = 2048;
+/** Smallest caster radius worth a depth draw at `mapSize`, in metres. @internal */
+export declare function minShadowCasterRadius(mapSize: number, reference?: number): number;

package/dist/render/shadowTiers.js

@@ -0,0 +1,50 @@
+/** Shadow map size when neither the game nor a profile names one. @internal */
+export const DEFAULT_SHADOW_MAP_SIZE = 1024;
+/** Cascades when neither the game nor a profile names a count. @internal */
+export const DEFAULT_CASCADES = 3;
+/**
+ * Shadow map size a tier will pay for. A game's authored size is a ceiling for its art, not a floor
+ * under the player's tier, so the profile caps it: a game built for 2048 renders 512 on `low`.
+ * @internal
+ */
+export function resolveShadowMapSize(profile, authored) {
+    const wanted = authored ?? profile?.shadowMapSize ?? DEFAULT_SHADOW_MAP_SIZE;
+    return profile === undefined ? wanted : Math.min(wanted, profile.shadowMapSize);
+}
+/**
+ * Cascades a tier will pay for, capped the same way. `low` asks for one, which the lighting tree
+ * mounts as a single shadow-casting light instead of a cascade rig.
+ * @internal
+ */
+export function resolveCascadeCount(profile, authored) {
+    const wanted = authored ?? profile?.cascades ?? DEFAULT_CASCADES;
+    return profile === undefined ? wanted : Math.min(wanted, profile.cascades);
+}
+/**
+ * Multiplier on the far cascades' refresh interval, by shadow map size. A tier that halves its map
+ * also accepts a far cascade lagging a frame or two longer: at 1024 and below the depth pass is
+ * cheap per cascade but there are several of them, and a half-res silhouette moving is harder to
+ * see than a full-res one. `high` and `ultra` keep the cadence they had.
+ * @internal
+ */
+export const SHADOW_REFRESH_SCALE_BY_MAP_SIZE = {
+    512: 2,
+    1024: 2,
+    2048: 1,
+    4096: 1,
+};
+/** Refresh-interval multiplier for a shadow map of `mapSize`. @internal */
+export function shadowRefreshScale(mapSize) {
+    return SHADOW_REFRESH_SCALE_BY_MAP_SIZE[mapSize] ?? 1;
+}
+/**
+ * Map size at which a caster's silhouette is still a few texels wide, the reference
+ * {@link MIN_SHADOW_CASTER_RADIUS} was measured at. A smaller map resolves less, so the smallest
+ * shadow worth a depth draw grows with it.
+ * @internal
+ */
+export const SHADOW_CASTER_RADIUS_REFERENCE_MAP = 2048;
+/** Smallest caster radius worth a depth draw at `mapSize`, in metres. @internal */
+export function minShadowCasterRadius(mapSize, reference = 0.5) {
+    return reference * Math.max(1, SHADOW_CASTER_RADIUS_REFERENCE_MAP / mapSize);
+}

package/dist/world/WorldScene.js

@@ -23,7 +23,7 @@ import { MeasuredBoundsGroup } from "../render/measureBounds.js";
 import { EntitySprite, IsolatedEntityModel } from "../render/SceneModels.js";
 import { CharacterCrowd } from "../render/CharacterCrowd.js";
 import { CharacterCrowdRegistry, crowdEligible, crowdKindOf, crowdKindReady, } from "../render/crowdRegistry.js";
-import { characterLodTier, clearCharacterLodTier, setCharacterLodTier, } from "../render/characterLod.js";
+import { characterLodTier, characterRigTier, clearCharacterLodTier, setCharacterLodTier, } from "../render/characterLod.js";
 import { resolveEntityModel, resolveObjectModel } from "../render/resolveModel.js";
 import { useRenderVisibility } from "../visibility/CullingProvider.js";
 import { writePoseIfChanged, writeRenderPoseIfChanged, emptyPoseMemo } from "./entityPose.js";
@@ -34,6 +34,7 @@ const GROUND_SIZE = 160;
 const GROUND_SEGMENTS = 80;
 function EntityMarker({ entity, custom, model, sprite, isLocal, targeted, selected, crowd, onSelect, }) {
     const groupRef = useRef(null);
+    const modelRef = useRef(null);
     const ctx = useGameContext();
     const visibleRef = useRenderVisibility();
     const entityId = entity.id;
@@ -53,21 +54,33 @@ function EntityMarker({ entity, custom, model, sprite, isLocal, targeted, select
         if (live === null)
             return;
         writeRenderPoseIfChanged(group, ctx, entityId, live, scratchRef.current, memoRef.current);
+        const shown = live.hidden !== true && visibleRef.current(entityId);
         let tier;
-        if (crowdModel !== undefined && crowd !== undefined && crowdKind !== undefined && crowdKindReady(crowdKind)) {
+        let batched = false;
+        if (crowdModel !== undefined && crowd !== undefined && crowdKind !== undefined && crowdKindReady(crowdKind) && shown) {
             const [x, y, z] = live.position;
             const distance = Math.sqrt((state.camera.position.x - x) ** 2 + (state.camera.position.y - y) ** 2 + (state.camera.position.z - z) ** 2);
-            tier = characterLodTier(distance, crowdModel.lod === false ? undefined : crowdModel.lod, tierRef.current);
-            setCharacterLodTier(entityId, tier);
+            const lod = crowdModel.lod === false ? undefined : crowdModel.lod;
+            tier = characterLodTier(distance, lod, tierRef.current);
             if (tier === "crowd") {
-                crowd.set(entityId, crowdKind, { x, y, z, rotationY: live.rotationY ?? 0, speed: groundSpeed(live) });
-            }
-            else {
-                crowd.delete(entityId);
+                // A painted character keeps its own rig: its strokes live on its materials, not in the batch.
+                const painted = ctx.scene.entity.paint.version(entityId) !== 0;
+                batched = !painted && crowd.claim(entityId, crowdKind, { x, y, z, rotationY: live.rotationY ?? 0, speed: groundSpeed(live) });
+                // An over-cap batch leaves the rest of its kind on their own rigs at the tier their distance
+                // earns, so a crowded scene loses draws rather than characters.
+                if (!batched)
+                    tier = characterRigTier(distance, lod);
             }
+            setCharacterLodTier(entityId, tier);
         }
+        if (!batched)
+            crowd?.delete(entityId);
         tierRef.current = tier;
-        group.visible = live.hidden !== true && visibleRef.current(entityId) && tier !== "crowd";
+        // The marker itself stays mounted and visible while a batch draws the character: its status
+        // rings and the hit test on its rig have to behave as they do when it draws itself.
+        if (modelRef.current !== null)
+            modelRef.current.visible = !batched;
+        group.visible = shown;
     });
     useEffect(() => () => {
         crowd?.delete(entityId);
@@ -80,7 +93,7 @@ function EntityMarker({ entity, custom, model, sprite, isLocal, targeted, select
             const live = ctx.scene.entity.get(entityId);
             if (live !== null)
                 onSelect(live);
-        }, children: [selected ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.02, children: [_jsx("ringGeometry", { args: [0.8, 0.95, 32] }), _jsx("meshBasicMaterial", { color: "#34d399", transparent: true, opacity: 0.9 })] })) : null, custom !== undefined && custom !== null ? (_jsx(MeasuredBoundsGroup, { target: "entity", measureKey: name, children: custom })) : model !== undefined ? (_jsx(IsolatedEntityModel, { model: model, instanceId: entityId, measure: { target: "entity", key: name }, fallback: sprite !== undefined ? _jsx(EntitySprite, { sprite: sprite }) : undefined })) : sprite !== undefined ? (_jsx(EntitySprite, { sprite: sprite })) : role === "prop" ? (_jsxs("mesh", { "position-y": 0.5, castShadow: true, receiveShadow: true, children: [_jsx("sphereGeometry", { args: [0.45, 24, 24] }), _jsx(DefaultSurface, { color: color })] })) : (_jsxs("group", { scale: ctx.scene.entity.visualScaleOf(entityId), children: [_jsxs("mesh", { "position-y": 0.95, castShadow: true, receiveShadow: true, children: [_jsx("capsuleGeometry", { args: [0.35, 1.1, 6, 14] }), _jsx(DefaultSurface, { color: color, roughness: 0.6 })] }), _jsxs("mesh", { position: [0, 1.35, 0.32], children: [_jsx("boxGeometry", { args: [0.16, 0.16, 0.16] }), _jsx("meshStandardMaterial", { color: "#f8fafc" })] })] })), targeted ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.03, children: [_jsx("ringGeometry", { args: [0.6, 0.75, 28] }), _jsx("meshBasicMaterial", { color: "#f87171" })] })) : null] }));
+        }, children: [selected ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.02, children: [_jsx("ringGeometry", { args: [0.8, 0.95, 32] }), _jsx("meshBasicMaterial", { color: "#34d399", transparent: true, opacity: 0.9 })] })) : null, _jsx("group", { ref: modelRef, children: custom !== undefined && custom !== null ? (_jsx(MeasuredBoundsGroup, { target: "entity", measureKey: name, children: custom })) : model !== undefined ? (_jsx(IsolatedEntityModel, { model: model, instanceId: entityId, measure: { target: "entity", key: name }, fallback: sprite !== undefined ? _jsx(EntitySprite, { sprite: sprite }) : undefined })) : sprite !== undefined ? (_jsx(EntitySprite, { sprite: sprite })) : role === "prop" ? (_jsxs("mesh", { "position-y": 0.5, castShadow: true, receiveShadow: true, children: [_jsx("sphereGeometry", { args: [0.45, 24, 24] }), _jsx(DefaultSurface, { color: color })] })) : (_jsxs("group", { scale: ctx.scene.entity.visualScaleOf(entityId), children: [_jsxs("mesh", { "position-y": 0.95, castShadow: true, receiveShadow: true, children: [_jsx("capsuleGeometry", { args: [0.35, 1.1, 6, 14] }), _jsx(DefaultSurface, { color: color, roughness: 0.6 })] }), _jsxs("mesh", { position: [0, 1.35, 0.32], children: [_jsx("boxGeometry", { args: [0.16, 0.16, 0.16] }), _jsx("meshStandardMaterial", { color: "#f8fafc" })] })] })) }), targeted ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.03, children: [_jsx("ringGeometry", { args: [0.6, 0.75, 28] }), _jsx("meshBasicMaterial", { color: "#f87171" })] })) : null] }));
 }
 function ObjectMarker({ object, custom, model, style, }) {
     const groupRef = useRef(null);
@@ -237,7 +250,11 @@ function WorldActors({ entitySprites, entityModels, objectModels, objectStyles,
                 if (crowdEligible(model))
                     crowdModels.set(crowdKindOf(model), model);
                 return (_jsx(EntityMarker, { entity: entity, custom: custom, model: model, sprite: sprite, isLocal: entityId === controlledId, targeted: entityId === targetId, selected: selectedIds.has(entityId), crowd: crowdRegistry, onSelect: handleSelect }, entityId));
-            }), crowdModels.size > 0 ? _jsx(CharacterCrowd, { models: [...crowdModels.values()], registry: crowdRegistry }) : null, grouped.singles.map((candidate) => renderSingle(candidate.object)), grouped.batches.map((batch) => _jsx(StaticObjectModels, { batch: batch, single: renderSingle }, batch.key))] }));
+            }), crowdModels.size > 0 ? (_jsx(CharacterCrowd, { models: [...crowdModels.values()], registry: crowdRegistry, onPick: (entityId) => {
+                    const live = ctx.scene.entity.get(entityId);
+                    if (live !== null)
+                        handleSelect(live);
+                } })) : null, grouped.singles.map((candidate) => renderSingle(candidate.object)), grouped.batches.map((batch) => _jsx(StaticObjectModels, { batch: batch, single: renderSingle }, batch.key))] }));
 }
 export function WorldView({ entitySprites, entityModels, objectModels, objectStyles, environment, assets, renderEntity, renderObject, selectedIds, hideLocalActor, editorLayers, }) {
     return (_jsxs(_Fragment, { children: [_jsx(WindClock, {}), _jsx(WorldEnvironment, { environment: environment }), _jsx(WorldActors, { entitySprites: entitySprites, entityModels: entityModels, objectModels: objectModels, objectStyles: objectStyles, assets: assets, renderEntity: renderEntity, renderObject: renderObject, selectedIds: selectedIds, hideLocalActor: hideLocalActor, editorLayers: editorLayers })] }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -16,6 +16,10 @@
     "skills"
   ],
   "exports": {
+    "./play": {
+      "types": "./dist/play/index.d.ts",
+      "default": "./dist/play/index.js"
+    },
     "./weather": {
       "types": "./dist/weather/index.d.ts",
       "default": "./dist/weather/index.js"
@@ -35,9 +39,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.33.0",
-    "@jgengine/react": "^0.33.0",
-    "@jgengine/ws": "^0.33.0"
+    "@jgengine/core": "^0.35.0",
+    "@jgengine/react": "^0.35.0",
+    "@jgengine/ws": "^0.35.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.33.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.35.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.33.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.35.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -436,7 +436,7 @@
 - `HeadlessCommandInterface` (interface): interface HeadlessCommandInterface — Canvas-free command/intent surface for {@link HeadlessRunner} — invoke a game's registered UI commands and read the resulting reactive state off `ctx`.
 - `HeadlessInput` (interface): interface HeadlessInput — One step's worth of player intent handed to {@link HeadlessRunner.step} — the held-action set and pointer state the shell would otherwise publish from the browser each frame.
 - `HeadlessRunner` (interface): interface HeadlessRunner — A renderer-free driver for a game loop: builds a {@link GameContext} from a {@link GameDefinition}, runs the init hooks, then advances the simulation one step at a time from injected input. No React, R3F, or three.js — the whole play path (time, input, `onTick`, behaviour nav, optional player movement) runs from `core` primitives alone, so a non-React host (a server tick, a test, a CLI replay) can play a real game and read its world snapshot. The shell's FrameDriver is one such driver bolted to `useFrame`; this is the same step distilled out of the render tree.
-- `HeadlessRunnerOptions` (interface): interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> { definition: GameDefinition<TAssetRef, TMultiplayer>; content?: GameContextContent; loop?: GameLoop<GameContext>; player?: {userId: string; isNew: boolean}; now?: () => number; maxStepSeconds?: number; playerMovement?: boolean; movement?: … — ⚠ undocumented
+- `HeadlessRunnerOptions` (interface): interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> { definition: GameDefinition<TAssetRef, TMultiplayer>; content?: GameContextContent; loop?: GameLoop<GameContext>; player?: {userId: string; isNew: boolean}; now?: () => number; seed?: string | number; maxStepSeconds?: number; playerMovemen… — ⚠ undocumented
 - `createHeadlessRunner` (function): function createHeadlessRunner<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HeadlessRunnerOptions<TAssetRef, TMultiplayer>): HeadlessRunner — ⚠ undocumented
 
 ## @jgengine/core/runtime/hostPersistence

package/skills/jgengine-ui/api.md

@@ -2162,10 +2162,13 @@
 
 ## @jgengine/shell/audio/audioEngine
 
-- `AudioEmitterHandle` (interface): interface AudioEmitterHandle { isPlaying?(): boolean; setPosition(position: Vec3): void; setRate(rate: number): void; setGain(gain: number): void; setLowpass(hz: number): void; setHighpass(hz: number): void; setVelocity(velocity: Vec3): void; stop(): void } — ⚠ undocumented
+- `AudioAmbienceState` (interface): interface AudioAmbienceState — Current ambience mix, by zone id.
+- `AudioEmitterHandle` (interface): interface AudioEmitterHandle { isPlaying?(): boolean; setPosition(position: Vec3): void; setRate(rate: number): void; setGain(gain: number): void; setLowpass(hz: number): void; setHighpass(hz: number): void; setVelocity(velocity: Vec3): void; setOcclusion(amount: numbe… — ⚠ undocumented
 - `AudioEngine` (interface): interface AudioEngine { setListenerPose(pose: ListenerPose | Vec3): void; setVoiceLimit(maxTotal: number, overflow?: VoiceAllocatorConfig["overflow"]): void; play(soundId: string, position?: Vec3): void; playOneShot(soundId: string, position?: Vec3): void; playL… — ⚠ undocumented · used by `createAudioEngine`: Game-owned sound catalog playback with bounded SFX reservations, spatial panning, and shared buses.
 - `AudioLevel` (interface): interface AudioLevel — Master-output level, `0..1`. Pooled by {@link AudioEngine.measure} - read it, don't retain it.
-- `AudioSceneConfig` (interface): interface AudioSceneConfig { sounds?: Record<string, SoundDef>; maxVoices?: number; voiceOverflow?: VoiceAllocatorConfig["overflow"]; voiceAllocator?: VoiceAllocator; buses?: Record<string, AudioBusDef>; music?: Record<string, MusicTheme>; musicBus?: string } — ⚠ undocumented · used by `createAudioEngine`: Game-owned sound catalog playback with bounded SFX reservations, spatial panning, and shared buses.
+- `AudioOcclusionStats` (interface): interface AudioOcclusionStats — Measured geometry-occlusion work, cumulative since the engine was created.
+- `AudioSceneConfig` (interface): interface AudioSceneConfig { sounds?: Record<string, SoundDef>; maxVoices?: number; voiceOverflow?: VoiceAllocatorConfig["overflow"]; voiceAllocator?: VoiceAllocator; buses?: Record<string, AudioBusDef>; music?: Record<string, MusicTheme>; musicBus?: string; zones?: … — ⚠ undocumented · used by `createAudioEngine`: Game-owned sound catalog playback with bounded SFX reservations, spatial panning, and shared buses.
+- `DuckOptions` (interface): interface DuckOptions — How long and how far to duck buses for {@link AudioEngine.duck}.
 - `ListenerPose` (interface): interface ListenerPose — Position and orientation for a spatial-audio listener.
 - `MAX_PENDING_CUES` (const): const MAX_PENDING_CUES: 16 — Cues held while the browser keeps the audio context suspended, before any user gesture.
 - `Vec3` (interface): interface Vec3 { x: number; y: number; z: number } — ⚠ undocumented · used by `coverPoints` (@jgengine/core/ai/tacticalQueries): Returns boundary locations that are hidden from a threat.
@@ -2174,7 +2177,7 @@
 ## @jgengine/shell/audio/audioProbe
 
 - `AudioProbe` (interface): interface AudioProbe — The read-only handle a capture script or devtools uses to prove the mix is producing sound.
-- `installAudioProbe` (function): function installAudioProbe(engine: AudioEngine): () => void — Publish the audio engine's own level readout on `window.__jgengineAudio`, so a headless capture can state a measured RMS instead of guessing from a screenshot. Reads only; it never plays or changes a bus.
+- `installAudioProbe` (function): function installAudioProbe(engine: AudioEngine): () => void — Publish the audio engine's own level, ambience and occlusion readouts on `window.__jgengineAudio`, so a headless capture can state measured values instead of guessing from a screenshot. Reads only; it never plays or changes a bus.
 
 ## @jgengine/shell/audio/busMix
 
@@ -2233,6 +2236,11 @@
 
 - `playMusicNote` (function): function playMusicNote(ctx: Ctx, event: NoteEvent, when: number, spb: number, out: GainNode, transpose = 0): void — Play one theme note through its instrument voice into `out` (a per-layer gain node the director wires to master + reverb). `spb` is seconds-per-beat and `transpose` shifts the note in semitones for per-zone key changes. This is the engine's reusable instrument library; unknown instruments fall back to a sine.
 
+## @jgengine/shell/audio/occlusion
+
+- `BlockingRaycastSource` (interface): interface BlockingRaycastSource — The narrow slice of the scene a line-of-hearing test needs.
+- `sceneLineBlocked` (function): function sceneLineBlocked(source: BlockingRaycastSource, from: Vec3, to: Vec3): boolean — Whether blocking world geometry (objects and wall segments, never creatures or terrain) lies between the listener and an emitter. One scene query per call; the engine owns how often it runs.
+
 ## @jgengine/shell/audio/synthEngine
 
 - `SynthPlayback` (interface): interface SynthPlayback — Scheduled procedural sources; stopping releases their source/filter/envelope graph.
@@ -2713,6 +2721,62 @@
 - `resolvePeerShellMultiplayer` (function): function resolvePeerShellMultiplayer(args: ResolvePeerShellMultiplayerArgs): Promise<ShellMultiplayer & { close: () => Promise<void> }> — Opens a peer session. With `playable`, one host runs the game loop and guests mirror its shared world. Await `close()` to finish authoritative persistence. Same-origin rooms use BroadcastChannel signaling.
 - `resolveShellMultiplayer` (function): function resolveShellMultiplayer(args: ResolveShellMultiplayerArgs): ShellMultiplayer | null — ⚠ undocumented
 
+## @jgengine/shell/play
+
+- `PLAY_MOVE_ACTIONS` (const): const PLAY_MOVE_ACTIONS: Readonly<Record<PlayMove, string>> — Movement action ids a {@link PlayMove} holds, so a script walks through the same controller a player does.
+- `PlayAimStep` (interface): interface PlayAimStep extends PlayStepBase — Point the walk controller and the aim payload at a yaw/pitch, in radians.
+- `PlayCommandStep` (interface): interface PlayCommandStep extends PlayStepBase — Run a registered command directly, with whatever input it declares.
+- `PlayExpectation` (interface): interface PlayExpectation — One assertion about world state. Read happens twice — right after `setup` and on the assertion's own tick — so a script can prove change ("health dropped") as well as a level ("wave is 2").
+- `PlayExpectationResult` (interface): interface PlayExpectationResult — One assertion's verdict, with both readings so a failure says what changed and by how much.
+- `PlayFireStep` (interface): interface PlayFireStep extends PlayStepBase — Hold the `fire` action: the bound `fire` command runs on the press tick, then on its repeat cadence.
+- `PlayMove` (type): type PlayMove = "forward" | "back" | "left" | "right" — Direction a scripted step walks, using the shell's own movement actions.
+- `PlayMoveStep` (interface): interface PlayMoveStep extends PlayStepBase — Hold a movement direction for `ticks` — the shell walk controller's own held actions.
+- `PlayRunOptions` (interface): interface PlayRunOptions — Options for one scripted play run.
+- `PlayRunResult` (interface): interface PlayRunResult — Everything a scripted run produced: the timeline, the assertion verdicts, and a digest of the timeline for replay comparison.
+- `PlayScript` (interface): interface PlayScript — A script to play against a real game: what to do, on which tick, and what must be true afterwards.
+- `PlayScriptSpec` (interface): interface PlayScriptSpec — What {@link createPlayScript} accepts: the same script with the derived fields optional.
+- `PlayStep` (type): type PlayStep = PlayMoveStep | PlayAimStep | PlayFireStep | PlayUseStep | PlayWaitStep | PlayCommandStep — One tick-based action in a script.
+- `PlayTimelineEntry` (interface): interface PlayTimelineEntry — One row of what happened, on the tick it happened.
+- `PlayTimelineKind` (type): type PlayTimelineKind = "step" | "command" | "event" | "check" — What a timeline row records: a scripted action, a command result, a world event, or an assertion reading.
+- `PlayUseStep` (interface): interface PlayUseStep extends PlayStepBase — Press one bound action id once (default one tick) — `interact`, `reload`, `useAbility`, a game's own action.
+- `PlayValue` (type): type PlayValue = number | string | boolean | null — A reading an assertion compares: a stat, a distance, a count, a phase id.
+- `PlayWaitStep` (interface): interface PlayWaitStep extends PlayStepBase — Hold nothing for `ticks`, letting the world run.
+- `createPlayScript` (function): function createPlayScript(spec: PlayScriptSpec): PlayScript — Validate and normalize a script: whole-tick timings, sorted steps, a derived run length.
+- `formatPlayTimelineEntry` (function): function formatPlayTimelineEntry(entry: PlayTimelineEntry): string — One compact timeline line: `t=120 event combat.damage to=bruiser amount=12 remaining=54`.
+- `playTimelineDigest` (function): function playTimelineDigest(timeline: readonly PlayTimelineEntry[]): string — FNV-1a over the timeline's canonical JSON. Cheap, dependency-free and stable across runs and machines, which is all a replay comparison needs.
+- `runPlayScript` (function): function runPlayScript(playable: PlayableGame, spec: PlayScript | PlayScriptSpec, options: PlayRunOptions = {}): PlayRunResult — Play a real game without a browser: boot its `PlayableGame` through the headless runner, apply a tick-based {@link PlayScript}, and return what happened plus whether the script's assertions held.
+
+## @jgengine/shell/play/run
+
+- `PlayRunOptions` (interface): interface PlayRunOptions — Options for one scripted play run.
+- `runPlayScript` (function): function runPlayScript(playable: PlayableGame, spec: PlayScript | PlayScriptSpec, options: PlayRunOptions = {}): PlayRunResult — Play a real game without a browser: boot its `PlayableGame` through the headless runner, apply a tick-based {@link PlayScript}, and return what happened plus whether the script's assertions held.
+
+## @jgengine/shell/play/script
+
+- `PLAY_MOVE_ACTIONS` (const): const PLAY_MOVE_ACTIONS: Readonly<Record<PlayMove, string>> — Movement action ids a {@link PlayMove} holds, so a script walks through the same controller a player does.
+- `PlayAimStep` (interface): interface PlayAimStep extends PlayStepBase — Point the walk controller and the aim payload at a yaw/pitch, in radians.
+- `PlayCommandStep` (interface): interface PlayCommandStep extends PlayStepBase — Run a registered command directly, with whatever input it declares.
+- `PlayExpectation` (interface): interface PlayExpectation — One assertion about world state. Read happens twice — right after `setup` and on the assertion's own tick — so a script can prove change ("health dropped") as well as a level ("wave is 2").
+- `PlayFireStep` (interface): interface PlayFireStep extends PlayStepBase — Hold the `fire` action: the bound `fire` command runs on the press tick, then on its repeat cadence.
+- `PlayMove` (type): type PlayMove = "forward" | "back" | "left" | "right" — Direction a scripted step walks, using the shell's own movement actions.
+- `PlayMoveStep` (interface): interface PlayMoveStep extends PlayStepBase — Hold a movement direction for `ticks` — the shell walk controller's own held actions.
+- `PlayScript` (interface): interface PlayScript — A script to play against a real game: what to do, on which tick, and what must be true afterwards.
+- `PlayScriptSpec` (interface): interface PlayScriptSpec — What {@link createPlayScript} accepts: the same script with the derived fields optional.
+- `PlayStep` (type): type PlayStep = PlayMoveStep | PlayAimStep | PlayFireStep | PlayUseStep | PlayWaitStep | PlayCommandStep — One tick-based action in a script.
+- `PlayUseStep` (interface): interface PlayUseStep extends PlayStepBase — Press one bound action id once (default one tick) — `interact`, `reload`, `useAbility`, a game's own action.
+- `PlayValue` (type): type PlayValue = number | string | boolean | null — A reading an assertion compares: a stat, a distance, a count, a phase id.
+- `PlayWaitStep` (interface): interface PlayWaitStep extends PlayStepBase — Hold nothing for `ticks`, letting the world run.
+- `createPlayScript` (function): function createPlayScript(spec: PlayScriptSpec): PlayScript — Validate and normalize a script: whole-tick timings, sorted steps, a derived run length.
+
+## @jgengine/shell/play/timeline
+
+- `PlayExpectationResult` (interface): interface PlayExpectationResult — One assertion's verdict, with both readings so a failure says what changed and by how much.
+- `PlayRunResult` (interface): interface PlayRunResult — Everything a scripted run produced: the timeline, the assertion verdicts, and a digest of the timeline for replay comparison.
+- `PlayTimelineEntry` (interface): interface PlayTimelineEntry — One row of what happened, on the tick it happened.
+- `PlayTimelineKind` (type): type PlayTimelineKind = "step" | "command" | "event" | "check" — What a timeline row records: a scripted action, a command result, a world event, or an assertion reading.
+- `formatPlayTimelineEntry` (function): function formatPlayTimelineEntry(entry: PlayTimelineEntry): string — One compact timeline line: `t=120 event combat.damage to=bruiser amount=12 remaining=54`.
+- `playTimelineDigest` (function): function playTimelineDigest(timeline: readonly PlayTimelineEntry[]): string — FNV-1a over the timeline's canonical JSON. Cheap, dependency-free and stable across runs and machines, which is all a replay comparison needs.
+
 ## @jgengine/shell/pointer/PointerOverlays
 
 - `ContextMenuView` (function): function ContextMenuView({ menu, x, y, onPick, onClose, }: { menu: ContextMenu; x: number; y: number; onPick: (verb: ContextVerb) => void; onClose: () => void; }): React.JSX.Element — ⚠ undocumented
@@ -2770,7 +2834,7 @@
 
 ## @jgengine/shell/render/CharacterCrowd
 
-- `CharacterCrowd` (function): function CharacterCrowd({ models, registry, fps = 24 }: CharacterCrowdProps): React.JSX.Element — Draws far characters through the GPU crowd path: one baked rig per character kind, one instanced draw per material, every member's clip, time offset and speed sampled in the vertex shader. The entity markers decide who is far enough (their `lod` tiers) and write poses into `registry`; this layer owns the bakes, the materials and the instance buffers. Mount it in the same canvas as the entity markers; unmount it to fall back to per-entity rigs.
+- `CharacterCrowd` (function): function CharacterCrowd({ models, registry, fps = 24, onPick }: CharacterCrowdProps): React.JSX.Element — Draws characters through the GPU batch path: one baked rig per character kind, one instanced draw per material, every member's clip, time offset and speed sampled in the vertex shader. The entity markers decide who is batched (their `lod` tiers and the batch capacity) and write poses into `registry`; this layer owns the bakes, the materials and the instance buffers. Mount it in the same canvas as the entity markers; unmount it to fall back to per-entity rigs.
 - `CharacterCrowdProps` (interface): interface CharacterCrowdProps — Props for {@link CharacterCrowd}.
 
 ## @jgengine/shell/render/EntityPreview
@@ -2809,7 +2873,7 @@
 - `SkinnedCrowdSource` (interface): interface SkinnedCrowdSource — A rig to bake: a loaded scene with skinned meshes and its clips.
 - `SkinnedInstances` (function): function SkinnedInstances({ url, instances, clips, once, fps, modelScale = 1, castShadow = true, receiveShadow = true, timeScale = 1, }: SkinnedInstancesProps): React.JSX.Element — Renders many animated copies of one rigged model in a single instanced draw per material: the rig's clips are baked to a bone-matrix texture once, and each instance samples its own clip, time offset and speed on the GPU. For crowds, spectators and distant NPCs; a character that needs blending, IK or attachments stays an entity model.
 - `SkinnedInstancesProps` (interface): interface SkinnedInstancesProps — Props for {@link SkinnedInstances}.
-- `bakeSkinnedCrowd` (function): function bakeSkinnedCrowd(source: SkinnedCrowdSource, options: BakeSkinnedCrowdOptions = {}): BakedSkinnedCrowd — Bakes a rig for {@link SkinnedInstances}: merges its skinned meshes into one geometry in bind space, samples every requested clip at `fps`, and writes each bone's model-space skinning matrix into a float texture laid out by `planBoneTexture`. Meshes with several materials keep only the first. Exported for tests and custom crowd renderers.
+- `bakeSkinnedCrowd` (function): function bakeSkinnedCrowd(source: SkinnedCrowdSource, options: BakeSkinnedCrowdOptions = {}): BakedSkinnedCrowd — Bakes a rig for {@link SkinnedInstances}: merges its meshes into one geometry per material, samples every requested clip at `fps`, and writes each slot's model-space matrix into a float texture laid out by `planBoneTexture`. A skinned mesh contributes its bones as slots; a rig-less part that a clip moves contributes that node, with its vertices weighted fully to it, so a node-transform character (a walking miniature with rotating limbs) batches through the same shader. A model with no clips at all bakes to `animated: false`: one merged geometry per material and no texture. Meshes with several materials keep only the first. Exported for tests and custom crowd renderers.
 - `createCrowdUniforms` (function): function createCrowdUniforms(baked: BakedSkinnedCrowd): CrowdUniforms — Builds the uniforms a crowd material reads: the texture and per-clip start, frames, fps and loop.
 - `patchCrowdMaterial` (function): function patchCrowdMaterial<T extends THREE.Material>(material: T, uniforms: CrowdUniforms): T — Patches a material so each instance skins itself from the crowd texture: per-instance `crowdPlay` is (clip index, time offset, speed). Works on any built-in material, the depth material for shadows included.
 
@@ -2833,14 +2897,20 @@
 - `characterLodInterval` (function): function characterLodInterval(tier: CharacterLodTier): number — Frames between pose updates for a tier: 1, 2, 4, and `0` meaning "never" for the crowd tier.
 - `characterLodRate` (function): function characterLodRate(tier: CharacterLodTier): number — Share of frames a tier poses the rig: 1, 0.5, 0.25, and 0 once the GPU crowd draws it.
 - `characterLodTier` (function): function characterLodTier(distance: number, config: ModelLodConfig | undefined, previous?: CharacterLodTier): CharacterLodTier — The tier a character at `distance` falls in. Passing the tier it held last frame applies the crowd hysteresis, so a character walking along the crowd boundary does not swap representation every frame.
+- `characterRigTier` (function): function characterRigTier(distance: number, config: ModelLodConfig | undefined): CharacterLodTier — The tier a character poses its own rig on, ignoring the crowd path. A crowd character whose batch is full falls back to this, so an over-cap crowd draws every member on its own rig instead of dropping the ones past the cap.
+
+## @jgengine/shell/render/crowdBatch
+
+- `poseTimeOffset` (function): function poseTimeOffset(id: string): number — A stable non-zero time offset for a member with no recorded pose, so a crowd is not in lockstep.
 
 ## @jgengine/shell/render/crowdRegistry
 
 - `CharacterCrowdRegistry` (class): class CharacterCrowdRegistry — The characters the crowd layer is currently drawing, written by their entity markers each frame. It holds poses rather than React state: 71 pedestrians writing matrices must not re-render the world, and the crowd batch reads the same entries back to fill its instance buffers.
-- `crowdClipForSpeed` (function): function crowdClipForSpeed(clips: readonly string[], speed: number): string | undefined — The baked clip a crowd member at `speed` plays; clips are `[idle, walk, run]` as {@link crowdClipsOf} orders them.
-- `crowdClipsOf` (function): function crowdClipsOf(model: ModelConfig, clipNames: readonly string[]): string[] — The clips a crowd batch bakes for a model: its resolved idle, walk and run, in that order. Empty when the rig's clip names do not resolve to locomotion roles, which leaves the character on its own rig instead of drawing a frozen crowd copy.
-- `crowdEligible` (function): function crowdEligible(model: ModelConfig | undefined): model is ModelConfig — Whether a model can leave its own rig for the GPU crowd path: a rigged, clip-played, plain model.
+- `crowdClipForSpeed` (function): function crowdClipForSpeed(clips: readonly string[], speed: number, bands?: CrowdSpeedBands): string | undefined — The baked clip a crowd member at `speed` plays; clips are `[idle, walk, run]` as {@link crowdClipsOf} orders them. `bands` is the model's own walk/run speed.
+- `crowdClipsOf` (function): function crowdClipsOf(model: ModelConfig, clipNames: readonly string[]): string[] — The clips a crowd batch bakes for a model: its resolved idle, walk and run, in that order. Empty when the model plays no clips at all (a static character) or when the rig's clip names do not resolve to locomotion roles, which leaves the character on its own rig instead of drawing a frozen crowd copy.
+- `crowdEligible` (function): function crowdEligible(model: ModelConfig | undefined): model is ModelConfig — Whether a model can leave its own rig for the GPU crowd path: one whose drawn result a batch can reproduce. A rigged, clip-played, plain model qualifies, and so does a model with no animation at all (a static crowd character) — it has no playback to lose. A model that needs per-entity materials, wind, hidden nodes, IK, attachments or a part composition keeps its own rig.
 - `crowdKindOf` (function): function crowdKindOf(model: ModelConfig): string — The identity a character model shares with every other model the GPU crowd can draw: rig url, height normalization and material tint. Two entity kinds with the same key can share one instanced draw; a different tint or height needs its own.
+- `crowdSpeedBandsOf` (function): function crowdSpeedBandsOf(model: ModelConfig, clipNames: readonly string[]): CrowdSpeedBands — The ground speeds the model's own locomotion graph switches clips at, so a batched character walks and idles at the same speed its own rig would. A model that declares none keeps the engine's defaults.
 
 ## @jgengine/shell/render/decalGeometry
 
@@ -2944,7 +3014,7 @@
 
 ## @jgengine/shell/render/shaderWarmup
 
-- `SHADER_WARMUP_DEFAULTS` (const): const SHADER_WARMUP_DEFAULTS: { readonly quietMs: 400; readonly budgetMs: 5000; readonly roundFloorMs: 1500; readonly streamWaitMs: 2000; } — Defaults sized to cover an initial burst of streamed models without holding the screen.
+- `SHADER_WARMUP_DEFAULTS` (const): const SHADER_WARMUP_DEFAULTS: { readonly quietMs: 250; readonly planBudgetMs: 12000; readonly planFloorMs: 1500; readonly pollMs: 100; readonly backgroundMs: 2000; readonly backgroundEveryMs: 250; } — Defaults sized to cover one load: the covered wait is the driver's link time, not a guess.
 - `ShaderWarmup` (interface): interface ShaderWarmup — A warmup in flight: its promise, its latest state, and a way to stop it.
 - `ShaderWarmupOptions` (interface): interface ShaderWarmupOptions — Options for {@link createShaderWarmup}; the clock, sleep and loader signal are injectable for tests.
 - `ShaderWarmupRenderer` (interface): interface ShaderWarmupRenderer — The renderer surface the warmup needs; a real `WebGLRenderer` satisfies it.

package/skills/jgengine-ui/capabilities.md

@@ -72,7 +72,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `attachWaveFeedback` (function) · `import { attachWaveFeedback } from "@jgengine/shell/audio/eventFeedback"`
 
-## audio-probe — read the live master RMS/peak and bus gains from a running page for capture and diagnostics
+## audio-probe — read the live master RMS/peak, bus gains, ambience zone mix and occlusion cost from a running page for capture and diagnostics
 
 - `installAudioProbe` (function) · `import { installAudioProbe } from "@jgengine/shell/audio/audioProbe"`
 
@@ -142,7 +142,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `captureCanvas` (function) · `import { captureCanvas } from "@jgengine/shell/render/sceneCapture"`
 
-## character-crowd — draw distant animated characters on the GPU instead of posing their skeletons
+## character-crowd — draw animated or static characters as batched instanced draws instead of posing each skeleton
 
 - `CharacterCrowd` (function) · `import { CharacterCrowd } from "@jgengine/shell/render/CharacterCrowd"`
 
@@ -736,6 +736,11 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `PlacementGhost` (function) · `import { PlacementGhost } from "@jgengine/shell/structures"`
 
+## play-script — write a game's behaviour as a tick-based script with declarative assertions instead of playing it in a browser
+
+- `createPlayScript` (function) · `import { createPlayScript } from "@jgengine/shell/play"`
+- `runPlayScript` (function) · `import { runPlayScript } from "@jgengine/shell/play"`
+
 ## popover — viewport-flipping, viewport-clamped anchored popover/tooltip shell
 
 - `Popover` (function) · `import { Popover } from "@jgengine/react"`

package/skills/jgengine-world/api.md

@@ -106,8 +106,10 @@
 - `DriverState` (interface): interface DriverState — Serializable per-driver state advanced in place by {@link driveStep}.
 - `DriverStep` (interface): interface DriverStep extends AxisInput — {@link driveStep}'s result: the axis sample to feed the vehicle sim, plus arrival.
 - `DriverTuning` (interface): interface DriverTuning — Vehicle-feel numbers the game supplies; everything has a sensible default except `maxSpeed`.
+- `PaceBand` (interface): interface PaceBand — Catch-up pacing for one car in a field: the gap it tries to hold to a reference car (a rival, the player, a convoy lead) and how its pace bends when it drifts off that gap. Past `margin` by `tolerance` it sheds up to `ease` of its pace; short of it by `tolerance` it gains up to `push`; inside that tolerance it leaves the car alone. The push never outdrives `DriverTuning.maxSpeed`, so a band changes how hard a car tries, never what it is built to do.
 - `createDriverState` (function): function createDriverState(targetX = 0, targetZ = 0): DriverState — Fresh driver state committed to an initial target (usually the spawn-time goal or the spawn position itself).
-- `driveStep` (function): function driveStep(state: DriverState, dt: number, pose: DriverPose, goal: DriverGoal, profile: DifficultyProfile, tuning: DriverTuning, rng: () => number, obstacleAhead: number | null = null): DriverStep — Advance one driving step, mutating `state`, and return the {@link AxisInput} to feed the vehicle sim. `obstacleAhead` is the caller-measured distance to the nearest blocker in the driving corridor this step (`null`/omitted when clear) — the driver perceives it late by `speed * reactionSeconds`, so easy tiers brake at the last moment and expert tiers with proper margin. The steering target is a delay-line over the goal — resampled every `reactionSeconds`, so it trails a moving goal by up to that long, which is what makes an easy chaser visibly cut toward where the target *was*. When throttle produces no motion for a tier-scaled while the driver reverses out with counter-steer (brake past standstill — the shared sim's reverse).
+- `driveStep` (function): function driveStep(state: DriverState, dt: number, pose: DriverPose, goal: DriverGoal, profile: DifficultyProfile, tuning: DriverTuning, rng: () => number, obstacleAhead: number | null = null): DriverStep — Advance one driving step, mutating `state`, and return the {@link AxisInput} to feed the vehicle sim. `obstacleAhead` is the caller-measured distance to the nearest blocker in the driving corridor this step (`null`/omitted when clear) — the driver perceives it late by `speed * reactionSeconds`, so easy tiers brake at the last moment and expert tiers with proper margin. The steering target is a delay-line over the goal — resampled every `reactionSeconds`, so it trails a moving goal by up to that long, which is what makes an easy chaser visibly cut toward where the target *was*. A {@link PaceBand} on the goal eases a car ahead of its margin and pushes one behind it, bounded by the car's own top speed. When throttle produces no motion for a tier-scaled while the driver reverses out with counter-steer (brake past standstill — the shared sim's reverse).
+- `paceBandFactor` (function): function paceBandFactor(band: PaceBand, gap: number): number — The pace multiplier a {@link PaceBand} asks for at `gap`: `1` inside the tolerance, `1 - ease * scale` fully ahead of it, `1 + push * scale` fully behind it, ramped linearly across `easeAt` / `pushAt` in between. Pure scalar math, so a band is deterministic and costs no allocation per step; the result never goes negative.
 - `pathTargetAhead` (function): function pathTargetAhead(path: readonly DrivePathPoint[], x: number, z: number, lookahead: number, loop = false): DrivePathPoint | null — The pure-pursuit target for street/route following: the point `lookahead` meters further along the polyline from wherever the vehicle currently projects onto it. Feed the result to {@link driveStep} as the goal each tick and the driver follows the road; `loop` wraps a circuit (traffic block, race lap) instead of pinning at the final point. Returns `null` for a degenerate path. Give sharper tiers a longer `lookahead` to cut corners cleanly and duller tiers a short one so they steer segment-to-segment.
 
 ## @jgengine/core/ai/flock
@@ -453,13 +455,22 @@
 - `sumMagnitude` (function): function sumMagnitude<P>(memberships: readonly AreaMembership<P>[], magnitudeOf: MagnitudeOf<P>): number — Sum a numeric magnitude across memberships — additive aggregation for a total field strength (total damage per tick, total slow). A terminal reducer, not a filter, so it returns the number.
 - `uniqueByStackKey` (function): function uniqueByStackKey<P>(magnitudeOf?: MagnitudeOf<P>): AreaStackPolicy<P> — Keep at most one membership per `stackKey`. With `magnitudeOf` the strongest per key wins (ties broken by `sourceId` for determinism); without it the first-seen per key wins. Use for unique-by-key buffs where reapplying the same aura should not stack.
 
+## @jgengine/core/audio/ambience
+
+- `AmbienceWeight` (interface): interface AmbienceWeight — One zone's share of the ambience mix at a listener position, 0..1.
+- `AmbienceZoneDef` (interface): interface AmbienceZoneDef — One ambience zone: a sound bed keyed to a volume of the scene.
+- `AmbienceZoneShape` (type): type AmbienceZoneShape = | { kind: "sphere"; center: readonly [number, number, number]; radius: number } | { kind: "box"; min: readonly [number, number, number]; max: readonly [number, number, number] } — A world-space volume whose sound bed plays while the listener is inside it.
+- `activeAmbienceZone` (function): function activeAmbienceZone(weights: readonly AmbienceWeight[]): string | null — The loudest zone in a weight list, or null when every zone is silent.
+- `ambienceWeights` (function): function ambienceWeights(zones: readonly AmbienceZoneDef[], x: number, y: number, z: number, out: AmbienceWeight[] = []): AmbienceWeight[] — Every zone's mix weight at a listener position. A zone is at full level `crossfade` units inside its boundary, at half level on the boundary and silent `crossfade` units outside, so a listener walking between two zones that share a boundary hears a constant-sum handover. Weights that would sum above 1 (overlapping zones) are normalized so total bed level never exceeds unity. Writes into `out` when given, so a per-frame caller allocates nothing.
+- `zoneSignedDistance` (function): function zoneSignedDistance(shape: AmbienceZoneShape, x: number, y: number, z: number): number — Distance from a point to a zone boundary, positive inside and negative outside. Spheres measure from the surface; boxes use the nearest face.
+
 ## @jgengine/core/audio/audioFalloff
 
 - `AudioBusDef` (interface): interface AudioBusDef { id: AudioBusId; gain?: number } — ⚠ undocumented · used by `withFeedbackCueSounds` (@jgengine/core/audio/feedbackCues): Merge the default feedback reactions into a game's sound catalog.
 - `AudioBusId` (type): type AudioBusId = string — ⚠ undocumented
 - `AudioFalloffConfig` (interface): interface AudioFalloffConfig { minDistance?: number; maxDistance?: number; curve?: FalloffCurve } — ⚠ undocumented
 - `FalloffCurve` (type): type FalloffCurve = "linear" | "inverse" | "none" — ⚠ undocumented
-- `SoundDef` (interface): interface SoundDef { id: string; url?: string; synth?: SynthPatch; bus: AudioBusId; gain?: number; loop?: boolean; maxVoices?: number; priority?: number; positional?: boolean; falloff?: AudioFalloffConfig; doppler?: number; spatial?: {panning: "hrtf" | "equal… — ⚠ undocumented · used by `DEFAULT_FEEDBACK_CUE_SOUNDS` (@jgengine/core/audio/feedbackCues): Short procedural reactions - no samples to load, so every game has impact feedback without authoring audio.
+- `SoundDef` (interface): interface SoundDef { id: string; url?: string; synth?: SynthPatch; bus: AudioBusId; gain?: number; loop?: boolean; maxVoices?: number; priority?: number; duck?: {buses?: readonly string[]; amount?: number; seconds?: number;}; positional?: boolean; falloff?: A… — ⚠ undocumented · used by `DEFAULT_FEEDBACK_CUE_SOUNDS` (@jgengine/core/audio/feedbackCues): Short procedural reactions - no samples to load, so every game has impact feedback without authoring audio.
 - `computeFalloffGain` (function): function computeFalloffGain(distance: number, config: AudioFalloffConfig = {}): number — ⚠ undocumented
 - `distance3` (function): function distance3(a: { x: number; y: number; z: number }, b: { x: number; y: number; z: number }): number — ⚠ undocumented
 - `resolveEmitterGain` (function): function resolveEmitterGain(distance: number, sound: Pick<SoundDef, "gain" | "positional" | "falloff">, busGain: number): number — ⚠ undocumented
@@ -511,6 +522,13 @@
 - `createMusicState` (function): function createMusicState(): MusicStateSnapshot — Fresh state with no tier entered, so the first resolve always settles and reports `changed`.
 - `resolveMusicState` (function): function resolveMusicState(state: MusicStateSnapshot, input: MusicStateInput, config: MusicStateConfig): MusicStateResult — Pick the theme for the current intensity. Escalation is immediate; de-escalation waits for the tier's `holdMs` and needs the intensity to fall a `release` margin below the tier it is leaving.
 
+## @jgengine/core/audio/occlusion
+
+- `AUDIO_OCCLUSION_DEFAULTS` (const): const AUDIO_OCCLUSION_DEFAULTS: { readonly maxTestsPerTick: 8; readonly intervalMs: 150; readonly attenuation: 0.55; readonly lowpassHz: 1200; readonly maxDistance: 60; } — Defaults for {@link AudioOcclusionConfig}.
+- `AudioOcclusionConfig` (interface): interface AudioOcclusionConfig — Geometry occlusion for retained positional loops: a cheap line test between the listener and an emitter behind blocking geometry, bounded so a busy scene can never turn audio into a raycast pass. The shell runs the test against the scene's blockable colliders; the engine applies the resulting attenuation and low-pass to the loop it already owns.
+- `ResolvedAudioOcclusionConfig` (interface): interface ResolvedAudioOcclusionConfig — A fully specified occlusion policy, with every unset field replaced by its default.
+- `resolveOcclusionConfig` (function): function resolveOcclusionConfig(config: AudioOcclusionConfig | false = {}): ResolvedAudioOcclusionConfig — Fill in the occlusion defaults and clamp each field to a workable range: a finite test budget, a non-negative retest interval and distance cap, and an attenuation in `0..1`.
+
 ## @jgengine/core/audio/stepCadence
 
 - `StepCadenceConfig` (interface): interface StepCadenceConfig — Distance-driven footstep cadence. Pure state-in/state-out: feed it how far a mover travelled this frame and it tells you how many steps landed, so foley stays locked to ground distance instead of a wall-clock timer that desyncs when speed changes.
@@ -2857,7 +2875,7 @@
 - `SnapMode` (type): type SnapMode = "grid" | "free" | "surface" — ⚠ undocumented
 - `SnowEnvironmentDescriptor` (type): type SnowEnvironmentDescriptor = { kind: "snow" } & Required< Pick<SnowEnvironmentConfig, "area" | "density" | "speed" | "flakeSize" | "drift" | "wind" | "color" | "opacity"> > — ⚠ undocumented · used by `snow`: Declares a snowfall weather effect for `environment()` — area, density, drift, wind, and flake opacity.
 - `SoilRules` (interface): interface SoilRules — Fully-defaulted soil params parsed from a volume's `meta`.
-- `SoundDef` (interface): interface SoundDef { id: string; url?: string; synth?: SynthPatch; bus: AudioBusId; gain?: number; loop?: boolean; maxVoices?: number; priority?: number; positional?: boolean; falloff?: AudioFalloffConfig; doppler?: number; spatial?: {panning: "hrtf" | "equal… — ⚠ undocumented · used by `DEFAULT_FEEDBACK_CUE_SOUNDS` (@jgengine/core/audio/feedbackCues): Short procedural reactions - no samples to load, so every game has impact feedback without authoring audio.
+- `SoundDef` (interface): interface SoundDef { id: string; url?: string; synth?: SynthPatch; bus: AudioBusId; gain?: number; loop?: boolean; maxVoices?: number; priority?: number; duck?: {buses?: readonly string[]; amount?: number; seconds?: number;}; positional?: boolean; falloff?: A… — ⚠ undocumented · used by `DEFAULT_FEEDBACK_CUE_SOUNDS` (@jgengine/core/audio/feedbackCues): Short procedural reactions - no samples to load, so every game has impact feedback without authoring audio.
 - `SpatialGrid` (class): class SpatialGrid — A uniform-grid broad-phase over the x/z plane, separate from the rigid-body sim, for cheap same-tick proximity across hundreds–thousands of simple movers (swarm enemies). Rebuild each tick from the caller's own position arrays, then `queryCircle` (enemies hitting the player / an AoE) or `forEachPair` (mutual separation). Both are precise: no false negatives, no false positives beyond the exact distance test.
 - `SpawnDirectorConfig` (interface): interface SpawnDirectorConfig { waves: readonly WaveManifest[]; maxAlive?: number; escalationPerSecond?: number; alertBudgetPerSecond?: number; alertDecayPerSecond?: number; playerBudgetPerSecond?: number; maxSpawnsPerTick?: number; loop?: boolean; seed?: number; spawnP… — ⚠ undocumented
 - `SpawnDirectorState` (interface): interface SpawnDirectorState { wave: number; elapsed: number; waveElapsed: number; budget: number; alert: number; spawnedThisWave: number; spawnedTotal: number; rng: RandomSeed; done: boolean } — ⚠ undocumented

package/skills/jgengine-world/capabilities.md

@@ -28,6 +28,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `measureAir` (function) · `import { measureAir } from "@jgengine/core/physics/handlingProbe"`
 
+## ambience-zones — a scene declares looping sound beds keyed to world volumes; walking between them crossfades bed levels on the existing buses instead of cutting.
+
+- `AmbienceZoneDef` (interface) · `import { AmbienceZoneDef } from "@jgengine/core/audio/ambience"`
+
 ## anim-graph — data-first animation state machine with blend trees, crossfades, layers, and clip events
 
 - `createAnimGraphRuntime` (function) · `import { createAnimGraphRuntime } from "@jgengine/core/anim/animGraph"`
@@ -109,6 +113,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `defineAttackMoveOrder` (function) · `import { defineAttackMoveOrder } from "@jgengine/core/world"`
 
+## audio-occlusion — an emitter behind blocking world geometry is attenuated and darkened by a budgeted line test, and falls back to distance-only once the tick's budget is spent.
+
+- `AudioOcclusionConfig` (interface) · `import { AudioOcclusionConfig } from "@jgengine/core/audio/occlusion"`
+
 ## audio-voice-budget — bound simultaneous sound playback with per-sound caps, priorities, and deterministic stealing
 
 - `createVoiceAllocator` (function) · `import { createVoiceAllocator } from "@jgengine/core/audio/voiceAllocator"`

package/skills/jgengine-world/reference.md

@@ -413,7 +413,7 @@ Replace behavior data through `ctx.scene.entity.update(id, { behaviors })` or en
 
 Compose, don't replace: scale `MobBrainConfig.aggroRadius` by `perceptionScale`, route `acquireTarget` scoring through `pickScored`, gate `advancePursuit` target swaps behind the reaction gate.
 
-**Drive** — `ai/driver` is the vehicle consumer of the profile: `driveStep(state, dt, pose, goal, profile, tuning, rng, obstacleAhead?)` turns a pose + goal into the shared `AxisInput` (`throttle`/`brake`/`steer`) for `tickDrivableVehicle`. The profile decides how well the car drives: the steering target is a delay-line resampled every `reactionSeconds` (easy chasers cut to where the target *was*), corners shed speed instead of orbiting at full throttle, obstacle distance is perceived late by `speed × reactionSeconds`, the wheel wobbles by `executionJitter` (resampled on an interval, so it reads as a loose wheel), and a car grinding a wall backs out with counter-steer after a tier-scaled delay (brake past standstill is the sim's reverse). `createDriverState` is one small serializable object; the caller owns the sim, collision, and all spatial queries. For streets and circuits, `pathTargetAhead(path, x, z, lookahead, loop?)` walks a road/route polyline to the pure-pursuit point ahead — feed it back in as the goal each tick and the same brain follows authored roads; give sharper tiers a longer lookahead.
+**Drive** — `ai/driver` is the vehicle consumer of the profile: `driveStep(state, dt, pose, goal, profile, tuning, rng, obstacleAhead?)` turns a pose + goal into the shared `AxisInput` (`throttle`/`brake`/`steer`) for `tickDrivableVehicle`. The profile decides how well the car drives: the steering target is a delay-line resampled every `reactionSeconds` (easy chasers cut to where the target *was*), corners shed speed instead of orbiting at full throttle, obstacle distance is perceived late by `speed × reactionSeconds`, the wheel wobbles by `executionJitter` (resampled on an interval, so it reads as a loose wheel), and a car grinding a wall backs out with counter-steer after a tier-scaled delay (brake past standstill is the sim's reverse). `createDriverState` is one small serializable object; the caller owns the sim, collision, and all spatial queries. For streets and circuits, `pathTargetAhead(path, x, z, lookahead, loop?)` walks a road/route polyline to the pure-pursuit point ahead — feed it back in as the goal each tick and the same brain follows authored roads; give sharper tiers a longer lookahead. Catch-up pacing is a `PaceBand` on the goal: the caller measures `paceGap` (positive = ahead of the reference) and the band's `margin`/`tolerance` leave a dead zone, `ease` sheds pace for a leader over `easeAt`, `push` adds it for a chaser over `pushAt`, and `scale` is the per-car share. `paceBandFactor(band, gap)` is the same rule on its own; the push never outdrives `tuning.maxSpeed`.
 
 ### Snapshot and restore on movement and visibility handles