three-base 2.0.142 → 2.0.166

package/instanced/InstancedBatch.js

@@ -1,348 +1,348 @@
-import { AnimationMixer, DynamicDrawUsage, Group, InstancedBufferAttribute, InstancedMesh, Matrix4, Vector3, } from "three";
-import { loadTemplate } from "./InstancedTemplate";
-import FPScontrol from "../FPScontrol";
-const _m = new Matrix4();
-const _v = new Vector3();
-const _n = new Vector3();
-const _skinMat = new Matrix4();
-const _tmpMat = new Matrix4();
-/**
- * 把 skeleton 当前姿态烘焙进 geometry（线性混合蒙皮，LBS）。
- * 由于同一 batch 内所有实例共享同一套骨骼矩阵（共享姿态），每帧只需烘焙一份几何，
- * 所有实例复用 —— 这是把"GPU skinning + instancing"降级为"每帧 CPU 烘焙一份共享几何 + instancing"的关键，
- * 复杂度从自定义 shader 降到几何更新，天然兼容项目所有材质与后处理。
- */
-function bakeSkinning(srcGeom, dstGeom, skeleton, bindMatrix, bindMatrixInverse) {
-    // 从 srcGeom（原始 bind-pose，只读）逐顶点读取，计算结果写入 dstGeom（渲染用几何）。
-    // 绝不能读改写同一份几何 —— 否则上一帧烘焙结果被当成 bind-pose 再烤一遍，蒙皮累积错位。
-    const pos = srcGeom.attributes.position;
-    const norm = srcGeom.attributes.normal;
-    const si = srcGeom.attributes.skinIndex;
-    const sw = srcGeom.attributes.skinWeight;
-    const dpos = dstGeom.attributes.position;
-    const dnorm = dstGeom.attributes.normal;
-    if (!pos || !si || !sw || !dpos) {
-        return;
-    }
-    const boneMatrices = skeleton.boneMatrices; // Float32Array，长度 = bones * 16
-    if (!boneMatrices) {
-        return;
-    }
-    for (let i = 0; i < pos.count; i++) {
-        // 与 three 着色器保持一致：先 bindMatrix 把顶点转到"骨骼局部坐标系"，
-        // 再叠加骨骼混合矩阵，最后 bindMatrixInverse 回到模型空间。顺序反了动画姿态会错。
-        _v.fromBufferAttribute(pos, i).applyMatrix4(bindMatrix);
-        _skinMat.set(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0);
-        for (let j = 0; j < 4; j++) {
-            const w = sw.getComponent(i, j);
-            if (w === 0) {
-                continue;
-            }
-            const bi = si.getComponent(i, j);
-            _tmpMat.fromArray(boneMatrices, bi * 16);
-            _tmpMat.multiplyScalar(w);
-            const se = _skinMat.elements;
-            const te = _tmpMat.elements;
-            for (let k = 0; k < 16; k++) {
-                se[k] += te[k];
-            }
-        }
-        _v.applyMatrix4(_skinMat).applyMatrix4(bindMatrixInverse);
-        dpos.setXYZ(i, _v.x, _v.y, _v.z);
-        if (norm && dnorm) {
-            _n.fromBufferAttribute(norm, i).applyMatrix4(_skinMat).normalize();
-            dnorm.setXYZ(i, _n.x, _n.y, _n.z);
-        }
-    }
-    dpos.needsUpdate = true;
-    if (dnorm) {
-        dnorm.needsUpdate = true;
-    }
-}
-/**
- * 把节点相对根的世界变换烘焙进几何（非骨骼节点动画的实例化方案）。
- * 与骨骼 LBS 同理：把"节点层级变换"降级为每帧 CPU 几何变换，
- * 所有实例复用一份变换后的几何，天然兼容项目所有材质与后处理。
- */
-function bakeNodeTransform(geometry, local, m) {
-    const pos = geometry.attributes.position;
-    const lp = local.attributes.position;
-    if (!pos || !lp) {
-        return;
-    }
-    for (let i = 0; i < lp.count; i++) {
-        _v.fromBufferAttribute(lp, i).applyMatrix4(m);
-        pos.setXYZ(i, _v.x, _v.y, _v.z);
-    }
-    pos.needsUpdate = true;
-    const norm = geometry.attributes.normal;
-    const ln = local.attributes.normal;
-    if (norm && ln) {
-        for (let i = 0; i < ln.count; i++) {
-            _n.fromBufferAttribute(ln, i).applyMatrix4(m).normalize();
-            norm.setXYZ(i, _n.x, _n.y, _n.z);
-        }
-        norm.needsUpdate = true;
-    }
-}
-/**
- * 内部类：封装一个 batch 的真实 InstancedMesh（多 submesh 时每个 submesh 一个，共享同一组实例序号）。
- * - 按 batchKey 分组（相同 geometry+material 或相同 instanceUrl+animation 为一类）；
- * - 增量同步：仅 needUpdate=true 的实例才重写 matrix/color，写完后立即置 false；
- * - 列表变化（增删/重排）时全量 compact 重写并重建索引；
- * - 含骨骼动画时：用共享姿态 AnimationMixer 驱动 skeleton，每帧烘焙到共享几何（LBS）；
- * - 含非骨骼节点动画时：同样用共享姿态 AnimationMixer 驱动节点变换，每帧把"节点相对根的世界变换"
- *   烘焙进几何（节点变换动画的实例化方案）。
- */
-export default class InstancedBatch {
-    key;
-    /** 渲染组：持有本 batch 的 InstancedMesh，由 InstancedGroup add 进 scene */
-    group = new Group();
-    template;
-    ready = false;
-    _children = [];
-    _meshes = [];
-    _capacity;
-    _step;
-    _loading;
-    _mixer;
-    _clipName;
-    /** 当前正在播放的动画剪辑名（运行时可由 child.playClip 切换） */
-    _currentClip;
-    /** 首例实例是否声明碰撞（构造时快照，buildMeshes 用它给 InstancedMesh 打标记） */
-    _sampleFpsCollision = false;
-    /** 当前正在播放的 AnimationAction（切换时先 stop 旧的） */
-    _currentAction;
-    /** 非骨骼动画：需每帧烘焙节点变换的几何列表（与 _meshes 顺序对齐） */
-    _nodeBake = [];
-    constructor(key, sample, capacity = 100, step = 100) {
-        this.key = key;
-        this._capacity = capacity;
-        this._step = step;
-        // 用实例当前生效动画（playClip 优先，否则 static animation）构建本 batch 的 mixer；
-        // 因 key 已含动画名，相同 glb+动画的实例都进同一个常驻 batch
-        this._clipName = sample.getEffectiveAnimation();
-        this._sampleFpsCollision = !!sample.fpsCollision;
-        this._loading = loadTemplate(sample).then((t) => {
-            const ctor = sample.constructor;
-            // GLB 模板就绪后，交给子类按需修正材质（如瓶子 metalness 修正）
-            if (typeof ctor.prepareTemplate === "function") {
-                ctor.prepareTemplate(t);
-            }
-            this.template = t;
-            this.buildMeshes();
-            this.ready = true;
-        });
-    }
-    /** 模板就绪后，为每个 submesh 建一个 InstancedMesh，并启动动画（若有） */
-    buildMeshes() {
-        if (!this.template) {
-            return;
-        }
-        for (const sub of this.template.submeshes) {
-            const geom = sub.skinned && this.template.sharedGeometry
-                ? this.template.sharedGeometry
-                : sub.geometry;
-            const im = new InstancedMesh(geom, sub.material, this._capacity);
-            im.frustumCulled = false;
-            im.instanceMatrix.setUsage(DynamicDrawUsage);
-            // 预创建 instanceColor（默认白，setColorAt 会覆盖）
-            im.instanceColor = new InstancedBufferAttribute(new Float32Array(this._capacity * 3).fill(1), 3);
-            im.count = 0;
-            im.userData.__batchKey = this.key;
-            // 若本 batch 的实例声明了碰撞检测，则把真实 InstancedMesh 标记为碰撞体，
-            // 供 FPScontrol 的碰撞射线命中（实例化对象的几何合并在 InstancedMesh 里，只能整体标记）。
-            im.userData.fpsCollision = this._sampleFpsCollision;
-            this._meshes.push(im);
-            this.group.add(im);
-            // 非骨骼动画：记录节点烘焙信息，每帧把节点相对根的世界变换写进几何
-            if (sub.node && this.template.animRoot && !this.template.skeleton && sub.localGeometry) {
-                this._nodeBake.push({ node: sub.node, local: sub.localGeometry, render: sub.geometry });
-            }
-        }
-        // 模板就绪即标记碰撞体，并通知所有 FPScontrol 重新收集（模板是异步加载的，
-        // 此时控制器多半已先创建，必须主动通知它重建碰撞列表，否则实例化碰撞体不生效）。
-        if (this._sampleFpsCollision) {
-            FPScontrol.markAllCollidersDirty();
-        }
-        // 动画：共享姿态，一个 mixer 驱动整批（骨骼 LBS 与非骨骼节点动画都走这里）。
-        // 一个 batch 只对应一种动画（key = glb+动画），故 mixer 启动即播放该动画、整批同源同步。
-        // 仅当本 batch 的动画名（_clipName）存在且 GLB 自带剪辑才启动；否则渲染静态绑定姿态（bind pose）。
-        if (this._clipName && this.template.animRoot && this.template.animations.length) {
-            const clip = this.template.animations.find((c) => c.name === this._clipName) ||
-                this.template.animations[0];
-            if (clip) {
-                this._mixer = new AnimationMixer(this.template.animRoot);
-                const action = this._mixer.clipAction(clip);
-                action.play();
-                this._currentAction = action;
-                this._currentClip = clip.name;
-            }
-        }
-    }
-    /** 每帧同步：children 为按 batchKey 收集的 InstancedChild 列表 */
-    sync(children, delta) {
-        if (!this.ready || !this.template) {
-            return;
-        }
-        const listChanged = this._children.length !== children.length ||
-            this._children.some((c, i) => c !== children[i]);
-        if (listChanged) {
-            this._children = children;
-            this.ensureCapacity(children.length);
-            this.compactWrite();
-            // 列表变化（含首帧就绪）：重新同步碰撞标记——实例可能在创建后才改 fpsCollision，
-            // 用最新 children[0] 的标记覆盖，并在开启时通知 FPScontrol 重建碰撞列表。
-            this._applyCollisionFlag();
-        }
-        else {
-            // 增量：只写 needUpdate 的实例，写完后立即置 false（避免重复写）
-            for (let i = 0; i < children.length; i++) {
-                const c = children[i];
-                if (c.needUpdate) {
-                    this.writeInstance(i, c);
-                    c.needUpdate = false;
-                }
-            }
-        }
-        // 动画（共享姿态）：更新骨骼/节点 → 烘焙到几何
-        // 注意：本 batch 只对应一种动画（key 已含动画名），动作切换由「实例迁移到另一个常驻 batch」完成，
-        // 故这里不再做 batch 内的 mixer 切换，只需推进当前动画即可。
-        if (this._mixer && this.template.animRoot) {
-            this._mixer.update(delta);
-            this.template.animRoot.updateMatrixWorld(true); // 触发骨架/skeleton 计算
-            if (this.template.skeleton &&
-                this.template.sourceGeometry &&
-                this.template.sharedGeometry &&
-                this.template.bindMatrix &&
-                this.template.bindMatrixInverse) {
-                // 关键：mixer 已更新 bone 的世界矩阵，但骨骼矩阵（boneMatrices）需显式重算，
-                // 否则每帧都停在构造时的绑定姿态（士兵会变成静止 T-pose 甚至退化不可见）。
-                this.template.skeleton.update();
-                // 骨骼 LBS 烘焙：从 sourceGeometry（bind-pose）读、写到 sharedGeometry（渲染用），避免累积。
-                bakeSkinning(this.template.sourceGeometry, this.template.sharedGeometry, this.template.skeleton, this.template.bindMatrix, this.template.bindMatrixInverse);
-            }
-            else if (this._nodeBake.length) {
-                // 非骨骼节点动画：把每个节点相对根的世界变换烘焙进几何
-                const rootInv = _tmpMat.copy(this.template.animRoot.matrixWorld).invert();
-                for (const nb of this._nodeBake) {
-                    _m.copy(nb.node.matrixWorld).multiply(rootInv);
-                    bakeNodeTransform(nb.render, nb.local, _m);
-                }
-            }
-        }
-        // 渲染数 = 当前子实例数
-        for (const im of this._meshes) {
-            im.count = children.length;
-            // ⚠️ 实例数量/矩阵变化后必须清空包围球：three 的 InstancedMesh.raycast 只在
-            // boundingSphere === null 时才重算，而它首次被计算时 count 往往还是 0
-            // （模板异步加载），算出的是「空球」radius = -1 并被永久缓存 →
-            // 后续所有射线检测（FPS 碰撞、鼠标 hover/click）在包围球剔除阶段就被全部跳过。
-            // 置 null 后由下一次 raycast 按需重算（本类 frustumCulled=false，不会每帧白算）。
-            im.boundingSphere = null;
-        }
-    }
-    /** 容量不足时按 step 扩容（只扩不缩，避免频繁 realloc） */
-    ensureCapacity(n) {
-        if (n <= this._capacity) {
-            return;
-        }
-        // 容量按 100 为一阶阶梯增长、只增不降：1 个对象→100 矩阵，101 个→200 矩阵，201 个→300 ...
-        // 避免每超出即整段 realloc，也避免从 200 回降到 100 造成反复分配/收缩。
-        const newCap = Math.ceil(n / 100) * 100;
-        for (const im of this._meshes) {
-            const imMat = new InstancedBufferAttribute(new Float32Array(newCap * 16), 16);
-            const imCol = new InstancedBufferAttribute(new Float32Array(newCap * 3).fill(1), 3);
-            for (let i = 0; i < im.count; i++) {
-                imMat.copyAt(i, im.instanceMatrix, i);
-                if (im.instanceColor) {
-                    imCol.copyAt(i, im.instanceColor, i);
-                }
-            }
-            im.instanceMatrix = imMat;
-            im.instanceColor = imCol;
-        }
-        this._capacity = newCap;
-    }
-    /** 全量重写所有实例（列表变化时调用） */
-    compactWrite() {
-        for (let i = 0; i < this._children.length; i++) {
-            this.writeInstance(i, this._children[i]);
-            this._children[i].needUpdate = false;
-        }
-    }
-    /** 根据当前首批实例的 fpsCollision 标记，把真实 InstancedMesh 的 userData.fpsCollision 同步过去，
-     *  并在开启时通知所有 FPScontrol 重建碰撞列表。碰撞以整个 batch 为单位开关。 */
-    _applyCollisionFlag() {
-        const col = this._children.length > 0 && this._children[0].fpsCollision;
-        for (const im of this._meshes) {
-            im.userData.fpsCollision = col;
-        }
-        if (col) {
-            FPScontrol.markAllCollidersDirty();
-        }
-    }
-    /** 把单个实例的 matrix + color 写入所有 submesh 的对应槽位 */
-    writeInstance(i, child) {
-        for (let k = 0; k < this._meshes.length; k++) {
-            const im = this._meshes[k];
-            const sub = this.template.submeshes[k];
-            // 叠加 GLB 节点层级的世界变换（如 Soldier.glb 根节点 scale=0.01），
-            // 使实例化渲染与"把整棵 GLB 场景图加进场景"一致（对齐 MeshBase 行为）。
-            _m.copy(child.matrixWorld);
-            if (sub.nodeWorldMatrix) {
-                _m.multiply(sub.nodeWorldMatrix);
-            }
-            im.setMatrixAt(i, _m);
-            im.instanceMatrix.needsUpdate = true;
-            if (im.instanceColor) {
-                im.setColorAt(i, child.color);
-                im.instanceColor.needsUpdate = true;
-            }
-        }
-    }
-    /** 事件路由：给定 InstancedMesh 与 instanceId，返回对应 InstancedChild */
-    resolveInstance(mesh, instanceId) {
-        if (!mesh.userData.__batchKey || mesh.userData.__batchKey !== this.key) {
-            return null;
-        }
-        return this._children[instanceId] ?? null;
-    }
-    /** 该 batch 是否有任一 child 注册了指定类型监听（供 ThreeMouse 决定是否可拾取） */
-    hasListener(types) {
-        for (const c of this._children) {
-            const listeners = c._listeners;
-            if (listeners && types.some((t) => listeners[t] && listeners[t].length)) {
-                return true;
-            }
-        }
-        return false;
-    }
-    /** 该 batch 是否有任一 child 设置了鼠标手势（cursor），供 InstancedGroup 决定是否收集 */
-    hasCursor() {
-        for (const c of this._children) {
-            if (c.userData && c.userData.cursor) {
-                return true;
-            }
-        }
-        return false;
-    }
-    /** 拾取用 InstancedMesh 列表 */
-    get pickables() {
-        return this._meshes;
-    }
-    dispose() {
-        for (const im of this._meshes) {
-            // 只释放 InstancedMesh 自带的实例缓冲（instanceMatrix / instanceColor），
-            // 不能 dispose geometry/material —— 它们来自 static geometry 或模板缓存，是共享资源，
-            // 一旦 dispose，后续重建同 batch 时会拿到已销毁的几何/材质导致渲染异常。
-            im.dispose();
-            this.group.remove(im);
-        }
-        this._meshes = [];
-        this._nodeBake = [];
-        if (this._mixer) {
-            this._mixer.stopAllAction();
-        }
-    }
-}
+import { AnimationMixer, DynamicDrawUsage, Group, InstancedBufferAttribute, InstancedMesh, Matrix4, Vector3, } from "three";
+import { loadTemplate } from "./InstancedTemplate";
+import FPScontrol from "../FPScontrol";
+const _m = new Matrix4();
+const _v = new Vector3();
+const _n = new Vector3();
+const _skinMat = new Matrix4();
+const _tmpMat = new Matrix4();
+/**
+ * 把 skeleton 当前姿态烘焙进 geometry（线性混合蒙皮，LBS）。
+ * 由于同一 batch 内所有实例共享同一套骨骼矩阵（共享姿态），每帧只需烘焙一份几何，
+ * 所有实例复用 —— 这是把"GPU skinning + instancing"降级为"每帧 CPU 烘焙一份共享几何 + instancing"的关键，
+ * 复杂度从自定义 shader 降到几何更新，天然兼容项目所有材质与后处理。
+ */
+function bakeSkinning(srcGeom, dstGeom, skeleton, bindMatrix, bindMatrixInverse) {
+    // 从 srcGeom（原始 bind-pose，只读）逐顶点读取，计算结果写入 dstGeom（渲染用几何）。
+    // 绝不能读改写同一份几何 —— 否则上一帧烘焙结果被当成 bind-pose 再烤一遍，蒙皮累积错位。
+    const pos = srcGeom.attributes.position;
+    const norm = srcGeom.attributes.normal;
+    const si = srcGeom.attributes.skinIndex;
+    const sw = srcGeom.attributes.skinWeight;
+    const dpos = dstGeom.attributes.position;
+    const dnorm = dstGeom.attributes.normal;
+    if (!pos || !si || !sw || !dpos) {
+        return;
+    }
+    const boneMatrices = skeleton.boneMatrices; // Float32Array，长度 = bones * 16
+    if (!boneMatrices) {
+        return;
+    }
+    for (let i = 0; i < pos.count; i++) {
+        // 与 three 着色器保持一致：先 bindMatrix 把顶点转到"骨骼局部坐标系"，
+        // 再叠加骨骼混合矩阵，最后 bindMatrixInverse 回到模型空间。顺序反了动画姿态会错。
+        _v.fromBufferAttribute(pos, i).applyMatrix4(bindMatrix);
+        _skinMat.set(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0);
+        for (let j = 0; j < 4; j++) {
+            const w = sw.getComponent(i, j);
+            if (w === 0) {
+                continue;
+            }
+            const bi = si.getComponent(i, j);
+            _tmpMat.fromArray(boneMatrices, bi * 16);
+            _tmpMat.multiplyScalar(w);
+            const se = _skinMat.elements;
+            const te = _tmpMat.elements;
+            for (let k = 0; k < 16; k++) {
+                se[k] += te[k];
+            }
+        }
+        _v.applyMatrix4(_skinMat).applyMatrix4(bindMatrixInverse);
+        dpos.setXYZ(i, _v.x, _v.y, _v.z);
+        if (norm && dnorm) {
+            _n.fromBufferAttribute(norm, i).applyMatrix4(_skinMat).normalize();
+            dnorm.setXYZ(i, _n.x, _n.y, _n.z);
+        }
+    }
+    dpos.needsUpdate = true;
+    if (dnorm) {
+        dnorm.needsUpdate = true;
+    }
+}
+/**
+ * 把节点相对根的世界变换烘焙进几何（非骨骼节点动画的实例化方案）。
+ * 与骨骼 LBS 同理：把"节点层级变换"降级为每帧 CPU 几何变换，
+ * 所有实例复用一份变换后的几何，天然兼容项目所有材质与后处理。
+ */
+function bakeNodeTransform(geometry, local, m) {
+    const pos = geometry.attributes.position;
+    const lp = local.attributes.position;
+    if (!pos || !lp) {
+        return;
+    }
+    for (let i = 0; i < lp.count; i++) {
+        _v.fromBufferAttribute(lp, i).applyMatrix4(m);
+        pos.setXYZ(i, _v.x, _v.y, _v.z);
+    }
+    pos.needsUpdate = true;
+    const norm = geometry.attributes.normal;
+    const ln = local.attributes.normal;
+    if (norm && ln) {
+        for (let i = 0; i < ln.count; i++) {
+            _n.fromBufferAttribute(ln, i).applyMatrix4(m).normalize();
+            norm.setXYZ(i, _n.x, _n.y, _n.z);
+        }
+        norm.needsUpdate = true;
+    }
+}
+/**
+ * 内部类：封装一个 batch 的真实 InstancedMesh（多 submesh 时每个 submesh 一个，共享同一组实例序号）。
+ * - 按 batchKey 分组（相同 geometry+material 或相同 instanceUrl+animation 为一类）；
+ * - 增量同步：仅 needUpdate=true 的实例才重写 matrix/color，写完后立即置 false；
+ * - 列表变化（增删/重排）时全量 compact 重写并重建索引；
+ * - 含骨骼动画时：用共享姿态 AnimationMixer 驱动 skeleton，每帧烘焙到共享几何（LBS）；
+ * - 含非骨骼节点动画时：同样用共享姿态 AnimationMixer 驱动节点变换，每帧把"节点相对根的世界变换"
+ *   烘焙进几何（节点变换动画的实例化方案）。
+ */
+export default class InstancedBatch {
+    key;
+    /** 渲染组：持有本 batch 的 InstancedMesh，由 InstancedGroup add 进 scene */
+    group = new Group();
+    template;
+    ready = false;
+    _children = [];
+    _meshes = [];
+    _capacity;
+    _step;
+    _loading;
+    _mixer;
+    _clipName;
+    /** 当前正在播放的动画剪辑名（运行时可由 child.playClip 切换） */
+    _currentClip;
+    /** 首例实例是否声明碰撞（构造时快照，buildMeshes 用它给 InstancedMesh 打标记） */
+    _sampleFpsCollision = false;
+    /** 当前正在播放的 AnimationAction（切换时先 stop 旧的） */
+    _currentAction;
+    /** 非骨骼动画：需每帧烘焙节点变换的几何列表（与 _meshes 顺序对齐） */
+    _nodeBake = [];
+    constructor(key, sample, capacity = 100, step = 100) {
+        this.key = key;
+        this._capacity = capacity;
+        this._step = step;
+        // 用实例当前生效动画（playClip 优先，否则 static animation）构建本 batch 的 mixer；
+        // 因 key 已含动画名，相同 glb+动画的实例都进同一个常驻 batch
+        this._clipName = sample.getEffectiveAnimation();
+        this._sampleFpsCollision = !!sample.fpsCollision;
+        this._loading = loadTemplate(sample).then((t) => {
+            const ctor = sample.constructor;
+            // GLB 模板就绪后，交给子类按需修正材质（如瓶子 metalness 修正）
+            if (typeof ctor.prepareTemplate === "function") {
+                ctor.prepareTemplate(t);
+            }
+            this.template = t;
+            this.buildMeshes();
+            this.ready = true;
+        });
+    }
+    /** 模板就绪后，为每个 submesh 建一个 InstancedMesh，并启动动画（若有） */
+    buildMeshes() {
+        if (!this.template) {
+            return;
+        }
+        for (const sub of this.template.submeshes) {
+            const geom = sub.skinned && this.template.sharedGeometry
+                ? this.template.sharedGeometry
+                : sub.geometry;
+            const im = new InstancedMesh(geom, sub.material, this._capacity);
+            im.frustumCulled = false;
+            im.instanceMatrix.setUsage(DynamicDrawUsage);
+            // 预创建 instanceColor（默认白，setColorAt 会覆盖）
+            im.instanceColor = new InstancedBufferAttribute(new Float32Array(this._capacity * 3).fill(1), 3);
+            im.count = 0;
+            im.userData.__batchKey = this.key;
+            // 若本 batch 的实例声明了碰撞检测，则把真实 InstancedMesh 标记为碰撞体，
+            // 供 FPScontrol 的碰撞射线命中（实例化对象的几何合并在 InstancedMesh 里，只能整体标记）。
+            im.userData.fpsCollision = this._sampleFpsCollision;
+            this._meshes.push(im);
+            this.group.add(im);
+            // 非骨骼动画：记录节点烘焙信息，每帧把节点相对根的世界变换写进几何
+            if (sub.node && this.template.animRoot && !this.template.skeleton && sub.localGeometry) {
+                this._nodeBake.push({ node: sub.node, local: sub.localGeometry, render: sub.geometry });
+            }
+        }
+        // 模板就绪即标记碰撞体，并通知所有 FPScontrol 重新收集（模板是异步加载的，
+        // 此时控制器多半已先创建，必须主动通知它重建碰撞列表，否则实例化碰撞体不生效）。
+        if (this._sampleFpsCollision) {
+            FPScontrol.markAllCollidersDirty();
+        }
+        // 动画：共享姿态，一个 mixer 驱动整批（骨骼 LBS 与非骨骼节点动画都走这里）。
+        // 一个 batch 只对应一种动画（key = glb+动画），故 mixer 启动即播放该动画、整批同源同步。
+        // 仅当本 batch 的动画名（_clipName）存在且 GLB 自带剪辑才启动；否则渲染静态绑定姿态（bind pose）。
+        if (this._clipName && this.template.animRoot && this.template.animations.length) {
+            const clip = this.template.animations.find((c) => c.name === this._clipName) ||
+                this.template.animations[0];
+            if (clip) {
+                this._mixer = new AnimationMixer(this.template.animRoot);
+                const action = this._mixer.clipAction(clip);
+                action.play();
+                this._currentAction = action;
+                this._currentClip = clip.name;
+            }
+        }
+    }
+    /** 每帧同步：children 为按 batchKey 收集的 InstancedChild 列表 */
+    sync(children, delta) {
+        if (!this.ready || !this.template) {
+            return;
+        }
+        const listChanged = this._children.length !== children.length ||
+            this._children.some((c, i) => c !== children[i]);
+        if (listChanged) {
+            this._children = children;
+            this.ensureCapacity(children.length);
+            this.compactWrite();
+            // 列表变化（含首帧就绪）：重新同步碰撞标记——实例可能在创建后才改 fpsCollision，
+            // 用最新 children[0] 的标记覆盖，并在开启时通知 FPScontrol 重建碰撞列表。
+            this._applyCollisionFlag();
+        }
+        else {
+            // 增量：只写 needUpdate 的实例，写完后立即置 false（避免重复写）
+            for (let i = 0; i < children.length; i++) {
+                const c = children[i];
+                if (c.needUpdate) {
+                    this.writeInstance(i, c);
+                    c.needUpdate = false;
+                }
+            }
+        }
+        // 动画（共享姿态）：更新骨骼/节点 → 烘焙到几何
+        // 注意：本 batch 只对应一种动画（key 已含动画名），动作切换由「实例迁移到另一个常驻 batch」完成，
+        // 故这里不再做 batch 内的 mixer 切换，只需推进当前动画即可。
+        if (this._mixer && this.template.animRoot) {
+            this._mixer.update(delta);
+            this.template.animRoot.updateMatrixWorld(true); // 触发骨架/skeleton 计算
+            if (this.template.skeleton &&
+                this.template.sourceGeometry &&
+                this.template.sharedGeometry &&
+                this.template.bindMatrix &&
+                this.template.bindMatrixInverse) {
+                // 关键：mixer 已更新 bone 的世界矩阵，但骨骼矩阵（boneMatrices）需显式重算，
+                // 否则每帧都停在构造时的绑定姿态（士兵会变成静止 T-pose 甚至退化不可见）。
+                this.template.skeleton.update();
+                // 骨骼 LBS 烘焙：从 sourceGeometry（bind-pose）读、写到 sharedGeometry（渲染用），避免累积。
+                bakeSkinning(this.template.sourceGeometry, this.template.sharedGeometry, this.template.skeleton, this.template.bindMatrix, this.template.bindMatrixInverse);
+            }
+            else if (this._nodeBake.length) {
+                // 非骨骼节点动画：把每个节点相对根的世界变换烘焙进几何
+                const rootInv = _tmpMat.copy(this.template.animRoot.matrixWorld).invert();
+                for (const nb of this._nodeBake) {
+                    _m.copy(nb.node.matrixWorld).multiply(rootInv);
+                    bakeNodeTransform(nb.render, nb.local, _m);
+                }
+            }
+        }
+        // 渲染数 = 当前子实例数
+        for (const im of this._meshes) {
+            im.count = children.length;
+            // ⚠️ 实例数量/矩阵变化后必须清空包围球：three 的 InstancedMesh.raycast 只在
+            // boundingSphere === null 时才重算，而它首次被计算时 count 往往还是 0
+            // （模板异步加载），算出的是「空球」radius = -1 并被永久缓存 →
+            // 后续所有射线检测（FPS 碰撞、鼠标 hover/click）在包围球剔除阶段就被全部跳过。
+            // 置 null 后由下一次 raycast 按需重算（本类 frustumCulled=false，不会每帧白算）。
+            im.boundingSphere = null;
+        }
+    }
+    /** 容量不足时按 step 扩容（只扩不缩，避免频繁 realloc） */
+    ensureCapacity(n) {
+        if (n <= this._capacity) {
+            return;
+        }
+        // 容量按 100 为一阶阶梯增长、只增不降：1 个对象→100 矩阵，101 个→200 矩阵，201 个→300 ...
+        // 避免每超出即整段 realloc，也避免从 200 回降到 100 造成反复分配/收缩。
+        const newCap = Math.ceil(n / 100) * 100;
+        for (const im of this._meshes) {
+            const imMat = new InstancedBufferAttribute(new Float32Array(newCap * 16), 16);
+            const imCol = new InstancedBufferAttribute(new Float32Array(newCap * 3).fill(1), 3);
+            for (let i = 0; i < im.count; i++) {
+                imMat.copyAt(i, im.instanceMatrix, i);
+                if (im.instanceColor) {
+                    imCol.copyAt(i, im.instanceColor, i);
+                }
+            }
+            im.instanceMatrix = imMat;
+            im.instanceColor = imCol;
+        }
+        this._capacity = newCap;
+    }
+    /** 全量重写所有实例（列表变化时调用） */
+    compactWrite() {
+        for (let i = 0; i < this._children.length; i++) {
+            this.writeInstance(i, this._children[i]);
+            this._children[i].needUpdate = false;
+        }
+    }
+    /** 根据当前首批实例的 fpsCollision 标记，把真实 InstancedMesh 的 userData.fpsCollision 同步过去，
+     *  并在开启时通知所有 FPScontrol 重建碰撞列表。碰撞以整个 batch 为单位开关。 */
+    _applyCollisionFlag() {
+        const col = this._children.length > 0 && this._children[0].fpsCollision;
+        for (const im of this._meshes) {
+            im.userData.fpsCollision = col;
+        }
+        if (col) {
+            FPScontrol.markAllCollidersDirty();
+        }
+    }
+    /** 把单个实例的 matrix + color 写入所有 submesh 的对应槽位 */
+    writeInstance(i, child) {
+        for (let k = 0; k < this._meshes.length; k++) {
+            const im = this._meshes[k];
+            const sub = this.template.submeshes[k];
+            // 叠加 GLB 节点层级的世界变换（如 Soldier.glb 根节点 scale=0.01），
+            // 使实例化渲染与"把整棵 GLB 场景图加进场景"一致（对齐 MeshBase 行为）。
+            _m.copy(child.matrixWorld);
+            if (sub.nodeWorldMatrix) {
+                _m.multiply(sub.nodeWorldMatrix);
+            }
+            im.setMatrixAt(i, _m);
+            im.instanceMatrix.needsUpdate = true;
+            if (im.instanceColor) {
+                im.setColorAt(i, child.color);
+                im.instanceColor.needsUpdate = true;
+            }
+        }
+    }
+    /** 事件路由：给定 InstancedMesh 与 instanceId，返回对应 InstancedChild */
+    resolveInstance(mesh, instanceId) {
+        if (!mesh.userData.__batchKey || mesh.userData.__batchKey !== this.key) {
+            return null;
+        }
+        return this._children[instanceId] ?? null;
+    }
+    /** 该 batch 是否有任一 child 注册了指定类型监听（供 ThreeMouse 决定是否可拾取） */
+    hasListener(types) {
+        for (const c of this._children) {
+            const listeners = c._listeners;
+            if (listeners && types.some((t) => listeners[t] && listeners[t].length)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** 该 batch 是否有任一 child 设置了鼠标手势（cursor），供 InstancedGroup 决定是否收集 */
+    hasCursor() {
+        for (const c of this._children) {
+            if (c.userData && c.userData.cursor) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** 拾取用 InstancedMesh 列表 */
+    get pickables() {
+        return this._meshes;
+    }
+    dispose() {
+        for (const im of this._meshes) {
+            // 只释放 InstancedMesh 自带的实例缓冲（instanceMatrix / instanceColor），
+            // 不能 dispose geometry/material —— 它们来自 static geometry 或模板缓存，是共享资源，
+            // 一旦 dispose，后续重建同 batch 时会拿到已销毁的几何/材质导致渲染异常。
+            im.dispose();
+            this.group.remove(im);
+        }
+        this._meshes = [];
+        this._nodeBake = [];
+        if (this._mixer) {
+            this._mixer.stopAllAction();
+        }
+    }
+}