@jgengine/shell 0.33.0 → 0.35.0

package/dist/render/SkinnedInstances.js

@@ -6,21 +6,86 @@ 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));
+const IDENTITY = new THREE.Matrix4();
+function slotFor(slots, node, inverse) {
+    const found = slots.findIndex((slot) => slot.node === node && slot.inverse.equals(inverse));
     if (found >= 0)
         return found;
-    slots.push({ bone, inverse: inverse.clone() });
+    slots.push({ node, inverse: inverse.clone() });
     return slots.length - 1;
 }
 function firstMaterial(material) {
     return Array.isArray(material) ? material[0] : material;
 }
+/** Node names any of the clips animate, so a rigid part rides the nearest one that carries it. */
+function animatedNodeNames(clips) {
+    const names = new Set();
+    for (const clip of clips) {
+        for (const track of clip.tracks) {
+            const parsed = THREE.PropertyBinding.parseTrackName(track.name);
+            if (parsed.nodeName !== undefined && parsed.nodeName.length > 0)
+                names.add(parsed.nodeName);
+        }
+    }
+    return names;
+}
+/** The nearest node (self included) a clip moves, or the root when nothing above this mesh is animated. */
+function rigidSlotNode(mesh, root, animated) {
+    let node = mesh;
+    while (node !== null) {
+        if (animated.has(node.name))
+            return node;
+        if (node === root)
+            break;
+        node = node.parent;
+    }
+    return root;
+}
+/** Attribute layout two geometries must agree on before their vertices can share a draw. */
+function layoutKey(geometry) {
+    const parts = [geometry.index === null ? "plain" : "indexed"];
+    for (const name of Object.keys(geometry.attributes).sort()) {
+        const attribute = geometry.attributes[name];
+        parts.push(`${name}:${attribute.itemSize}:${attribute.normalized === true ? 1 : 0}`);
+    }
+    return parts.join(",");
+}
 /**
- * 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.
+ * Flattens an indexed part so every baked geometry shares one attribute set. Bakes happen once per
+ * character kind, and mixed indexed/non-indexed sources (a box plus an icosahedron) would otherwise
+ * refuse to merge into one draw.
+ */
+function flatten(geometry) {
+    if (geometry.index === null)
+        return geometry;
+    const expanded = geometry.toNonIndexed();
+    geometry.dispose();
+    return expanded;
+}
+/** Copies the attributes a batch can draw: the vertex, its normal and its texture coordinate. */
+function bakePart(mesh, relative) {
+    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(relative);
+    return { geometry: flatten(geometry), layout: "", material: firstMaterial(mesh.material) };
+}
+/**
+ * Bakes a rig for {@link SkinnedInstances}: merges its meshes into one geometry per material, samples
+ * every requested clip at `fps`, and writes each slot's model-space matrix into a float texture laid
+ * out by `planBoneTexture`. A skinned mesh contributes its bones as slots; a rig-less part that a
+ * clip moves contributes that node, with its vertices weighted fully to it, so a node-transform
+ * character (a walking miniature with rotating limbs) batches through the same shader. A model with
+ * no clips at all bakes to `animated: false`: one merged geometry per material and no texture.
+ * 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);
@@ -28,59 +93,136 @@ export function bakeSkinnedCrowd(source, options = {}) {
     root.quaternion.identity();
     root.scale.set(1, 1, 1);
     root.updateMatrixWorld(true);
-    const meshes = [];
-    root.traverse((object) => {
-        if (object.isSkinnedMesh === true)
-            meshes.push(object);
+    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;
     });
-    if (meshes.length === 0)
-        throw new Error("bakeSkinnedCrowd: the source has no skinned mesh");
+    const animatedClips = clips.length > 0 ? clips : source.animations;
+    const animatedNames = animatedNodeNames(animatedClips);
+    const rootInverse = root.matrixWorld.clone().invert();
     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);
+    const bounds = new THREE.Box3();
+    const groups = new Map();
+    root.updateMatrixWorld(true);
+    root.traverse((object) => {
+        const mesh = object;
+        if (mesh.isMesh !== true || Array.isArray(mesh.material) || mesh.material === undefined)
+            return;
+        if (Object.keys(mesh.geometry.morphAttributes).length > 0)
+            throw new Error("bakeSkinnedCrowd: the rig has morph targets");
+        if (mesh.geometry.getAttribute("position") === undefined)
+            return;
+        mesh.geometry.computeBoundingBox();
+        if (mesh.geometry.boundingBox !== null)
+            bounds.union(mesh.geometry.boundingBox.clone().applyMatrix4(mesh.matrixWorld));
+        const skinned = mesh;
+        let part;
+        if (skinned.isSkinnedMesh === true) {
+            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(skinned.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 = skinned.skeleton.bones.map((bone, index) => slotFor(slots, bone, skinned.skeleton.boneInverses[index]));
+            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));
+            const flat = flatten(geometry);
+            part = { geometry: flat, layout: layoutKey(flat), material: firstMaterial(mesh.material) };
+        }
+        else {
+            const slotNode = rigidSlotNode(mesh, root, animatedNames);
+            const nodeInverse = slotNode.matrixWorld.clone().invert();
+            const slot = slotFor(slots, slotNode, IDENTITY);
+            const relative = new THREE.Matrix4().multiplyMatrices(nodeInverse, mesh.matrixWorld);
+            part = bakePart(mesh, relative);
+            const count = part.geometry.getAttribute("position").count;
+            const skinIndex = new Float32Array(count * 4);
+            const skinWeight = new Float32Array(count * 4);
+            for (let v = 0; v < count; v += 1) {
+                skinIndex[v * 4] = slot;
+                skinWeight[v * 4] = 1;
+            }
+            part.geometry.setAttribute("skinIndex", new THREE.Float32BufferAttribute(skinIndex, 4));
+            part.geometry.setAttribute("skinWeight", new THREE.Float32BufferAttribute(skinWeight, 4));
+            part.layout = layoutKey(part.geometry);
+        }
+        // Vertices are already in slot space, chosen per vertex by skinIndex, so parts that share a
+        // material and a vertex layout merge into one draw whatever node moves them.
+        const key = `${part.material.uuid}|${part.layout}`;
+        const existing = groups.get(key);
+        if (existing === undefined)
+            groups.set(key, { geometry: part.geometry, material: part.material });
+        else {
+            const merged = mergeGeometries([existing.geometry, part.geometry], false);
+            if (merged === null) {
+                groups.set(`${key}|${groups.size}`, { geometry: part.geometry, material: part.material });
+            }
+            else {
+                existing.geometry.dispose();
+                part.geometry.dispose();
+                existing.geometry = merged;
             }
         }
-        geometry.setAttribute("skinIndex", new THREE.Float32BufferAttribute(remapped, 4));
-        geometry.setAttribute("skinWeight", new THREE.Float32BufferAttribute(weights, 4));
-        geometries.push(geometry);
-        materials.push(firstMaterial(mesh.material));
+    });
+    for (const group of groups.values()) {
+        geometries.push(group.geometry);
+        materials.push(group.material);
+    }
+    if (geometries.length === 0)
+        throw new Error("bakeSkinnedCrowd: the source has no drawable mesh");
+    // The shader transforms a normal by the slot matrix, which is only exact for uniform scale.
+    const scale = new THREE.Vector3();
+    for (const slot of slots) {
+        slot.node.matrixWorld.decompose(new THREE.Vector3(), new THREE.Quaternion(), scale);
+        if (Math.abs(scale.x - scale.y) > 1e-4 || Math.abs(scale.y - scale.z) > 1e-4) {
+            throw new Error("bakeSkinnedCrowd: the rig animates a node with non-uniform scale");
+        }
     }
-    const geometry = mergeGeometries(geometries, true);
-    for (const part of geometries)
-        part.dispose();
+    const geometry = geometries.length === 1 ? geometries[0] : mergeGeometries(geometries, true);
+    if (geometries.length > 1)
+        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;
-    });
+    if (clips.length === 0) {
+        return {
+            geometry,
+            materials,
+            texture: null,
+            layout: null,
+            loops: [],
+            clipIndex: new Map(),
+            animated: false,
+            bounds,
+            dispose() {
+                geometry.dispose();
+            },
+        };
+    }
     const layout = planBoneTexture({
         boneCount: slots.length,
         clips: clips.map((clip) => ({ name: clip.name, duration: clip.duration })),
@@ -89,7 +231,6 @@ export function bakeSkinnedCrowd(source, options = {}) {
     });
     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];
@@ -101,7 +242,7 @@ export function bakeSkinnedCrowd(source, options = {}) {
             root.updateMatrixWorld(true);
             const rowOffset = (baked.startFrame + frame) * layout.width * 4;
             slots.forEach((slot, s) => {
-                matrix.multiplyMatrices(rootInverse, slot.bone.matrixWorld).multiply(slot.inverse);
+                matrix.multiplyMatrices(rootInverse, slot.node.matrixWorld).multiply(slot.inverse);
                 data.set(matrix.elements, rowOffset + s * 16);
             });
         }
@@ -121,6 +262,8 @@ export function bakeSkinnedCrowd(source, options = {}) {
         layout,
         loops: layout.clips.map((clip) => !once.has(clip.name)),
         clipIndex: new Map(layout.clips.map((clip, index) => [clip.name, index])),
+        animated: true,
+        bounds,
         dispose() {
             geometry.dispose();
             texture.dispose();
@@ -129,11 +272,14 @@ export function bakeSkinnedCrowd(source, options = {}) {
 }
 /** Builds the uniforms a crowd material reads: the texture and per-clip start, frames, fps and loop. */
 export function createCrowdUniforms(baked) {
+    const layout = baked.layout;
+    if (baked.texture === null || layout === null)
+        throw new Error("createCrowdUniforms: the rig is static and needs no crowd uniforms");
     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)),
+            value: layout.clips.map((clip, index) => new THREE.Vector4(clip.startFrame, clip.frameCount, layout.fps, baked.loops[index] ? 1 : 0)),
         },
     };
 }
@@ -207,43 +353,47 @@ export function SkinnedInstances({ url, instances, clips, once, fps, modelScale
     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]);
+    const uniforms = useMemo(() => (baked.animated ? createCrowdUniforms(baked) : null), [baked]);
+    const materials = useMemo(() => baked.materials.map((material) => (uniforms === null ? material.clone() : patchCrowdMaterial(material.clone(), uniforms))), [baked, uniforms]);
+    const depthMaterial = useMemo(() => (uniforms === null ? null : patchCrowdMaterial(new THREE.MeshDepthMaterial({ depthPacking: THREE.RGBADepthPacking }), uniforms)), [uniforms]);
     useEffect(() => () => {
         for (const material of materials)
             material.dispose();
-        depthMaterial.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));
+        const instanced = new THREE.InstancedMesh(baked.geometry, materials.length === 1 ? materials[0] : materials, capacity);
+        if (depthMaterial !== null)
+            instanced.customDepthMaterial = depthMaterial;
+        if (uniforms !== null)
+            instanced.geometry.setAttribute("crowdPlay", new THREE.InstancedBufferAttribute(new Float32Array(capacity * 3), 3));
         return instanced;
-    }, [baked, materials, depthMaterial, capacity]);
+    }, [baked, materials, depthMaterial, uniforms, capacity]);
     useEffect(() => () => {
         mesh.dispose();
     }, [mesh]);
     useLayoutEffect(() => {
-        const play = mesh.geometry.getAttribute("crowdPlay");
+        const play = uniforms === null ? null : 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);
+            play?.setXYZ(i, instance.clip === undefined ? 0 : baked.clipIndex.get(instance.clip) ?? 0, instance.timeOffset ?? 0, instance.speed ?? 1);
         });
         mesh.count = instances.length;
         mesh.instanceMatrix.needsUpdate = true;
-        play.needsUpdate = true;
+        if (play !== null)
+            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]);
+    }, [mesh, instances, baked, modelScale, uniforms]);
     useFrame((_three, delta) => {
-        uniforms.crowdTime.value += delta * timeScale;
+        if (uniforms !== null)
+            uniforms.crowdTime.value += delta * timeScale;
     });
     return _jsx("primitive", { object: mesh, castShadow: castShadow, receiveShadow: receiveShadow });
 }

package/dist/render/characterLod.d.ts

@@ -6,6 +6,7 @@ export interface CharacterLodPolicy {
     halfRateDistance: number;
     crowdDistance: number;
     crowdHysteresis: number;
+    crowdCapacity: number;
 }
 /** The engine's default character tiers: full under 15 m, half under 40 m, GPU crowd beyond 25 m. */
 export declare const DEFAULT_CHARACTER_LOD: CharacterLodPolicy;
@@ -22,6 +23,12 @@ export declare function characterLodPolicy(config: ModelLodConfig | undefined):
  * hysteresis, so a character walking along the crowd boundary does not swap representation every frame.
  */
 export declare function characterLodTier(distance: number, config: ModelLodConfig | undefined, previous?: CharacterLodTier): CharacterLodTier;
+/**
+ * The tier a character poses its own rig on, ignoring the crowd path. A crowd character whose batch
+ * is full falls back to this, so an over-cap crowd draws every member on its own rig instead of
+ * dropping the ones past the cap.
+ */
+export declare function characterRigTier(distance: number, config: ModelLodConfig | undefined): CharacterLodTier;
 /** Share of frames a tier poses the rig: 1, 0.5, 0.25, and 0 once the GPU crowd draws it. */
 export declare function characterLodRate(tier: CharacterLodTier): number;
 /** Frames between pose updates for a tier: 1, 2, 4, and `0` meaning "never" for the crowd tier. */

package/dist/render/characterLod.js

@@ -4,6 +4,7 @@ export const DEFAULT_CHARACTER_LOD = {
     halfRateDistance: 40,
     crowdDistance: 25,
     crowdHysteresis: 2,
+    crowdCapacity: 128,
 };
 /**
  * Fills a model's authoring gaps with {@link DEFAULT_CHARACTER_LOD}. A missing, negative or
@@ -17,6 +18,7 @@ export function characterLodPolicy(config) {
         halfRateDistance: finite(config?.halfRateDistance, DEFAULT_CHARACTER_LOD.halfRateDistance),
         crowdDistance: finite(config?.crowdDistance, DEFAULT_CHARACTER_LOD.crowdDistance),
         crowdHysteresis: finite(config?.crowdHysteresis, DEFAULT_CHARACTER_LOD.crowdHysteresis),
+        crowdCapacity: Math.floor(finite(config?.crowdCapacity, DEFAULT_CHARACTER_LOD.crowdCapacity)),
     };
     // Tiers read in order, so a game that sets half below full would otherwise make "full" unreachable.
     policy.halfRateDistance = Math.max(policy.halfRateDistance, policy.fullRateDistance);
@@ -31,6 +33,15 @@ export function characterLodTier(distance, config, previous) {
     const crowdBoundary = previous === "crowd" ? policy.crowdDistance - policy.crowdHysteresis : policy.crowdDistance;
     if (distance >= crowdBoundary)
         return "crowd";
+    return characterRigTier(distance, config);
+}
+/**
+ * The tier a character poses its own rig on, ignoring the crowd path. A crowd character whose batch
+ * is full falls back to this, so an over-cap crowd draws every member on its own rig instead of
+ * dropping the ones past the cap.
+ */
+export function characterRigTier(distance, config) {
+    const policy = characterLodPolicy(config);
     if (distance < policy.fullRateDistance)
         return "full";
     if (distance < policy.halfRateDistance)

package/dist/render/crowdBatch.d.ts

@@ -0,0 +1,45 @@
+import * as THREE from "three";
+import { type CrowdMember, type CrowdSpeedBands } from "./crowdRegistry.js";
+/** How a batch places every member of one character kind. @internal */
+export interface CrowdBatchPlacement {
+    /** Uniform scale applied to the baked geometry. */
+    scale: number;
+    /** Translation applied after the member's own pose, so the baked rig stands where its own rig would. */
+    offset: THREE.Vector3;
+}
+/** The clip and time offset a batch is playing for one member. @internal */
+export interface CrowdPlayback {
+    clip: number;
+    offset: number;
+}
+/** Everything one frame of a character batch needs. @internal */
+export interface CrowdBatchFrame {
+    mesh: THREE.InstancedMesh;
+    /** Per-instance clip, time offset and speed; `null` for a static character kind. */
+    play: THREE.InstancedBufferAttribute | null;
+    /** Drawn members in batch order, already filtered by visibility. */
+    members: readonly {
+        id: string;
+        member: CrowdMember;
+    }[];
+    placement: CrowdBatchPlacement;
+    /** Baked clip names in `[idle, walk, run]` order. */
+    clips: readonly string[];
+    bands: CrowdSpeedBands;
+    clipIndex: ReadonlyMap<string, number>;
+    /** Seconds of batch time, so a member entering mid-clip continues the pose it was holding. */
+    time: number;
+    /** Per-member playback state, kept across frames; cleared by the caller when the batch unmounts. */
+    playback: Map<string, CrowdPlayback>;
+    /** Ids written into the compacted instance slots, in draw order. */
+    ids: string[];
+}
+/** A stable non-zero time offset for a member with no recorded pose, so a crowd is not in lockstep. */
+export declare function poseTimeOffset(id: string): number;
+/**
+ * Writes one frame of instances for a batch and returns how many it drew. Slots are compacted from
+ * zero every frame and `ids` is truncated to the drawn range, so a character that left the batch or
+ * went out of view never leaves its last matrix or id behind for the next member to inherit.
+ * @internal
+ */
+export declare function writeCrowdBatch(frame: CrowdBatchFrame): number;

package/dist/render/crowdBatch.js

@@ -0,0 +1,68 @@
+import * as THREE from "three";
+import { animationPhaseOf } from "./characterLod.js";
+import { crowdClipForSpeed, } from "./crowdRegistry.js";
+const scratchMatrix = new THREE.Matrix4();
+const scratchOffset = new THREE.Matrix4();
+const scratchQuaternion = new THREE.Quaternion();
+const scratchPosition = new THREE.Vector3();
+const scratchScale = new THREE.Vector3();
+/** A stable non-zero time offset for a member with no recorded pose, so a crowd is not in lockstep. */
+export function poseTimeOffset(id) {
+    let hash = 0;
+    for (let index = 0; index < id.length; index += 1)
+        hash = (hash * 31 + id.charCodeAt(index)) | 0;
+    return (Math.abs(hash) % 1000) / 1000 + 0.05;
+}
+/**
+ * Writes one frame of instances for a batch and returns how many it drew. Slots are compacted from
+ * zero every frame and `ids` is truncated to the drawn range, so a character that left the batch or
+ * went out of view never leaves its last matrix or id behind for the next member to inherit.
+ * @internal
+ */
+export function writeCrowdBatch(frame) {
+    const { mesh, play, members, placement, clips, bands, clipIndex, time, playback, ids } = frame;
+    let count = 0;
+    let minX = Infinity, minY = Infinity, minZ = Infinity, maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+    for (const { id, member } of members) {
+        if (count >= mesh.instanceMatrix.count)
+            break;
+        if (play !== null) {
+            const clipName = crowdClipForSpeed(clips, member.speed, bands);
+            const clip = clipName === undefined ? 0 : clipIndex.get(clipName) ?? 0;
+            let entry = playback.get(id);
+            if (entry === undefined || entry.clip !== clip) {
+                // Hand the batch the pose the rig was holding, so the swap continues the same gait instead
+                // of restarting the clip at a different phase.
+                const phase = animationPhaseOf(id);
+                entry = { clip, offset: phase !== undefined && phase.clip === clipName ? phase.time - time : poseTimeOffset(id) };
+                playback.set(id, entry);
+            }
+            play.setXYZ(count, entry.clip, entry.offset, 1);
+        }
+        scratchQuaternion.setFromAxisAngle(THREE.Object3D.DEFAULT_UP, member.rotationY);
+        scratchMatrix.compose(scratchPosition.set(member.x, member.y, member.z), scratchQuaternion, scratchScale.setScalar(placement.scale));
+        scratchMatrix.multiply(scratchOffset.makeTranslation(placement.offset.x, placement.offset.y, placement.offset.z));
+        mesh.setMatrixAt(count, scratchMatrix);
+        ids[count] = id;
+        minX = Math.min(minX, member.x);
+        maxX = Math.max(maxX, member.x);
+        minY = Math.min(minY, member.y);
+        maxY = Math.max(maxY, member.y);
+        minZ = Math.min(minZ, member.z);
+        maxZ = Math.max(maxZ, member.z);
+        count += 1;
+    }
+    ids.length = count;
+    mesh.count = count;
+    mesh.instanceMatrix.needsUpdate = true;
+    if (play !== null)
+        play.needsUpdate = true;
+    if (count > 0) {
+        // One batch spans every drawn member, so its cull sphere has to follow them; three cannot cull
+        // an InstancedMesh per instance.
+        const sphere = mesh.boundingSphere ?? (mesh.boundingSphere = new THREE.Sphere());
+        sphere.center.set((minX + maxX) / 2, (minY + maxY) / 2, (minZ + maxZ) / 2);
+        sphere.radius = Math.hypot(maxX - minX, maxY - minY, maxZ - minZ) / 2 + placement.scale * 1.2;
+    }
+    return count;
+}

package/dist/render/crowdRegistry.d.ts

@@ -1,3 +1,4 @@
+import type * as THREE from "three";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
 /** One character the GPU crowd path is drawing instead of its own rig. @internal */
 export interface CrowdMember {
@@ -8,22 +9,49 @@ export interface CrowdMember {
     /** Ground speed in metres per second, which picks the crowd's idle/walk/run clip. */
     speed: number;
 }
+/** Where a batch's merged geometry sits, so picking hits what the batch draws. @internal */
+export interface CrowdBatchGeometry {
+    geometry: THREE.BufferGeometry;
+    /** Placement the batch draws its members with, relative to each member's world pose. */
+    position: readonly [number, number, number];
+    scale: number;
+}
+/** Speed at or above which a crowd member walks, and one at which it runs. @internal */
+export interface CrowdSpeedBands {
+    walk: number;
+    run: number;
+}
 /**
  * The identity a character model shares with every other model the GPU crowd can draw: rig url,
  * height normalization and material tint. Two entity kinds with the same key can share one instanced
  * draw; a different tint or height needs its own.
  */
 export declare function crowdKindOf(model: ModelConfig): string;
-/** Whether a model can leave its own rig for the GPU crowd path: a rigged, clip-played, plain model. */
+/**
+ * Whether a model can leave its own rig for the GPU crowd path: one whose drawn result a batch can
+ * reproduce. A rigged, clip-played, plain model qualifies, and so does a model with no animation at
+ * all (a static crowd character) — it has no playback to lose. A model that needs per-entity
+ * materials, wind, hidden nodes, IK, attachments or a part composition keeps its own rig.
+ */
 export declare function crowdEligible(model: ModelConfig | undefined): model is ModelConfig;
 /**
  * The clips a crowd batch bakes for a model: its resolved idle, walk and run, in that order. Empty
- * when the rig's clip names do not resolve to locomotion roles, which leaves the character on its own
- * rig instead of drawing a frozen crowd copy.
+ * when the model plays no clips at all (a static character) or when the rig's clip names do not
+ * resolve to locomotion roles, which leaves the character on its own rig instead of drawing a frozen
+ * crowd copy.
  */
 export declare function crowdClipsOf(model: ModelConfig, clipNames: readonly string[]): string[];
-/** The baked clip a crowd member at `speed` plays; clips are `[idle, walk, run]` as {@link crowdClipsOf} orders them. */
-export declare function crowdClipForSpeed(clips: readonly string[], speed: number): string | undefined;
+/**
+ * The ground speeds the model's own locomotion graph switches clips at, so a batched character walks
+ * and idles at the same speed its own rig would. A model that declares none keeps the engine's
+ * defaults.
+ */
+export declare function crowdSpeedBandsOf(model: ModelConfig, clipNames: readonly string[]): CrowdSpeedBands;
+/**
+ * The baked clip a crowd member at `speed` plays; clips are `[idle, walk, run]` as {@link crowdClipsOf}
+ * orders them. `bands` is the model's own walk/run speed.
+ */
+export declare function crowdClipForSpeed(clips: readonly string[], speed: number, bands?: CrowdSpeedBands): string | undefined;
 /** Mark a crowd batch drawable, so markers may hand it characters. @internal */
 export declare function setCrowdKindReady(kind: string, ready: boolean): void;
 /** Whether a character kind has a crowd batch that can draw it. @internal */
@@ -32,13 +60,35 @@ export declare function crowdKindReady(kind: string): boolean;
  * The characters the crowd layer is currently drawing, written by their entity markers each frame.
  * It holds poses rather than React state: 71 pedestrians writing matrices must not re-render the
  * world, and the crowd batch reads the same entries back to fill its instance buffers.
+ *
+ * A marker asks {@link claim} for a slot; the batch declares how many it can draw, so a full batch
+ * leaves the rest of its kind on their own rigs. The registry keeps drawn ids in claim order, which
+ * is the instance order the batch writes, so a character leaving compacts the rest instead of
+ * leaving a stale matrix behind.
  */
 export declare class CharacterCrowdRegistry {
     private readonly members;
+    private readonly capacities;
+    private readonly geometries;
+    /** Declare how many characters one kind's batch can draw; `undefined` clears the batch. */
+    setCapacity(kind: string, capacity: number | undefined): void;
+    /** How many characters one kind's batch can draw; zero until its batch mounts. */
+    capacity(kind: string): number;
+    /** Record the geometry and placement a batch draws its kind with, for picking. */
+    setGeometry(kind: string, geometry: CrowdBatchGeometry | undefined): void;
+    /** The drawn geometry of one kind, once its batch is ready. */
+    geometry(kind: string): CrowdBatchGeometry | undefined;
+    /**
+     * Hand a character to the batch. Returns false when the batch is full, and the caller then keeps
+     * that character on its own rig. An existing member always updates.
+     */
+    claim(id: string, kind: string, member: CrowdMember): boolean;
     /** Record the pose an entity is showing as a crowd instance this frame. */
     set(id: string, kind: string, member: CrowdMember): void;
     /** The entity went back to its own rig, or unmounted. */
     delete(id: string): void;
+    /** The kind this character is batched as, or `undefined` when it draws its own rig. */
+    kindOf(id: string): string | undefined;
     /** How many characters this kind is drawing; zero means the batch can skip its work. */
     count(kind: string): number;
     /** Visit every character of one kind, in insertion order. */