three-base 2.0.137 → 2.0.145

package/instanced/InstancedBatch.ts

@@ -0,0 +1,406 @@
+import {
+    AnimationAction,
+    AnimationMixer,
+    BufferGeometry,
+    Color,
+    DynamicDrawUsage,
+    Group,
+    InstancedBufferAttribute,
+    InstancedMesh,
+    Matrix4,
+    Object3D,
+    Skeleton,
+    Vector3,
+} from "three";
+import InstancedChild from "./InstancedChild";
+import { InstancedTemplate, 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: BufferGeometry,
+    dstGeom: BufferGeometry,
+    skeleton: Skeleton,
+    bindMatrix: Matrix4,
+    bindMatrixInverse: Matrix4
+): void {
+    // 从 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: BufferGeometry,
+    local: BufferGeometry,
+    m: Matrix4
+): void {
+    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: string;
+    /** 渲染组：持有本 batch 的 InstancedMesh，由 InstancedGroup add 进 scene */
+    group: Group = new Group();
+    template?: InstancedTemplate;
+    ready: boolean = false;
+
+    private _children: InstancedChild[] = [];
+    private _meshes: InstancedMesh[] = [];
+    private _capacity: number;
+    private _step: number;
+    private _loading?: Promise<void>;
+    private _mixer?: AnimationMixer;
+    private _clipName?: string;
+    /** 当前正在播放的动画剪辑名（运行时可由 child.playClip 切换） */
+    private _currentClip?: string;
+    /** 首例实例是否声明碰撞（构造时快照，buildMeshes 用它给 InstancedMesh 打标记） */
+    private _sampleFpsCollision: boolean = false;
+    /** 当前正在播放的 AnimationAction（切换时先 stop 旧的） */
+    private _currentAction?: AnimationAction;
+    /** 非骨骼动画：需每帧烘焙节点变换的几何列表（与 _meshes 顺序对齐） */
+    private _nodeBake: { node: Object3D; local: BufferGeometry; render: BufferGeometry }[] = [];
+
+    constructor(key: string, sample: InstancedChild, 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 as typeof InstancedChild;
+            // GLB 模板就绪后，交给子类按需修正材质（如瓶子 metalness 修正）
+            if (typeof ctor.prepareTemplate === "function") {
+                ctor.prepareTemplate(t);
+            }
+            this.template = t;
+            this.buildMeshes();
+            this.ready = true;
+        });
+    }
+
+    /** 模板就绪后，为每个 submesh 建一个 InstancedMesh，并启动动画（若有） */
+    private buildMeshes(): void {
+        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: InstancedChild[], delta: number): void {
+        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） */
+    private ensureCapacity(n: number): void {
+        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;
+    }
+
+    /** 全量重写所有实例（列表变化时调用） */
+    private compactWrite(): void {
+        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 为单位开关。 */
+    private _applyCollisionFlag(): void {
+        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 的对应槽位 */
+    private writeInstance(i: number, child: InstancedChild): void {
+        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: InstancedMesh, instanceId: number): InstancedChild | null {
+        if (!mesh.userData.__batchKey || mesh.userData.__batchKey !== this.key) {
+            return null;
+        }
+        return this._children[instanceId] ?? null;
+    }
+
+    /** 该 batch 是否有任一 child 注册了指定类型监听（供 ThreeMouse 决定是否可拾取） */
+    hasListener(types: string[]): boolean {
+        for (const c of this._children) {
+            const listeners = (c as any)._listeners as
+                | Record<string, unknown[]>
+                | undefined;
+            if (listeners && types.some((t) => listeners[t] && listeners[t].length)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /** 该 batch 是否有任一 child 设置了鼠标手势（cursor），供 InstancedGroup 决定是否收集 */
+    hasCursor(): boolean {
+        for (const c of this._children) {
+            if (c.userData && c.userData.cursor) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /** 拾取用 InstancedMesh 列表 */
+    get pickables(): InstancedMesh[] {
+        return this._meshes;
+    }
+
+    dispose(): void {
+        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();
+        }
+    }
+}

package/instanced/InstancedChild.d.ts

@@ -0,0 +1,174 @@
+import { BufferGeometry, Color, Group, Material, Object3D } from "three";
+import type { InstancedTemplate } from "./InstancedTemplate";
+/** 选择代理可叠加的后处理效果开关；默认只开描边（保持向后兼容），可被 glow / bloom / cover 任意叠加。 */
+export interface SelectProxyOptions {
+    stroke?: boolean;
+    glow?: boolean;
+    bloom?: boolean;
+    cover?: boolean;
+    /** 描边粗细（像素级，越大越粗）；不传则沿用 stroke_pass 默认 1 */
+    stroke_width?: number;
+    stroke_color?: string;
+    glow_color?: string;
+    glow_width?: number;
+    glow_opacity?: number;
+    bloom_strength?: number;
+    bloom_radius?: number;
+    cover_color?: string;
+    cover_opacity?: number;
+}
+/**
+ * 所有活着的 InstancedChild 实例集合，供 InstancedGroup 每帧收集。
+ * 用全局注册表而非遍历整棵 scene，避免大场景每帧 traverse 全树的性能开销。
+ *
+ * ⚠️ 多 InstancedGroup 共存时的归属（owner）：见 `instancedChildOwner` 与 `getOwner()`。
+ * 同一个进程里可能并存多个 InstancedGroup（如主编辑器的 ThreeBase 与预览弹窗各自一套），
+ * 若不隔离，双方会互相把对方的实例收进自己的 batch，导致「A 场景的立方体出现在 B 场景」。
+ */
+export declare const instancedChildRegistry: Set<InstancedChild>;
+/**
+ * 实例归属（owner tag）注册表：child -> owner 字符串。
+ * InstancedGroup 构造时可声明自己的 owner，每帧只收集 `owner` 匹配（或未声明 owner）的实例。
+ * 未在表中登记的实例视为「无归属」，会被**声明了 owner 的组**忽略、
+ * 被**未声明 owner 的组**（如 ThreeBase 的默认组）收集 —— 保持对既有代码零影响。
+ */
+export declare const instancedChildOwner: Map<InstancedChild, string>;
+/**
+ * 用户继承的「逻辑实例」基类。自身不参与渲染，只描述"一个实例"的位置 / 颜色 / 事件。
+ *
+ * 用法：
+ * ```ts
+ * class Cube extends InstancedChild {
+ *   static geometry = new BoxGeometry(1, 1, 1);
+ *   static material = new MeshStandardMaterial({ color: 0xffffff });
+ *   constructor() {
+ *     super();
+ *     this.addEventListener("click", () => {
+ *       this.setColor("#ff0000");
+ *       this.position.set(0, 0, 0);
+ *     });
+ *   }
+ * }
+ * const cube = new Cube();
+ * cube.position.set(1, 2, 3);
+ * threeBase.scene.add(cube); // 加进任意层级即可
+ * ```
+ *
+ * ThreeBase 里固定的 InstancedGroup 会自动把「同 geometry+material」（或「同 instanceUrl+animation」）
+ * 的 InstancedChild 合并进同一个 InstancedMesh 批量渲染，无需用户管理实例缓冲。
+ */
+export default class InstancedChild extends Object3D {
+    /** 内置几何模式：子类覆盖这两个静态字段 */
+    static geometry?: BufferGeometry;
+    /** 内置几何模式材质 */
+    static material?: Material;
+    /** GLB 模式：模型地址（与 geometry/material 互斥，优先于内置） */
+    static instanceUrl?: string;
+    /** GLB 模式：要播放的动画剪辑名；不同动画 = 不同 batch（彼此独立） */
+    static animation?: string;
+    /** GLB 模式：模板（含材质）加载完成后回调，用于按需修正材质（如瓷器瓶 metalness=1 改 0） */
+    static prepareTemplate?: (template: InstancedTemplate) => void;
+    /** 实例颜色，写入 InstancedMesh.instanceColor */
+    color: Color;
+    /**
+     * 脏标记：true 时本帧由 InstancedGroup 把本实例的 matrix/color 写回实例缓冲，
+     * 写完后立即置 false —— 避免没有改动时重复写入真正参与渲染的 InstancedMesh。
+     */
+    needUpdate: boolean;
+    /** 模板是否就绪（GLB 异步加载完成后置 true） */
+    templateReady: boolean;
+    /**
+     * 第一人称碰撞检测标记：为 true 时，本实例所属 batch 的 InstancedMesh 会被打上
+     * `userData.fpsCollision = true`，从而被 FPScontrol 的碰撞射线命中（实例自身的世界矩阵即碰撞体位置）。
+     * 需配合 three-base 的 FPScontrol 使用（详见 FPSDemo 示例页）。
+     *
+     * ⚠️ 语义约束：真实几何合并在同一个 InstancedMesh 里，故碰撞以「整个 batch
+     * （相同 geometry+material / 相同 instanceUrl+animation 的所有实例）」为单位开关——
+     * 同一 batch 内的所有实例要么都参与碰撞、要么都不参与。若只想让部分实例参与碰撞，
+     * 请把它们拆成不同的 InstancedChild 子类（不同 geometry 或不同 batchKey）。
+     */
+    fpsCollision: boolean;
+    /**
+     * 自动脏检测开关（实验用，默认开）：
+     * - true：markDirtyIfWorldChanged 每帧比对 matrixWorld，变化则自动置 needUpdate（位置/旋转/缩放变化无需手动置位）；
+     * - false：关闭自动检测，仅手动置 needUpdate（如 setColor）的实例才会写回实例缓冲。
+     * 关闭后，静态布置的实例渲染不变，但「运动」（旋转/移动/缩放）将不再反映到画面（因为 matrixWorld 变了却没写回）。
+     * 可在运行时于控制台切换：InstancedChild.AUTO_MARK_DIRTY = true / false。
+     */
+    static AUTO_MARK_DIRTY: boolean;
+    /**
+     * 请求切换到的动画剪辑名（由所属 batch 每帧应用）。
+     * 实例化是"整批共享一个 mixer"，动画是 batch 级而非实例级；
+     * 默认 null 表示不主动切换，沿用 batch 构造时的 static animation。
+     */
+    private _pendingClip;
+    private _cachedWorld;
+    constructor(fpsCollision?: boolean);
+    /** 该实例归属哪个 batch 的 key：相同 geometry+material 或相同 instanceUrl+当前生效动画 合并为一类。
+     *  因 key 含「当前生效动画」，切换动画 = 实例在「glb+旧动画」与「glb+新动画」两个常驻 batch 间迁移，而非 batch 内切 mixer。 */
+    getBatchKey(): string;
+    /** 本实例当前生效的动画名：优先 playClip 请求，否则类声明的 static animation；用于分桶 key 与 batch mixer 构建 */
+    getEffectiveAnimation(): string | undefined;
+    /**
+     * 为一组 InstancedChild 构建"选择代理"（select proxy）：
+     * 用每个实例的世界矩阵 matrixWorld + 同款 geometry/material 重建独立网格，
+     * 供 stroke_pass 单独渲染其深度 / 灰度，从而得到这组实例"专属"的描边。
+     *
+     * 为什么需要它：InstancedChild 是纯逻辑节点（无几何），真实几何在 InstancedGroup 合并出的
+     * InstancedMesh 里，且一个 InstancedMesh 通常包含很多实例。要单独描边"某一个 / 某一组"实例，
+     * 无法靠直接渲染该 InstancedChild（空）或整个 InstancedMesh（会描到所有实例）。
+     * 本方法把目标实例重新"画"成一份独立几何，就能像普通 Mesh 一样单独取深度、单独描边。
+     *
+     * 关键点：
+     * - 用 instance.matrixWorld 直接作为代理网格的 local matrix（代理本身不在 scene 内、无父变换），
+     *   因此代理在屏幕上的位置 / 深度与真实实例严格一致，描边轮廓正好贴合，且能被同一张 baseDepthTexture 正确遮挡；
+     * - 代理对象通常注册到 ThreeBase.addStrokeObject（不在 scene 内），由渲染管线在效果阶段描边，
+     *   不会被正常 base pass 重复绘制。
+     *
+     * 仅支持内置几何模式（static geometry + static material）；GLB 模式的几何由 batch 解析，
+     * 需从对应 InstancedBatch 取几何，此处暂跳过（无 static geometry 的实例不进代理）。
+     *
+     * @param children 要描边的一组实例（如某个 Group 的全部 InstancedChild）
+     * @returns 代理 Group（含顺序与 children 一一对应的代理网格）；若没有任何可重建的实例则返回 null
+     */
+    static buildSelectProxy(children: InstancedChild[], options?: SelectProxyOptions): {
+        proxy: Group;
+        sources: InstancedChild[];
+    } | null;
+    /** 把代理网格的矩阵同步到各源实例最新的 matrixWorld（组旋转 / 实例移动时描边跟着动）。
+     *  代理网格与 sources 一一对应（顺序由 buildSelectProxy 保证）。 */
+    static syncSelectProxy(proxy: Group): void;
+    /** 设置实例颜色（自动置 needUpdate） */
+    setColor(c: Color | number | string): this;
+    /**
+     * 请求切换本实例的动画剪辑。batch 按「glb + 当前生效动画」分桶（每个动画一个常驻 InstancedBatch），
+     * 调用 playClip 只改变本实例的生效动画，下一帧 getBatchKey 随之变化，实例便自动从旧动画 batch
+     * 迁移到新动画 batch（两 batch 常驻、不销毁）。传 null 恢复为 static animation。
+     * 例：soldier.playClip("Walk") / soldier.playClip("Idle")
+     */
+    playClip(name: string | null): this;
+    /** 供 InstancedBatch 每帧读取当前请求的动画剪辑 */
+    get pendingClip(): string | null;
+    /**
+     * 位置 / 缩放 / 旋转直接用 three 原生写法即可（position.set / scale.setScalar / rotation.set），
+     * 无需任何自定义 setter；任一变换变化都会由 InstancedGroup 每帧的 matrixWorld 比对自动置 needUpdate。
+     * 注：Vector3 在 three 0.167 没有 onChange 回调；Euler/Quaternion 虽有 onChange，但 three 内部已用它
+     * 同步 rotation↔quaternion，不能覆盖，故统一用 matrixWorld 比对兜底，最贴合 three 的变换检测机制。
+     */
+    /** 设置鼠标手势（悬停时光标样式）：pointer / grab / move / text / crosshair ... */
+    setCursor(c: string): this;
+    /** 由 InstancedGroup 每帧调用：世界矩阵变化则置 needUpdate（setPosition 等已置过，这里双保险） */
+    markDirtyIfWorldChanged(): void;
+    /** 从注册表移除（对象销毁时调用，避免内存泄漏） */
+    dispose(): void;
+    /**
+     * 声明本实例归属哪个 InstancedGroup（owner tag）。多组共存时用于隔离，
+     * 只有 owner 相同的 InstancedGroup 会收集本实例。
+     *
+     * 用法：`new Cube().setOwner("preview")`，配合 `new InstancedGroup("preview")`。
+     * 不调用则归属为空 —— 会被「未声明 owner 的组」（如 ThreeBase 默认组）收集，保持旧行为。
+     */
+    setOwner(tag: string): this;
+    /** 读取本实例的归属 tag（未声明返回 undefined） */
+    getOwner(): string | undefined;
+}