@jgengine/shell 0.26.0 → 0.28.0

package/dist/camera/cameraCollision.js

@@ -1,5 +1,5 @@
 /**
- * Camera spring-arm occlusion filtering.
+ * Camera spring-arm occlusion filtering and camera clearance.
  *
  * The orbit rig raycasts target→camera each frame and pulls the boom in past
  * occluders. Author decor mounted through the `WorldOverlay` presentation seam
@@ -7,6 +7,10 @@
  * decor group flags itself camera-transparent once (`jgCameraTransparent`) and
  * every descendant inherits it — a child can opt back into blocking the camera
  * with `jgCameraCollide`.
+ *
+ * `clearCameraBoom` is the collision half every rig (and a game-owned camera)
+ * shares: one query against the world's existing collision, one boom length that
+ * cannot leave the camera inside geometry.
  */
 /** userData applied to the group wrapping author `WorldOverlay` decor so the spring-arm ignores it by default. */
 export const CAMERA_TRANSPARENT_USERDATA = {
@@ -32,3 +36,70 @@ export function isCameraOccluderTransparent(object) {
     }
     return false;
 }
+function clampNumber(value, min, max) {
+    return value < min ? min : value > max ? max : value;
+}
+/**
+ * Pull a camera in along its boom so it never sits inside world collision.
+ * A blocking surface rejects the desired position: the camera moves to
+ * `clearance` before it, and onto the pivot when the surface is closer than that
+ * (the pivot is inside, so no camera position is clear). Pulling in is immediate
+ * — a camera must not spend a frame inside a trunk — while releasing eases back
+ * at `releaseRate`, which is what makes the boom read as a spring arm instead of
+ * a hard stop.
+ *
+ * @capability camera-clearance keep any camera out of world collision with a spring-arm pull-in
+ */
+export function clearCameraBoom(input) {
+    const { pivot, desired, query } = input;
+    const dx = desired.x - pivot.x;
+    const dy = desired.y - pivot.y;
+    const dz = desired.z - pivot.z;
+    const length = Math.hypot(dx, dy, dz);
+    if (!(length > 1e-6) || !Number.isFinite(length)) {
+        return { position: { ...desired }, arm: 0, pulled: false };
+    }
+    const clearance = Math.max(0, input.clearance ?? 0.3);
+    const direction = { x: dx / length, y: dy / length, z: dz / length };
+    const hit = query.firstHit(pivot, direction, length + clearance);
+    // A zero hit means the boom origin is itself inside collision, so the ray says nothing
+    // about the eye; moving to it would teleport the camera into whatever holds the origin.
+    if (hit !== null && hit <= 0) {
+        return { position: { ...desired }, arm: length, pulled: false };
+    }
+    const allowed = hit === null ? length : clampNumber(hit - clearance, 0, length);
+    let arm = allowed;
+    const previous = input.previousArm;
+    const dt = input.deltaSeconds ?? 0;
+    if (previous !== null && previous !== undefined && previous < allowed && dt > 0) {
+        const rate = Math.max(0, input.releaseRate ?? 8);
+        arm = Math.min(allowed, previous + (allowed - previous) * (1 - Math.exp(-rate * dt)));
+    }
+    return {
+        position: { x: pivot.x + direction.x * arm, y: pivot.y + direction.y * arm, z: pivot.z + direction.z * arm },
+        arm,
+        pulled: hit !== null && arm < length - 1e-9,
+    };
+}
+/**
+ * `CameraCollisionQuery` over the scene's existing collision query (`ctx.scene.raycast`),
+ * which already reads world solids, scene-object colliders and walls. Entities and
+ * terrain stay out by default: the followed body must not push its own camera, and
+ * looking down at the ground must not pull the boom.
+ *
+ * @capability camera-clearance keep any camera out of world collision with a spring-arm pull-in
+ */
+export function sceneCameraQuery(raycast, options = {}) {
+    const filter = { entities: options.entities ?? false, terrain: options.terrain ?? false };
+    return {
+        firstHit(origin, direction, maxDistance) {
+            const hit = raycast({
+                origin: [origin.x, origin.y, origin.z],
+                direction: [direction.x, direction.y, direction.z],
+                maxDistance,
+                filter,
+            });
+            return hit === null ? null : hit.distance;
+        },
+    };
+}

package/dist/camera/index.d.ts

@@ -8,5 +8,5 @@ export { CameraShakeContext, cameraShake, createCameraShakeChannel, defaultCamer
 export { ControllerCameraShake, type ControllerCameraShakeProps } from "./ControllerCameraShake.js";
 export { rtsPanKeysConflict } from "./rigMath.js";
 export { GAME_SIM_FRAME_PRIORITY } from "./orbitCameraMath.js";
-export { CAMERA_TRANSPARENT_USERDATA, isCameraOccluderTransparent, type CameraOccluder, } from "./cameraCollision.js";
+export { CAMERA_TRANSPARENT_USERDATA, clearCameraBoom, isCameraOccluderTransparent, sceneCameraQuery, type CameraClearanceInput, type CameraClearanceResult, type CameraCollisionQuery, type CameraOccluder, type CameraPoint, } from "./cameraCollision.js";
 export { registerFirstPersonMuzzle, type FirstPersonMuzzleReader } from "./customMuzzle.js";

package/dist/camera/index.js

@@ -8,5 +8,5 @@ export { CameraShakeContext, cameraShake, createCameraShakeChannel, defaultCamer
 export { ControllerCameraShake } from "./ControllerCameraShake.js";
 export { rtsPanKeysConflict } from "./rigMath.js";
 export { GAME_SIM_FRAME_PRIORITY } from "./orbitCameraMath.js";
-export { CAMERA_TRANSPARENT_USERDATA, isCameraOccluderTransparent, } from "./cameraCollision.js";
+export { CAMERA_TRANSPARENT_USERDATA, clearCameraBoom, isCameraOccluderTransparent, sceneCameraQuery, } from "./cameraCollision.js";
 export { registerFirstPersonMuzzle } from "./customMuzzle.js";

package/dist/camera/rigResolve.d.ts

@@ -2,6 +2,19 @@ import type { CameraRigKind, GameCameraConfig } from "@jgengine/core/game/playab
 import type { CameraRigOverride } from "@jgengine/core/runtime/cameraDirector";
 /** @internal */
 export declare function resolveRuntimeCameraConfig(config: GameCameraConfig | undefined, override: CameraRigOverride | null | undefined): GameCameraConfig | undefined;
+/**
+ * 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 declare function resolveCaptureCameraConfig(config: GameCameraConfig | undefined, override: CameraRigOverride | null | undefined): GameCameraConfig | undefined;
 /**
  * Resolves which rig mounts from a `GameCameraConfig`. Precedence, most to least
  * specific: an explicit `rig` field always wins; then `perspective: "first"`

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 { 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";
@@ -18,14 +18,16 @@ import { buildAuthoredRoadNetwork, RoadRibbons } from "./RoadRibbons.js";
 import { terrainGroundColorSampler } from "./terrainGroundColor.js";
 import { InstancedBuildings } from "../structures/GeneratedBuilding.js";
 import { GrassField } from "../terrain/GrassField.js";
+import { GrassCover } from "../terrain/GrassCover.js";
 import { CarvedTerrain } from "../terrain/CarvedTerrain.js";
 import { createTerrainDetailMaterial } from "../terrain/terrainDetailMaterial.js";
+import { MAX_TERRAIN_LAYER_MAPS } from "../terrain/terrainDetailMaterial.js";
 import { useTerrainQuality } from "../terrain/terrainQuality.js";
 import { createTerrainPaintTextures, packTerrainPaintWeights } from "../terrain/terrainSurfaces.js";
 import { Ocean } from "../water/Ocean.js";
 import { RainField } from "../weather/RainField.js";
 import { SnowField } from "../weather/SnowField.js";
-function TexturedTerrainGround({ detail, layout, }) {
+function TexturedTerrainGround({ detail, layout, layerMaps, }) {
     const maps = detail.material.maps;
     const textures = useRecoverableTexture({
         color: maps.color,
@@ -42,9 +44,105 @@ function TexturedTerrainGround({ detail, layout, }) {
         }
     }, [textures]);
     const quality = useTerrainQuality();
-    const material = useDisposable(() => createTerrainDetailMaterial(detail, textures, { paint: layout.paint, quality }).material, [detail, textures, layout.paint, quality]);
+    const material = useDisposable(() => createTerrainDetailMaterial(detail, textures, { paint: layout.paint, quality, ...(layerMaps === undefined ? {} : { layerMaps }) }).material, [detail, textures, layout.paint, quality, layerMaps]);
     return (_jsxs(_Fragment, { children: [_jsx(PresentationRecoveredDraw, {}), _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 })] }));
 }
+/** 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
+ * authored data (`TerrainMaterialLayer.materialUrl`), resolved by the editor from a library name, so
+ * the renderer never reaches into the asset pipeline.
+ */
+function useTerrainLayerMaps(paint) {
+    const urls = useMemo(() => Array.from({ length: MAX_TERRAIN_LAYER_MAPS }, (_, index) => {
+        const url = paint?.slots[index + 1]?.materialUrl;
+        return url === undefined || url.length === 0 ? NO_LAYER_MAP : url;
+    }), [paint]);
+    const textures = useRecoverableTexture({ layer1: urls[0], layer2: urls[1], layer3: urls[2], layer4: urls[3] });
+    useEffect(() => {
+        for (const texture of Object.values(textures)) {
+            texture.colorSpace = THREE.SRGBColorSpace;
+            texture.wrapS = THREE.RepeatWrapping;
+            texture.wrapT = THREE.RepeatWrapping;
+            texture.needsUpdate = true;
+        }
+    }, [textures]);
+    const slots = paint?.slots;
+    return useMemo(() => {
+        if (slots === undefined)
+            return undefined;
+        return Array.from({ length: MAX_TERRAIN_LAYER_MAPS }, (_, index) => {
+            const slot = slots[index + 1];
+            if (slot?.materialUrl === undefined)
+                return undefined;
+            const texture = textures[`layer${index + 1}`];
+            return texture === undefined ? undefined : { color: texture, tileMetres: slot.tileMetres };
+        });
+    }, [slots, textures]);
+}
 function TerrainGround({ terrain, field, center, sculpt, }) {
     const detailEnabled = terrain.detail !== false;
     const paint = useMemo(() => {
@@ -79,14 +177,19 @@ function TerrainGround({ terrain, field, center, sculpt, }) {
     }, [terrain.baseHeight, terrain.height]);
     const resolvedDetail = useMemo(() => (terrain.detail === false ? undefined : resolveTerrainDetail(terrain.detail, terrain.waterLevel)), [terrain.detail, terrain.waterLevel]);
     const quality = useTerrainQuality();
-    const proceduralMaterial = useMemo(() => resolvedDetail === undefined || resolvedDetail.material !== undefined
+    const layerMaps = useTerrainLayerMaps(paint);
+    const proceduralMaterial = useMemo(() => resolvedDetail === undefined || (resolvedDetail.material !== undefined && resolvedDetail.material.missing === "fail")
         ? undefined
-        : createTerrainDetailMaterial(resolvedDetail, undefined, { paint, quality }).material, [resolvedDetail, paint, quality]);
+        : 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 } }) }));
+        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];
@@ -100,7 +203,7 @@ function Vegetation({ grass, field, groundColor, }) {
     const wind = useMemo(() => ({ strength: grass.windStrength }), [grass.windStrength]);
     const colorBase = grass.colors[0];
     const colorTip = grass.colors[grass.colors.length - 1];
-    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(GrassField, { area: area, count: Math.max(1500, Math.min(250000, Math.ceil(grass.density * grass.area.w * grass.area.d))), density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, bladeBend: grass.bladeBend, tuftRadius: grass.tuftRadius, colorVariation: grass.colorVariation, normalLift: grass.normalLift, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, colorGround: groundColor, wind: wind, edgeFeather: Math.min(8, Math.max(1.5, Math.min(grass.area.w, grass.area.d) * 0.12)), frustumCulled: true }) }));
+    return (_jsxs("group", { position: [cx, 0, cz], children: [_jsx(GrassCover, { area: area, seed: typeof grass.seed === "number" ? grass.seed : 1, colorBase: colorBase ?? "#3f7d2d", colorTip: colorTip ?? "#66a83f", strength: grass.groundCover ?? 0.9, edgeFeather: Math.min(8, Math.max(1.5, Math.min(grass.area.w, grass.area.d) * 0.12)), heightAt: heightAt, coverageAt: () => 1 }), _jsx(GrassField, { area: area, count: Math.max(1500, Math.min(250000, Math.ceil(grass.density * grass.area.w * grass.area.d))), density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, bladeBend: grass.bladeBend, tuftRadius: grass.tuftRadius, colorVariation: grass.colorVariation, normalLift: grass.normalLift, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, colorGround: groundColor, wind: wind, edgeFeather: Math.min(8, Math.max(1.5, Math.min(grass.area.w, grass.area.d) * 0.12)), frustumCulled: true })] }));
 }
 /** Terrain color under a grass patch center — so blade roots blend into the ground they stand on. */
 function vegetationGroundColor(terrain, field, grass, sculpt) {
@@ -142,19 +245,24 @@ function DynamicWater({ ocean }) {
     const groupRef = useRef(null);
     const [x, z] = ocean.position ?? [0, 0];
     const config = useOceanConfig(ocean);
+    const depthAt = useCallback((lx, lz) => ocean.levelAt(ctx.time.now()) - ctx.world.ground.sampleHeight(x + lx, z + lz), [ctx.time.now, ctx.world.ground, ocean.levelAt, x, z]);
     useFrame(() => {
         if (groupRef.current !== null)
             groupRef.current.position.y = ocean.levelAt(ctx.time.now());
     });
-    return (_jsx("group", { ref: groupRef, position: [0, ocean.level, 0], children: _jsx(Ocean, { position: [x, 0, z], config: config }) }));
+    return (_jsx("group", { ref: groupRef, position: [0, ocean.level, 0], children: _jsx(Ocean, { position: [x, 0, z], config: config, depthAt: depthAt }) }));
 }
 function Water({ ocean }) {
+    const ctx = useGameContext();
     const [x, z] = ocean.position ?? [0, 0];
     const config = useOceanConfig(ocean);
+    // The ocean descriptor has no depth field: sample the live ground so the sheet shades
+    // shallow→deep and the shoreline foam band lands where the bed meets the surface.
+    const depthAt = useCallback((lx, lz) => ocean.level - ctx.world.ground.sampleHeight(x + lx, z + lz), [ctx.world.ground, ocean.level, x, z]);
     if (ocean.levelAt !== undefined) {
         return _jsx(DynamicWater, { ocean: ocean });
     }
-    return _jsx(Ocean, { position: [x, ocean.level, z], config: config });
+    return _jsx(Ocean, { position: [x, ocean.level, z], config: config, depthAt: depthAt });
 }
 function Structures({ structures, field }) {
     const placements = useMemo(() => resolveStructureBuildings(structures).map((building) => ({

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;