three-base 2.0.137 → 2.0.145

package/ThreeMouse.d.ts

@@ -1,5 +1,9 @@
-import { Object3D, Raycaster, Scene, Vector2, WebGLRenderer } from "three";
-import { Camera, Intersection } from "three";
+import { Camera, Intersection, Object3D, Raycaster, Scene, Vector2, WebGLRenderer } from "three";
+import { computeBoundsTree, acceleratedRaycast } from "three-mesh-bvh";
+import type InstancedGroup from "./instanced/InstancedGroup";
+/** Patch Mesh.raycast with BVH acceleration. Call once before using ThreeMouse. */
+export declare function initBVHRaycast(): void;
+export { computeBoundsTree, acceleratedRaycast };
 export interface ThreeMouseEvent extends Intersection {
     e: MouseEvent;
     renderer: WebGLRenderer;
@@ -10,6 +14,7 @@ export interface ThreeMouseEvent extends Intersection {
     x: number;
     y: number;
 }
+export type MouseEventType = "leftclick" | "rightclick" | "click" | "dbclick" | "mouseenter" | "mouseleave" | "mousemove" | "mousedown" | "mouseup";
 /**
  *  js 专用的鼠标拾取模型对象
  */
@@ -18,6 +23,7 @@ export default class ThreeMouse {
     _renderer: WebGLRenderer;
     _camera: Camera;
     _scene: Scene;
+    instancedGroup?: InstancedGroup;
     _mosePosition: Vector2;
     _mouseDownPosition: Vector2;
     _mesh_on?: Object3D;
@@ -25,16 +31,23 @@ export default class ThreeMouse {
     _raycaster: Raycaster;
     _frame: number;
     _mouseInRenderer: boolean;
-    _mousemoveEvent?: MouseEvent;
-    _mouseEvent?: MouseEvent;
+    _mousemoveEvent?: MouseEvent | PointerEvent;
+    _mouseEvent?: MouseEvent | PointerEvent;
     _object3ds: Object3D[];
     _click_num: number;
     _getSelected(object3ds: Object3D[]): Intersection | undefined;
-    hasEvent(object?: Object3D, types?: Array<"leftclick" | "rightclick" | "click" | "dbclick" | "mouseenter" | "mouseleave" | "mousemove" | "mousedown" | "mouseup">): boolean;
-    hasCursor(object?: Object3D): boolean;
+    hasEvent(object?: Object3D, types?: Array<MouseEventType>): boolean;
+    hasCursor(object?: Object3D): boolean | undefined;
+    private resolveTarget;
     dispatchEvent(): void;
     _mouseleave: (e: MouseEvent) => void;
     _mousemove: (e: MouseEvent) => void;
-    _mousedown: (e: MouseEvent) => void;
+    _mousedown: (e: PointerEvent) => void;
     _mouseup: import("lodash").DebouncedFunc<(e: PointerEvent) => Promise<void>>;
+    /** 设置 Points（点云）拾取阈值（世界单位），数值越大越容易点中。
+     *  全景纹理标记改用 Points 后，通过它调节点击命中范围。 */
+    setPointsThreshold(threshold: number): void;
+    /** 移除 canvas 上的所有鼠标/指针事件监听（渲染器销毁时调用）。
+     *  注：mouseenter 为内联匿名监听，销毁时 canvas 已脱离 DOM，无需显式移除。 */
+    dispose(): void;
 }

package/ThreeMouse.js

@@ -3,13 +3,22 @@
 //
 //
 //
-// 启动鼠标事件
-import { Raycaster, Vector2 } from "three";
-import { Mesh } from "three";
+//  启动鼠标事件
+import { InstancedMesh, Mesh, Raycaster, Vector2 } from "three";
 import { debounce } from "lodash";
 import { computeBoundsTree, acceleratedRaycast } from "three-mesh-bvh";
-// Add the extension functions
-Mesh.prototype.raycast = acceleratedRaycast;
+/** 安全地分发事件到 Object3D 对象 */
+function dispatchObjectEvent(object, event) {
+    // 使用双重断言来安全地传递事件对象
+    object.dispatchEvent(event);
+}
+/** Patch Mesh.raycast with BVH acceleration. Call once before using ThreeMouse. */
+export function initBVHRaycast() {
+    if (Mesh.prototype.raycast !== acceleratedRaycast) {
+        Mesh.prototype.raycast = acceleratedRaycast;
+    }
+}
+export { computeBoundsTree, acceleratedRaycast };
 /**
  *  js 专用的鼠标拾取模型对象
  */
@@ -31,6 +40,8 @@ export default class ThreeMouse {
     _renderer;
     _camera;
     _scene;
+    // 固定的实例化分组器（由 ThreeBase 注入），用于把 InstancedMesh 命中路由到 InstancedChild
+    instancedGroup;
     // 鼠标在渲染器上面的位置
     _mosePosition = new Vector2(0, 0);
     // 鼠标按下的位置 如果和鼠标弹起的位置相同 才算一次有效的点击事件
@@ -70,17 +81,11 @@ export default class ThreeMouse {
         if (object["userData"] && object["userData"]["enableEvent"] === false) {
             return false;
         }
+        // 注意：three 的 hasEventListener(type, null) 因 indexOf(null) 永远 -1 而恒返回 false，
+        // 无法用来判断"是否存在任意监听器"。改为直接读取私有 _listeners 表判断该类型是否有监听。
+        const listeners = object._listeners;
         const hasevent = types.some((type) => {
-            //@ts-ignore
-            if (object["_listeners"] &&
-                object["_listeners"][type] &&
-                object["_listeners"][type][0]) {
-                return true;
-            }
-            // if (object["userData"] && object["userData"]["cursor"]) {
-            //     return true;
-            // }
-            return false;
+            return !!(listeners && listeners[type] && listeners[type].length > 0);
         });
         return hasevent;
     }
@@ -97,11 +102,26 @@ export default class ThreeMouse {
             return true;
         }
     }
+    // 把命中的对象解析为事件派发目标：若命中 InstancedMesh 且属于某个 batch，
+    // 则路由到对应的 InstancedChild（逻辑实例），使实例成为透明事件接收端。
+    resolveTarget(object, instanceId) {
+        if (object instanceof InstancedMesh && this.instancedGroup) {
+            const child = this.instancedGroup.resolveInstance(object, instanceId);
+            if (child) {
+                return child;
+            }
+        }
+        return object;
+    }
     // 分发鼠标拾取事件
     dispatchEvent() {
         // 提取有事件的对象
         const meshs = [];
         this._scene.traverseVisible((mesh) => {
+            // 逻辑实例节点（InstancedChild）自身不渲染、无几何，跳过收集（命中由 InstancedMesh 路由回来）
+            if (mesh.userData?.__instancedChild) {
+                return;
+            }
             // 判断对象是否有指定的事件
             if (this.hasCursor(mesh) ||
                 this.hasEvent(mesh, [
@@ -115,7 +135,7 @@ export default class ThreeMouse {
                     "mousedown",
                     "mouseup",
                 ])) {
-                if (mesh.isMesh &&
+                if (mesh instanceof Mesh &&
                     !mesh.geometry.boundsTree &&
                     mesh.geometry.attributes.position &&
                     mesh.geometry.attributes.position.count > 0) {
@@ -126,6 +146,10 @@ export default class ThreeMouse {
             }
         });
         this._object3ds = meshs;
+        // 收集可拾取的 InstancedMesh（仅含注册了监听的已就绪 batch）
+        if (this.instancedGroup) {
+            this.instancedGroup.collectPickable(meshs);
+        }
         // 没有鼠标事件就不往下执行了
         if (!this._mousemoveEvent || !this._mouseInRenderer) {
             return;
@@ -147,22 +171,26 @@ export default class ThreeMouse {
                 x: this._mousemoveEvent.x,
                 y: this._mousemoveEvent.y,
             });
+            // 命中 InstancedMesh 时，把派发目标重定向到对应的 InstancedChild
+            const _target = this.resolveTarget(intersection.object, intersection.instanceId);
+            if (_target)
+                MouseEvent.object = _target;
             // 触发滑动事件
             if (this._mesh_on === MouseEvent.object) {
                 if (this.hasEvent(MouseEvent.object, ["mousemove"])) {
                     MouseEvent.type = "mousemove";
-                    MouseEvent.object.dispatchEvent(MouseEvent);
+                    dispatchObjectEvent(MouseEvent.object, MouseEvent);
                 }
                 // 鼠标划入滑出事件
             }
             else if (this._mesh_on !== MouseEvent.object) {
                 if (this.hasEvent(this._mesh_on, ["mouseleave"])) {
                     MouseEvent.type = "mouseleave";
-                    this._mesh_on.dispatchEvent(MouseEvent);
+                    dispatchObjectEvent(this._mesh_on, MouseEvent);
                 }
                 if (this.hasEvent(MouseEvent.object, ["mouseenter"])) {
                     MouseEvent.type = "mouseenter";
-                    MouseEvent.object.dispatchEvent(MouseEvent);
+                    dispatchObjectEvent(MouseEvent.object, MouseEvent);
                 }
             }
             this._mesh_on = MouseEvent.object || undefined; // 设置为当前鼠标上的对象
@@ -179,7 +207,7 @@ export default class ThreeMouse {
         else {
             if (this.hasEvent(this._mesh_on, ["mouseleave"])) {
                 // 鼠标离开事件
-                this._mesh_on.dispatchEvent({
+                dispatchObjectEvent(this._mesh_on, {
                     e: this._mouseEvent,
                     renderer: this._renderer,
                     camera: this._camera,
@@ -202,7 +230,7 @@ export default class ThreeMouse {
         this._mouseInRenderer = false;
         // 鼠标离开事件
         if (this._mousemoveEvent && this.hasEvent(this._mesh_on, ["mouseleave"])) {
-            this._mesh_on.dispatchEvent({
+            dispatchObjectEvent(this._mesh_on, {
                 e: this._mouseEvent,
                 renderer: this._renderer,
                 camera: this._camera,
@@ -242,10 +270,12 @@ export default class ThreeMouse {
         if (!intersection || !this._mousemoveEvent) {
             return;
         }
-        this._mesh_Down = this._mesh_on = intersection.object;
+        // 命中 InstancedMesh 时把派发目标重定向到 InstancedChild，并改写 intersection.object
+        this._mesh_Down = this._mesh_on = this.resolveTarget(intersection.object, intersection.instanceId);
+        intersection.object = this._mesh_Down;
         // 触发鼠标按下事件
         if (this.hasEvent(this._mesh_Down, ["mousedown"])) {
-            this._mesh_Down.dispatchEvent({
+            dispatchObjectEvent(this._mesh_Down, {
                 e: this._mouseEvent,
                 ...intersection,
                 renderer: this._renderer,
@@ -268,9 +298,11 @@ export default class ThreeMouse {
         if (!intersection || !this._mousemoveEvent) {
             return;
         }
-        this._mesh_on = intersection.object;
+        // 命中 InstancedMesh 时把派发目标重定向到 InstancedChild，并改写 intersection.object
+        this._mesh_on = this.resolveTarget(intersection.object, intersection.instanceId);
+        intersection.object = this._mesh_on;
         if (this.hasEvent(this._mesh_on, ["mouseup"])) {
-            this._mesh_on.dispatchEvent({
+            dispatchObjectEvent(this._mesh_on, {
                 e: this._mouseEvent,
                 ...intersection,
                 renderer: this._renderer,
@@ -295,7 +327,7 @@ export default class ThreeMouse {
                 // 只点击了一次
                 if (this._click_num === 1) {
                     if (this.hasEvent(this._mesh_Down, ["click"])) {
-                        this._mesh_Down.dispatchEvent({
+                        dispatchObjectEvent(this._mesh_Down, {
                             e: this._mouseEvent,
                             ...intersection,
                             renderer: this._renderer,
@@ -309,7 +341,7 @@ export default class ThreeMouse {
                         });
                     }
                     if (this.hasEvent(this._mesh_Down, ["leftclick"]) && e.button === 0) {
-                        this._mesh_Down.dispatchEvent({
+                        dispatchObjectEvent(this._mesh_Down, {
                             e: this._mouseEvent,
                             ...intersection,
                             renderer: this._renderer,
@@ -324,7 +356,7 @@ export default class ThreeMouse {
                     }
                     if (this.hasEvent(this._mesh_Down, ["rightclick"]) &&
                         e.button === 2) {
-                        this._mesh_Down.dispatchEvent({
+                        dispatchObjectEvent(this._mesh_Down, {
                             e: this._mouseEvent,
                             ...intersection,
                             renderer: this._renderer,
@@ -342,7 +374,7 @@ export default class ThreeMouse {
                     if (this.hasEvent(this._mesh_Down, ["dbclick"]) &&
                         new Date().valueOf() - this._click_num > 1 &&
                         e.button === 0) {
-                        this._mesh_Down.dispatchEvent({
+                        dispatchObjectEvent(this._mesh_Down, {
                             e: this._mouseEvent,
                             ...intersection,
                             renderer: this._renderer,
@@ -359,7 +391,7 @@ export default class ThreeMouse {
             }
             else {
                 if (this.hasEvent(this._mesh_Down, ["click"])) {
-                    this._mesh_Down.dispatchEvent({
+                    dispatchObjectEvent(this._mesh_Down, {
                         e: this._mouseEvent,
                         ...intersection,
                         renderer: this._renderer,
@@ -373,7 +405,7 @@ export default class ThreeMouse {
                     });
                 }
                 if (this.hasEvent(this._mesh_Down, ["leftclick"]) && e.button === 0) {
-                    this._mesh_Down.dispatchEvent({
+                    dispatchObjectEvent(this._mesh_Down, {
                         e: this._mouseEvent,
                         ...intersection,
                         renderer: this._renderer,
@@ -387,7 +419,7 @@ export default class ThreeMouse {
                     });
                 }
                 if (this.hasEvent(this._mesh_Down, ["rightclick"]) && e.button === 2) {
-                    this._mesh_Down.dispatchEvent({
+                    dispatchObjectEvent(this._mesh_Down, {
                         e: this._mouseEvent,
                         ...intersection,
                         renderer: this._renderer,
@@ -404,4 +436,18 @@ export default class ThreeMouse {
             this._click_num = 0;
         }
     });
+    /** 设置 Points（点云）拾取阈值（世界单位），数值越大越容易点中。
+     *  全景纹理标记改用 Points 后，通过它调节点击命中范围。 */
+    setPointsThreshold(threshold) {
+        this._raycaster.params.Points.threshold = threshold;
+    }
+    /** 移除 canvas 上的所有鼠标/指针事件监听（渲染器销毁时调用）。
+     *  注：mouseenter 为内联匿名监听，销毁时 canvas 已脱离 DOM，无需显式移除。 */
+    dispose() {
+        const dom = this._renderer.domElement;
+        dom.removeEventListener("mouseleave", this._mouseleave, true);
+        dom.removeEventListener("mousemove", this._mousemove, true);
+        dom.removeEventListener("pointerdown", this._mousedown, true);
+        dom.removeEventListener("pointerup", this._mouseup, true);
+    }
 }