three-base 2.0.142 → 2.0.166

package/instanced/InstancedGroup.d.ts

@@ -1,43 +1,43 @@
-import { Object3D } from "three";
-import InstancedChild from "./InstancedChild";
-import InstancedBatch from "./InstancedBatch";
-/**
- * 固定在 ThreeBase.scene 里的分组器。每帧收集所有 InstancedChild，按 batchKey（glb+当前生效动画）分组，
- * 为每个 key 创建/复用 InstancedBatch，把实例的世界矩阵 / 颜色同步进真实 InstancedMesh。
- * batch 常驻（空桶不销毁），切换动画 = 实例在「glb+旧动画」「glb+新动画」两个常驻 batch 间迁移。
- *
- * 同时也是事件路由中枢：ThreeMouse 命中 InstancedMesh 后，通过本类把 (mesh, instanceId)
- * 还原成对应的 InstancedChild，使逻辑实例成为透明事件接收端。
- */
-export default class InstancedGroup extends Object3D {
-    /** batchKey -> InstancedBatch */
-    batches: Map<string, InstancedBatch>;
-    private _clock;
-    /**
-     * 本组的归属 tag（可选）。多 InstancedGroup 共存时用于隔离：
-     * - 声明了 owner 的组：**只**收集 `getOwner() === owner` 的实例（未声明归属的实例一律不收）；
-     * - 未声明 owner 的组（如 ThreeBase 的默认组）：只收**未声明归属**的实例，跳过已归属他组的实例。
-     * 这样主编辑器（默认组）与预览弹窗（owner="preview"）各自只画自己的实例，互不污染。
-     */
-    readonly owner?: string;
-    constructor(owner?: string);
-    /** 本组是否该收集该实例：按 owner 归属隔离（详见 owner 字段注释） */
-    private _accepts;
-    /** 每帧由 ThreeBase.render 在 scene.updateMatrixWorld 之后调用 */
-    update(): void;
-    /** 事件路由：命中 InstancedMesh 时返回对应 InstancedChild，否则 null */
-    resolveInstance(mesh: Object3D, instanceId: number | undefined): InstancedChild | null;
-    /** 收集可拾取的 InstancedMesh（已就绪 batch，且注册了监听或设置了 cursor 的），供 ThreeMouse 候选 */
-    collectPickable(out: Object3D[]): void;
-    /**
-     * 释放本组的全部 batch（实例缓冲 + 从组内摘除 mesh）。
-     *
-     * 用途：自建 InstancedGroup 的场景（如预览弹窗的独立轻量渲染器）在销毁时调用，
-     * 避免 InstancedMesh 的实例缓冲随组对象一起被丢弃却未释放。
-     *
-     * 注：batch 的 geometry/material **不会**被释放（InstancedBatch.dispose 刻意跳过）——
-     * 它们来自 `InstancedChild` 的 static geometry/material 或模板缓存，是跨实例共享资源。
-     * ⚠️ 默认的 ThreeBase 组**不要**调用本方法：它随应用生命周期常驻，batch 复用是设计意图。
-     */
-    dispose(): void;
-}
+import { Object3D } from "three";
+import InstancedChild from "./InstancedChild";
+import InstancedBatch from "./InstancedBatch";
+/**
+ * 固定在 ThreeBase.scene 里的分组器。每帧收集所有 InstancedChild，按 batchKey（glb+当前生效动画）分组，
+ * 为每个 key 创建/复用 InstancedBatch，把实例的世界矩阵 / 颜色同步进真实 InstancedMesh。
+ * batch 常驻（空桶不销毁），切换动画 = 实例在「glb+旧动画」「glb+新动画」两个常驻 batch 间迁移。
+ *
+ * 同时也是事件路由中枢：ThreeMouse 命中 InstancedMesh 后，通过本类把 (mesh, instanceId)
+ * 还原成对应的 InstancedChild，使逻辑实例成为透明事件接收端。
+ */
+export default class InstancedGroup extends Object3D {
+    /** batchKey -> InstancedBatch */
+    batches: Map<string, InstancedBatch>;
+    private _clock;
+    /**
+     * 本组的归属 tag（可选）。多 InstancedGroup 共存时用于隔离：
+     * - 声明了 owner 的组：**只**收集 `getOwner() === owner` 的实例（未声明归属的实例一律不收）；
+     * - 未声明 owner 的组（如 ThreeBase 的默认组）：只收**未声明归属**的实例，跳过已归属他组的实例。
+     * 这样主编辑器（默认组）与预览弹窗（owner="preview"）各自只画自己的实例，互不污染。
+     */
+    readonly owner?: string;
+    constructor(owner?: string);
+    /** 本组是否该收集该实例：按 owner 归属隔离（详见 owner 字段注释） */
+    private _accepts;
+    /** 每帧由 ThreeBase.render 在 scene.updateMatrixWorld 之后调用 */
+    update(): void;
+    /** 事件路由：命中 InstancedMesh 时返回对应 InstancedChild，否则 null */
+    resolveInstance(mesh: Object3D, instanceId: number | undefined): InstancedChild | null;
+    /** 收集可拾取的 InstancedMesh（已就绪 batch，且注册了监听或设置了 cursor 的），供 ThreeMouse 候选 */
+    collectPickable(out: Object3D[]): void;
+    /**
+     * 释放本组的全部 batch（实例缓冲 + 从组内摘除 mesh）。
+     *
+     * 用途：自建 InstancedGroup 的场景（如预览弹窗的独立轻量渲染器）在销毁时调用，
+     * 避免 InstancedMesh 的实例缓冲随组对象一起被丢弃却未释放。
+     *
+     * 注：batch 的 geometry/material **不会**被释放（InstancedBatch.dispose 刻意跳过）——
+     * 它们来自 `InstancedChild` 的 static geometry/material 或模板缓存，是跨实例共享资源。
+     * ⚠️ 默认的 ThreeBase 组**不要**调用本方法：它随应用生命周期常驻，batch 复用是设计意图。
+     */
+    dispose(): void;
+}

package/instanced/InstancedGroup.js

@@ -1,126 +1,126 @@
-import { Clock, Object3D } from "three";
-import { instancedChildRegistry, instancedChildOwner } from "./InstancedChild";
-import InstancedBatch from "./InstancedBatch";
-const PICK_EVENT_TYPES = [
-    "mouseenter",
-    "mouseleave",
-    "mousemove",
-    "click",
-    "leftclick",
-    "rightclick",
-    "dbclick",
-    "mousedown",
-    "mouseup",
-];
-/**
- * 固定在 ThreeBase.scene 里的分组器。每帧收集所有 InstancedChild，按 batchKey（glb+当前生效动画）分组，
- * 为每个 key 创建/复用 InstancedBatch，把实例的世界矩阵 / 颜色同步进真实 InstancedMesh。
- * batch 常驻（空桶不销毁），切换动画 = 实例在「glb+旧动画」「glb+新动画」两个常驻 batch 间迁移。
- *
- * 同时也是事件路由中枢：ThreeMouse 命中 InstancedMesh 后，通过本类把 (mesh, instanceId)
- * 还原成对应的 InstancedChild，使逻辑实例成为透明事件接收端。
- */
-export default class InstancedGroup extends Object3D {
-    /** batchKey -> InstancedBatch */
-    batches = new Map();
-    _clock = new Clock();
-    /**
-     * 本组的归属 tag（可选）。多 InstancedGroup 共存时用于隔离：
-     * - 声明了 owner 的组：**只**收集 `getOwner() === owner` 的实例（未声明归属的实例一律不收）；
-     * - 未声明 owner 的组（如 ThreeBase 的默认组）：只收**未声明归属**的实例，跳过已归属他组的实例。
-     * 这样主编辑器（默认组）与预览弹窗（owner="preview"）各自只画自己的实例，互不污染。
-     */
-    owner;
-    constructor(owner) {
-        super();
-        this.owner = owner;
-    }
-    /** 本组是否该收集该实例：按 owner 归属隔离（详见 owner 字段注释） */
-    _accepts(child) {
-        const childOwner = instancedChildOwner.get(child);
-        if (this.owner === undefined) {
-            // 无归属的组（ThreeBase 默认组）：只收未声明归属的实例，跳过已归属他组的
-            return childOwner === undefined;
-        }
-        // 有归属的组：只收 owner 完全一致的实例
-        return childOwner === this.owner;
-    }
-    /** 每帧由 ThreeBase.render 在 scene.updateMatrixWorld 之后调用 */
-    update() {
-        const delta = this._clock.getDelta();
-        // 1. 按 batchKey 收集所有活着的 InstancedChild（按 owner 归属过滤，避免多组互相污染）
-        const groups = new Map();
-        for (const child of instancedChildRegistry) {
-            if (!this._accepts(child))
-                continue;
-            // 强制刷新世界矩阵（实例可能位于任意层级，不依赖 scene 遍历顺序）
-            child.updateWorldMatrix(true, false);
-            child.markDirtyIfWorldChanged();
-            const key = child.getBatchKey();
-            let arr = groups.get(key);
-            if (!arr) {
-                arr = [];
-                groups.set(key, arr);
-            }
-            arr.push(child);
-        }
-        // 2. 创建 / 更新每个有实例的 batch（按 glb+当前动画分桶，每个动画一个常驻 batch）
-        for (const [key, children] of groups) {
-            let batch = this.batches.get(key);
-            if (!batch) {
-                batch = new InstancedBatch(key, children[0]);
-                this.batches.set(key, batch);
-                this.add(batch.group);
-            }
-            batch.sync(children, delta);
-        }
-        // 3. 持久化：实例已迁移走的空 batch 仍需 sync([]) 把 count 归零，避免残留上一帧实例；
-        //    但【不销毁】，使其常驻可复用 —— 切换动作时实例在常驻 batch 间迁移，无需频繁创建/销毁 InstancedBatch。
-        for (const [key, batch] of this.batches) {
-            if (!groups.has(key)) {
-                batch.sync([], delta);
-            }
-        }
-    }
-    /** 事件路由：命中 InstancedMesh 时返回对应 InstancedChild，否则 null */
-    resolveInstance(mesh, instanceId) {
-        if (instanceId === undefined) {
-            return null;
-        }
-        const key = mesh.userData?.__batchKey;
-        if (!key) {
-            return null;
-        }
-        const batch = this.batches.get(key);
-        if (!batch) {
-            return null;
-        }
-        return batch.resolveInstance(mesh, instanceId);
-    }
-    /** 收集可拾取的 InstancedMesh（已就绪 batch，且注册了监听或设置了 cursor 的），供 ThreeMouse 候选 */
-    collectPickable(out) {
-        for (const batch of this.batches.values()) {
-            if (batch.ready && (batch.hasListener(PICK_EVENT_TYPES) || batch.hasCursor())) {
-                for (const im of batch.pickables) {
-                    out.push(im);
-                }
-            }
-        }
-    }
-    /**
-     * 释放本组的全部 batch（实例缓冲 + 从组内摘除 mesh）。
-     *
-     * 用途：自建 InstancedGroup 的场景（如预览弹窗的独立轻量渲染器）在销毁时调用，
-     * 避免 InstancedMesh 的实例缓冲随组对象一起被丢弃却未释放。
-     *
-     * 注：batch 的 geometry/material **不会**被释放（InstancedBatch.dispose 刻意跳过）——
-     * 它们来自 `InstancedChild` 的 static geometry/material 或模板缓存，是跨实例共享资源。
-     * ⚠️ 默认的 ThreeBase 组**不要**调用本方法：它随应用生命周期常驻，batch 复用是设计意图。
-     */
-    dispose() {
-        for (const batch of this.batches.values()) {
-            batch.dispose();
-        }
-        this.batches.clear();
-    }
-}
+import { Clock, Object3D } from "three";
+import { instancedChildRegistry, instancedChildOwner } from "./InstancedChild";
+import InstancedBatch from "./InstancedBatch";
+const PICK_EVENT_TYPES = [
+    "mouseenter",
+    "mouseleave",
+    "mousemove",
+    "click",
+    "leftclick",
+    "rightclick",
+    "dbclick",
+    "mousedown",
+    "mouseup",
+];
+/**
+ * 固定在 ThreeBase.scene 里的分组器。每帧收集所有 InstancedChild，按 batchKey（glb+当前生效动画）分组，
+ * 为每个 key 创建/复用 InstancedBatch，把实例的世界矩阵 / 颜色同步进真实 InstancedMesh。
+ * batch 常驻（空桶不销毁），切换动画 = 实例在「glb+旧动画」「glb+新动画」两个常驻 batch 间迁移。
+ *
+ * 同时也是事件路由中枢：ThreeMouse 命中 InstancedMesh 后，通过本类把 (mesh, instanceId)
+ * 还原成对应的 InstancedChild，使逻辑实例成为透明事件接收端。
+ */
+export default class InstancedGroup extends Object3D {
+    /** batchKey -> InstancedBatch */
+    batches = new Map();
+    _clock = new Clock();
+    /**
+     * 本组的归属 tag（可选）。多 InstancedGroup 共存时用于隔离：
+     * - 声明了 owner 的组：**只**收集 `getOwner() === owner` 的实例（未声明归属的实例一律不收）；
+     * - 未声明 owner 的组（如 ThreeBase 的默认组）：只收**未声明归属**的实例，跳过已归属他组的实例。
+     * 这样主编辑器（默认组）与预览弹窗（owner="preview"）各自只画自己的实例，互不污染。
+     */
+    owner;
+    constructor(owner) {
+        super();
+        this.owner = owner;
+    }
+    /** 本组是否该收集该实例：按 owner 归属隔离（详见 owner 字段注释） */
+    _accepts(child) {
+        const childOwner = instancedChildOwner.get(child);
+        if (this.owner === undefined) {
+            // 无归属的组（ThreeBase 默认组）：只收未声明归属的实例，跳过已归属他组的
+            return childOwner === undefined;
+        }
+        // 有归属的组：只收 owner 完全一致的实例
+        return childOwner === this.owner;
+    }
+    /** 每帧由 ThreeBase.render 在 scene.updateMatrixWorld 之后调用 */
+    update() {
+        const delta = this._clock.getDelta();
+        // 1. 按 batchKey 收集所有活着的 InstancedChild（按 owner 归属过滤，避免多组互相污染）
+        const groups = new Map();
+        for (const child of instancedChildRegistry) {
+            if (!this._accepts(child))
+                continue;
+            // 强制刷新世界矩阵（实例可能位于任意层级，不依赖 scene 遍历顺序）
+            child.updateWorldMatrix(true, false);
+            child.markDirtyIfWorldChanged();
+            const key = child.getBatchKey();
+            let arr = groups.get(key);
+            if (!arr) {
+                arr = [];
+                groups.set(key, arr);
+            }
+            arr.push(child);
+        }
+        // 2. 创建 / 更新每个有实例的 batch（按 glb+当前动画分桶，每个动画一个常驻 batch）
+        for (const [key, children] of groups) {
+            let batch = this.batches.get(key);
+            if (!batch) {
+                batch = new InstancedBatch(key, children[0]);
+                this.batches.set(key, batch);
+                this.add(batch.group);
+            }
+            batch.sync(children, delta);
+        }
+        // 3. 持久化：实例已迁移走的空 batch 仍需 sync([]) 把 count 归零，避免残留上一帧实例；
+        //    但【不销毁】，使其常驻可复用 —— 切换动作时实例在常驻 batch 间迁移，无需频繁创建/销毁 InstancedBatch。
+        for (const [key, batch] of this.batches) {
+            if (!groups.has(key)) {
+                batch.sync([], delta);
+            }
+        }
+    }
+    /** 事件路由：命中 InstancedMesh 时返回对应 InstancedChild，否则 null */
+    resolveInstance(mesh, instanceId) {
+        if (instanceId === undefined) {
+            return null;
+        }
+        const key = mesh.userData?.__batchKey;
+        if (!key) {
+            return null;
+        }
+        const batch = this.batches.get(key);
+        if (!batch) {
+            return null;
+        }
+        return batch.resolveInstance(mesh, instanceId);
+    }
+    /** 收集可拾取的 InstancedMesh（已就绪 batch，且注册了监听或设置了 cursor 的），供 ThreeMouse 候选 */
+    collectPickable(out) {
+        for (const batch of this.batches.values()) {
+            if (batch.ready && (batch.hasListener(PICK_EVENT_TYPES) || batch.hasCursor())) {
+                for (const im of batch.pickables) {
+                    out.push(im);
+                }
+            }
+        }
+    }
+    /**
+     * 释放本组的全部 batch（实例缓冲 + 从组内摘除 mesh）。
+     *
+     * 用途：自建 InstancedGroup 的场景（如预览弹窗的独立轻量渲染器）在销毁时调用，
+     * 避免 InstancedMesh 的实例缓冲随组对象一起被丢弃却未释放。
+     *
+     * 注：batch 的 geometry/material **不会**被释放（InstancedBatch.dispose 刻意跳过）——
+     * 它们来自 `InstancedChild` 的 static geometry/material 或模板缓存，是跨实例共享资源。
+     * ⚠️ 默认的 ThreeBase 组**不要**调用本方法：它随应用生命周期常驻，batch 复用是设计意图。
+     */
+    dispose() {
+        for (const batch of this.batches.values()) {
+            batch.dispose();
+        }
+        this.batches.clear();
+    }
+}

package/instanced/InstancedGroup.ts

@@ -1,137 +1,137 @@
-import { Clock, Object3D } from "three";
-import InstancedChild, { instancedChildRegistry, instancedChildOwner } from "./InstancedChild";
-import InstancedBatch from "./InstancedBatch";
-
-const PICK_EVENT_TYPES = [
-    "mouseenter",
-    "mouseleave",
-    "mousemove",
-    "click",
-    "leftclick",
-    "rightclick",
-    "dbclick",
-    "mousedown",
-    "mouseup",
-];
-
-/**
- * 固定在 ThreeBase.scene 里的分组器。每帧收集所有 InstancedChild，按 batchKey（glb+当前生效动画）分组，
- * 为每个 key 创建/复用 InstancedBatch，把实例的世界矩阵 / 颜色同步进真实 InstancedMesh。
- * batch 常驻（空桶不销毁），切换动画 = 实例在「glb+旧动画」「glb+新动画」两个常驻 batch 间迁移。
- *
- * 同时也是事件路由中枢：ThreeMouse 命中 InstancedMesh 后，通过本类把 (mesh, instanceId)
- * 还原成对应的 InstancedChild，使逻辑实例成为透明事件接收端。
- */
-export default class InstancedGroup extends Object3D {
-    /** batchKey -> InstancedBatch */
-    batches = new Map<string, InstancedBatch>();
-    private _clock = new Clock();
-
-    /**
-     * 本组的归属 tag（可选）。多 InstancedGroup 共存时用于隔离：
-     * - 声明了 owner 的组：**只**收集 `getOwner() === owner` 的实例（未声明归属的实例一律不收）；
-     * - 未声明 owner 的组（如 ThreeBase 的默认组）：只收**未声明归属**的实例，跳过已归属他组的实例。
-     * 这样主编辑器（默认组）与预览弹窗（owner="preview"）各自只画自己的实例，互不污染。
-     */
-    readonly owner?: string;
-
-    constructor(owner?: string) {
-        super();
-        this.owner = owner;
-    }
-
-    /** 本组是否该收集该实例：按 owner 归属隔离（详见 owner 字段注释） */
-    private _accepts(child: InstancedChild): boolean {
-        const childOwner = instancedChildOwner.get(child);
-        if (this.owner === undefined) {
-            // 无归属的组（ThreeBase 默认组）：只收未声明归属的实例，跳过已归属他组的
-            return childOwner === undefined;
-        }
-        // 有归属的组：只收 owner 完全一致的实例
-        return childOwner === this.owner;
-    }
-
-    /** 每帧由 ThreeBase.render 在 scene.updateMatrixWorld 之后调用 */
-    update(): void {
-        const delta = this._clock.getDelta();
-
-        // 1. 按 batchKey 收集所有活着的 InstancedChild（按 owner 归属过滤，避免多组互相污染）
-        const groups = new Map<string, InstancedChild[]>();
-        for (const child of instancedChildRegistry) {
-            if (!this._accepts(child)) continue;
-            // 强制刷新世界矩阵（实例可能位于任意层级，不依赖 scene 遍历顺序）
-            child.updateWorldMatrix(true, false);
-            child.markDirtyIfWorldChanged();
-            const key = child.getBatchKey();
-            let arr = groups.get(key);
-            if (!arr) {
-                arr = [];
-                groups.set(key, arr);
-            }
-            arr.push(child);
-        }
-
-        // 2. 创建 / 更新每个有实例的 batch（按 glb+当前动画分桶，每个动画一个常驻 batch）
-        for (const [key, children] of groups) {
-            let batch = this.batches.get(key);
-            if (!batch) {
-                batch = new InstancedBatch(key, children[0]);
-                this.batches.set(key, batch);
-                this.add(batch.group);
-            }
-            batch.sync(children, delta);
-        }
-
-        // 3. 持久化：实例已迁移走的空 batch 仍需 sync([]) 把 count 归零，避免残留上一帧实例；
-        //    但【不销毁】，使其常驻可复用 —— 切换动作时实例在常驻 batch 间迁移，无需频繁创建/销毁 InstancedBatch。
-        for (const [key, batch] of this.batches) {
-            if (!groups.has(key)) {
-                batch.sync([], delta);
-            }
-        }
-    }
-
-    /** 事件路由：命中 InstancedMesh 时返回对应 InstancedChild，否则 null */
-    resolveInstance(mesh: Object3D, instanceId: number | undefined): InstancedChild | null {
-        if (instanceId === undefined) {
-            return null;
-        }
-        const key = (mesh as any).userData?.__batchKey as string | undefined;
-        if (!key) {
-            return null;
-        }
-        const batch = this.batches.get(key);
-        if (!batch) {
-            return null;
-        }
-        return batch.resolveInstance(mesh as any, instanceId);
-    }
-
-    /** 收集可拾取的 InstancedMesh（已就绪 batch，且注册了监听或设置了 cursor 的），供 ThreeMouse 候选 */
-    collectPickable(out: Object3D[]): void {
-        for (const batch of this.batches.values()) {
-            if (batch.ready && (batch.hasListener(PICK_EVENT_TYPES) || batch.hasCursor())) {
-                for (const im of batch.pickables) {
-                    out.push(im);
-                }
-            }
-        }
-    }
-
-    /**
-     * 释放本组的全部 batch（实例缓冲 + 从组内摘除 mesh）。
-     *
-     * 用途：自建 InstancedGroup 的场景（如预览弹窗的独立轻量渲染器）在销毁时调用，
-     * 避免 InstancedMesh 的实例缓冲随组对象一起被丢弃却未释放。
-     *
-     * 注：batch 的 geometry/material **不会**被释放（InstancedBatch.dispose 刻意跳过）——
-     * 它们来自 `InstancedChild` 的 static geometry/material 或模板缓存，是跨实例共享资源。
-     * ⚠️ 默认的 ThreeBase 组**不要**调用本方法：它随应用生命周期常驻，batch 复用是设计意图。
-     */
-    dispose(): void {
-        for (const batch of this.batches.values()) {
-            batch.dispose();
-        }
-        this.batches.clear();
-    }
-}
+import { Clock, Object3D } from "three";
+import InstancedChild, { instancedChildRegistry, instancedChildOwner } from "./InstancedChild";
+import InstancedBatch from "./InstancedBatch";
+
+const PICK_EVENT_TYPES = [
+    "mouseenter",
+    "mouseleave",
+    "mousemove",
+    "click",
+    "leftclick",
+    "rightclick",
+    "dbclick",
+    "mousedown",
+    "mouseup",
+];
+
+/**
+ * 固定在 ThreeBase.scene 里的分组器。每帧收集所有 InstancedChild，按 batchKey（glb+当前生效动画）分组，
+ * 为每个 key 创建/复用 InstancedBatch，把实例的世界矩阵 / 颜色同步进真实 InstancedMesh。
+ * batch 常驻（空桶不销毁），切换动画 = 实例在「glb+旧动画」「glb+新动画」两个常驻 batch 间迁移。
+ *
+ * 同时也是事件路由中枢：ThreeMouse 命中 InstancedMesh 后，通过本类把 (mesh, instanceId)
+ * 还原成对应的 InstancedChild，使逻辑实例成为透明事件接收端。
+ */
+export default class InstancedGroup extends Object3D {
+    /** batchKey -> InstancedBatch */
+    batches = new Map<string, InstancedBatch>();
+    private _clock = new Clock();
+
+    /**
+     * 本组的归属 tag（可选）。多 InstancedGroup 共存时用于隔离：
+     * - 声明了 owner 的组：**只**收集 `getOwner() === owner` 的实例（未声明归属的实例一律不收）；
+     * - 未声明 owner 的组（如 ThreeBase 的默认组）：只收**未声明归属**的实例，跳过已归属他组的实例。
+     * 这样主编辑器（默认组）与预览弹窗（owner="preview"）各自只画自己的实例，互不污染。
+     */
+    readonly owner?: string;
+
+    constructor(owner?: string) {
+        super();
+        this.owner = owner;
+    }
+
+    /** 本组是否该收集该实例：按 owner 归属隔离（详见 owner 字段注释） */
+    private _accepts(child: InstancedChild): boolean {
+        const childOwner = instancedChildOwner.get(child);
+        if (this.owner === undefined) {
+            // 无归属的组（ThreeBase 默认组）：只收未声明归属的实例，跳过已归属他组的
+            return childOwner === undefined;
+        }
+        // 有归属的组：只收 owner 完全一致的实例
+        return childOwner === this.owner;
+    }
+
+    /** 每帧由 ThreeBase.render 在 scene.updateMatrixWorld 之后调用 */
+    update(): void {
+        const delta = this._clock.getDelta();
+
+        // 1. 按 batchKey 收集所有活着的 InstancedChild（按 owner 归属过滤，避免多组互相污染）
+        const groups = new Map<string, InstancedChild[]>();
+        for (const child of instancedChildRegistry) {
+            if (!this._accepts(child)) continue;
+            // 强制刷新世界矩阵（实例可能位于任意层级，不依赖 scene 遍历顺序）
+            child.updateWorldMatrix(true, false);
+            child.markDirtyIfWorldChanged();
+            const key = child.getBatchKey();
+            let arr = groups.get(key);
+            if (!arr) {
+                arr = [];
+                groups.set(key, arr);
+            }
+            arr.push(child);
+        }
+
+        // 2. 创建 / 更新每个有实例的 batch（按 glb+当前动画分桶，每个动画一个常驻 batch）
+        for (const [key, children] of groups) {
+            let batch = this.batches.get(key);
+            if (!batch) {
+                batch = new InstancedBatch(key, children[0]);
+                this.batches.set(key, batch);
+                this.add(batch.group);
+            }
+            batch.sync(children, delta);
+        }
+
+        // 3. 持久化：实例已迁移走的空 batch 仍需 sync([]) 把 count 归零，避免残留上一帧实例；
+        //    但【不销毁】，使其常驻可复用 —— 切换动作时实例在常驻 batch 间迁移，无需频繁创建/销毁 InstancedBatch。
+        for (const [key, batch] of this.batches) {
+            if (!groups.has(key)) {
+                batch.sync([], delta);
+            }
+        }
+    }
+
+    /** 事件路由：命中 InstancedMesh 时返回对应 InstancedChild，否则 null */
+    resolveInstance(mesh: Object3D, instanceId: number | undefined): InstancedChild | null {
+        if (instanceId === undefined) {
+            return null;
+        }
+        const key = (mesh as any).userData?.__batchKey as string | undefined;
+        if (!key) {
+            return null;
+        }
+        const batch = this.batches.get(key);
+        if (!batch) {
+            return null;
+        }
+        return batch.resolveInstance(mesh as any, instanceId);
+    }
+
+    /** 收集可拾取的 InstancedMesh（已就绪 batch，且注册了监听或设置了 cursor 的），供 ThreeMouse 候选 */
+    collectPickable(out: Object3D[]): void {
+        for (const batch of this.batches.values()) {
+            if (batch.ready && (batch.hasListener(PICK_EVENT_TYPES) || batch.hasCursor())) {
+                for (const im of batch.pickables) {
+                    out.push(im);
+                }
+            }
+        }
+    }
+
+    /**
+     * 释放本组的全部 batch（实例缓冲 + 从组内摘除 mesh）。
+     *
+     * 用途：自建 InstancedGroup 的场景（如预览弹窗的独立轻量渲染器）在销毁时调用，
+     * 避免 InstancedMesh 的实例缓冲随组对象一起被丢弃却未释放。
+     *
+     * 注：batch 的 geometry/material **不会**被释放（InstancedBatch.dispose 刻意跳过）——
+     * 它们来自 `InstancedChild` 的 static geometry/material 或模板缓存，是跨实例共享资源。
+     * ⚠️ 默认的 ThreeBase 组**不要**调用本方法：它随应用生命周期常驻，batch 复用是设计意图。
+     */
+    dispose(): void {
+        for (const batch of this.batches.values()) {
+            batch.dispose();
+        }
+        this.batches.clear();
+    }
+}