three-base 2.0.137 → 2.0.145

package/instanced/InstancedGroup.js

@@ -0,0 +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();
+    }
+}

package/instanced/InstancedGroup.ts

@@ -0,0 +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();
+    }
+}

package/{InstancedMeshBase.d.ts → instanced/InstancedMeshBase.d.ts}

@@ -1,14 +1,13 @@
-import { Color, Euler, InstancedBufferAttribute, InstancedMesh, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "three";
-import MeshBase from "./MeshBase";
+import { Color, Event, Euler, InstancedBufferAttribute, InstancedMesh, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "three";
+import MeshBase from "../MeshBase";
+import { DebouncedFuncLeading } from "lodash";
 export default class InstancedMeshBase extends MeshBase {
     constructor(url?: string);
-    isInstancedGroupMesh: boolean;
     count: number;
     size: Vector3;
     meshCollect: Record<string, Mesh[]>;
     instanceCollect: Record<string, InstancedMesh>;
     colorMap: Map<String, Color>;
-    children: InstancedMesh[];
     static _position: Vector3;
     static _scale: Vector3;
     static _rotation: Euler;
@@ -18,7 +17,7 @@ export default class InstancedMeshBase extends MeshBase {
     instanceColor: InstancedBufferAttribute;
     reset(...object: Object3D[]): this;
     loadModel(url: string | File | Array<File>, filename?: string): Promise<void>;
-    computeBoundingSphere: import("lodash").DebouncedFuncLeading<() => void>;
+    computeBoundingSphere: DebouncedFuncLeading<() => void>;
     setCount(count?: number): Promise<void>;
     setMatrixAt(index: number, matrix?: Matrix4): Promise<void>;
     setTRS(index: number, { position, rotation, scale, }: {
@@ -34,6 +33,6 @@ export default class InstancedMeshBase extends MeshBase {
     setColorAt(index: number, color: (instancedMesh: InstancedMesh) => Color | undefined): Promise<void>;
     getColorAt(index?: number): Promise<Color>;
     updateMatrixWorld(force?: boolean): void;
-    addEventListener(name: string, callback: (e: any) => void): Promise<void>;
-    removeEventListener(name: string, callback: (e: any) => void): void;
+    addEventListener<T extends string>(name: T, callback: (e: Event<T, this>) => void): Promise<void>;
+    removeEventListener<T extends string>(name: T, callback: (e: Event<T, this>) => void): void;
 }

package/{InstancedMeshBase.js → instanced/InstancedMeshBase.js}

@@ -2,19 +2,19 @@
  * @Author: xiaosihan
  * @Date: 2024-02-05 09:31:57
  * @Last Modified by: xiaosihan
- * @Last Modified time: 2024-06-07 22:14:53
+ * @Last Modified time: 2025-06-25
  */
 import { first, isString, throttle } from "lodash";
-import { Color, Euler, InstancedBufferAttribute, InstancedMesh, Matrix4, Quaternion, Vector3, } from "three";
-import MeshBase from "./MeshBase";
-import threeUtils from "./threeUtils";
-import threeLoader from "./threeLoader";
+import { Color, Euler, InstancedBufferAttribute, InstancedMesh, Matrix4, Quaternion, Vector3 } from "three";
+import MeshBase from "../MeshBase";
+import threeUtils from "../threeUtils";
+import threeLoader from "../threeLoader";
+import { dispatchCustomEvent } from "../EventMap";
 // 实例模型组对象
 export default class InstancedMeshBase extends MeshBase {
     constructor(url) {
         super(url);
     }
-    isInstancedGroupMesh = true;
     count = 0;
     size = new Vector3(1, 1, 1);
     meshCollect = {};
@@ -62,6 +62,7 @@ export default class InstancedMeshBase extends MeshBase {
                 }
                 return modelurl;
             }
+            return "";
         })();
         this.url = modelurl || "";
         if (!url) {
@@ -83,33 +84,20 @@ export default class InstancedMeshBase extends MeshBase {
         } while (MeshBase.loadModeling.get(this.url));
         if (MeshBase.models.get(this.url)) {
             const mesh = MeshBase.models.get(this.url);
-            // // 判断是否有动画
-            // this.hasAnimation = mesh.animations.length > 0;
-            // if (this.hasAnimation) {
-            //     const model = SkeletonUtils.clone(mesh);
-            //     this.mixer = new AnimationMixer(model);
-            //     this.animationActions = {};
-            //     mesh.animations.map(animation => {
-            //         const animationAction = this.mixer!.clipAction(animation).play();
-            //         animationAction.weight = 0;
-            //         this.animationActions[animation.name] = animationAction;
-            //     });
-            //     this.add(model);
-            // } else {
-            //     this.add(mesh.clone(true));
-            // }
+            // 兜底：与 MeshBase 一致，为缺失顶点法线的几何体补算法线，避免 AO 全黑与金属材质发黑
+            this.ensureNormals(mesh);
             this.size.copy(threeUtils.getSize(mesh));
             const { meshCollect, instanceCollect } = this;
             mesh.updateMatrixWorld(true);
-            // collect all mesh counts, in case there are more than one copy of the same mesh in this group
+            // collect all mesh counts
             mesh.traverse((obj) => {
                 const mesh = obj;
                 if (mesh.isMesh) {
                     mesh.matrixWorld.decompose(mesh.position, mesh.quaternion, mesh.scale);
                     mesh.rotation.setFromQuaternion(mesh.quaternion);
                     mesh.updateMatrix();
-                    // same geometry and same material consider as the same mesh
-                    const uuid = mesh.geometry.uuid + "/" + mesh.material.uuid;
+                    const materialUuid = mesh.material instanceof Array ? mesh.material[0].uuid : mesh.material.uuid;
+                    const uuid = mesh.geometry.uuid + "/" + materialUuid;
                     if (meshCollect[uuid]) {
                         meshCollect[uuid].push(mesh);
                     }
@@ -136,16 +124,16 @@ export default class InstancedMeshBase extends MeshBase {
             });
             // 加载完成事件
             await new Promise((resolve) => setTimeout(resolve, 30));
-            // 加载完成事件
             this.loaded = true;
-            this.dispatchEvent({ type: "loaded" });
+            dispatchCustomEvent(this, { type: "loaded" });
         }
     }
     // 更新包围盒
     computeBoundingSphere = throttle(() => {
-        this.children.map((instancedMesh) => {
+        for (const child of this.children) {
+            const instancedMesh = child;
             instancedMesh.computeBoundingSphere && instancedMesh.computeBoundingSphere();
-        });
+        }
     }, 1000);
     //初始实例矩阵的数量
     async setCount(count = 0) {
@@ -166,25 +154,28 @@ export default class InstancedMeshBase extends MeshBase {
         this.instanceMatrix = instanceMatrix;
         this.instanceColor = instanceColor;
         this.count = count;
-        this.children.map((instanceMesh) => {
-            const instanceMatrix = new InstancedBufferAttribute(new Float32Array(count * 16), 16);
-            const instanceColor = new InstancedBufferAttribute(new Float32Array(count * 3).fill(1), 3);
+        for (const child of this.children) {
+            const instanceMesh = child;
+            const im = new InstancedBufferAttribute(new Float32Array(count * 16), 16);
+            const ic = new InstancedBufferAttribute(new Float32Array(count * 3).fill(1), 3);
             for (let i = 0; i < count; i++) {
-                instanceMatrix.set(InstancedMeshBase._matrix.identity().toArray(), i * 16);
-                instanceColor.set([1, 1, 1], i * 3);
+                im.set(InstancedMeshBase._matrix.identity().toArray(), i * 16);
+                ic.set([1, 1, 1], i * 3);
             }
             for (let i = 0; i < instanceMesh.count; i++) {
-                instanceMatrix.copyAt(i, instanceMesh.instanceMatrix, i);
-                instanceColor.copyAt(i, instanceMesh.instanceColor, i);
+                im.copyAt(i, instanceMesh.instanceMatrix, i);
+                if (instanceMesh.instanceColor) {
+                    ic.copyAt(i, instanceMesh.instanceColor, i);
+                }
             }
-            instanceMesh.instanceMatrix = instanceMatrix;
-            instanceMesh.instanceColor = instanceColor;
+            instanceMesh.instanceMatrix = im;
+            instanceMesh.instanceColor = ic;
             instanceMesh.count = count;
-        });
+        }
     }
     // 设置矩阵
     async setMatrixAt(index, matrix = new Matrix4().identity()) {
-        const new_matrix = matrix.clone(); // 把矩阵克隆一下避免对象引用问题
+        const new_matrix = matrix.clone();
         await this.awaitLoaded();
         Object.keys(this.meshCollect).forEach((uuid) => {
             const instancedMesh = this.instanceCollect[uuid];
@@ -208,7 +199,6 @@ export default class InstancedMeshBase extends MeshBase {
             const instancedMesh = this.instanceCollect[uuid];
             const collect = this.meshCollect[uuid];
             collect.forEach((mesh, i) => {
-                //获取对应的模型的矩阵
                 instancedMesh.getMatrixAt(collect.length * index + i, InstancedMeshBase._matrix);
                 InstancedMeshBase._matrix.premultiply(mesh.matrix.clone().invert());
                 InstancedMeshBase._matrix.decompose(InstancedMeshBase._position, InstancedMeshBase._Quaternion, InstancedMeshBase._scale);
@@ -278,16 +268,15 @@ export default class InstancedMeshBase extends MeshBase {
     async addEventListener(name, callback) {
         super.addEventListener(name, callback);
         await this.awaitLoaded();
-        super.addEventListener(name, callback);
-        this.children.map((mesh) => {
-            mesh.addEventListener(name, callback);
-        });
+        for (const child of this.children) {
+            child.addEventListener(name, callback);
+        }
     }
     // 取消事件的监听
     removeEventListener(name, callback) {
         super.removeEventListener(name, callback);
-        this.children.map((mesh) => {
-            mesh.removeEventListener(name, callback);
-        });
+        for (const child of this.children) {
+            child.removeEventListener(name, callback);
+        }
     }
 }