three-base 2.0.172 → 2.0.180

package/instanced/InstancedBatch.d.ts

@@ -27,6 +27,13 @@ export default class InstancedBatch {
     private _currentClip?;
     /** 首例实例是否声明碰撞（构造时快照，buildMeshes 用它给 InstancedMesh 打标记） */
     private _sampleFpsCollision;
+    /**
+     * 首例实例所在类是否声明 `static panoIndexAttribute`（构造时快照，与 _sampleFpsCollision 同一套路）：
+     * true ⇒ buildMeshes 给本 batch 克隆一份渲染用几何并挂上逐实例 `aPanoIndex`（全景序号直取着色器读它）。
+     */
+    private _samplePanoIndexAttr;
+    /** 本 batch 自己挂上去的逐实例 `aPanoIndex` 缓冲（与 _meshes 顺序对齐；未启用则为空数组） */
+    private _panoAttrs;
     /** 当前正在播放的 AnimationAction（切换时先 stop 旧的） */
     private _currentAction?;
     /** 非骨骼动画：需每帧烘焙节点变换的几何列表（与 _meshes 顺序对齐） */
@@ -43,7 +50,7 @@ export default class InstancedBatch {
     /** 根据当前首批实例的 fpsCollision 标记，把真实 InstancedMesh 的 userData.fpsCollision 同步过去，
      *  并在开启时通知所有 FPScontrol 重建碰撞列表。碰撞以整个 batch 为单位开关。 */
     private _applyCollisionFlag;
-    /** 把单个实例的 matrix + color 写入所有 submesh 的对应槽位 */
+    /** 把单个实例的 matrix + color +（若启用）全景序号写入所有 submesh 的对应槽位 */
     private writeInstance;
     /** 事件路由：给定 InstancedMesh 与 instanceId，返回对应 InstancedChild */
     resolveInstance(mesh: InstancedMesh, instanceId: number): InstancedChild | null;
@@ -53,5 +60,11 @@ export default class InstancedBatch {
     hasCursor(): boolean;
     /** 拾取用 InstancedMesh 列表 */
     get pickables(): InstancedMesh[];
+    /** 只读快照（拓扑图面板用）：本 batch 当前持有的逻辑实例数 */
+    get childCount(): number;
+    /** 只读快照：实例缓冲容量（不够时按 step 扩容，从不缩容） */
+    get capacity(): number;
+    /** 只读快照：本 batch 的逻辑实例列表（只给引用，调用方不得增删） */
+    get childrenView(): readonly InstancedChild[];
     dispose(): void;
 }

package/instanced/InstancedBatch.js

@@ -111,6 +111,13 @@ export default class InstancedBatch {
     _currentClip;
     /** 首例实例是否声明碰撞（构造时快照，buildMeshes 用它给 InstancedMesh 打标记） */
     _sampleFpsCollision = false;
+    /**
+     * 首例实例所在类是否声明 `static panoIndexAttribute`（构造时快照，与 _sampleFpsCollision 同一套路）：
+     * true ⇒ buildMeshes 给本 batch 克隆一份渲染用几何并挂上逐实例 `aPanoIndex`（全景序号直取着色器读它）。
+     */
+    _samplePanoIndexAttr = false;
+    /** 本 batch 自己挂上去的逐实例 `aPanoIndex` 缓冲（与 _meshes 顺序对齐；未启用则为空数组） */
+    _panoAttrs = [];
     /** 当前正在播放的 AnimationAction（切换时先 stop 旧的） */
     _currentAction;
     /** 非骨骼动画：需每帧烘焙节点变换的几何列表（与 _meshes 顺序对齐） */
@@ -123,6 +130,7 @@ export default class InstancedBatch {
         // 因 key 已含动画名，相同 glb+动画的实例都进同一个常驻 batch
         this._clipName = sample.getEffectiveAnimation();
         this._sampleFpsCollision = !!sample.fpsCollision;
+        this._samplePanoIndexAttr = !!sample.constructor.panoIndexAttribute;
         this._loading = loadTemplate(sample).then((t) => {
             const ctor = sample.constructor;
             // GLB 模板就绪后，交给子类按需修正材质（如瓶子 metalness 修正）
@@ -140,9 +148,22 @@ export default class InstancedBatch {
             return;
         }
         for (const sub of this.template.submeshes) {
-            const geom = sub.skinned && this.template.sharedGeometry
+            let geom = sub.skinned && this.template.sharedGeometry
                 ? this.template.sharedGeometry
                 : sub.geometry;
+            // 逐实例全景序号：本 batch 用**自己克隆的一份几何**挂 `aPanoIndex`（InstancedBufferAttribute
+            // 只能挂在 geometry 上，而 static geometry 跨 batch 共享 ⇒ 挂原几何会被别的 batch 覆盖，
+            // 详见 InstancedChild.panoIndexAttribute 的注释）。
+            // ⚠️ 骨骼蒙皮那条路不能克隆：sharedGeometry 每帧由 bakeSkinning 从 sourceGeometry 烤出来，
+            //    克隆一份就再也收不到烘焙结果（实例全部定格在绑定姿态）⇒ 蒙皮批次不加此属性。
+            if (this._samplePanoIndexAttr && !sub.skinned) {
+                const instGeom = geom.clone();
+                const panoAttr = new InstancedBufferAttribute(new Float32Array(this._capacity).fill(-1), 1);
+                panoAttr.setUsage(DynamicDrawUsage);
+                instGeom.setAttribute("aPanoIndex", panoAttr);
+                this._panoAttrs.push(panoAttr);
+                geom = instGeom;
+            }
             const im = new InstancedMesh(geom, sub.material, this._capacity);
             im.frustumCulled = false;
             im.instanceMatrix.setUsage(DynamicDrawUsage);
@@ -250,7 +271,8 @@ export default class InstancedBatch {
         // 容量按 100 为一阶阶梯增长、只增不降：1 个对象→100 矩阵，101 个→200 矩阵，201 个→300 ...
         // 避免每超出即整段 realloc，也避免从 200 回降到 100 造成反复分配/收缩。
         const newCap = Math.ceil(n / 100) * 100;
-        for (const im of this._meshes) {
+        for (let k = 0; k < this._meshes.length; k++) {
+            const im = this._meshes[k];
             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++) {
@@ -261,6 +283,14 @@ export default class InstancedBatch {
             }
             im.instanceMatrix = imMat;
             im.instanceColor = imCol;
+            // 逐实例全景序号缓冲跟着一起扩容（与上面两份实例缓冲同步换）。
+            // 不必搬旧值：唯一的调用点 ensureCapacity → compactWrite() 紧接着全量重写每个实例。
+            if (this._panoAttrs[k]) {
+                const pano = new InstancedBufferAttribute(new Float32Array(newCap).fill(-1), 1);
+                pano.setUsage(DynamicDrawUsage);
+                im.geometry.setAttribute("aPanoIndex", pano);
+                this._panoAttrs[k] = pano;
+            }
         }
         this._capacity = newCap;
     }
@@ -282,7 +312,7 @@ export default class InstancedBatch {
             FPScontrol.markAllCollidersDirty();
         }
     }
-    /** 把单个实例的 matrix + color 写入所有 submesh 的对应槽位 */
+    /** 把单个实例的 matrix + color +（若启用）全景序号写入所有 submesh 的对应槽位 */
     writeInstance(i, child) {
         for (let k = 0; k < this._meshes.length; k++) {
             const im = this._meshes[k];
@@ -299,6 +329,11 @@ export default class InstancedBatch {
                 im.setColorAt(i, child.color);
                 im.instanceColor.needsUpdate = true;
             }
+            const pano = this._panoAttrs[k];
+            if (pano) {
+                pano.setX(i, child.panoIndex);
+                pano.needsUpdate = true;
+            }
         }
     }
     /** 事件路由：给定 InstancedMesh 与 instanceId，返回对应 InstancedChild */
@@ -331,6 +366,18 @@ export default class InstancedBatch {
     get pickables() {
         return this._meshes;
     }
+    /** 只读快照（拓扑图面板用）：本 batch 当前持有的逻辑实例数 */
+    get childCount() {
+        return this._children.length;
+    }
+    /** 只读快照：实例缓冲容量（不够时按 step 扩容，从不缩容） */
+    get capacity() {
+        return this._capacity;
+    }
+    /** 只读快照：本 batch 的逻辑实例列表（只给引用，调用方不得增删） */
+    get childrenView() {
+        return this._children;
+    }
     dispose() {
         for (const im of this._meshes) {
             // 只释放 InstancedMesh 自带的实例缓冲（instanceMatrix / instanceColor），
@@ -341,6 +388,9 @@ export default class InstancedBatch {
         }
         this._meshes = [];
         this._nodeBake = [];
+        // 逐实例全景序号缓冲随 batch 一起散手（克隆的那份几何按本类既有规矩不 dispose：
+        // 它的 position/normal 数组与共享 static 几何同源，dispose 会把那份共享缓冲的 GPU 绑定一并摘掉）。
+        this._panoAttrs = [];
         if (this._mixer) {
             this._mixer.stopAllAction();
         }

package/instanced/InstancedBatch.ts

@@ -140,6 +140,13 @@ export default class InstancedBatch {
     private _currentClip?: string;
     /** 首例实例是否声明碰撞（构造时快照，buildMeshes 用它给 InstancedMesh 打标记） */
     private _sampleFpsCollision: boolean = false;
+    /**
+     * 首例实例所在类是否声明 `static panoIndexAttribute`（构造时快照，与 _sampleFpsCollision 同一套路）：
+     * true ⇒ buildMeshes 给本 batch 克隆一份渲染用几何并挂上逐实例 `aPanoIndex`（全景序号直取着色器读它）。
+     */
+    private _samplePanoIndexAttr: boolean = false;
+    /** 本 batch 自己挂上去的逐实例 `aPanoIndex` 缓冲（与 _meshes 顺序对齐；未启用则为空数组） */
+    private _panoAttrs: InstancedBufferAttribute[] = [];
     /** 当前正在播放的 AnimationAction（切换时先 stop 旧的） */
     private _currentAction?: AnimationAction;
     /** 非骨骼动画：需每帧烘焙节点变换的几何列表（与 _meshes 顺序对齐） */
@@ -153,6 +160,7 @@ export default class InstancedBatch {
         // 因 key 已含动画名，相同 glb+动画的实例都进同一个常驻 batch
         this._clipName = sample.getEffectiveAnimation();
         this._sampleFpsCollision = !!sample.fpsCollision;
+        this._samplePanoIndexAttr = !!(sample.constructor as typeof InstancedChild).panoIndexAttribute;
         this._loading = loadTemplate(sample).then((t) => {
             const ctor = sample.constructor as typeof InstancedChild;
             // GLB 模板就绪后，交给子类按需修正材质（如瓶子 metalness 修正）
@@ -171,10 +179,26 @@ export default class InstancedBatch {
             return;
         }
         for (const sub of this.template.submeshes) {
-            const geom =
+            let geom =
                 sub.skinned && this.template.sharedGeometry
                     ? this.template.sharedGeometry
                     : sub.geometry;
+            // 逐实例全景序号：本 batch 用**自己克隆的一份几何**挂 `aPanoIndex`（InstancedBufferAttribute
+            // 只能挂在 geometry 上，而 static geometry 跨 batch 共享 ⇒ 挂原几何会被别的 batch 覆盖，
+            // 详见 InstancedChild.panoIndexAttribute 的注释）。
+            // ⚠️ 骨骼蒙皮那条路不能克隆：sharedGeometry 每帧由 bakeSkinning 从 sourceGeometry 烤出来，
+            //    克隆一份就再也收不到烘焙结果（实例全部定格在绑定姿态）⇒ 蒙皮批次不加此属性。
+            if (this._samplePanoIndexAttr && !sub.skinned) {
+                const instGeom = geom.clone();
+                const panoAttr = new InstancedBufferAttribute(
+                    new Float32Array(this._capacity).fill(-1),
+                    1
+                );
+                panoAttr.setUsage(DynamicDrawUsage);
+                instGeom.setAttribute("aPanoIndex", panoAttr);
+                this._panoAttrs.push(panoAttr);
+                geom = instGeom;
+            }
             const im = new InstancedMesh(geom, sub.material, this._capacity);
             im.frustumCulled = false;
             im.instanceMatrix.setUsage(DynamicDrawUsage);
@@ -295,7 +319,8 @@ export default class InstancedBatch {
         // 容量按 100 为一阶阶梯增长、只增不降：1 个对象→100 矩阵，101 个→200 矩阵，201 个→300 ...
         // 避免每超出即整段 realloc，也避免从 200 回降到 100 造成反复分配/收缩。
         const newCap = Math.ceil(n / 100) * 100;
-        for (const im of this._meshes) {
+        for (let k = 0; k < this._meshes.length; k++) {
+            const im = this._meshes[k];
             const imMat = new InstancedBufferAttribute(new Float32Array(newCap * 16), 16);
             const imCol = new InstancedBufferAttribute(
                 new Float32Array(newCap * 3).fill(1),
@@ -309,6 +334,17 @@ export default class InstancedBatch {
             }
             im.instanceMatrix = imMat;
             im.instanceColor = imCol;
+            // 逐实例全景序号缓冲跟着一起扩容（与上面两份实例缓冲同步换）。
+            // 不必搬旧值：唯一的调用点 ensureCapacity → compactWrite() 紧接着全量重写每个实例。
+            if (this._panoAttrs[k]) {
+                const pano = new InstancedBufferAttribute(
+                    new Float32Array(newCap).fill(-1),
+                    1
+                );
+                pano.setUsage(DynamicDrawUsage);
+                im.geometry.setAttribute("aPanoIndex", pano);
+                this._panoAttrs[k] = pano;
+            }
         }
         this._capacity = newCap;
     }
@@ -333,7 +369,7 @@ export default class InstancedBatch {
         }
     }
 
-    /** 把单个实例的 matrix + color 写入所有 submesh 的对应槽位 */
+    /** 把单个实例的 matrix + color +（若启用）全景序号写入所有 submesh 的对应槽位 */
     private writeInstance(i: number, child: InstancedChild): void {
         for (let k = 0; k < this._meshes.length; k++) {
             const im = this._meshes[k];
@@ -350,6 +386,11 @@ export default class InstancedBatch {
                 im.setColorAt(i, child.color);
                 im.instanceColor.needsUpdate = true;
             }
+            const pano = this._panoAttrs[k];
+            if (pano) {
+                pano.setX(i, child.panoIndex);
+                pano.needsUpdate = true;
+            }
         }
     }
 
@@ -389,6 +430,21 @@ export default class InstancedBatch {
         return this._meshes;
     }
 
+    /** 只读快照（拓扑图面板用）：本 batch 当前持有的逻辑实例数 */
+    get childCount(): number {
+        return this._children.length;
+    }
+
+    /** 只读快照：实例缓冲容量（不够时按 step 扩容，从不缩容） */
+    get capacity(): number {
+        return this._capacity;
+    }
+
+    /** 只读快照：本 batch 的逻辑实例列表（只给引用，调用方不得增删） */
+    get childrenView(): readonly InstancedChild[] {
+        return this._children;
+    }
+
     dispose(): void {
         for (const im of this._meshes) {
             // 只释放 InstancedMesh 自带的实例缓冲（instanceMatrix / instanceColor），
@@ -399,6 +455,9 @@ export default class InstancedBatch {
         }
         this._meshes = [];
         this._nodeBake = [];
+        // 逐实例全景序号缓冲随 batch 一起散手（克隆的那份几何按本类既有规矩不 dispose：
+        // 它的 position/normal 数组与共享 static 几何同源，dispose 会把那份共享缓冲的 GPU 绑定一并摘掉）。
+        this._panoAttrs = [];
         if (this._mixer) {
             this._mixer.stopAllAction();
         }

package/instanced/InstancedChild.d.ts

@@ -66,10 +66,26 @@ export default class InstancedChild extends Object3D {
     static instanceUrl?: string;
     /** GLB 模式：要播放的动画剪辑名；不同动画 = 不同 batch（彼此独立） */
     static animation?: string;
+    /**
+     * 逐实例全景序号开关（内置几何模式）：声明 true 的类，其 batch 会给渲染用的几何挂上一份
+     * 名为 `aPanoIndex` 的 InstancedBufferAttribute，每帧把每个实例的 `panoIndex` 写进去 ——
+     * 「全景序号直取」投射着色器（MktMesh/mktMappingShader）就按它逐实例挑那张全景。
+     *
+     * ⚠️ 为什么属性挂在**克隆出来的一份几何**上而不是 `static geometry` 本身（见 InstancedBatch）：
+     *    three 的逐实例自定义属性只能挂在 geometry 上，而 `static geometry` 是**跨 batch 共享**的
+     *    （主编辑器与预览弹窗各有一份 InstancedMesh、实例序号各自独立排）⇒ 挂在原几何上等于两边
+     *    往同一块缓冲写各自的表，后写的把先写的覆盖掉，两边显示的图都会错。
+     */
+    static panoIndexAttribute: boolean;
     /** GLB 模式：模板（含材质）加载完成后回调，用于按需修正材质（如瓷器瓶 metalness=1 改 0） */
     static prepareTemplate?: (template: InstancedTemplate) => void;
     /** 实例颜色，写入 InstancedMesh.instanceColor */
     color: Color;
+    /**
+     * 逐实例全景序号（映射着色器的 `aPanoIndex`）：-1 = 未指派 ⇒ 着色器回落 `uFaceMissingColor` 深灰。
+     * 仅当本类声明 `static panoIndexAttribute = true` 时才会被写进实例缓冲（见该静态字段的注释）。
+     */
+    panoIndex: number;
     /**
      * 脏标记：true 时本帧由 InstancedGroup 把本实例的 matrix/color 写回实例缓冲，
      * 写完后立即置 false —— 避免没有改动时重复写入真正参与渲染的 InstancedMesh。
@@ -96,6 +112,12 @@ export default class InstancedChild extends Object3D {
      * 可在运行时于控制台切换：InstancedChild.AUTO_MARK_DIRTY = true / false。
      */
     static AUTO_MARK_DIRTY: boolean;
+    /**
+     * 累计创建过的逻辑实例数（只增不减）：构造函数里 +1，`dispose()` 不回退。
+     * 与 `instancedChildRegistry.size`（当前存活）配对看：已销毁 = 本值 - 存活数。
+     * 注册表是 Set，实例销毁就掉出去，看不到历史 ⇒ 「一共创建了多少个」只能靠这个计数器统计。
+     */
+    static createdTotal: number;
     /**
      * 请求切换到的动画剪辑名（由所属 batch 每帧应用）。
      * 实例化是"整批共享一个 mixer"，动画是 batch 级而非实例级；
@@ -140,6 +162,8 @@ export default class InstancedChild extends Object3D {
     static syncSelectProxy(proxy: Group): void;
     /** 设置实例颜色（自动置 needUpdate） */
     setColor(c: Color | number | string): this;
+    /** 设置逐实例全景序号（自动置 needUpdate，与 setColor 同一条脏标记路） */
+    setPanoIndex(v: number): this;
     /**
      * 请求切换本实例的动画剪辑。batch 按「glb + 当前生效动画」分桶（每个动画一个常驻 InstancedBatch），
      * 调用 playClip 只改变本实例的生效动画，下一帧 getBatchKey 随之变化，实例便自动从旧动画 batch

package/instanced/InstancedChild.js

@@ -48,10 +48,26 @@ export default class InstancedChild extends Object3D {
     static instanceUrl;
     /** GLB 模式：要播放的动画剪辑名；不同动画 = 不同 batch（彼此独立） */
     static animation;
+    /**
+     * 逐实例全景序号开关（内置几何模式）：声明 true 的类，其 batch 会给渲染用的几何挂上一份
+     * 名为 `aPanoIndex` 的 InstancedBufferAttribute，每帧把每个实例的 `panoIndex` 写进去 ——
+     * 「全景序号直取」投射着色器（MktMesh/mktMappingShader）就按它逐实例挑那张全景。
+     *
+     * ⚠️ 为什么属性挂在**克隆出来的一份几何**上而不是 `static geometry` 本身（见 InstancedBatch）：
+     *    three 的逐实例自定义属性只能挂在 geometry 上，而 `static geometry` 是**跨 batch 共享**的
+     *    （主编辑器与预览弹窗各有一份 InstancedMesh、实例序号各自独立排）⇒ 挂在原几何上等于两边
+     *    往同一块缓冲写各自的表，后写的把先写的覆盖掉，两边显示的图都会错。
+     */
+    static panoIndexAttribute = false;
     /** GLB 模式：模板（含材质）加载完成后回调，用于按需修正材质（如瓷器瓶 metalness=1 改 0） */
     static prepareTemplate;
     /** 实例颜色，写入 InstancedMesh.instanceColor */
     color = new Color(0xffffff);
+    /**
+     * 逐实例全景序号（映射着色器的 `aPanoIndex`）：-1 = 未指派 ⇒ 着色器回落 `uFaceMissingColor` 深灰。
+     * 仅当本类声明 `static panoIndexAttribute = true` 时才会被写进实例缓冲（见该静态字段的注释）。
+     */
+    panoIndex = -1;
     /**
      * 脏标记：true 时本帧由 InstancedGroup 把本实例的 matrix/color 写回实例缓冲，
      * 写完后立即置 false —— 避免没有改动时重复写入真正参与渲染的 InstancedMesh。
@@ -78,6 +94,12 @@ export default class InstancedChild extends Object3D {
      * 可在运行时于控制台切换：InstancedChild.AUTO_MARK_DIRTY = true / false。
      */
     static AUTO_MARK_DIRTY = true;
+    /**
+     * 累计创建过的逻辑实例数（只增不减）：构造函数里 +1，`dispose()` 不回退。
+     * 与 `instancedChildRegistry.size`（当前存活）配对看：已销毁 = 本值 - 存活数。
+     * 注册表是 Set，实例销毁就掉出去，看不到历史 ⇒ 「一共创建了多少个」只能靠这个计数器统计。
+     */
+    static createdTotal = 0;
     /**
      * 请求切换到的动画剪辑名（由所属 batch 每帧应用）。
      * 实例化是"整批共享一个 mixer"，动画是 batch 级而非实例级；
@@ -87,10 +109,22 @@ export default class InstancedChild extends Object3D {
     _cachedWorld = new Matrix4();
     constructor(fpsCollision = false) {
         super();
+        // 控制台取证用：three 给的默认值是 `type = "Object3D"` + `name = ""`，一整棵场景树里根本看不出哪个是逻辑实例、
+        // 是哪个模型来的。⇒ name = `InstancedChild-来源`（皇上旨 2026-10-12），来源 GLB 模式**只取 url 的文件名**
+        //   （`./models/bottle.glb` ⇒ `bottle.glb`，整条路径在控制台里太长且没信息量），内置几何模式没有 url ⇒ 取几何类型（BoxGeometry）。
+        // ⚠️ @types/three 把 Object3D.type 声明成 readonly（只允许声明类内部赋值），故这里走一次显式类型转换。
+        this.type = "InstancedChild";
+        const ctor = this.constructor;
+        // 文件名：切掉目录（最后一截）、再丢掉可能挂着的 ?查询 / #片段
+        const urlBase = ctor.instanceUrl ? ctor.instanceUrl.split("?")[0].split("#")[0].split("/").pop() : "";
+        const src = urlBase || (ctor.geometry ? ctor.geometry.type : "noSource");
+        this.name = `${this.type}-${src}`;
         this.fpsCollision = fpsCollision;
         // 标记：逻辑实例节点，ThreeMouse 收集候选时跳过（不渲染、无几何，靠 InstancedMesh 命中后路由回来）
         this.userData.__instancedChild = true;
         instancedChildRegistry.add(this);
+        // 累计统计走基类静态字段本身（⛔ 别用 this.constructor：子类各自有一份静态槽会漏计）
+        InstancedChild.createdTotal++;
     }
     /** 该实例归属哪个 batch 的 key：相同 geometry+material 或相同 instanceUrl+当前生效动画 合并为一类。
      *  因 key 含「当前生效动画」，切换动画 = 实例在「glb+旧动画」与「glb+新动画」两个常驻 batch 间迁移，而非 batch 内切 mixer。 */
@@ -207,6 +241,12 @@ export default class InstancedChild extends Object3D {
         this.needUpdate = true;
         return this;
     }
+    /** 设置逐实例全景序号（自动置 needUpdate，与 setColor 同一条脏标记路） */
+    setPanoIndex(v) {
+        this.panoIndex = v;
+        this.needUpdate = true;
+        return this;
+    }
     /**
      * 请求切换本实例的动画剪辑。batch 按「glb + 当前生效动画」分桶（每个动画一个常驻 InstancedBatch），
      * 调用 playClip 只改变本实例的生效动画，下一帧 getBatchKey 随之变化，实例便自动从旧动画 batch

package/instanced/InstancedChild.ts

@@ -78,11 +78,27 @@ export default class InstancedChild extends Object3D {
     static instanceUrl?: string;
     /** GLB 模式：要播放的动画剪辑名；不同动画 = 不同 batch（彼此独立） */
     static animation?: string;
+    /**
+     * 逐实例全景序号开关（内置几何模式）：声明 true 的类，其 batch 会给渲染用的几何挂上一份
+     * 名为 `aPanoIndex` 的 InstancedBufferAttribute，每帧把每个实例的 `panoIndex` 写进去 ——
+     * 「全景序号直取」投射着色器（MktMesh/mktMappingShader）就按它逐实例挑那张全景。
+     *
+     * ⚠️ 为什么属性挂在**克隆出来的一份几何**上而不是 `static geometry` 本身（见 InstancedBatch）：
+     *    three 的逐实例自定义属性只能挂在 geometry 上，而 `static geometry` 是**跨 batch 共享**的
+     *    （主编辑器与预览弹窗各有一份 InstancedMesh、实例序号各自独立排）⇒ 挂在原几何上等于两边
+     *    往同一块缓冲写各自的表，后写的把先写的覆盖掉，两边显示的图都会错。
+     */
+    static panoIndexAttribute: boolean = false;
     /** GLB 模式：模板（含材质）加载完成后回调，用于按需修正材质（如瓷器瓶 metalness=1 改 0） */
     static prepareTemplate?: (template: InstancedTemplate) => void;
 
     /** 实例颜色，写入 InstancedMesh.instanceColor */
     color: Color = new Color(0xffffff);
+    /**
+     * 逐实例全景序号（映射着色器的 `aPanoIndex`）：-1 = 未指派 ⇒ 着色器回落 `uFaceMissingColor` 深灰。
+     * 仅当本类声明 `static panoIndexAttribute = true` 时才会被写进实例缓冲（见该静态字段的注释）。
+     */
+    panoIndex: number = -1;
     /**
      * 脏标记：true 时本帧由 InstancedGroup 把本实例的 matrix/color 写回实例缓冲，
      * 写完后立即置 false —— 避免没有改动时重复写入真正参与渲染的 InstancedMesh。
@@ -109,6 +125,12 @@ export default class InstancedChild extends Object3D {
      * 可在运行时于控制台切换：InstancedChild.AUTO_MARK_DIRTY = true / false。
      */
     static AUTO_MARK_DIRTY: boolean = true;
+    /**
+     * 累计创建过的逻辑实例数（只增不减）：构造函数里 +1，`dispose()` 不回退。
+     * 与 `instancedChildRegistry.size`（当前存活）配对看：已销毁 = 本值 - 存活数。
+     * 注册表是 Set，实例销毁就掉出去，看不到历史 ⇒ 「一共创建了多少个」只能靠这个计数器统计。
+     */
+    static createdTotal: number = 0;
     /**
      * 请求切换到的动画剪辑名（由所属 batch 每帧应用）。
      * 实例化是"整批共享一个 mixer"，动画是 batch 级而非实例级；
@@ -120,10 +142,22 @@ export default class InstancedChild extends Object3D {
 
     constructor(fpsCollision: boolean = false) {
         super();
+        // 控制台取证用：three 给的默认值是 `type = "Object3D"` + `name = ""`，一整棵场景树里根本看不出哪个是逻辑实例、
+        // 是哪个模型来的。⇒ name = `InstancedChild-来源`（皇上旨 2026-10-12），来源 GLB 模式**只取 url 的文件名**
+        //   （`./models/bottle.glb` ⇒ `bottle.glb`，整条路径在控制台里太长且没信息量），内置几何模式没有 url ⇒ 取几何类型（BoxGeometry）。
+        // ⚠️ @types/three 把 Object3D.type 声明成 readonly（只允许声明类内部赋值），故这里走一次显式类型转换。
+        (this as { type: string }).type = "InstancedChild";
+        const ctor = this.constructor as typeof InstancedChild;
+        // 文件名：切掉目录（最后一截）、再丢掉可能挂着的 ?查询 / #片段
+        const urlBase = ctor.instanceUrl ? ctor.instanceUrl.split("?")[0].split("#")[0].split("/").pop() : "";
+        const src = urlBase || (ctor.geometry ? ctor.geometry.type : "noSource");
+        this.name = `${this.type}-${src}`;
         this.fpsCollision = fpsCollision;
         // 标记：逻辑实例节点，ThreeMouse 收集候选时跳过（不渲染、无几何，靠 InstancedMesh 命中后路由回来）
         this.userData.__instancedChild = true;
         instancedChildRegistry.add(this);
+        // 累计统计走基类静态字段本身（⛔ 别用 this.constructor：子类各自有一份静态槽会漏计）
+        InstancedChild.createdTotal++;
     }
 
     /** 该实例归属哪个 batch 的 key：相同 geometry+material 或相同 instanceUrl+当前生效动画 合并为一类。
@@ -265,6 +299,13 @@ export default class InstancedChild extends Object3D {
         return this;
     }
 
+    /** 设置逐实例全景序号（自动置 needUpdate，与 setColor 同一条脏标记路） */
+    setPanoIndex(v: number): this {
+        this.panoIndex = v;
+        this.needUpdate = true;
+        return this;
+    }
+
     /**
      * 请求切换本实例的动画剪辑。batch 按「glb + 当前生效动画」分桶（每个动画一个常驻 InstancedBatch），
      * 调用 playClip 只改变本实例的生效动画，下一帧 getBatchKey 随之变化，实例便自动从旧动画 batch

package/instanced/InstancedGroup.d.ts

@@ -1,6 +1,44 @@
 import { Object3D } from "three";
 import InstancedChild from "./InstancedChild";
 import InstancedBatch from "./InstancedBatch";
+/** 一个 batch 的合并情况快照（详见 `InstancedGroup.snapshot`） */
+export interface InstancedBatchSnapshot {
+    /** 分桶键：`geo:<geometryUuid>/<materialUuid>` 或 `url:<glb>:anim:<剪辑名>` */
+    key: string;
+    /** 本桶里的逻辑实例数（InstancedChild） */
+    childCount: number;
+    /** 真实 InstancedMesh 个数 = 本桶一帧的 draw call 数（GLB 多 submesh ⇒ 大于 1） */
+    drawCalls: number;
+    /** 实例缓冲容量（只增不减） */
+    capacity: number;
+    /** GLB 模板是否已就绪；false ⇒ 实例已登记但还没画出来 */
+    ready: boolean;
+    /** 每个 InstancedMesh 实际写入的实例数（与 drawCalls 一一对应） */
+    counts: number[];
+    /** 子实例的可读标签（name 优先，其次构造器名） */
+    children: string[];
+    /** 首个 InstancedMesh 的几何类型名（如 `BoxGeometry`）；模板未就绪时为空串 */
+    geomType: string;
+    /** 首个 InstancedMesh 的材质类型名（多材质为 `多材质`）；模板未就绪时为空串 */
+    matType: string;
+}
+/** 一个 InstancedGroup 的合并总览 */
+export interface InstancedGroupSnapshot {
+    /** 本组归属 tag；undefined = ThreeBase 默认组（只收未声明归属的实例） */
+    owner?: string;
+    batches: InstancedBatchSnapshot[];
+    /** 已收进各 batch 的实例总数 */
+    merged: number;
+    /** 全局注册表里的 InstancedChild 总数（含归属其他组的） */
+    registryTotal: number;
+    /**
+     * 累计创建过的 InstancedChild 总数（只增不减，dispose 不回退）。
+     * 与 `registryTotal` 配对即得「已销毁 = createdTotal - registryTotal」。
+     */
+    createdTotal: number;
+    /** 归属本组却没进任何 batch 的实例数：正常恒为 0，非 0 说明分桶/收集有漏 */
+    leaked: number;
+}
 /**
  * 固定在 ThreeBase.scene 里的分组器。每帧收集所有 InstancedChild，按 batchKey（glb+当前生效动画）分组，
  * 为每个 key 创建/复用 InstancedBatch，把实例的世界矩阵 / 颜色同步进真实 InstancedMesh。
@@ -29,6 +67,16 @@ export default class InstancedGroup extends Object3D {
     resolveInstance(mesh: Object3D, instanceId: number | undefined): InstancedChild | null;
     /** 收集可拾取的 InstancedMesh（已就绪 batch，且注册了监听或设置了 cursor 的），供 ThreeMouse 候选 */
     collectPickable(out: Object3D[]): void;
+    /**
+     * 只读快照：本组当前的合并情况，供调试面板画拓扑图。
+     *
+     * 归属判定（哪些注册表实例该由本组收集）刻意留在这里而不是让调用方自己判 ——
+     * 规则与 `_accepts` 必须同源，否则面板报的「未合并数」会与实际渲染不符。
+     *
+     * ⚠️ 子实例标签取 `name`，其次取构造器名：业务子类若没设 `name`，生产构建（压缩后）
+     * 构造器名会变成短标识符。要在拓扑图里认出实例，请给实例设 `name`（同 [[InstancedChild]] 的控制台可读命名约定）。
+     */
+    snapshot(): InstancedGroupSnapshot;
     /**
      * 释放本组的全部 batch（实例缓冲 + 从组内摘除 mesh）。
      *

package/instanced/InstancedGroup.js

@@ -1,5 +1,5 @@
 import { Clock, Object3D } from "three";
-import { instancedChildRegistry, instancedChildOwner } from "./InstancedChild";
+import InstancedChild, { instancedChildRegistry, instancedChildOwner } from "./InstancedChild";
 import InstancedBatch from "./InstancedBatch";
 const PICK_EVENT_TYPES = [
     "mouseenter",
@@ -107,6 +107,50 @@ export default class InstancedGroup extends Object3D {
             }
         }
     }
+    /**
+     * 只读快照：本组当前的合并情况，供调试面板画拓扑图。
+     *
+     * 归属判定（哪些注册表实例该由本组收集）刻意留在这里而不是让调用方自己判 ——
+     * 规则与 `_accepts` 必须同源，否则面板报的「未合并数」会与实际渲染不符。
+     *
+     * ⚠️ 子实例标签取 `name`，其次取构造器名：业务子类若没设 `name`，生产构建（压缩后）
+     * 构造器名会变成短标识符。要在拓扑图里认出实例，请给实例设 `name`（同 [[InstancedChild]] 的控制台可读命名约定）。
+     */
+    snapshot() {
+        const batches = [];
+        let merged = 0;
+        for (const batch of this.batches.values()) {
+            const childCount = batch.childCount;
+            merged += childCount;
+            const first = batch.pickables[0];
+            const mat = first?.material;
+            batches.push({
+                key: batch.key,
+                childCount,
+                drawCalls: batch.pickables.length,
+                capacity: batch.capacity,
+                ready: batch.ready,
+                counts: batch.pickables.map((im) => im.count),
+                children: batch.childrenView.map((c) => c.name || c.constructor.name),
+                geomType: first?.geometry.type ?? "",
+                matType: Array.isArray(mat) ? "多材质" : mat?.type ?? "",
+            });
+        }
+        let accepted = 0;
+        for (const child of instancedChildRegistry) {
+            if (this._accepts(child)) {
+                accepted++;
+            }
+        }
+        return {
+            owner: this.owner,
+            batches,
+            merged,
+            registryTotal: instancedChildRegistry.size,
+            createdTotal: InstancedChild.createdTotal,
+            leaked: accepted - merged,
+        };
+    }
     /**
      * 释放本组的全部 batch（实例缓冲 + 从组内摘除 mesh）。
      *