@jgengine/shell 0.18.1 → 0.19.0

package/dist/postfx/stylizePass.d.ts

@@ -0,0 +1,23 @@
+import * as THREE from "three";
+import { Pass } from "three-stdlib";
+import type { StylizeConfig } from "@jgengine/core/render/postProcessing";
+/**
+ * Art-style post pass: ink outlines from a normal+depth prepass, cel luminance bands, and
+ * pixelation. Runs on the display-space frame after `OutputPass`. The prepass renders only
+ * when outlines are on, and reuses the frame's shadow maps instead of re-rendering them.
+ */
+export declare class StylizePass extends Pass {
+    private readonly scene;
+    private readonly camera;
+    private readonly quad;
+    private readonly material;
+    private readonly normalTarget;
+    private readonly normalMaterial;
+    private readonly hidden;
+    private readonly clearColor;
+    constructor(scene: THREE.Scene, camera: THREE.Camera, config: StylizeConfig);
+    setSize(width: number, height: number): void;
+    render(renderer: THREE.WebGLRenderer, writeBuffer: THREE.WebGLRenderTarget, readBuffer: THREE.WebGLRenderTarget): void;
+    private renderPrepass;
+    dispose(): void;
+}

package/dist/postfx/stylizePass.js

@@ -0,0 +1,216 @@
+import * as THREE from "three";
+import { FullScreenQuad, Pass } from "three-stdlib";
+import { isPostfxOverlay } from "./postfxOverlay.js";
+const DEFAULT_OUTLINE_COLOR = "#101014";
+const DEFAULT_DEPTH_THRESHOLD = 0.08;
+const DEFAULT_NORMAL_THRESHOLD = 0.35;
+const DEFAULT_FADE_DISTANCE = 160;
+const fragmentShader = /* glsl */ `
+  #include <packing>
+  uniform sampler2D tDiffuse;
+  uniform sampler2D tNormal;
+  uniform sampler2D tDepth;
+  uniform vec2 uResolution;
+  uniform float uNear;
+  uniform float uFar;
+  uniform bool uOrtho;
+  uniform bool uOutline;
+  uniform vec3 uOutlineColor;
+  uniform float uOutlineOpacity;
+  uniform float uThickness;
+  uniform float uDepthThreshold;
+  uniform float uNormalThreshold;
+  uniform float uFade;
+  uniform float uBands;
+  uniform float uPixel;
+  varying vec2 vUv;
+
+  float viewDepth(vec2 uv) {
+    float d = texture2D(tDepth, uv).x;
+    return -(uOrtho ? orthographicDepthToViewZ(d, uNear, uFar) : perspectiveDepthToViewZ(d, uNear, uFar));
+  }
+
+  vec3 viewNormal(vec2 uv) {
+    return texture2D(tNormal, uv).xyz * 2.0 - 1.0;
+  }
+
+  // Ink a normal crease only on its nearer side, so a thin or tiny feature stays one line wide
+  // instead of stamping a plus-shaped blot onto the surface behind it.
+  float crease(vec3 nc, float dc, vec2 uv, float dn) {
+    return (1.0 - dot(nc, viewNormal(uv))) * step(dc, dn + dc * 0.02);
+  }
+
+  void main() {
+    vec2 uv = vUv;
+    if (uPixel > 1.0) {
+      vec2 block = uPixel / uResolution;
+      uv = (floor(uv / block) + 0.5) * block;
+    }
+    vec3 c = texture2D(tDiffuse, uv).rgb;
+
+    if (uBands > 0.5) {
+      float luma = dot(c, vec3(0.2126, 0.7152, 0.0722));
+      float x = min(luma * uBands, uBands - 0.001);
+      // Each band takes its centre brightness: the darkest band keeps colour instead of going black
+      // and the top band never clips a bright sky to flat white. A narrow soft step hides aliasing.
+      float q = (floor(x) + 0.5 + smoothstep(0.92, 1.0, fract(x))) / uBands;
+      c *= q / max(luma, 1e-4);
+    }
+
+    if (uOutline) {
+      vec2 px = uThickness / uResolution;
+      float dc = viewDepth(uv);
+      float dl = viewDepth(uv - vec2(px.x, 0.0));
+      float dr = viewDepth(uv + vec2(px.x, 0.0));
+      float dd = viewDepth(uv - vec2(0.0, px.y));
+      float du = viewDepth(uv + vec2(0.0, px.y));
+      // Laplacian is zero across flat planes at any angle, so only real depth breaks draw lines.
+      float lap = abs(dl + dr + dd + du - 4.0 * dc) / max(dc, 1e-3);
+      float nearest = min(dc, min(min(dl, dr), min(dd, du)));
+      // Same nearer-side rule as creases: the background around a silhouette stays clean.
+      float depthEdge = smoothstep(uDepthThreshold, uDepthThreshold * 2.0, lap) * step(dc, nearest + dc * 0.03);
+
+      vec3 nc = viewNormal(uv);
+      float nd = max(
+        max(crease(nc, dc, uv - vec2(px.x, 0.0), dl), crease(nc, dc, uv + vec2(px.x, 0.0), dr)),
+        max(crease(nc, dc, uv - vec2(0.0, px.y), dd), crease(nc, dc, uv + vec2(0.0, px.y), du))
+      );
+      float normalEdge = smoothstep(uNormalThreshold, uNormalThreshold + 0.25, nd);
+
+      float fade = 1.0 - smoothstep(uFade * 0.5, uFade, nearest);
+      float edge = max(depthEdge, normalEdge) * fade * uOutlineOpacity;
+      c = mix(c, uOutlineColor, clamp(edge, 0.0, 1.0));
+    }
+
+    gl_FragColor = vec4(c, 1.0);
+  }
+`;
+const vertexShader = /* glsl */ `
+  varying vec2 vUv;
+  void main() {
+    vUv = uv;
+    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+  }
+`;
+function skipsDepthPrepass(material) {
+    const list = Array.isArray(material) ? material : [material];
+    // Shader materials place vertices in their own code, which the override material cannot reproduce.
+    return list.some((m) => m.transparent || m.alphaTest > 0 || !m.depthWrite || !m.colorWrite || m.isShaderMaterial === true);
+}
+/**
+ * Hide what the outline prepass must not see: marked overlays, points/lines/sprites, custom
+ * shader meshes, and transparent or alpha-cut meshes (foliage cards would otherwise outline as
+ * solid quads).
+ */
+function hideForPrepass(scene, out) {
+    out.length = 0;
+    scene.traverse((object) => {
+        if (!object.visible)
+            return;
+        const drawable = object;
+        const hide = isPostfxOverlay(object) ||
+            object.isPoints === true ||
+            object.isLine === true ||
+            object.isSprite === true ||
+            (drawable.isMesh === true && skipsDepthPrepass(drawable.material));
+        if (!hide)
+            return;
+        object.visible = false;
+        out.push(object);
+    });
+}
+/**
+ * Art-style post pass: ink outlines from a normal+depth prepass, cel luminance bands, and
+ * pixelation. Runs on the display-space frame after `OutputPass`. The prepass renders only
+ * when outlines are on, and reuses the frame's shadow maps instead of re-rendering them.
+ */
+export class StylizePass extends Pass {
+    scene;
+    camera;
+    quad;
+    material;
+    normalTarget;
+    normalMaterial = new THREE.MeshNormalMaterial();
+    hidden = [];
+    clearColor = new THREE.Color();
+    constructor(scene, camera, config) {
+        super();
+        this.scene = scene;
+        this.camera = camera;
+        const outline = config.outline === undefined || config.outline === false ? null : config.outline;
+        this.normalTarget = outline === null
+            ? null
+            : new THREE.WebGLRenderTarget(1, 1, { depthTexture: new THREE.DepthTexture(1, 1), type: THREE.UnsignedByteType });
+        this.material = new THREE.ShaderMaterial({
+            uniforms: {
+                tDiffuse: { value: null },
+                tNormal: { value: this.normalTarget?.texture ?? null },
+                tDepth: { value: this.normalTarget?.depthTexture ?? null },
+                uResolution: { value: new THREE.Vector2(1, 1) },
+                uNear: { value: 0.1 },
+                uFar: { value: 1000 },
+                uOrtho: { value: false },
+                uOutline: { value: outline !== null },
+                uOutlineColor: { value: new THREE.Color(outline?.color ?? DEFAULT_OUTLINE_COLOR) },
+                uOutlineOpacity: { value: outline?.opacity ?? 1 },
+                uThickness: { value: Math.max(0.5, outline?.thickness ?? 1) },
+                uDepthThreshold: { value: outline?.depthThreshold ?? DEFAULT_DEPTH_THRESHOLD },
+                uNormalThreshold: { value: outline?.normalThreshold ?? DEFAULT_NORMAL_THRESHOLD },
+                uFade: { value: outline?.fadeDistance ?? DEFAULT_FADE_DISTANCE },
+                uBands: { value: Math.max(0, Math.floor(config.bands ?? 0)) },
+                uPixel: { value: Math.max(0, config.pixelSize ?? 0) },
+            },
+            vertexShader,
+            fragmentShader,
+            depthTest: false,
+            depthWrite: false,
+        });
+        this.quad = new FullScreenQuad(this.material);
+    }
+    setSize(width, height) {
+        this.material.uniforms.uResolution.value.set(width, height);
+        this.normalTarget?.setSize(width, height);
+    }
+    render(renderer, writeBuffer, readBuffer) {
+        const uniforms = this.material.uniforms;
+        if (this.normalTarget !== null)
+            this.renderPrepass(renderer, this.normalTarget);
+        const camera = this.camera;
+        uniforms.uNear.value = camera.near;
+        uniforms.uFar.value = camera.far;
+        uniforms.uOrtho.value = camera.isOrthographicCamera === true;
+        uniforms.tDiffuse.value = readBuffer.texture;
+        renderer.setRenderTarget(this.renderToScreen ? null : writeBuffer);
+        this.quad.render(renderer);
+    }
+    renderPrepass(renderer, target) {
+        const scene = this.scene;
+        const previousOverride = scene.overrideMaterial;
+        const previousBackground = scene.background;
+        const previousShadowUpdate = renderer.shadowMap.autoUpdate;
+        const previousClearAlpha = renderer.getClearAlpha();
+        renderer.getClearColor(this.clearColor);
+        hideForPrepass(scene, this.hidden);
+        scene.overrideMaterial = this.normalMaterial;
+        scene.background = null;
+        renderer.shadowMap.autoUpdate = false;
+        renderer.setRenderTarget(target);
+        renderer.setClearColor(0x8080ff, 1);
+        renderer.clear();
+        renderer.render(scene, this.camera);
+        renderer.setClearColor(this.clearColor, previousClearAlpha);
+        renderer.shadowMap.autoUpdate = previousShadowUpdate;
+        scene.background = previousBackground;
+        scene.overrideMaterial = previousOverride;
+        for (const object of this.hidden)
+            object.visible = true;
+        this.hidden.length = 0;
+    }
+    dispose() {
+        this.material.dispose();
+        this.normalMaterial.dispose();
+        this.quad.dispose();
+        this.normalTarget?.depthTexture?.dispose();
+        this.normalTarget?.dispose();
+    }
+}

package/dist/render/SceneModels.js

@@ -218,7 +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);
+    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;

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;
+}