@jgengine/shell 0.18.0 → 0.19.0

package/dist/render/EnvironmentLighting.js

@@ -1,6 +1,8 @@
 import { useThree } from "@react-three/fiber";
 import { useEffect } from "react";
 import * as THREE from "three";
+import { EXRLoader } from "three/examples/jsm/loaders/EXRLoader.js";
+import { RGBELoader } from "three/examples/jsm/loaders/RGBELoader.js";
 /**
  * Image-based lighting from a procedural sky/ground probe (not three's stock
  * RoomEnvironment gray studio box). Metals and dielectrics pick up sky color and
@@ -10,27 +12,61 @@ import * as THREE from "three";
  * Opt out of cinematic IBL with `look: "flat"` on the shell presentation.
  * @internal shell-internal default lighting; games never import it.
  */
-export function EnvironmentLighting({ intensity = 0.35, skyColor = "#87b5e0", groundColor = "#3d4a38", sunDirection, sunColor = "#fff2d6", }) {
+export function EnvironmentLighting({ source, intensity = 0.35, skyColor = "#87b5e0", groundColor = "#3d4a38", sunDirection, sunColor = "#fff2d6", }) {
     const gl = useThree((state) => state.gl);
     const scene = useThree((state) => state.scene);
     useEffect(() => {
         const pmrem = new THREE.PMREMGenerator(gl);
-        const probe = buildSkyProbeScene({ skyColor, groundColor, sunDirection, sunColor });
-        const target = pmrem.fromScene(probe, 0.04);
+        let target;
+        let loadedTexture;
+        let cancelled = false;
+        const effective = source?.kind === "gradient" ? source : undefined;
+        const apply = (next, rotation) => {
+            if (cancelled) {
+                next.dispose();
+                return;
+            }
+            target = next;
+            scene.environment = next.texture;
+            if (rotation !== undefined)
+                scene.environmentRotation = new THREE.Euler(0, rotation, 0);
+        };
         const previous = scene.environment;
-        scene.environment = target.texture;
+        const previousRotation = scene.environmentRotation;
+        if (source?.kind === "hdri") {
+            const Loader = /\.exr(?:$|\?)/i.test(source.url) ? EXRLoader : RGBELoader;
+            new Loader().loadAsync(source.url).then((texture) => {
+                loadedTexture = texture;
+                texture.mapping = THREE.EquirectangularReflectionMapping;
+                apply(pmrem.fromEquirectangular(texture), source.rotation);
+            }).catch(() => undefined);
+        }
+        else if (source?.kind === "cube") {
+            new THREE.CubeTextureLoader().loadAsync(source.urls).then((texture) => {
+                loadedTexture = texture;
+                apply(pmrem.fromCubemap(texture));
+            }).catch(() => undefined);
+        }
+        else {
+            const probe = buildSkyProbeScene({ skyColor: effective?.sky ?? skyColor, groundColor: effective?.ground ?? groundColor, sunDirection, sunColor: effective?.sun ?? sunColor });
+            apply(pmrem.fromScene(probe, 0.04));
+            disposeScene(probe);
+        }
         const sceneWithIntensity = scene;
         const previousIntensity = sceneWithIntensity.environmentIntensity;
-        sceneWithIntensity.environmentIntensity = intensity;
-        disposeScene(probe);
-        pmrem.dispose();
+        sceneWithIntensity.environmentIntensity = source?.intensity ?? intensity;
         return () => {
-            target.dispose();
+            cancelled = true;
+            pmrem.dispose();
+            target?.dispose();
+            loadedTexture?.dispose();
             scene.environment = previous;
+            if (previousRotation !== undefined)
+                scene.environmentRotation = previousRotation;
             if (previousIntensity !== undefined)
                 sceneWithIntensity.environmentIntensity = previousIntensity;
         };
-    }, [gl, scene, intensity, skyColor, groundColor, sunColor, sunDirection?.[0], sunDirection?.[1], sunDirection?.[2]]);
+    }, [gl, scene, source, intensity, skyColor, groundColor, sunColor, sunDirection?.[0], sunDirection?.[1], sunDirection?.[2]]);
     return null;
 }
 function buildSkyProbeScene(options) {

package/dist/render/SceneLighting.d.ts

@@ -1,6 +1,20 @@
-import type { BackdropConfig, LightingConfig } from "@jgengine/core/game/playableGame";
-export declare function ConfiguredLighting({ lighting }: {
+import type { DirectionalLight } from "three";
+import type { BackdropConfig, LightingConfig, PointLightingConfig } from "@jgengine/core/game/playableGame";
+import type { GraphicsProfile } from "@jgengine/core/settings/graphicsProfile";
+/** Default cap for combined dynamic point and spot lights. */
+export declare const POINT_LIGHT_BUDGET = 8;
+/** @internal Clamp point lights for the runtime budget. */
+export declare function resolvePointLightBudget(entries: readonly PointLightingConfig[] | undefined): readonly PointLightingConfig[];
+/**
+ * Refresh a directional light's shadow projection after its frustum bounds change.
+ * R3F pierced `shadow-camera-*` props write the bounds but never call
+ * `updateProjectionMatrix()`, so depth renders with the stale default ~10×10 box
+ * and `shadowCameraSize` is silently inert.
+ */
+export declare function syncShadowProjection(light: DirectionalLight): void;
+export declare function ConfiguredLighting({ lighting, profile }: {
     lighting: LightingConfig;
+    profile?: GraphicsProfile;
 }): import("react").JSX.Element;
 export declare function BackdropFog({ fog }: {
     fog: BackdropConfig["fog"];

package/dist/render/SceneLighting.js

@@ -1,22 +1,72 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useLayoutEffect, useRef } from "react";
 import { CascadedShadows } from "./CascadedShadows.js";
 const DEFAULT_BACKDROP_FOG_COLOR = "#1a1c22";
+/** Default cap for combined dynamic point and spot lights. */
+export const POINT_LIGHT_BUDGET = 8;
+/** @internal Clamp point lights for the runtime budget. */
+export function resolvePointLightBudget(entries) {
+    if (entries === undefined || entries.length <= POINT_LIGHT_BUDGET)
+        return entries ?? [];
+    if (typeof console !== "undefined" && typeof console.warn === "function") {
+        console.warn(`[jgengine:lighting] ${entries.length} point lights requested — clamped to budget ${POINT_LIGHT_BUDGET}`);
+    }
+    return entries.slice(0, POINT_LIGHT_BUDGET);
+}
+function resolveDynamicLights(lighting) {
+    const point = lighting.point ?? [];
+    const spot = lighting.spot ?? [];
+    const budget = Math.max(0, Math.floor(lighting.maxDynamicLights ?? POINT_LIGHT_BUDGET));
+    if (point.length + spot.length <= budget)
+        return { point, spot };
+    if (typeof console !== "undefined" && typeof console.warn === "function")
+        console.warn(`[jgengine:lighting] ${point.length + spot.length} dynamic lights requested — clamped to budget ${budget}`);
+    return { point: point.slice(0, budget), spot: spot.slice(0, Math.max(0, budget - point.length)) };
+}
 function usesCascades(entry) {
     return (entry.castShadow ?? false) && (entry.cascades ?? 1) > 1;
 }
-function DirectionalShadowLight({ entry }) {
-    if (usesCascades(entry)) {
-        return _jsx(CascadedShadows, { entry: entry });
+function DirectionalShadowLight({ entry, profile }) {
+    const resolved = profile === undefined ? entry : { ...entry, shadowMapSize: entry.shadowMapSize ?? profile.shadowMapSize, cascades: entry.cascades ?? profile.cascades };
+    if (usesCascades(resolved)) {
+        return _jsx(CascadedShadows, { entry: resolved });
     }
+    return _jsx(SingleShadowLight, { entry: resolved });
+}
+/**
+ * Refresh a directional light's shadow projection after its frustum bounds change.
+ * R3F pierced `shadow-camera-*` props write the bounds but never call
+ * `updateProjectionMatrix()`, so depth renders with the stale default ~10×10 box
+ * and `shadowCameraSize` is silently inert.
+ */
+export function syncShadowProjection(light) {
+    light.shadow.camera.updateProjectionMatrix();
+}
+function SingleShadowLight({ entry }) {
+    const lightRef = useRef(null);
     const size = entry.shadowCameraSize ?? 40;
-    return (_jsx("directionalLight", { position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1.3, color: entry.color, castShadow: entry.castShadow ?? false, "shadow-mapSize-width": entry.shadowMapSize ?? 1024, "shadow-mapSize-height": entry.shadowMapSize ?? 1024, "shadow-camera-left": -size, "shadow-camera-right": size, "shadow-camera-top": size, "shadow-camera-bottom": -size, "shadow-camera-near": 0.5, "shadow-camera-far": Math.max(200, size * 6), "shadow-bias": entry.shadowBias ?? -0.0004, "shadow-normalBias": entry.shadowNormalBias ?? 0.02 }));
+    const far = Math.max(200, size * 6);
+    const mapSize = entry.shadowMapSize ?? 1024;
+    useLayoutEffect(() => {
+        if (lightRef.current !== null)
+            syncShadowProjection(lightRef.current);
+    }, [size, far]);
+    useLayoutEffect(() => {
+        const light = lightRef.current;
+        if (light === null || light.shadow.map === null)
+            return;
+        light.shadow.map.dispose();
+        light.shadow.map = null;
+    }, [mapSize]);
+    return (_jsx("directionalLight", { ref: lightRef, position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1.3, color: entry.color, castShadow: entry.castShadow ?? false, "shadow-mapSize-width": mapSize, "shadow-mapSize-height": mapSize, "shadow-camera-left": -size, "shadow-camera-right": size, "shadow-camera-top": size, "shadow-camera-bottom": -size, "shadow-camera-near": 0.5, "shadow-camera-far": far, "shadow-bias": entry.shadowBias ?? -0.0004, "shadow-normalBias": entry.shadowNormalBias ?? 0.02 }));
 }
-export function ConfiguredLighting({ lighting }) {
+export function ConfiguredLighting({ lighting, profile }) {
+    const dynamic = resolveDynamicLights(lighting);
     return (_jsxs(_Fragment, { children: [lighting.ambient !== undefined ? (_jsx("ambientLight", { color: lighting.ambient.color, intensity: lighting.ambient.intensity ?? 0.55 })) : null, lighting.hemisphere !== undefined ? (_jsx("hemisphereLight", { args: [
                     lighting.hemisphere.skyColor ?? "#bfe3ff",
                     lighting.hemisphere.groundColor ?? "#4c6b34",
                     lighting.hemisphere.intensity ?? 0.55,
-                ] })) : null, (lighting.directional ?? []).map((entry, index) => (_jsx(DirectionalShadowLight, { entry: entry }, index)))] }));
+                ] })) : null, (lighting.directional ?? []).map((entry, index) => (_jsx(DirectionalShadowLight, { entry: entry, profile: profile }, index))), dynamic.point.map((entry, index) => (_jsx("pointLight", { position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1, color: entry.color, distance: entry.distance ?? 0, decay: entry.decay ?? 2, castShadow: entry.castShadow ?? false }, index))), dynamic.spot.map((entry, index) => (_jsx("spotLight", { position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1, color: entry.color, distance: entry.distance ?? 0, decay: entry.decay ?? 2, angle: entry.angle ?? Math.PI / 6, penumbra: entry.penumbra ?? 0, castShadow: entry.castShadow ?? false, "target-position": [...(entry.target ?? [0, 0, 0])] }, index)))] }));
 }
 export function BackdropFog({ fog }) {
     if (fog === undefined)

package/dist/render/SceneModels.js

@@ -3,23 +3,51 @@ import { useFrame, useLoader } from "@react-three/fiber";
 import { useTexture } from "@react-three/drei";
 import { Component, Suspense, useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
+import { createSpriteClipPlayer } from "@jgengine/core/render/sprite2d";
 import { reportFallbackSeam } from "@jgengine/core/devtools/fallbackSeams";
 import { useOptionalGameContext } from "@jgengine/react/provider";
 import { sharedGltfLoader } from "./modelLoad.js";
 import { measureLocalBounds, reportMeasuredBounds } from "./measureBounds.js";
 import { measureLocalCollisionTriangles, reportMeasuredCollisionMesh } from "./measureCollisionMesh.js";
 import { useModelAnimation } from "./useModelAnimation.js";
+import { useFootIk } from "./useFootIk.js";
 import { PartMotionRig } from "./PartMotion.js";
 import { applyMaterialOverride } from "../materialOverride.js";
 import { applyPaintTextureToMaterials, cacheStandardMaterials, cloneModelScene, createPaintCanvas, disposeClonedMaterials, disposePaintCanvas, syncPaintCanvas, } from "./modelRender.js";
 export function EntitySprite({ sprite }) {
-    const texture = useLoader(THREE.TextureLoader, sprite.url);
+    const texture = useLoader(THREE.TextureLoader, sprite.clip?.atlas.image ?? sprite.url);
+    const map = useMemo(() => texture.clone(), [texture]);
+    const player = useMemo(() => (sprite.clip === undefined ? null : createSpriteClipPlayer(sprite.clip.atlas)), [sprite.clip]);
+    const animation = sprite.clip?.animation;
     useEffect(() => {
-        texture.colorSpace = THREE.SRGBColorSpace;
-        texture.anisotropy = 4;
-        texture.needsUpdate = true;
-    }, [texture]);
-    return (_jsx("sprite", { "position-y": sprite.y, scale: [sprite.width, sprite.height, 1], children: _jsx("spriteMaterial", { map: texture, transparent: true, alphaTest: 0.08, depthWrite: false }) }));
+        map.colorSpace = THREE.SRGBColorSpace;
+        map.anisotropy = 4;
+        map.needsUpdate = true;
+        return () => map.dispose();
+    }, [map]);
+    useEffect(() => {
+        if (player !== null && animation !== undefined)
+            player.play(animation);
+    }, [player, animation]);
+    useFrame((_state, delta) => {
+        if (player === null || sprite.clip === undefined)
+            return;
+        player.advance(delta);
+        const frame = player.frame();
+        if (frame === undefined)
+            return;
+        const [atlasWidth, atlasHeight] = sprite.clip.atlas.size;
+        map.repeat.set(frame.w / atlasWidth, frame.h / atlasHeight);
+        map.offset.set(frame.x / atlasWidth, 1 - (frame.y + frame.h) / atlasHeight);
+        map.needsUpdate = true;
+    });
+    useEffect(() => {
+        if (player === null) {
+            map.repeat.set(1, 1);
+            map.offset.set(0, 0);
+        }
+    }, [map, player]);
+    return (_jsx("sprite", { "position-y": sprite.y, scale: [sprite.width, sprite.height, 1], children: _jsx("spriteMaterial", { map: map, transparent: true, alphaTest: 0.08, depthWrite: false }) }));
 }
 /**
  * Catches a render throw from a model subtree and swaps in `fallback` — but never silently: the
@@ -102,8 +130,14 @@ function ModelMaterialMapsApplier({ scene, maps }) {
             record.roughness = maps.roughness;
         if (maps.ao !== undefined)
             record.ao = maps.ao;
+        if (maps.metalness !== undefined)
+            record.metalness = maps.metalness;
+        if (maps.emissive !== undefined)
+            record.emissive = maps.emissive;
+        if (maps.height !== undefined)
+            record.height = maps.height;
         return record;
-    }, [maps.color, maps.normal, maps.roughness, maps.ao]);
+    }, [maps.color, maps.normal, maps.roughness, maps.ao, maps.metalness, maps.emissive, maps.height]);
     const textures = useTexture(entries);
     useEffect(() => {
         if (textures.color !== undefined)
@@ -121,12 +155,13 @@ export function EntityModel({ model, instanceId, measure, }) {
     const material = model.material;
     const baseY = model.y ?? 0;
     const dims = model.dims;
+    const shadows = model.shadows;
     const scene = useMemo(() => {
-        const cloned = cloneModelScene(gltf.scene);
+        const cloned = cloneModelScene(gltf.scene, { shadows });
         if (material !== undefined)
             applyMaterialOverride(cloned, material, { clone: false });
         return cloned;
-    }, [gltf, material]);
+    }, [gltf, material, shadows]);
     const measured = useMemo(() => {
         if (model.targetHeight === undefined)
             return null;
@@ -183,6 +218,7 @@ export function EntityModel({ model, instanceId, measure, }) {
             reportMeasuredCollisionMesh(ctx, measureTarget, measureKey, triangles);
     }, [ctx, scene, scale, positionX, positionY, positionZ, measureTarget, measureKey]);
     useModelAnimation(scene, gltf.animations, model.animation, instanceId);
+    useFootIk(scene, model.ik, ctx, instanceId, baseY);
     const paintCanvasRef = useRef(null);
     const paintDrawnCountRef = useRef(0);
     const paintVersionRef = useRef(-1);

package/dist/render/SkinnedInstances.d.ts

@@ -0,0 +1,91 @@
+import * as THREE from "three";
+import { type BoneTextureLayout } from "@jgengine/core/anim/boneTexture";
+/** A rig to bake: a loaded scene with skinned meshes and its clips. */
+export interface SkinnedCrowdSource {
+    scene: THREE.Object3D;
+    animations: readonly THREE.AnimationClip[];
+}
+/** Options for {@link bakeSkinnedCrowd}. */
+export interface BakeSkinnedCrowdOptions {
+    /** Clip names to bake, in order; default every clip on the rig. */
+    clips?: readonly string[];
+    /** Baked samples per second. Default 30. */
+    fps?: number;
+    /** Clips that hold their last pose instead of looping. */
+    once?: readonly string[];
+    maxTextureSize?: number;
+}
+/** A rig baked for instancing: one merged geometry, the bone-matrix texture and its layout. */
+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;
+    /** Per clip: whether it loops. Same order as `layout.clips`. */
+    loops: boolean[];
+    clipIndex: ReadonlyMap<string, number>;
+    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.
+ */
+export declare function bakeSkinnedCrowd(source: SkinnedCrowdSource, options?: BakeSkinnedCrowdOptions): BakedSkinnedCrowd;
+/** Uniforms shared by every material of one crowd; `crowdTime` advances once per frame. */
+export interface CrowdUniforms {
+    crowdBones: {
+        value: THREE.DataTexture;
+    };
+    crowdTime: {
+        value: number;
+    };
+    crowdClips: {
+        value: THREE.Vector4[];
+    };
+}
+/** Builds the uniforms a crowd material reads: the texture and per-clip start, frames, fps and loop. */
+export declare function createCrowdUniforms(baked: BakedSkinnedCrowd): CrowdUniforms;
+/**
+ * Patches a material so each instance skins itself from the crowd texture: per-instance `crowdPlay`
+ * is (clip index, time offset, speed). Works on any built-in material, the depth material for
+ * shadows included.
+ */
+export declare function patchCrowdMaterial<T extends THREE.Material>(material: T, uniforms: CrowdUniforms): T;
+/** One crowd member: where it stands and what it plays. */
+export interface CrowdInstance {
+    position: readonly [number, number, number];
+    rotationY?: number;
+    scale?: number;
+    /** A baked clip name. */
+    clip: string;
+    /** Seconds into the clip at crowd time zero, so members do not move in lockstep. */
+    timeOffset?: number;
+    /** Playback rate. Default 1. */
+    speed?: number;
+}
+/** Props for {@link SkinnedInstances}. */
+export interface SkinnedInstancesProps {
+    url: string;
+    instances: readonly CrowdInstance[];
+    /** Clip names to bake; default every clip on the rig. */
+    clips?: readonly string[];
+    /** Clips that hold their last pose instead of looping. */
+    once?: readonly string[];
+    fps?: number;
+    /** Uniform scale applied to every member, e.g. to normalize a rig to a height. */
+    modelScale?: number;
+    castShadow?: boolean;
+    receiveShadow?: boolean;
+    /** Multiplies crowd time; `0` freezes every member. Default 1. */
+    timeScale?: number;
+}
+/**
+ * Renders many animated copies of one rigged model in a single instanced draw per material: the
+ * rig's clips are baked to a bone-matrix texture once, and each instance samples its own clip, time
+ * offset and speed on the GPU. For crowds, spectators and distant NPCs; a character that needs
+ * blending, IK or attachments stays an entity model.
+ */
+export declare function SkinnedInstances({ url, instances, clips, once, fps, modelScale, castShadow, receiveShadow, timeScale, }: SkinnedInstancesProps): import("react").JSX.Element;

package/dist/render/SkinnedInstances.js

@@ -0,0 +1,249 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame, useLoader } from "@react-three/fiber";
+import { useEffect, useLayoutEffect, useMemo } from "react";
+import * as THREE from "three";
+import { mergeGeometries } from "three/examples/jsm/utils/BufferGeometryUtils.js";
+import { clone as cloneSkinned } from "three/examples/jsm/utils/SkeletonUtils.js";
+import { planBoneTexture } from "@jgengine/core/anim/boneTexture";
+import { sharedGltfLoader } from "./modelLoad.js";
+function slotFor(slots, bone, inverse) {
+    const found = slots.findIndex((slot) => slot.bone === bone && slot.inverse.equals(inverse));
+    if (found >= 0)
+        return found;
+    slots.push({ bone, inverse: inverse.clone() });
+    return slots.length - 1;
+}
+function firstMaterial(material) {
+    return Array.isArray(material) ? material[0] : material;
+}
+/**
+ * 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.
+ */
+export function bakeSkinnedCrowd(source, options = {}) {
+    const root = cloneSkinned(source.scene);
+    root.position.set(0, 0, 0);
+    root.quaternion.identity();
+    root.scale.set(1, 1, 1);
+    root.updateMatrixWorld(true);
+    const meshes = [];
+    root.traverse((object) => {
+        if (object.isSkinnedMesh === true)
+            meshes.push(object);
+    });
+    if (meshes.length === 0)
+        throw new Error("bakeSkinnedCrowd: the source has no skinned mesh");
+    const slots = [];
+    const geometries = [];
+    const materials = [];
+    for (const mesh of meshes) {
+        const source = mesh.geometry;
+        const geometry = new THREE.BufferGeometry();
+        geometry.setAttribute("position", source.getAttribute("position").clone());
+        if (source.getAttribute("normal") !== undefined)
+            geometry.setAttribute("normal", source.getAttribute("normal").clone());
+        else
+            geometry.setAttribute("normal", new THREE.Float32BufferAttribute(new Float32Array(source.getAttribute("position").count * 3), 3));
+        const uv = source.getAttribute("uv");
+        geometry.setAttribute("uv", uv !== undefined ? uv.clone() : new THREE.Float32BufferAttribute(new Float32Array(source.getAttribute("position").count * 2), 2));
+        if (source.index !== null)
+            geometry.setIndex(source.index.clone());
+        geometry.applyMatrix4(mesh.bindMatrix);
+        const skinIndex = source.getAttribute("skinIndex");
+        const skinWeight = source.getAttribute("skinWeight");
+        const remapped = new Float32Array(skinIndex.count * 4);
+        const weights = new Float32Array(skinWeight.count * 4);
+        const bySkeletonIndex = mesh.skeleton.bones.map((bone, i) => slotFor(slots, bone, mesh.skeleton.boneInverses[i]));
+        for (let v = 0; v < skinIndex.count; v += 1) {
+            for (let c = 0; c < 4; c += 1) {
+                remapped[v * 4 + c] = bySkeletonIndex[skinIndex.getComponent(v, c)] ?? 0;
+                weights[v * 4 + c] = skinWeight.getComponent(v, c);
+            }
+        }
+        geometry.setAttribute("skinIndex", new THREE.Float32BufferAttribute(remapped, 4));
+        geometry.setAttribute("skinWeight", new THREE.Float32BufferAttribute(weights, 4));
+        geometries.push(geometry);
+        materials.push(firstMaterial(mesh.material));
+    }
+    const geometry = mergeGeometries(geometries, true);
+    for (const part of geometries)
+        part.dispose();
+    if (geometry === null)
+        throw new Error("bakeSkinnedCrowd: could not merge the rig's meshes");
+    geometry.computeBoundingBox();
+    geometry.computeBoundingSphere();
+    const names = options.clips ?? source.animations.map((clip) => clip.name);
+    const clips = names.map((name) => {
+        const clip = THREE.AnimationClip.findByName(source.animations, name);
+        if (clip === null)
+            throw new Error(`bakeSkinnedCrowd: no clip named "${name}"`);
+        return clip;
+    });
+    const layout = planBoneTexture({
+        boneCount: slots.length,
+        clips: clips.map((clip) => ({ name: clip.name, duration: clip.duration })),
+        fps: options.fps,
+        maxTextureSize: options.maxTextureSize,
+    });
+    const data = new Float32Array(layout.width * layout.height * 4);
+    const mixer = new THREE.AnimationMixer(root);
+    const rootInverse = root.matrixWorld.clone().invert();
+    const matrix = new THREE.Matrix4();
+    clips.forEach((clip, clipIndex) => {
+        const baked = layout.clips[clipIndex];
+        const action = mixer.clipAction(clip);
+        action.play();
+        for (let frame = 0; frame < baked.frameCount; frame += 1) {
+            action.time = Math.min(frame / layout.fps, clip.duration);
+            mixer.update(0);
+            root.updateMatrixWorld(true);
+            const rowOffset = (baked.startFrame + frame) * layout.width * 4;
+            slots.forEach((slot, s) => {
+                matrix.multiplyMatrices(rootInverse, slot.bone.matrixWorld).multiply(slot.inverse);
+                data.set(matrix.elements, rowOffset + s * 16);
+            });
+        }
+        action.stop();
+    });
+    mixer.uncacheRoot(root);
+    const texture = new THREE.DataTexture(data, layout.width, layout.height, THREE.RGBAFormat, THREE.FloatType);
+    texture.minFilter = THREE.NearestFilter;
+    texture.magFilter = THREE.NearestFilter;
+    texture.generateMipmaps = false;
+    texture.needsUpdate = true;
+    const once = new Set(options.once ?? []);
+    return {
+        geometry,
+        materials,
+        texture,
+        layout,
+        loops: layout.clips.map((clip) => !once.has(clip.name)),
+        clipIndex: new Map(layout.clips.map((clip, index) => [clip.name, index])),
+        dispose() {
+            geometry.dispose();
+            texture.dispose();
+        },
+    };
+}
+/** Builds the uniforms a crowd material reads: the texture and per-clip start, frames, fps and loop. */
+export function createCrowdUniforms(baked) {
+    return {
+        crowdBones: { value: baked.texture },
+        crowdTime: { value: 0 },
+        crowdClips: {
+            value: baked.layout.clips.map((clip, index) => new THREE.Vector4(clip.startFrame, clip.frameCount, baked.layout.fps, baked.loops[index] ? 1 : 0)),
+        },
+    };
+}
+const CROWD_HEADER = /* glsl */ `
+uniform highp sampler2D crowdBones;
+uniform float crowdTime;
+uniform vec4 crowdClips[CROWD_CLIP_COUNT];
+attribute vec4 skinIndex;
+attribute vec4 skinWeight;
+attribute vec3 crowdPlay;
+mat4 crowdMatrix;
+bool crowdReady = false;
+mat4 crowdBone(float slot, float row) {
+  int x = int(slot + 0.5) * 4;
+  int y = int(row + 0.5);
+  return mat4(
+    texelFetch(crowdBones, ivec2(x, y), 0),
+    texelFetch(crowdBones, ivec2(x + 1, y), 0),
+    texelFetch(crowdBones, ivec2(x + 2, y), 0),
+    texelFetch(crowdBones, ivec2(x + 3, y), 0));
+}
+mat4 crowdSkin() {
+  if (crowdReady) return crowdMatrix;
+  vec4 clip = crowdClips[int(crowdPlay.x + 0.5)];
+  float span = clip.y - 1.0;
+  float raw = (crowdTime * crowdPlay.z + crowdPlay.y) * clip.z;
+  float frame = clip.w > 0.5 ? mod(raw, span) : clamp(raw, 0.0, span);
+  float a = floor(frame);
+  float t = frame - a;
+  float rowA = clip.x + a;
+  float rowB = clip.x + min(a + 1.0, span);
+  crowdMatrix = mat4(0.0);
+  for (int i = 0; i < 4; i++) {
+    float w = skinWeight[i];
+    if (w > 0.0) crowdMatrix += w * ((1.0 - t) * crowdBone(skinIndex[i], rowA) + t * crowdBone(skinIndex[i], rowB));
+  }
+  crowdReady = true;
+  return crowdMatrix;
+}
+`;
+/**
+ * Patches a material so each instance skins itself from the crowd texture: per-instance `crowdPlay`
+ * is (clip index, time offset, speed). Works on any built-in material, the depth material for
+ * shadows included.
+ */
+export function patchCrowdMaterial(material, uniforms) {
+    const clipCount = Math.max(1, uniforms.crowdClips.value.length);
+    material.onBeforeCompile = (shader) => {
+        Object.assign(shader.uniforms, uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", `#include <common>\n#define CROWD_CLIP_COUNT ${clipCount}\n${CROWD_HEADER}`)
+            .replace("#include <beginnormal_vertex>", "#include <beginnormal_vertex>\nobjectNormal = mat3(crowdSkin()) * objectNormal;")
+            .replace("#include <begin_vertex>", "#include <begin_vertex>\ntransformed = (crowdSkin() * vec4(transformed, 1.0)).xyz;");
+    };
+    material.customProgramCacheKey = () => `jg-crowd-${clipCount}`;
+    return material;
+}
+const scratchMatrix = new THREE.Matrix4();
+const scratchQuaternion = new THREE.Quaternion();
+const scratchPosition = new THREE.Vector3();
+const scratchScale = new THREE.Vector3();
+/**
+ * Renders many animated copies of one rigged model in a single instanced draw per material: the
+ * rig's clips are baked to a bone-matrix texture once, and each instance samples its own clip, time
+ * offset and speed on the GPU. For crowds, spectators and distant NPCs; a character that needs
+ * blending, IK or attachments stays an entity model.
+ */
+export function SkinnedInstances({ url, instances, clips, once, fps, modelScale = 1, castShadow = true, receiveShadow = true, timeScale = 1, }) {
+    const gltf = useLoader(sharedGltfLoader, url);
+    const clipKey = clips?.join("\u0000");
+    const onceKey = once?.join("\u0000");
+    const baked = useMemo(() => bakeSkinnedCrowd({ scene: gltf.scene, animations: gltf.animations }, { clips, once, fps }), [gltf, clipKey, onceKey, fps]);
+    useEffect(() => () => baked.dispose(), [baked]);
+    const uniforms = useMemo(() => createCrowdUniforms(baked), [baked]);
+    const materials = useMemo(() => baked.materials.map((material) => patchCrowdMaterial(material.clone(), uniforms)), [baked, uniforms]);
+    const depthMaterial = useMemo(() => patchCrowdMaterial(new THREE.MeshDepthMaterial({ depthPacking: THREE.RGBADepthPacking }), uniforms), [uniforms]);
+    useEffect(() => () => {
+        for (const material of materials)
+            material.dispose();
+        depthMaterial.dispose();
+    }, [materials, depthMaterial]);
+    const capacity = Math.max(1, instances.length);
+    const mesh = useMemo(() => {
+        const instanced = new THREE.InstancedMesh(baked.geometry, materials, capacity);
+        instanced.customDepthMaterial = depthMaterial;
+        instanced.geometry.setAttribute("crowdPlay", new THREE.InstancedBufferAttribute(new Float32Array(capacity * 3), 3));
+        return instanced;
+    }, [baked, materials, depthMaterial, capacity]);
+    useEffect(() => () => {
+        mesh.dispose();
+    }, [mesh]);
+    useLayoutEffect(() => {
+        const play = mesh.geometry.getAttribute("crowdPlay");
+        instances.forEach((instance, i) => {
+            const scale = (instance.scale ?? 1) * modelScale;
+            scratchQuaternion.setFromAxisAngle(THREE.Object3D.DEFAULT_UP, instance.rotationY ?? 0);
+            scratchMatrix.compose(scratchPosition.set(instance.position[0], instance.position[1], instance.position[2]), scratchQuaternion, scratchScale.set(scale, scale, scale));
+            mesh.setMatrixAt(i, scratchMatrix);
+            play.setXYZ(i, baked.clipIndex.get(instance.clip) ?? 0, instance.timeOffset ?? 0, instance.speed ?? 1);
+        });
+        mesh.count = instances.length;
+        mesh.instanceMatrix.needsUpdate = true;
+        play.needsUpdate = true;
+        mesh.computeBoundingSphere();
+        // Poses reach past the bind-pose bounds (arms out, a lunge), so pad the cull sphere.
+        if (mesh.boundingSphere !== null)
+            mesh.boundingSphere.radius += (baked.geometry.boundingSphere?.radius ?? 0) * modelScale;
+    }, [mesh, instances, baked, modelScale]);
+    useFrame((_three, delta) => {
+        uniforms.crowdTime.value += delta * timeScale;
+    });
+    return _jsx("primitive", { object: mesh, castShadow: castShadow, receiveShadow: receiveShadow });
+}

package/dist/render/TextureFiltering.d.ts

@@ -0,0 +1,16 @@
+import * as THREE from "three";
+/**
+ * Retune already-loaded textures that still carry the old default anisotropy. Textures a
+ * system set on purpose (pixel-art sprites pin 1) keep their value.
+ * @internal
+ */
+export declare function retuneTextureAnisotropy(root: THREE.Object3D, from: number, to: number): number;
+/**
+ * Applies the player's texture-filtering choice. Sets three's construction-time default so
+ * every texture loaded afterwards (GLTF, texture loaders) samples anisotropically, and walks the
+ * scene once per change for textures loaded before. No per-frame work.
+ * @internal shell-internal; driven by `GraphicsProfile.anisotropy`.
+ */
+export declare function TextureFiltering({ anisotropy }: {
+    anisotropy: number;
+}): null;