@jgengine/shell 0.34.0 → 0.35.0

package/dist/postfx/postfxTierPolicy.js

@@ -0,0 +1,17 @@
+/**
+ * The post chain's quality tiers. `high` and `ultra` render at native size; the tiers below pay for
+ * their cheaper stage set twice, by building fewer passes and by rendering the ones left smaller.
+ * `stages` mirrors `DEFAULT_GRAPHICS_PROFILES.postStages`, so a plan built without the player's
+ * toggles spends the same passes the profile names.
+ * @internal
+ */
+export const POSTFX_TIER_POLICY = {
+    low: { resolutionScale: 0.7, aoSamples: 8, stages: { ao: false, bloom: true, dof: false, smaa: true } },
+    medium: { resolutionScale: 0.85, aoSamples: 8, stages: { ao: true, bloom: true, dof: true, smaa: true } },
+    high: { resolutionScale: 1, aoSamples: 12, stages: { ao: true, bloom: true, dof: true, smaa: true } },
+    ultra: { resolutionScale: 1, aoSamples: 16, stages: { ao: true, bloom: true, dof: true, smaa: true } },
+};
+/** A tier's post-chain budget; `high` is the reference every lower tier is measured against. @internal */
+export function postfxTierPolicy(quality) {
+    return POSTFX_TIER_POLICY[quality];
+}

package/dist/render/CascadedShadows.d.ts

@@ -30,9 +30,12 @@ export declare function cascadeShadowCadence(index: number, cascades: number): n
 /**
  * Set each cascade's shadow refresh policy for `frame`. A cascade that is not due keeps both
  * its matrix and its map from the last refresh, so the pair stays consistent with itself.
+ * `refreshScale` stretches the far cascades' interval further on a tier whose maps are cheap
+ * enough to lag; `1` is the cadence the cascade rig was measured with. The nearest cascade always
+ * refreshes every frame: it is the one a moving camera crosses fastest.
  * @internal
  */
-export declare function scheduleCascadeRefresh(lights: readonly THREE.DirectionalLight[], frame: number): void;
+export declare function scheduleCascadeRefresh(lights: readonly THREE.DirectionalLight[], frame: number, refreshScale?: number): void;
 /**
  * Cascaded shadow maps for one directional light — outdoor scenes keep shadows past a
  * single 40-unit ortho frustum. Uses three.js `CSM` (shader injection on standard materials).

package/dist/render/CascadedShadows.js

@@ -2,6 +2,7 @@ import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
 import * as THREE from "three";
 import { CSM } from "three/examples/jsm/csm/CSM.js";
+import { resolveCascadeCount, resolveShadowMapSize, shadowRefreshScale } from "./shadowTiers.js";
 /** @internal Default PCF penumbra in shadow-map texels for configured directional lights. */
 export const DEFAULT_SHADOW_RADIUS = 1.25;
 /** @internal Reach in metres used when neither the game nor a graphics profile sets one. */
@@ -47,12 +48,17 @@ export function cascadeShadowCadence(index, cascades) {
 /**
  * Set each cascade's shadow refresh policy for `frame`. A cascade that is not due keeps both
  * its matrix and its map from the last refresh, so the pair stays consistent with itself.
+ * `refreshScale` stretches the far cascades' interval further on a tier whose maps are cheap
+ * enough to lag; `1` is the cadence the cascade rig was measured with. The nearest cascade always
+ * refreshes every frame: it is the one a moving camera crosses fastest.
  * @internal
  */
-export function scheduleCascadeRefresh(lights, frame) {
+export function scheduleCascadeRefresh(lights, frame, refreshScale = 1) {
+    const stretch = Math.max(1, Math.floor(refreshScale));
     for (let index = 0; index < lights.length; index += 1) {
         const shadow = lights[index].shadow;
-        const cadence = cascadeShadowCadence(index, lights.length);
+        const base = cascadeShadowCadence(index, lights.length);
+        const cadence = base === 1 ? 1 : base * stretch;
         shadow.autoUpdate = cadence === 1;
         if (cadence > 1)
             shadow.needsUpdate = frame % cadence === 0;
@@ -77,8 +83,10 @@ export function CascadedShadows({ entry, profile, modulation, }) {
     const frameRef = useRef(0);
     const baseIntensity = entry.intensity ?? 1.3;
     const maxFar = resolveShadowDistance(profile, entry.shadowMaxFar);
+    const shadowMapSize = resolveShadowMapSize(profile, entry.shadowMapSize);
+    const cascades = Math.max(2, Math.min(4, Math.floor(resolveCascadeCount(profile, entry.cascades))));
+    const refreshScale = shadowRefreshScale(shadowMapSize);
     useEffect(() => {
-        const cascades = Math.max(2, Math.min(4, Math.floor(entry.cascades ?? 3)));
         const lightDirection = new THREE.Vector3(-entry.position[0], -entry.position[1], -entry.position[2]);
         if (lightDirection.lengthSq() < 1e-8)
             lightDirection.set(-1, -1, -1);
@@ -89,7 +97,7 @@ export function CascadedShadows({ entry, profile, modulation, }) {
             cascades,
             maxFar,
             mode: "practical",
-            shadowMapSize: entry.shadowMapSize ?? 1024,
+            shadowMapSize,
             shadowBias: entry.shadowBias ?? -0.0004,
             lightDirection,
             lightIntensity: entry.intensity ?? 1.3,
@@ -112,7 +120,7 @@ export function CascadedShadows({ entry, profile, modulation, }) {
     }, [
         camera,
         scene,
-        entry.cascades,
+        cascades,
         entry.color,
         entry.intensity,
         entry.position[0],
@@ -120,7 +128,7 @@ export function CascadedShadows({ entry, profile, modulation, }) {
         entry.position[2],
         entry.shadowBias,
         entry.shadowCameraSize,
-        entry.shadowMapSize,
+        shadowMapSize,
         maxFar,
         entry.shadowRadius,
     ]);
@@ -137,7 +145,7 @@ export function CascadedShadows({ entry, profile, modulation, }) {
         }
         csm.camera = camera;
         csm.update();
-        scheduleCascadeRefresh(csm.lights, frameRef.current++);
+        scheduleCascadeRefresh(csm.lights, frameRef.current++, refreshScale);
     });
     return null;
 }

package/dist/render/CharacterCrowd.d.ts

@@ -1,5 +1,7 @@
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
 import { CharacterCrowdRegistry } from "./crowdRegistry.js";
+/** Instance slot → entity id, so picking a batched character resolves like its own rig. @internal */
+export declare const ENTITY_INSTANCES_KEY = "jgEntityInstances";
 /** Props for {@link CharacterCrowd}. */
 export interface CharacterCrowdProps {
     /** Character models the world can draw; only models with a `lod` policy join the crowd path. */
@@ -8,13 +10,15 @@ export interface CharacterCrowdProps {
     registry: CharacterCrowdRegistry;
     /** Baked samples per second for the crowd clips. Default 24. */
     fps?: number;
+    /** Called when a batched character is clicked, with the entity a click on its own rig would select. */
+    onPick?: (entityId: string) => void;
 }
 /**
- * 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.
- * @capability character-crowd draw distant animated characters on the GPU instead of posing their skeletons
+ * 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.
+ * @capability character-crowd draw animated or static characters as batched instanced draws instead of posing each skeleton
  */
-export declare function CharacterCrowd({ models, registry, fps }: CharacterCrowdProps): import("react").JSX.Element;
+export declare function CharacterCrowd({ models, registry, fps, onPick }: CharacterCrowdProps): import("react").JSX.Element;

package/dist/render/CharacterCrowd.js

@@ -4,33 +4,27 @@ import { Suspense, useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { devtools } from "@jgengine/core/devtools/devtools";
 import { warnOnce } from "@jgengine/core/devtools/warnOnce";
-import { animationPhaseOf, characterLodProbe, clearCrowdKind, noteCharacterFrame, noteCrowdInstances, } from "./characterLod.js";
-import { CharacterCrowdRegistry, crowdClipForSpeed, crowdClipsOf, crowdKindOf, setCrowdKindReady, } from "./crowdRegistry.js";
+import { characterLodPolicy, characterLodProbe, clearCrowdKind, noteCharacterFrame, noteCrowdInstances, } from "./characterLod.js";
+import { CharacterCrowdRegistry, crowdClipsOf, crowdKindOf, crowdSpeedBandsOf, setCrowdKindReady, } from "./crowdRegistry.js";
 import { applyMaterialOverrideToMaterial } from "../materialOverride.js";
 import { useRenderVisibility } from "../visibility/CullingProvider.js";
+import { useOptionalGameContext } from "@jgengine/react/provider";
+import { POINTER_ENTITY_INSTANCES_KEY } from "../pointer/pointerService.js";
+import { writeCrowdBatch } from "./crowdBatch.js";
 import { ModelFallbackBoundary } from "./SceneModels.js";
 import { sharedGltfLoader } from "./modelLoad.js";
+import { modelPlacementTransform } from "./modelRender.js";
 import { bakeSkinnedCrowd, createCrowdUniforms, patchCrowdMaterial, } from "./SkinnedInstances.js";
-/** Instances one crowd batch can draw; a batch skips past this rather than allocate mid-frame. */
-const CROWD_CAPACITY = 128;
-const scratchMatrix = new THREE.Matrix4();
-const scratchOffset = new THREE.Matrix4();
-const scratchQuaternion = new THREE.Quaternion();
-const scratchPosition = new THREE.Vector3();
-const scratchScale = new THREE.Vector3();
-/** A stable non-zero time offset for a member with no recorded pose, so a crowd is not in lockstep. */
-function poseOffset(id) {
-    let hash = 0;
-    for (let index = 0; index < id.length; index += 1)
-        hash = (hash * 31 + id.charCodeAt(index)) | 0;
-    return (Math.abs(hash) % 1000) / 1000 + 0.05;
-}
-function CrowdBatch({ kind, model, registry, fps, }) {
+function CrowdBatch({ kind, model, registry, fps, onPick, }) {
     const gltf = useLoader(sharedGltfLoader, model.url);
     const clipNames = useMemo(() => gltf.animations.map((clip) => clip.name), [gltf]);
     const clips = useMemo(() => crowdClipsOf(model, clipNames), [model, clipNames]);
+    const bands = useMemo(() => crowdSpeedBandsOf(model, clipNames), [model, clipNames]);
+    const capacity = useMemo(() => characterLodPolicy(model.lod === false ? undefined : model.lod).crowdCapacity, [model.lod]);
     const baked = useMemo(() => {
-        if (clips.length === 0)
+        // A model that plays clips but resolves none of them to locomotion keeps its own rig: batching it
+        // would draw a frozen stance. A model with no clips at all is a static character, which batches.
+        if (clipNames.length > 0 && clips.length === 0)
             return null;
         try {
             return bakeSkinnedCrowd({ scene: gltf.scene, animations: gltf.animations }, { clips, fps });
@@ -38,123 +32,142 @@ function CrowdBatch({ kind, model, registry, fps, }) {
         catch (error) {
             // A model can carry clips without a skin (a node-transform prop animation). It keeps its own
             // rig rather than entering the crowd path, which is what the readiness flag then reports.
-            warnOnce(`character-crowd:${model.url}`, `[jgengine] character crowd: "${model.url}" cannot be baked (no skinned mesh) and stays on its own rig`);
+            warnOnce(`character-crowd:${model.url}`, `[jgengine] character crowd: "${model.url}" cannot be baked and stays on its own rig`);
             return null;
         }
-    }, [gltf, clips, fps, model.url]);
+    }, [gltf, clips, clipNames.length, fps, model.url]);
     useEffect(() => () => baked?.dispose(), [baked]);
-    const uniforms = useMemo(() => (baked === null ? null : createCrowdUniforms(baked)), [baked]);
+    const uniforms = useMemo(() => (baked === null || !baked.animated ? null : createCrowdUniforms(baked)), [baked]);
     const materials = useMemo(() => {
-        if (baked === null || uniforms === null)
+        if (baked === null)
             return [];
         return baked.materials.map((material) => {
             const tinted = model.material === undefined ? material.clone() : applyMaterialOverrideToMaterial(material.clone(), model.material, false, undefined);
-            return patchCrowdMaterial(tinted, uniforms);
+            return uniforms === null ? tinted : patchCrowdMaterial(tinted, uniforms);
         });
     }, [baked, uniforms, model]);
     const depthMaterial = useMemo(() => (uniforms === null ? null : patchCrowdMaterial(new THREE.MeshDepthMaterial({ depthPacking: THREE.RGBADepthPacking }), uniforms)), [uniforms]);
     const mesh = useMemo(() => {
-        if (baked === null || depthMaterial === null || materials.length === 0)
+        if (baked === null || materials.length === 0)
             return null;
-        const instanced = new THREE.InstancedMesh(baked.geometry, materials, CROWD_CAPACITY);
-        instanced.customDepthMaterial = depthMaterial;
+        const instanced = new THREE.InstancedMesh(baked.geometry, materials.length === 1 ? materials[0] : materials, capacity);
+        if (depthMaterial !== null)
+            instanced.customDepthMaterial = depthMaterial;
         instanced.boundingSphere = new THREE.Sphere(new THREE.Vector3(), 0);
         instanced.count = 0;
-        instanced.geometry.setAttribute("crowdPlay", new THREE.InstancedBufferAttribute(new Float32Array(CROWD_CAPACITY * 3), 3));
+        if (uniforms !== null)
+            instanced.geometry.setAttribute("crowdPlay", new THREE.InstancedBufferAttribute(new Float32Array(capacity * 3), 3));
         instanced.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
         return instanced;
-    }, [baked, materials, depthMaterial]);
+    }, [baked, materials, depthMaterial, uniforms, capacity]);
     useEffect(() => () => {
         for (const material of materials)
             material.dispose();
         depthMaterial?.dispose();
         mesh?.dispose();
     }, [materials, depthMaterial, mesh]);
-    useEffect(() => {
-        // A kind without a bakeable locomotion clip set keeps every character on its own rig rather than
-        // making them invisible past the crowd distance.
-        setCrowdKindReady(kind, mesh !== null && clips.length > 0);
-        return () => setCrowdKindReady(kind, false);
-    }, [kind, mesh, clips]);
     /** The height and centering the full entity path gives this model, so a crowd copy stands in the same place. */
     const placement = useMemo(() => {
         if (baked === null)
             return null;
-        const box = baked.geometry.boundingBox ?? (baked.geometry.computeBoundingBox(), baked.geometry.boundingBox);
-        const height = box.max.y - box.min.y;
-        const scale = (model.scale ?? 1) * (model.targetHeight !== undefined && height > 0 ? model.targetHeight / height : 1);
+        const next = modelPlacementTransform(new THREE.Group(), model, {
+            min: baked.bounds.min.toArray(),
+            max: baked.bounds.max.toArray(),
+            meshCount: 1,
+        });
         return {
-            scale,
-            offset: new THREE.Vector3(-scale * (box.min.x + box.max.x) / 2, (model.y ?? 0) - scale * box.min.y, -scale * (box.min.z + box.max.z) / 2),
+            scale: next.scale,
+            offset: new THREE.Vector3(next.position[0], next.position[1], next.position[2]),
         };
     }, [baked, model]);
+    useEffect(() => {
+        // A kind without a bakeable set keeps every character on its own rig rather than making them
+        // invisible past the crowd distance.
+        const ready = mesh !== null && placement !== null;
+        setCrowdKindReady(kind, ready);
+        registry.setCapacity(kind, ready ? capacity : 0);
+        if (ready && baked !== null && placement !== null) {
+            registry.setGeometry(kind, { geometry: baked.geometry, position: placement.offset.toArray(), scale: placement.scale });
+        }
+        return () => {
+            setCrowdKindReady(kind, false);
+            registry.setCapacity(kind, 0);
+            registry.setGeometry(kind, undefined);
+        };
+    }, [kind, mesh, placement, registry, capacity, baked]);
     const playback = useRef(new Map());
     const visibleRef = useRenderVisibility();
+    const ctx = useOptionalGameContext();
+    const drawnIds = useRef([]);
+    const drawnMembers = useRef([]);
     useFrame((_state, delta) => {
-        if (mesh === null || baked === null || uniforms === null || placement === null)
+        if (mesh === null || baked === null || placement === null)
             return;
-        uniforms.crowdTime.value += delta;
-        const play = mesh.geometry.getAttribute("crowdPlay");
-        const active = playback.current;
-        let count = 0;
-        let minX = Infinity, minY = Infinity, minZ = Infinity, maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+        // A crowd on a game clock stops when the game stops; an unbound preview advances on real time.
+        if (uniforms !== null) {
+            const advanced = ctx?.time.advancedSeconds?.();
+            uniforms.crowdTime.value = advanced !== undefined && advanced > 0 ? advanced : uniforms.crowdTime.value + delta;
+        }
+        const batches = drawnMembers.current;
+        let visible = 0;
         registry.forEach(kind, (id, member) => {
-            if (count >= CROWD_CAPACITY)
-                return;
             if (!visibleRef.current(id))
                 return;
-            const clipName = crowdClipForSpeed(clips, member.speed);
-            const clip = clipName === undefined ? 0 : baked.clipIndex.get(clipName) ?? 0;
-            let entry = active.get(id);
-            if (entry === undefined || entry.clip !== clip) {
-                // Hand the crowd the pose the rig was holding, so the swap continues the same gait instead
-                // of restarting the clip at a different phase.
-                const phase = animationPhaseOf(id);
-                entry = {
-                    clip,
-                    offset: phase !== undefined && phase.clip === clipName ? phase.time - uniforms.crowdTime.value : poseOffset(id),
-                };
-                active.set(id, entry);
+            const existing = batches[visible];
+            if (existing === undefined)
+                batches[visible] = { id, member };
+            else {
+                existing.id = id;
+                existing.member = member;
             }
-            scratchQuaternion.setFromAxisAngle(THREE.Object3D.DEFAULT_UP, member.rotationY);
-            scratchMatrix.compose(scratchPosition.set(member.x, member.y, member.z), scratchQuaternion, scratchScale.setScalar(placement.scale));
-            scratchMatrix.multiply(scratchOffset.makeTranslation(placement.offset.x, placement.offset.y, placement.offset.z));
-            mesh.setMatrixAt(count, scratchMatrix);
-            play.setXYZ(count, entry.clip, entry.offset, 1);
-            minX = Math.min(minX, member.x);
-            maxX = Math.max(maxX, member.x);
-            minY = Math.min(minY, member.y);
-            maxY = Math.max(maxY, member.y);
-            minZ = Math.min(minZ, member.z);
-            maxZ = Math.max(maxZ, member.z);
-            count += 1;
+            visible += 1;
         });
-        mesh.count = count;
-        mesh.instanceMatrix.needsUpdate = true;
-        play.needsUpdate = true;
-        if (count > 0) {
-            // One batch spans every drawn member, so its cull sphere has to follow them; three cannot cull
-            // an InstancedMesh per instance.
-            const sphere = mesh.boundingSphere ?? (mesh.boundingSphere = new THREE.Sphere());
-            sphere.center.set((minX + maxX) / 2, (minY + maxY) / 2, (minZ + maxZ) / 2);
-            sphere.radius = Math.hypot(maxX - minX, maxY - minY, maxZ - minZ) / 2 + placement.scale * 1.2;
-        }
+        batches.length = visible;
+        const count = writeCrowdBatch({
+            mesh,
+            play: uniforms === null ? null : mesh.geometry.getAttribute("crowdPlay"),
+            members: batches,
+            placement,
+            clips,
+            bands,
+            clipIndex: baked.clipIndex,
+            time: uniforms === null ? 0 : uniforms.crowdTime.value,
+            playback: playback.current,
+            ids: drawnIds.current,
+        });
+        mesh.userData[ENTITY_INSTANCES_KEY] = drawnIds.current;
         noteCrowdInstances(kind, count);
     });
     useEffect(() => () => clearCrowdKind(kind), [kind]);
+    // A member removed while its matrix is still in the buffer must not linger on screen.
+    useEffect(() => () => {
+        playback.current.clear();
+    }, []);
     if (mesh === null)
         return null;
-    return _jsx("primitive", { object: mesh, castShadow: true, receiveShadow: true });
+    return (_jsx("primitive", { object: mesh, castShadow: true, receiveShadow: true, onPointerDown: onPick === undefined
+            ? undefined
+            : (event) => {
+                if (event.instanceId === undefined)
+                    return;
+                const id = drawnIds.current[event.instanceId];
+                if (id === undefined)
+                    return;
+                event.stopPropagation();
+                onPick(id);
+            } }));
 }
+/** Instance slot → entity id, so picking a batched character resolves like its own rig. @internal */
+export const ENTITY_INSTANCES_KEY = POINTER_ENTITY_INSTANCES_KEY;
 /**
- * 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.
- * @capability character-crowd draw distant animated characters on the GPU instead of posing their skeletons
+ * 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.
+ * @capability character-crowd draw animated or static characters as batched instanced draws instead of posing each skeleton
  */
-export function CharacterCrowd({ models, registry, fps = 24 }) {
+export function CharacterCrowd({ models, registry, fps = 24, onPick }) {
     const kinds = useMemo(() => {
         const unique = new Map();
         for (const model of models) {
@@ -172,5 +185,5 @@ export function CharacterCrowd({ models, registry, fps = 24 }) {
         noteCharacterFrame();
     });
     useEffect(() => () => registry.clear(), [registry]);
-    return (_jsx(_Fragment, { children: kinds.map(([kind, model]) => (_jsx(ModelFallbackBoundary, { fallback: null, url: model.url, seam: "entity", children: _jsx(Suspense, { fallback: null, children: _jsx(CrowdBatch, { kind: kind, model: model, registry: registry, fps: fps }) }) }, kind))) }));
+    return (_jsx(_Fragment, { children: kinds.map(([kind, model]) => (_jsx(ModelFallbackBoundary, { fallback: null, url: model.url, seam: "entity", children: _jsx(Suspense, { fallback: null, children: _jsx(CrowdBatch, { kind: kind, model: model, registry: registry, fps: fps, onPick: onPick }) }) }, kind))) }));
 }

package/dist/render/SceneLighting.js

@@ -4,6 +4,7 @@ import { useFrame, useThree } from "@react-three/fiber";
 import { devtools } from "@jgengine/core/devtools/devtools";
 import { CascadedShadows, DEFAULT_SHADOW_RADIUS } from "./CascadedShadows.js";
 import { cullSmallShadowCasters, MIN_SHADOW_CASTER_RADIUS } from "./shadowCasters.js";
+import { minShadowCasterRadius, resolveCascadeCount, resolveShadowMapSize, SHADOW_CASTER_RADIUS_REFERENCE_MAP } from "./shadowTiers.js";
 const DEFAULT_BACKDROP_FOG_COLOR = "#1a1c22";
 /** Default cap for combined dynamic point and spot lights. */
 export const POINT_LIGHT_BUDGET = 8;
@@ -30,7 +31,13 @@ function usesCascades(entry) {
     return (entry.castShadow ?? false) && (entry.cascades ?? 1) > 1;
 }
 function DirectionalShadowLight({ entry, profile, modulation }) {
-    const resolved = profile === undefined ? entry : { ...entry, shadowMapSize: entry.shadowMapSize ?? profile.shadowMapSize, cascades: entry.cascades ?? profile.cascades };
+    const resolved = profile === undefined
+        ? entry
+        : {
+            ...entry,
+            shadowMapSize: resolveShadowMapSize(profile, entry.shadowMapSize),
+            cascades: resolveCascadeCount(profile, entry.cascades),
+        };
     if (usesCascades(resolved)) {
         return _jsx(CascadedShadows, { entry: resolved, profile: profile, modulation: modulation });
     }
@@ -76,25 +83,26 @@ export function ConfiguredLighting({ lighting, profile, modulation, }) {
     const scene = useThree((s) => s.scene);
     const shadowsCast = (lighting.directional ?? []).some((entry) => entry.castShadow === true);
     const cullRef = useRef(null);
+    const casterRadius = minShadowCasterRadius(profile?.shadowMapSize ?? SHADOW_CASTER_RADIUS_REFERENCE_MAP, MIN_SHADOW_CASTER_RADIUS);
     useEffect(() => {
         if (!shadowsCast)
             return;
-        const cull = cullSmallShadowCasters(scene);
+        const cull = cullSmallShadowCasters(scene, casterRadius);
         cullRef.current = cull;
         return () => {
             cull.restore();
             cullRef.current = null;
         };
-    }, [scene, shadowsCast]);
+    }, [scene, shadowsCast, casterRadius]);
     useEffect(() => devtools.probes.registerSystem("render/shadows", {
-        counters: () => cullRef.current?.stats() ?? { casters: 0, skipped: 0 },
+        counters: () => cullRef.current?.stats() ?? { casters: 0, skipped: 0, minRadius: casterRadius },
         state: () => {
             const stats = cullRef.current?.stats();
             return stats === undefined
                 ? "no shadow-casting directional light"
-                : `${stats.casters} casters · ${stats.skipped} under ${MIN_SHADOW_CASTER_RADIUS} m skipped`;
+                : `${stats.casters} casters · ${stats.skipped} under ${stats.minRadius} m skipped`;
         },
-    }), []);
+    }), [casterRadius]);
     const ambientRef = useRef(null);
     const hemisphereRef = useRef(null);
     const baseAmbient = lighting.ambient?.intensity ?? 0.55;

package/dist/render/SceneWarmupGate.d.ts

@@ -6,9 +6,14 @@ export declare const SCENE_WARMUP_PENDING: ShaderWarmupState;
  * Mounted inside the canvas, after the world, so the first round sees the world's materials.
  * @internal
  */
-export declare function SceneWarmupGate({ onState }: {
+export declare function SceneWarmupGate({ onState, sceneDrawsToTarget }: {
     onState: (state: ShaderWarmupState) => void;
+    sceneDrawsToTarget?: boolean;
 }): null;
+/** What the loading cover says, so a wait that takes seconds reads as progress instead of a blank. @internal */
+export declare function warmupLabel(state: ShaderWarmupState): string;
+/** Whether the cover is still up: a failed compile releases the frame rather than hiding a broken scene. @internal */
+export declare function warmupCovering(state: ShaderWarmupState): boolean;
 /**
  * Opaque cover over the canvas while the scene warms: the first frames of a scene compile its
  * materials, and a player should not see those frames. Game UI and menus mount after this and

package/dist/render/SceneWarmupGate.js

@@ -1,24 +1,34 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useThree } from "@react-three/fiber";
 import { useEffect } from "react";
 import { devtools } from "@jgengine/core/devtools/devtools";
 import { createShaderWarmup } from "./shaderWarmup.js";
 /** Warmup state before the gate has run, so the loading screen covers the very first frame. @internal */
-export const SCENE_WARMUP_PENDING = { phase: "waiting", rounds: 0, programs: 0, elapsedMs: 0 };
+export const SCENE_WARMUP_PENDING = { phase: "waiting", rounds: 0, programs: 0, planned: 0, deferred: 0, elapsedMs: 0 };
 /**
  * Compiles the mounted scene's shaders behind the loading screen and reports progress to it.
  * Mounted inside the canvas, after the world, so the first round sees the world's materials.
  * @internal
  */
-export function SceneWarmupGate({ onState }) {
+export function SceneWarmupGate({ onState, sceneDrawsToTarget }) {
     const gl = useThree((state) => state.gl);
     const scene = useThree((state) => state.scene);
     const camera = useThree((state) => state.camera);
+    // With no answer from the canvas owner, a priority frame loop is taken for the post chain, which
+    // draws the scene into its own buffer. A scissored split-screen loop also takes priority and draws
+    // the canvas, so the composition passes the answer where it knows it.
+    const internal = useThree((state) => state.internal);
     useEffect(() => {
-        const warmup = createShaderWarmup({ renderer: gl, scene, camera, onState });
+        const warmup = createShaderWarmup({
+            renderer: gl,
+            scene,
+            camera,
+            onState,
+            sceneDrawsToTarget: () => sceneDrawsToTarget ?? internal.priority > 0,
+        });
         const unregister = devtools.probes.register("sceneWarmup", () => {
             const state = warmup.state();
-            return `${state.phase}, ${state.rounds} rounds, ${state.programs} programs, ${state.elapsedMs}ms`;
+            return `${state.phase}, ${state.rounds} rounds, ${state.programs} programs, ${state.planned} planned, ${state.deferred} deferred, ${state.elapsedMs}ms`;
         });
         return () => {
             warmup.cancel();
@@ -27,6 +37,17 @@ export function SceneWarmupGate({ onState }) {
     }, [gl, scene, camera, onState]);
     return null;
 }
+/** What the loading cover says, so a wait that takes seconds reads as progress instead of a blank. @internal */
+export function warmupLabel(state) {
+    if (state.phase === "compiling") {
+        return state.programs === 0 ? "Preparing scene." : `Preparing scene (${state.programs} shaders)`;
+    }
+    return "Preparing scene.";
+}
+/** Whether the cover is still up: a failed compile releases the frame rather than hiding a broken scene. @internal */
+export function warmupCovering(state) {
+    return state.phase !== "ready" && state.phase !== "failed";
+}
 /**
  * Opaque cover over the canvas while the scene warms: the first frames of a scene compile its
  * materials, and a player should not see those frames. Game UI and menus mount after this and
@@ -34,7 +55,7 @@ export function SceneWarmupGate({ onState }) {
  * @internal
  */
 export function SceneWarmupCover({ state }) {
-    if (state.phase === "ready" || state.phase === "failed")
+    if (!warmupCovering(state))
         return null;
     return (_jsx("div", { "data-shell-code-loading": true, "data-shell-warmup": true, role: "status", "aria-live": "polite", style: {
             position: "absolute",
@@ -44,5 +65,10 @@ export function SceneWarmupCover({ state }) {
             background: "#0f172a",
             color: "#e2e8f0",
             fontFamily: "ui-sans-serif, system-ui, sans-serif",
-        }, children: state.phase === "compiling" && state.programs > 0 ? `Preparing scene (${state.programs} shaders)` : "Preparing scene." }));
+        }, children: _jsxs("div", { style: { display: "grid", gap: 10, justifyItems: "center", fontSize: 14 }, children: [_jsx("span", { children: warmupLabel(state) }), _jsx("div", { "data-shell-warmup-bar": true, "aria-hidden": "true", style: { width: 160, height: 3, borderRadius: 2, background: "#1e293b", overflow: "hidden" }, children: _jsx("div", { style: {
+                            width: state.phase === "compiling" ? "100%" : "20%",
+                            height: "100%",
+                            background: "#38bdf8",
+                            opacity: state.phase === "compiling" ? 1 : 0.4,
+                        } }) }), state.deferred > 0 ? (_jsx("span", { style: { fontSize: 11, color: "#94a3b8" }, children: `${state.deferred} more prepare after this` })) : null, state.phase === "compiling" && state.elapsedMs >= 1_000 ? (_jsx("span", { style: { fontSize: 11, color: "#64748b" }, children: `${(state.elapsedMs / 1000).toFixed(1)}s` })) : null] }) }));
 }

package/dist/render/SkinnedInstances.d.ts

@@ -20,18 +20,26 @@ export interface BakedSkinnedCrowd {
     geometry: THREE.BufferGeometry;
     /** One material per merged mesh, in geometry-group order, not yet patched. */
     materials: THREE.Material[];
-    texture: THREE.DataTexture;
-    layout: BoneTextureLayout;
+    /** The bone-matrix texture, or `null` for a rig with no clips: a static character needs no sampling. */
+    texture: THREE.DataTexture | null;
+    layout: BoneTextureLayout | null;
     /** Per clip: whether it loops. Same order as `layout.clips`. */
     loops: boolean[];
     clipIndex: ReadonlyMap<string, number>;
+    /** Whether members play the baked clips; false for a static character, whose geometry never moves. */
+    animated: boolean;
+    /** Bind-pose bounds of every merged part, for placement that matches the per-entity path. */
+    bounds: THREE.Box3;
     dispose(): void;
 }
 /**
- * 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.
+ * 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.
  */
 export declare function bakeSkinnedCrowd(source: SkinnedCrowdSource, options?: BakeSkinnedCrowdOptions): BakedSkinnedCrowd;
 /** Uniforms shared by every material of one crowd; `crowdTime` advances once per frame. */
@@ -59,8 +67,8 @@ export interface CrowdInstance {
     position: readonly [number, number, number];
     rotationY?: number;
     scale?: number;
-    /** A baked clip name. */
-    clip: string;
+    /** A baked clip name; a static rig draws bind pose whatever the member names. */
+    clip?: string;
     /** Seconds into the clip at crowd time zero, so members do not move in lockstep. */
     timeOffset?: number;
     /** Playback rate. Default 1. */