@jgengine/shell 0.27.0 → 0.28.0

package/dist/camera/rigResolve.js

@@ -1,3 +1,4 @@
+import { readCaptureCamera } from "@jgengine/core/world/captureCamera";
 /** @internal */
 export function resolveRuntimeCameraConfig(config, override) {
     if (override === null || override === undefined)
@@ -9,6 +10,21 @@ export function resolveRuntimeCameraConfig(config, override) {
     }
     return merged;
 }
+/**
+ * The camera config that renders this frame, with the capture camera winning over everything.
+ *
+ * A game owns its camera three ways: the static `camera` block, a runtime `ctx.camera.setRig`
+ * selection, and a director cinematic. A capture harness can rewrite the first, but the other two
+ * run afterwards and quietly photograph the game's own camera. `installCaptureCamera` is read here,
+ * above all three, so `?look=`/`--look` frames what it was asked for; with nothing installed this is
+ * exactly `resolveRuntimeCameraConfig` and every game behaves as before.
+ *
+ * @capability capture render a framed capture camera over a game that owns its camera
+ * @internal
+ */
+export function resolveCaptureCameraConfig(config, override) {
+    return resolveRuntimeCameraConfig(config, readCaptureCamera() ?? override);
+}
 /**
  * Resolves which rig mounts from a `GameCameraConfig`. Precedence, most to least
  * specific: an explicit `rig` field always wins; then `perspective: "first"`

package/dist/environment/EnvironmentScene.js

@@ -1,5 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useMemo, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useFrame } from "@react-three/fiber";
 import { PresentationAssetBoundary } from "../presentationRecovery.js";
 import { PresentationRecoveredDraw, useRecoverableTexture } from "../presentationRecovery3d.js";
@@ -49,6 +49,67 @@ function TexturedTerrainGround({ detail, layout, layerMaps, }) {
 }
 /** 1×1 white PNG: binds a valid sampler for a painted layer that has no scanned map. */
 const NO_LAYER_MAP = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+/** The map roles a detail material samples, in the order the loader starts them. */
+function scanRoles(maps) {
+    return [
+        ["color", maps.color],
+        ["normal", maps.normal],
+        ...(maps.roughness === undefined ? [] : [["roughness", maps.roughness]]),
+        ...(maps.ao === undefined ? [] : [["ao", maps.ao]]),
+    ];
+}
+/**
+ * The same ground as {@link TexturedTerrainGround} for a scan the game pulled rather than shipped:
+ * the maps load straight through `THREE.TextureLoader`, so a missing one stays a warning instead of
+ * a suspense rejection that would take the view down, and the authored procedural ground renders
+ * until they answer.
+ */
+function TolerantTerrainGround({ detail, layout, layerMaps, fallback, }) {
+    const maps = detail.material.maps;
+    const roles = scanRoles(maps);
+    const key = roles.map(([role, url]) => `${role}:${url}`).join("|");
+    const [loaded, setLoaded] = useState({ key });
+    useEffect(() => {
+        let active = true;
+        const textures = {};
+        let pending = roles.length;
+        const loader = new THREE.TextureLoader();
+        for (const [role, url] of roles) {
+            loader.load(url, (texture) => {
+                if (!active) {
+                    texture.dispose();
+                    return;
+                }
+                texture.colorSpace = role === "color" ? THREE.SRGBColorSpace : THREE.NoColorSpace;
+                texture.wrapS = THREE.RepeatWrapping;
+                texture.wrapT = THREE.RepeatWrapping;
+                textures[role] = texture;
+                pending -= 1;
+                if (pending === 0)
+                    setLoaded({ key, textures: textures });
+            }, undefined, () => {
+                if (!active)
+                    return;
+                active = false;
+                console.warn(`[jgengine] terrain detail maps did not load (${url}) — keeping the procedural ground. Pull the game's asset packs (\`bun run provision\`) to restore them.`);
+                setLoaded({ key });
+            });
+        }
+        return () => {
+            active = false;
+            for (const texture of Object.values(textures))
+                texture?.dispose();
+        };
+    }, [key]);
+    const quality = useTerrainQuality();
+    const material = useMemo(() => loaded.key !== key || loaded.textures === undefined
+        ? undefined
+        : createTerrainDetailMaterial(detail, loaded.textures, { paint: layout.paint, quality, ...(layerMaps === undefined ? {} : { layerMaps }) }).material, [detail, loaded, key, layout.paint, quality, layerMaps]);
+    useEffect(() => () => material?.dispose(), [material]);
+    if (material === undefined)
+        return _jsx(_Fragment, { children: fallback });
+    return (_jsx(CarvedTerrain, { field: layout.field, size: layout.size, segments: layout.segments, colors: layout.colors, heightRange: layout.heightRange, paletteAt: layout.paletteAt, center: layout.center, roughness: 0.94, surfaceMaterial: material }));
+}
 /**
  * Scanned color maps for up to {@link MAX_TERRAIN_LAYER_MAPS} painted terrain layers, loaded through
  * the shared recoverable texture path and tiled at each layer's own authored metres. The URL is
@@ -117,14 +178,18 @@ function TerrainGround({ terrain, field, center, sculpt, }) {
     const resolvedDetail = useMemo(() => (terrain.detail === false ? undefined : resolveTerrainDetail(terrain.detail, terrain.waterLevel)), [terrain.detail, terrain.waterLevel]);
     const quality = useTerrainQuality();
     const layerMaps = useTerrainLayerMaps(paint);
-    const proceduralMaterial = useMemo(() => resolvedDetail === undefined || resolvedDetail.material !== undefined
+    const proceduralMaterial = useMemo(() => resolvedDetail === undefined || (resolvedDetail.material !== undefined && resolvedDetail.material.missing === "fail")
         ? undefined
         : createTerrainDetailMaterial(resolvedDetail, undefined, { paint, quality, ...(layerMaps === undefined ? {} : { layerMaps }) }).material, [resolvedDetail, paint, quality, layerMaps]);
     useEffect(() => () => proceduralMaterial?.dispose(), [proceduralMaterial]);
+    const proceduralGround = (_jsx(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, paintColorAt: paintColorAt, center: center, roughness: 0.94, surfaceMaterial: proceduralMaterial }));
     if (resolvedDetail?.material !== undefined) {
-        return (_jsx(PresentationAssetBoundary, { children: _jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, paint, center }, ...(layerMaps === undefined ? {} : { layerMaps }) }) }));
+        const textured = (_jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, paint, center }, ...(layerMaps === undefined ? {} : { layerMaps }) }));
+        if (resolvedDetail.material.missing === "fail")
+            return _jsx(PresentationAssetBoundary, { children: textured });
+        return (_jsx(TolerantTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, paint, center }, ...(layerMaps === undefined ? {} : { layerMaps }), fallback: proceduralGround }));
     }
-    return (_jsx(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, paintColorAt: paintColorAt, center: center, roughness: 0.94, surfaceMaterial: proceduralMaterial }));
+    return proceduralGround;
 }
 function areaCenter(area) {
     return area.position ?? [0, 0];

package/dist/postfx/shadowPrepass.d.ts

@@ -1,3 +1,10 @@
 import type * as THREE from "three";
-/** Reuse the beauty pass's shadow maps while drawing a scene prepass. @internal */
+/**
+ * Draw a prepass with the world matrices the beauty pass already built. A postfx prepass renders the
+ * same scene a few milliseconds later in the same frame, so three's `updateMatrixWorld` walk there
+ * recomposes a graph nothing has moved — skipping it removes one full scene-graph walk per frame.
+ * @internal
+ */
+export declare function renderWithCurrentMatrices<T>(scene: THREE.Object3D, render: () => T): T;
+/** Reuse the beauty pass's shadow maps and world matrices while drawing a scene prepass. @internal */
 export declare function renderShadowlessPrepass<T>(renderer: Pick<THREE.WebGLRenderer, "shadowMap">, scene: THREE.Object3D, hiddenOverlays: THREE.Object3D[], render: () => T): T;

package/dist/postfx/shadowPrepass.js

@@ -1,5 +1,21 @@
 import { hidePostfxOverlays, restorePostfxOverlays } from "./postfxOverlay.js";
-/** Reuse the beauty pass's shadow maps while drawing a scene prepass. @internal */
+/**
+ * Draw a prepass with the world matrices the beauty pass already built. A postfx prepass renders the
+ * same scene a few milliseconds later in the same frame, so three's `updateMatrixWorld` walk there
+ * recomposes a graph nothing has moved — skipping it removes one full scene-graph walk per frame.
+ * @internal
+ */
+export function renderWithCurrentMatrices(scene, render) {
+    const autoUpdate = scene.matrixWorldAutoUpdate;
+    scene.matrixWorldAutoUpdate = false;
+    try {
+        return render();
+    }
+    finally {
+        scene.matrixWorldAutoUpdate = autoUpdate;
+    }
+}
+/** Reuse the beauty pass's shadow maps and world matrices while drawing a scene prepass. @internal */
 export function renderShadowlessPrepass(renderer, scene, hiddenOverlays, render) {
     const shadowMap = renderer.shadowMap;
     const autoUpdate = shadowMap.autoUpdate;
@@ -8,7 +24,7 @@ export function renderShadowlessPrepass(renderer, scene, hiddenOverlays, render)
     shadowMap.autoUpdate = false;
     shadowMap.needsUpdate = false;
     try {
-        return render();
+        return renderWithCurrentMatrices(scene, render);
     }
     finally {
         shadowMap.autoUpdate = autoUpdate;

package/dist/postfx/stylizePass.js

@@ -1,6 +1,7 @@
 import * as THREE from "three";
 import { FullScreenQuad, Pass } from "three-stdlib";
 import { isPostfxOverlay } from "./postfxOverlay.js";
+import { renderWithCurrentMatrices } from "./shadowPrepass.js";
 const DEFAULT_OUTLINE_COLOR = "#101014";
 const DEFAULT_DEPTH_THRESHOLD = 0.08;
 const DEFAULT_NORMAL_THRESHOLD = 0.35;
@@ -197,7 +198,7 @@ export class StylizePass extends Pass {
         renderer.setRenderTarget(target);
         renderer.setClearColor(0x8080ff, 1);
         renderer.clear();
-        renderer.render(scene, this.camera);
+        renderWithCurrentMatrices(scene, () => renderer.render(scene, this.camera));
         renderer.setClearColor(this.clearColor, previousClearAlpha);
         renderer.shadowMap.autoUpdate = previousShadowUpdate;
         scene.background = previousBackground;

package/dist/render/CascadedShadows.d.ts

@@ -1,9 +1,38 @@
 import * as THREE from "three";
 import { CSM } from "three/examples/jsm/csm/CSM.js";
 import type { DirectionalLightingConfig } from "@jgengine/core/game/playableGame";
+import type { GraphicsProfile } from "@jgengine/core/settings/graphicsProfile";
 import type { DaylightModulation } from "./SceneLighting.js";
 /** @internal Default PCF penumbra in shadow-map texels for configured directional lights. */
 export declare const DEFAULT_SHADOW_RADIUS = 1.25;
+/** @internal Reach in metres used when neither the game nor a graphics profile sets one. */
+export declare const DEFAULT_SHADOW_DISTANCE = 200;
+/**
+ * Shadow reach each tier's map resolution pays for. A cascade's texels stop describing a
+ * silhouette past roughly a tenth of a metre, so a smaller map covers less ground instead
+ * of covering the same ground coarsely.
+ * @internal
+ */
+export declare const SHADOW_DISTANCE_BY_MAP_SIZE: Readonly<Record<number, number>>;
+/**
+ * Cascaded-shadow reach from the graphics tier, clamped by that tier's draw distance.
+ * A game's own `shadowMaxFar` still wins.
+ * @internal
+ */
+export declare function resolveShadowDistance(profile?: GraphicsProfile, authored?: number): number;
+/**
+ * Frames between shadow-map refreshes for the cascade at `index`, nearest first. The nearest
+ * cascades move several texels per frame and refresh every frame; the far ones cover ground a
+ * slow camera barely crosses, so they pay the depth pass a half or a quarter as often.
+ * @internal
+ */
+export declare function cascadeShadowCadence(index: number, cascades: number): number;
+/**
+ * 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.
+ * @internal
+ */
+export declare function scheduleCascadeRefresh(lights: readonly THREE.DirectionalLight[], frame: 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).
@@ -13,8 +42,9 @@ export declare const DEFAULT_SHADOW_RADIUS = 1.25;
  *
  * @internal shell SceneLighting helper — games set `cascades` on directional lighting config.
  */
-export declare function CascadedShadows({ entry, modulation }: {
+export declare function CascadedShadows({ entry, profile, modulation, }: {
     entry: DirectionalLightingConfig;
+    profile?: GraphicsProfile;
     modulation?: DaylightModulation;
 }): null;
 /** Structural slice of CSM so the patcher is testable without a renderer. */

package/dist/render/CascadedShadows.js

@@ -4,6 +4,60 @@ import * as THREE from "three";
 import { CSM } from "three/examples/jsm/csm/CSM.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. */
+export const DEFAULT_SHADOW_DISTANCE = 200;
+/**
+ * Shadow reach each tier's map resolution pays for. A cascade's texels stop describing a
+ * silhouette past roughly a tenth of a metre, so a smaller map covers less ground instead
+ * of covering the same ground coarsely.
+ * @internal
+ */
+export const SHADOW_DISTANCE_BY_MAP_SIZE = {
+    512: 100,
+    1024: 150,
+    2048: 200,
+    4096: 200,
+};
+/**
+ * Cascaded-shadow reach from the graphics tier, clamped by that tier's draw distance.
+ * A game's own `shadowMaxFar` still wins.
+ * @internal
+ */
+export function resolveShadowDistance(profile, authored) {
+    if (authored !== undefined)
+        return authored;
+    if (profile === undefined)
+        return DEFAULT_SHADOW_DISTANCE;
+    const reach = SHADOW_DISTANCE_BY_MAP_SIZE[profile.shadowMapSize] ?? DEFAULT_SHADOW_DISTANCE;
+    return Math.min(profile.drawDistance, reach);
+}
+/**
+ * Frames between shadow-map refreshes for the cascade at `index`, nearest first. The nearest
+ * cascades move several texels per frame and refresh every frame; the far ones cover ground a
+ * slow camera barely crosses, so they pay the depth pass a half or a quarter as often.
+ * @internal
+ */
+export function cascadeShadowCadence(index, cascades) {
+    if (index < cascades - 2)
+        return 1;
+    if (cascades <= 2)
+        return index === 0 ? 1 : 2;
+    return 2 ** (index - (cascades - 3));
+}
+/**
+ * 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.
+ * @internal
+ */
+export function scheduleCascadeRefresh(lights, frame) {
+    for (let index = 0; index < lights.length; index += 1) {
+        const shadow = lights[index].shadow;
+        const cadence = cascadeShadowCadence(index, lights.length);
+        shadow.autoUpdate = cadence === 1;
+        if (cadence > 1)
+            shadow.needsUpdate = frame % cadence === 0;
+    }
+}
 function isStandardMaterial(mat) {
     return mat instanceof THREE.MeshStandardMaterial || mat instanceof THREE.MeshPhysicalMaterial;
 }
@@ -16,11 +70,13 @@ function isStandardMaterial(mat) {
  *
  * @internal shell SceneLighting helper — games set `cascades` on directional lighting config.
  */
-export function CascadedShadows({ entry, modulation }) {
+export function CascadedShadows({ entry, profile, modulation, }) {
     const camera = useThree((s) => s.camera);
     const scene = useThree((s) => s.scene);
     const csmRef = useRef(null);
+    const frameRef = useRef(0);
     const baseIntensity = entry.intensity ?? 1.3;
+    const maxFar = resolveShadowDistance(profile, entry.shadowMaxFar);
     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]);
@@ -31,7 +87,7 @@ export function CascadedShadows({ entry, modulation }) {
             camera,
             parent: scene,
             cascades,
-            maxFar: entry.shadowMaxFar ?? 200,
+            maxFar,
             mode: "practical",
             shadowMapSize: entry.shadowMapSize ?? 1024,
             shadowBias: entry.shadowBias ?? -0.0004,
@@ -65,7 +121,7 @@ export function CascadedShadows({ entry, modulation }) {
         entry.shadowBias,
         entry.shadowCameraSize,
         entry.shadowMapSize,
-        entry.shadowMaxFar,
+        maxFar,
         entry.shadowRadius,
     ]);
     useFrame(() => {
@@ -81,6 +137,7 @@ export function CascadedShadows({ entry, modulation }) {
         }
         csm.camera = camera;
         csm.update();
+        scheduleCascadeRefresh(csm.lights, frameRef.current++);
     });
     return null;
 }
@@ -153,14 +210,23 @@ export function bindCsmMaterials(scene, csm) {
         const added = ({ child }) => attach(child);
         const removed = ({ child }) => detach(child);
         const prior = node.onBeforeRender;
+        // One reference compare per draw: a mesh whose material has not been swapped costs nothing
+        // more than the authored hook. Re-patching only on a change keeps the swap detection.
+        let lastMaterial;
+        const mesh = node;
         const before = function (...args) {
             prior.apply(this, args);
-            patchMesh(this);
+            if (mesh.material === lastMaterial)
+                return;
+            lastMaterial = mesh.material;
+            patchMesh(mesh);
         };
         node.addEventListener("childadded", added);
         node.addEventListener("childremoved", removed);
-        if (node.isMesh)
+        if (mesh.isMesh) {
+            lastMaterial = mesh.material;
             node.onBeforeRender = before;
+        }
         nodes.set(node, () => {
             node.removeEventListener("childadded", added);
             node.removeEventListener("childremoved", removed);

package/dist/render/CharacterCrowd.d.ts

@@ -0,0 +1,20 @@
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+import { CharacterCrowdRegistry } from "./crowdRegistry.js";
+/** Props for {@link CharacterCrowd}. */
+export interface CharacterCrowdProps {
+    /** Character models the world can draw; only models with a `lod` policy join the crowd path. */
+    models: readonly ModelConfig[];
+    /** Where entity markers record the characters the crowd is drawing. */
+    registry: CharacterCrowdRegistry;
+    /** Baked samples per second for the crowd clips. Default 24. */
+    fps?: number;
+}
+/**
+ * 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
+ */
+export declare function CharacterCrowd({ models, registry, fps }: CharacterCrowdProps): import("react").JSX.Element;

package/dist/render/CharacterCrowd.js

@@ -0,0 +1,176 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useFrame, useLoader } from "@react-three/fiber";
+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 { applyMaterialOverrideToMaterial } from "../materialOverride.js";
+import { useRenderVisibility } from "../visibility/CullingProvider.js";
+import { ModelFallbackBoundary } from "./SceneModels.js";
+import { sharedGltfLoader } from "./modelLoad.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, }) {
+    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 baked = useMemo(() => {
+        if (clips.length === 0)
+            return null;
+        try {
+            return bakeSkinnedCrowd({ scene: gltf.scene, animations: gltf.animations }, { clips, 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`);
+            return null;
+        }
+    }, [gltf, clips, fps, model.url]);
+    useEffect(() => () => baked?.dispose(), [baked]);
+    const uniforms = useMemo(() => (baked === null ? null : createCrowdUniforms(baked)), [baked]);
+    const materials = useMemo(() => {
+        if (baked === null || uniforms === 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);
+        });
+    }, [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)
+            return null;
+        const instanced = new THREE.InstancedMesh(baked.geometry, materials, CROWD_CAPACITY);
+        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));
+        instanced.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+        return instanced;
+    }, [baked, materials, depthMaterial]);
+    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);
+        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),
+        };
+    }, [baked, model]);
+    const playback = useRef(new Map());
+    const visibleRef = useRenderVisibility();
+    useFrame((_state, delta) => {
+        if (mesh === null || baked === null || uniforms === 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;
+        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);
+            }
+            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;
+        });
+        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;
+        }
+        noteCrowdInstances(kind, count);
+    });
+    useEffect(() => () => clearCrowdKind(kind), [kind]);
+    if (mesh === null)
+        return null;
+    return _jsx("primitive", { object: mesh, castShadow: true, receiveShadow: true });
+}
+/**
+ * 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
+ */
+export function CharacterCrowd({ models, registry, fps = 24 }) {
+    const kinds = useMemo(() => {
+        const unique = new Map();
+        for (const model of models) {
+            const kind = crowdKindOf(model);
+            if (!unique.has(kind))
+                unique.set(kind, model);
+        }
+        return [...unique.entries()];
+    }, [models]);
+    useEffect(() => {
+        const dispose = devtools.probes.registerSystem("render/characters", characterLodProbe());
+        return () => dispose();
+    }, []);
+    useFrame(() => {
+        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))) }));
+}

package/dist/render/SceneLighting.js

@@ -1,7 +1,9 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useLayoutEffect, useRef } from "react";
-import { useFrame } from "@react-three/fiber";
+import { useEffect, useLayoutEffect, useRef } from "react";
+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";
 const DEFAULT_BACKDROP_FOG_COLOR = "#1a1c22";
 /** Default cap for combined dynamic point and spot lights. */
 export const POINT_LIGHT_BUDGET = 8;
@@ -30,7 +32,7 @@ function usesCascades(entry) {
 function DirectionalShadowLight({ entry, profile, modulation }) {
     const resolved = profile === undefined ? entry : { ...entry, shadowMapSize: entry.shadowMapSize ?? profile.shadowMapSize, cascades: entry.cascades ?? profile.cascades };
     if (usesCascades(resolved)) {
-        return _jsx(CascadedShadows, { entry: resolved, modulation: modulation });
+        return _jsx(CascadedShadows, { entry: resolved, profile: profile, modulation: modulation });
     }
     return _jsx(SingleShadowLight, { entry: resolved, modulation: modulation });
 }
@@ -71,6 +73,28 @@ function SingleShadowLight({ entry, modulation }) {
 }
 export function ConfiguredLighting({ lighting, profile, modulation, }) {
     const dynamic = resolveDynamicLights(lighting);
+    const scene = useThree((s) => s.scene);
+    const shadowsCast = (lighting.directional ?? []).some((entry) => entry.castShadow === true);
+    const cullRef = useRef(null);
+    useEffect(() => {
+        if (!shadowsCast)
+            return;
+        const cull = cullSmallShadowCasters(scene);
+        cullRef.current = cull;
+        return () => {
+            cull.restore();
+            cullRef.current = null;
+        };
+    }, [scene, shadowsCast]);
+    useEffect(() => devtools.probes.registerSystem("render/shadows", {
+        counters: () => cullRef.current?.stats() ?? { casters: 0, skipped: 0 },
+        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`;
+        },
+    }), []);
     const ambientRef = useRef(null);
     const hemisphereRef = useRef(null);
     const baseAmbient = lighting.ambient?.intensity ?? 0.55;

package/dist/render/SceneWarmupGate.d.ts

@@ -0,0 +1,20 @@
+import { type ShaderWarmupState } from "./shaderWarmup.js";
+/** Warmup state before the gate has run, so the loading screen covers the very first frame. @internal */
+export declare const SCENE_WARMUP_PENDING: ShaderWarmupState;
+/**
+ * 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 declare function SceneWarmupGate({ onState }: {
+    onState: (state: ShaderWarmupState) => void;
+}): null;
+/**
+ * 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
+ * paint over it, so a title screen stays usable.
+ * @internal
+ */
+export declare function SceneWarmupCover({ state }: {
+    state: ShaderWarmupState;
+}): import("react").JSX.Element | null;