@jgengine/shell 0.18.1 → 0.21.0

package/dist/render/SceneModels.js

@@ -1,20 +1,25 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useFrame, useLoader } from "@react-three/fiber";
-import { useTexture } from "@react-three/drei";
-import { Component, Suspense, useEffect, useMemo, useRef } from "react";
+import { useFrame, useLoader, useThree } from "@react-three/fiber";
+import { Component, Suspense, useCallback, useEffect, useLayoutEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
+import { parseModelHiddenNodes } from "@jgengine/core/editor/modelNodeVisibility";
 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 { detectKtx2Support, sharedGltfLoader } from "./modelLoad.js";
+import { modelAssetRequests } from "./modelAssets.js";
 import { measureLocalBounds, reportMeasuredBounds } from "./measureBounds.js";
 import { measureLocalCollisionTriangles, reportMeasuredCollisionMesh } from "./measureCollisionMesh.js";
-import { useModelAnimation } from "./useModelAnimation.js";
+import { useModelInstance } from "./useModelInstance.js";
+import { applyMaterialAssignments, useModelMaterialTextures, MaterialTextureLoader, validateMaterialAssignmentTargets } from "./materialAsset.js";
 import { useFootIk } from "./useFootIk.js";
+import { resolveRigNode } from "./rigNode.js";
 import { PartMotionRig } from "./PartMotion.js";
+import { syncSpriteFrame } from "./spriteRender.js";
 import { applyMaterialOverride } from "../materialOverride.js";
-import { applyPaintTextureToMaterials, cacheStandardMaterials, cloneModelScene, createPaintCanvas, disposeClonedMaterials, disposePaintCanvas, syncPaintCanvas, } from "./modelRender.js";
+import { applyPaintTextureToMaterials, cacheStandardMaterials, cloneModelScene, createPaintCanvas, disposeModelScene, ownModelMaterial, disposePaintCanvas, syncPaintCanvas, } from "./modelRender.js";
 export function EntitySprite({ sprite }) {
+    const invalidate = useThree((state) => state.invalidate);
     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]);
@@ -28,7 +33,11 @@ export function EntitySprite({ sprite }) {
     useEffect(() => {
         if (player !== null && animation !== undefined)
             player.play(animation);
-    }, [player, animation]);
+        const frame = player?.frame();
+        if (frame !== undefined && sprite.clip !== undefined)
+            syncSpriteFrame(map, frame, sprite.clip.atlas.size);
+        invalidate();
+    }, [player, animation, map, sprite.clip, invalidate]);
     useFrame((_state, delta) => {
         if (player === null || sprite.clip === undefined)
             return;
@@ -36,10 +45,7 @@ export function EntitySprite({ sprite }) {
         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;
+        syncSpriteFrame(map, frame, sprite.clip.atlas.size);
     });
     useEffect(() => {
         if (player === null) {
@@ -97,13 +103,14 @@ function BoneAttachment({ rig, model, slot, position, rotation, scale, }) {
     const rz = rotation?.[2] ?? 0;
     const s = scale ?? 1;
     useEffect(() => {
-        const bone = rig.getObjectByName(slot);
-        if (bone === undefined) {
+        const resolved = resolveRigNode(rig, slot);
+        if (resolved.node === undefined) {
             if (typeof console !== "undefined") {
-                console.warn(`[jgengine] entityModels attachment: bone/slot "${slot}" not found on the rig`);
+                console.warn(`[jgengine] entityModels attachment: ${resolved.diagnostic.message}`);
             }
             return;
         }
+        const bone = resolved.node;
         weaponScene.position.set(px, py, pz);
         weaponScene.rotation.set(rx, ry, rz);
         weaponScene.scale.setScalar(s);
@@ -112,80 +119,47 @@ function BoneAttachment({ rig, model, slot, position, rotation, scale, }) {
             bone.remove(weaponScene);
         };
     }, [rig, weaponScene, slot, px, py, pz, rx, ry, rz, s]);
-    useEffect(() => () => disposeClonedMaterials(weaponScene), [weaponScene]);
+    useEffect(() => () => disposeModelScene(weaponScene), [weaponScene]);
     return null;
 }
 /** Renders a static kit-of-parts child at a fixed local offset under the parent model — no bone/rig lookup, unlike `BoneAttachment`. The nested `EntityModel` still applies its own `dims`/anchor centering, so scale/pivot sanity carries over per part. */
 function ModelPartGroup({ model, position, rotation, scale, }) {
     return (_jsx("group", { position: position ?? [0, 0, 0], rotation: rotation ?? [0, 0, 0], scale: scale ?? 1, children: _jsx(IsolatedModelPart, { model: model, children: _jsx(EntityModel, { model: model }) }) }));
 }
-function ModelMaterialMapsApplier({ scene, maps }) {
-    const entries = useMemo(() => {
-        const record = {};
-        if (maps.color !== undefined)
-            record.color = maps.color;
-        if (maps.normal !== undefined)
-            record.normal = maps.normal;
-        if (maps.roughness !== undefined)
-            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.metalness, maps.emissive, maps.height]);
-    const textures = useTexture(entries);
-    useEffect(() => {
-        if (textures.color !== undefined)
-            textures.color.colorSpace = THREE.SRGBColorSpace;
-        applyMaterialOverride(scene, {}, { clone: false, textures });
-    }, [scene, textures]);
-    return null;
-}
 export function EntityModel({ model, instanceId, measure, }) {
-    const gltf = useLoader(sharedGltfLoader, model.url);
+    parseModelHiddenNodes(model.hiddenNodes);
+    const renderer = useThree(state => state.gl);
+    if (renderer.isWebGLRenderer)
+        detectKtx2Support(renderer);
+    const assets = modelAssetRequests(model);
+    for (const url of assets.models)
+        useLoader.preload(sharedGltfLoader, url);
     // Optional, not required: measured bounds and paint strokes are live-world extras, and a model
     // that threw without a running game could not be inspected outside one — which is how a broken
     // composition stayed undiagnosable in `EntityPreview` (#1588).
     const ctx = useOptionalGameContext();
     const material = model.material;
+    const materialAssetKey = JSON.stringify((model.materialAssets ?? []).filter(asset => model.materialAssignments?.some(assignment => assignment.materialId === asset.id)));
+    const materialAssets = useMemo(() => (model.materialAssets ?? []).filter(asset => model.materialAssignments?.some(assignment => assignment.materialId === asset.id)), [materialAssetKey]);
+    const materialAssignments = model.materialAssignments;
+    const assignmentSource = useLoader(sharedGltfLoader, materialAssignments?.length ? [model.url] : [])[0]?.scene;
+    const assignmentKey = JSON.stringify(materialAssignments);
+    useMemo(() => {
+        if (assignmentSource !== undefined)
+            validateMaterialAssignmentTargets(assignmentSource, materialAssets, materialAssignments, { baseAlphaMode: material?.alphaMode });
+    }, [assignmentSource, materialAssets, assignmentKey, material?.alphaMode]);
+    for (const urls of assets.textureGroups)
+        useLoader.preload(MaterialTextureLoader, urls);
+    const materialTextures = useModelMaterialTextures(model);
     const baseY = model.y ?? 0;
     const dims = model.dims;
-    const shadows = model.shadows;
-    const scene = useMemo(() => {
-        const cloned = cloneModelScene(gltf.scene, { shadows });
+    const configure = useCallback((content) => {
         if (material !== undefined)
-            applyMaterialOverride(cloned, material, { clone: false });
-        return cloned;
-    }, [gltf, material, shadows]);
-    const measured = useMemo(() => {
-        if (model.targetHeight === undefined)
-            return null;
-        const box = new THREE.Box3().setFromObject(scene);
-        const height = box.max.y - box.min.y;
-        if (!Number.isFinite(height) || height <= 0)
-            return null;
-        return {
-            normalize: model.targetHeight / height,
-            minY: box.min.y,
-            centerX: (box.min.x + box.max.x) / 2,
-            centerZ: (box.min.z + box.max.z) / 2,
-        };
-    }, [scene, model.targetHeight]);
-    const scale = (model.scale ?? 1) * (measured?.normalize ?? 1);
-    const centered = (model.anchor ?? "center") === "center" && dims !== undefined;
-    const position = measured !== null
-        ? [-scale * measured.centerX, baseY - scale * measured.minY, -scale * measured.centerZ]
-        : centered
-            ? [-scale * dims.center.x, baseY - scale * dims.minY, -scale * dims.center.z]
-            : [0, baseY, 0];
-    useEffect(() => () => {
-        disposeClonedMaterials(scene);
-    }, [scene]);
+            applyMaterialOverride(content, material, { clone: false, textures: materialTextures.global, ownMaterial: replacement => ownModelMaterial(content, replacement) });
+        if (materialAssignments !== undefined)
+            applyMaterialAssignments(content, materialAssets ?? [], materialAssignments, materialTextures.assets);
+    }, [material, materialTextures, materialAssets, materialAssignments]);
+    const { scene, scale, position } = useModelInstance(model, { instanceId, configure });
     // A model without index-measured dims can't drive the fitted-collider path, so report the live
     // measurement (the primitive mounts with only this uniform scale + position) instead of letting
     // the kind fall back to a fixed-size box. Index dims keep priority — skip when they exist.
@@ -193,7 +167,8 @@ export function EntityModel({ model, instanceId, measure, }) {
     const measureKey = measure?.key;
     const dimsMaxY = dims?.maxY;
     const [positionX, positionY, positionZ] = position;
-    useEffect(() => {
+    // Measure before the instance hook's passive animation effects can move imported root nodes.
+    useLayoutEffect(() => {
         if (ctx === null || measureTarget === undefined || measureKey === undefined || dimsMaxY !== undefined)
             return;
         const raw = measureLocalBounds(scene);
@@ -207,7 +182,7 @@ export function EntityModel({ model, instanceId, measure, }) {
     }, [ctx, scene, scale, positionX, positionY, positionZ, measureTarget, measureKey, dimsMaxY]);
     // Runs with or without index dims: the loaded geometry upgrades whatever box the kind resolved
     // (fitted or measured) to a hitbox that raycasts the model's own triangles.
-    useEffect(() => {
+    useLayoutEffect(() => {
         if (ctx === null || measureTarget === undefined || measureKey === undefined)
             return;
         const triangles = measureLocalCollisionTriangles(scene, {
@@ -217,8 +192,7 @@ export function EntityModel({ model, instanceId, measure, }) {
         if (triangles !== null)
             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);
+    useFootIk(scene, model.ik, ctx, instanceId, baseY);
     const paintCanvasRef = useRef(null);
     const paintDrawnCountRef = useRef(0);
     const paintVersionRef = useRef(-1);
@@ -255,7 +229,7 @@ export function EntityModel({ model, instanceId, measure, }) {
         }
         paintDrawnCountRef.current = syncPaintCanvas(paintCanvasRef.current, cache.seedColor, strokes, paintDrawnCountRef.current);
     });
-    const base = (_jsxs(_Fragment, { children: [_jsx("primitive", { object: scene, position: position, scale: [scale, scale, scale] }), material?.maps !== undefined ? (_jsx(IsolatedModelPart, { model: model, children: _jsx(ModelMaterialMapsApplier, { scene: scene, maps: material.maps }) })) : null, (model.attachments ?? []).map((attachment, index) => typeof attachment.model === "string" ? null : (_jsx(IsolatedModelPart, { model: attachment.model, children: _jsx(BoneAttachment, { rig: scene, model: attachment.model, slot: attachment.slot, position: attachment.position, rotation: attachment.rotation, scale: attachment.scale }) }, `${attachment.slot}-${index}`)))] }));
+    const base = (_jsxs(_Fragment, { children: [_jsx("primitive", { object: scene, position: position, scale: [scale, scale, scale] }), (model.attachments ?? []).map((attachment, index) => typeof attachment.model === "string" ? null : (_jsx(IsolatedModelPart, { model: attachment.model, children: _jsx(BoneAttachment, { rig: scene, model: attachment.model, slot: attachment.slot, position: attachment.position, rotation: attachment.rotation, scale: attachment.scale }) }, `${attachment.slot}-${index}`)))] }));
     const parts = model.parts ?? [];
     // Any role-tagged part switches the composition onto the procedural part-motion rig:
     // root bob/flinch/topple plus per-role limb swing, driven from the entity's live state.

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;

package/dist/render/TextureFiltering.js

@@ -0,0 +1,64 @@
+import { useThree } from "@react-three/fiber";
+import { useLayoutEffect } from "react";
+import * as THREE from "three";
+const TEXTURE_SLOTS = [
+    "map",
+    "normalMap",
+    "roughnessMap",
+    "metalnessMap",
+    "aoMap",
+    "emissiveMap",
+    "bumpMap",
+    "alphaMap",
+    "displacementMap",
+];
+/**
+ * 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 function retuneTextureAnisotropy(root, from, to) {
+    const seen = new Set();
+    root.traverse((node) => {
+        const mesh = node;
+        if (mesh.material === undefined)
+            return;
+        const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        for (const material of materials) {
+            const slots = material;
+            for (const slot of TEXTURE_SLOTS) {
+                const texture = slots[slot];
+                if (texture === null || texture === undefined || seen.has(texture))
+                    continue;
+                seen.add(texture);
+                if (texture.anisotropy !== from)
+                    continue;
+                texture.anisotropy = to;
+                texture.needsUpdate = true;
+            }
+        }
+    });
+    return seen.size;
+}
+/**
+ * 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 function TextureFiltering({ anisotropy }) {
+    const gl = useThree((state) => state.gl);
+    const scene = useThree((state) => state.scene);
+    useLayoutEffect(() => {
+        const target = Math.max(1, Math.min(anisotropy, gl.capabilities.getMaxAnisotropy()));
+        const previous = THREE.Texture.DEFAULT_ANISOTROPY;
+        if (previous === target)
+            return;
+        THREE.Texture.DEFAULT_ANISOTROPY = target;
+        retuneTextureAnisotropy(scene, previous, target);
+        return () => {
+            THREE.Texture.DEFAULT_ANISOTROPY = previous;
+        };
+    }, [gl, scene, anisotropy]);
+    return null;
+}