three-base 2.0.137 → 2.0.145

package/DirectionalLight.d.ts

@@ -1,6 +1,6 @@
-import { DirectionalLight as THREEDirectionalLight } from "three";
+import { DirectionalLight as THREEDirectionalLight, Group, Object3DEventMap } from "three";
 /** 平行光（dev 模式显示方向箭头 + 阴影范围线框） */
 export default class DirectionalLight extends THREEDirectionalLight {
     constructor(color?: string, intensity?: number);
-    private _devGroup;
+    _devGroup: Group<Object3DEventMap> | false;
 }

package/DirectionalLight.js

@@ -4,7 +4,7 @@
  * @Last Modified by: xiaosihan
  * @Last Modified time: 2024-06-08 14:00:00
  */
-import { DirectionalLight as THREEDirectionalLight, Group, BufferGeometry, BufferAttribute, LineBasicMaterial, LineSegments, ConeGeometry, MeshBasicMaterial, Mesh, } from "three";
+import { DirectionalLight as THREEDirectionalLight, Group, BufferGeometry, BufferAttribute, LineBasicMaterial, LineSegments, ConeGeometry, MeshBasicMaterial, Mesh } from "three";
 import threeUtils from "./threeUtils";
 import SpriteText from "./SpriteText";
 /** 平行光（dev 模式显示方向箭头 + 阴影范围线框） */

package/DirectionalLight.ts

@@ -0,0 +1,70 @@
+/*
+ * @Author: xiaosihan
+ * @Date: 2024-06-08 14:00:00
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2024-06-08 14:00:00
+ */
+import { DirectionalLight as THREEDirectionalLight, Group, BufferGeometry, BufferAttribute, LineBasicMaterial, LineSegments, ConeGeometry, MeshBasicMaterial, Mesh, Object3DEventMap } from "three";
+import threeUtils from "./threeUtils";
+import SpriteText from "./SpriteText";
+
+/** 平行光（dev 模式显示方向箭头 + 阴影范围线框） */
+export default class DirectionalLight extends THREEDirectionalLight {
+    constructor(color: string = "#fff", intensity: number = 1) {
+        super(color, intensity);
+    }
+
+    /* ============ dev 模式可视化 ============ */
+    _devGroup: Group<Object3DEventMap> | false = threeUtils.isDev && (() => {
+        const group = new Group();
+        // ——— 方向箭头 ———
+        const arrVerts = new Float32Array([
+            0, 0, 0.3, 0, 0, -2,
+            0, 0, -2, -0.2, 0, -1.6,
+            0, 0, -2, 0.2, 0, -1.6,
+        ]);
+        const arrGeo = new BufferGeometry();
+        arrGeo.setAttribute("position", new BufferAttribute(arrVerts, 3));
+        const arrLine = new LineSegments(arrGeo, new LineBasicMaterial({
+            color: this.color, depthTest: false,
+        }));
+        group.add(arrLine);
+        // ——— 阴影范围线框 ———
+        const half = 2;
+        const rectVerts = new Float32Array([
+            -half, -half, -2.2, half, -half, -2.2,
+            half, -half, -2.2, half, half, -2.2,
+            half, half, -2.2, -half, half, -2.2,
+            -half, half, -2.2, -half, -half, -2.2,
+        ]);
+        const rectGeo = new BufferGeometry();
+        rectGeo.setAttribute("position", new BufferAttribute(rectVerts, 3));
+        const rectLine = new LineSegments(rectGeo, new LineBasicMaterial({
+            color: this.color, depthTest: false,
+        }));
+        group.add(rectLine);
+        // ——— 小锥体箭头头部 ———
+        const cone = new Mesh(new ConeGeometry(0.15, 0.35, 6), new MeshBasicMaterial({ color: this.color, depthTest: false }));
+        cone.position.set(0, 0, -2);
+        cone.rotation.x = Math.PI / 2;
+        group.add(cone);
+        // ——— 标签 ———
+        const label = new SpriteText("平行光\n\n");
+        label.renderOrder = Infinity;
+        label.padding = 4;
+        label.strokeColor = "#333";
+        label.strokeWidth = 2;
+        label.position.set(0, -0.5, 0);
+        label.visible = false;
+        label.material.color = this.color;
+        label.material.sizeAttenuation = false;
+        label.scale.multiplyScalar(0.003);
+        group.add(label);
+        // ——— 交互 ———
+        group.userData = { cursor: "pointer" };
+        group.addEventListener("mouseenter", () => { label.visible = true; });
+        group.addEventListener("mouseleave", () => { label.visible = false; });
+        this.add(group);
+        return group;
+    })();
+}

package/EventMap.d.ts

@@ -0,0 +1,103 @@
+import type { Object3DEventMap, Vector3 } from "three";
+export interface LoadedEvent {
+    type: "loaded";
+}
+export interface LoadingEvent {
+    type: "loadding";
+}
+export interface OnLoadEvent {
+    type: "onLoad";
+}
+export interface BeforeRenderEvent {
+    type: "beforeRender";
+}
+export interface AfterRenderEvent {
+    type: "afterRender";
+}
+export interface RAFEvent {
+    type: "requestAnimationFrame";
+    timeTemp: number;
+    accumulate: number;
+}
+export interface KeyAddEvent {
+    type: "add";
+    [key: string]: unknown;
+}
+export interface KeyDeleteEvent {
+    type: "delete";
+    [key: string]: unknown;
+}
+export interface KeyEnterEvent {
+    type: "enter";
+    [key: string]: unknown;
+}
+export interface KeyChangeEvent {
+    type: "change";
+    direction: Vector3;
+}
+export interface FPSJumpStartEvent {
+    type: "jump_start";
+}
+export interface FPSJumpEndEvent {
+    type: "jump_end";
+}
+export interface FPSMoveStartEvent {
+    type: "move_start";
+}
+export interface FPSMoveEndEvent {
+    type: "move_end";
+}
+export interface MeshBaseEventMap extends Object3DEventMap {
+    "loaded": LoadedEvent;
+}
+export interface ThreeLoaderEventMap extends Object3DEventMap {
+    "loadding": LoadingEvent;
+    "onLoad": OnLoadEvent;
+}
+export interface ThreeBaseEventTypeMap extends Object3DEventMap {
+    "loadding": LoadingEvent;
+    "onLoad": OnLoadEvent;
+    "beforeRender": BeforeRenderEvent;
+    "afterRender": AfterRenderEvent;
+}
+export interface ThreeUtilsEventTypeMap extends Object3DEventMap {
+    "requestAnimationFrame": RAFEvent;
+}
+export interface KeyControlsEventTypeMap extends Object3DEventMap {
+    "add": KeyAddEvent;
+    "delete": KeyDeleteEvent;
+    "enter": KeyEnterEvent;
+    "change": KeyChangeEvent;
+}
+export interface FPScontrolEventTypeMap extends Object3DEventMap {
+    "jump_start": FPSJumpStartEvent;
+    "jump_end": FPSJumpEndEvent;
+    "move_start": FPSMoveStartEvent;
+    "move_end": FPSMoveEndEvent;
+}
+export interface SpriteWithHtmlEventMap extends Object3DEventMap {
+    "loaded": LoadedEvent;
+}
+export interface PlaneWithHtmlEventMap extends Object3DEventMap {
+    "loaded": LoadedEvent;
+}
+export interface InstancedMeshBaseEventMap extends Object3DEventMap {
+    "loaded": LoadedEvent;
+}
+/**
+ * Dispatch a custom-typed event on any Three.js object.
+ *
+ * Why a helper instead of overriding `dispatchEvent` on every class?
+ * Three.js `Object3D.dispatchEvent` is declared as:
+ *   <T extends keyof Object3DEventMap>(event: BaseEvent<T> & …) => void
+ * Overriding it to accept `{ type: "foo" }` breaks the method signature
+ * and causes cascading errors.  This helper sidesteps the issue cleanly
+ * by doing a single type assertion internally.
+ */
+export declare function dispatchCustomEvent<TEvt extends {
+    type: string;
+}>(target: {
+    dispatchEvent(event: {
+        type: string;
+    }): void;
+}, event: TEvt): void;

package/EventMap.js

@@ -0,0 +1,17 @@
+// ───────────────────────────────────────
+// Helper: type-safe custom-event dispatch
+// ───────────────────────────────────────
+/**
+ * Dispatch a custom-typed event on any Three.js object.
+ *
+ * Why a helper instead of overriding `dispatchEvent` on every class?
+ * Three.js `Object3D.dispatchEvent` is declared as:
+ *   <T extends keyof Object3DEventMap>(event: BaseEvent<T> & …) => void
+ * Overriding it to accept `{ type: "foo" }` breaks the method signature
+ * and causes cascading errors.  This helper sidesteps the issue cleanly
+ * by doing a single type assertion internally.
+ */
+export function dispatchCustomEvent(target, event) {
+    // Single type assertion - unavoidable because Three.js types are strict
+    target.dispatchEvent(event);
+}

package/EventMap.ts

@@ -0,0 +1,139 @@
+/*
+ * Global custom event maps for three-base.
+ *
+ * Provides typed interfaces for every custom event used throughout the
+ * codebase so that callers get full IntelliSense and type safety when
+ * listening for events.  Because Three.js ≥0.148 types EventDispatcher
+ * very strictly, we *cannot* override `dispatchEvent` on classes that
+ * extend Object3D / Mesh / Sprite — the signatures are incompatible.
+ *
+ * Instead of fighting Three.js types we use a **thin helper function**
+ * (`dispatchCustomEvent`) inside the consuming code.  This keeps all
+ * custom-event dispatches type-safe at the call-site while still
+ * receiving proper autocomplete when **subscribing** to events via
+ * `addEventListener` (which works because the generic EventDispatcher
+ * signature accepts the event-map types below).
+ *
+ * Summary of the pattern used:
+ *   - Listening / subscribing:  use the typed `EventDispatcher<TEventMap>`
+ *     generic so IDE autocomplete works.
+ *   - Dispatching:              call `dispatchCustomEvent(this, { type })`
+ *     which handles the one necessary cast internally.
+ */
+import type { Object3DEventMap, Vector3 } from "three";
+
+// ────────────────────────────────────────
+// Event payload interfaces
+// ────────────────────────────────────────
+
+export interface LoadedEvent { type: "loaded"; }
+export interface LoadingEvent { type: "loadding"; }
+export interface OnLoadEvent { type: "onLoad"; }
+export interface BeforeRenderEvent { type: "beforeRender"; }
+export interface AfterRenderEvent { type: "afterRender"; }
+
+export interface RAFEvent {
+    type: "requestAnimationFrame";
+    timeTemp: number;
+    accumulate: number;
+}
+
+export interface KeyAddEvent {
+    type: "add";
+    [key: string]: unknown;
+}
+
+export interface KeyDeleteEvent {
+    type: "delete";
+    [key: string]: unknown;
+}
+
+export interface KeyEnterEvent {
+    type: "enter";
+    [key: string]: unknown;
+}
+
+export interface KeyChangeEvent {
+    type: "change";
+    direction: Vector3;
+}
+
+export interface FPSJumpStartEvent { type: "jump_start"; }
+export interface FPSJumpEndEvent { type: "jump_end"; }
+export interface FPSMoveStartEvent { type: "move_start"; }
+export interface FPSMoveEndEvent { type: "move_end"; }
+
+// ────────────────────────────────────────
+// Event maps — merge custom events with
+// Three.js built-in Object3DEventMap so
+// both custom and native events get
+// autocomplete when subscribing.
+// ────────────────────────────────────────
+
+export interface MeshBaseEventMap extends Object3DEventMap {
+    "loaded": LoadedEvent;
+}
+
+export interface ThreeLoaderEventMap extends Object3DEventMap {
+    "loadding": LoadingEvent;
+    "onLoad": OnLoadEvent;
+}
+
+export interface ThreeBaseEventTypeMap extends Object3DEventMap {
+    "loadding": LoadingEvent;
+    "onLoad": OnLoadEvent;
+    "beforeRender": BeforeRenderEvent;
+    "afterRender": AfterRenderEvent;
+}
+
+export interface ThreeUtilsEventTypeMap extends Object3DEventMap {
+    "requestAnimationFrame": RAFEvent;
+}
+
+export interface KeyControlsEventTypeMap extends Object3DEventMap {
+    "add": KeyAddEvent;
+    "delete": KeyDeleteEvent;
+    "enter": KeyEnterEvent;
+    "change": KeyChangeEvent;
+}
+
+export interface FPScontrolEventTypeMap extends Object3DEventMap {
+    "jump_start": FPSJumpStartEvent;
+    "jump_end": FPSJumpEndEvent;
+    "move_start": FPSMoveStartEvent;
+    "move_end": FPSMoveEndEvent;
+}
+
+export interface SpriteWithHtmlEventMap extends Object3DEventMap {
+    "loaded": LoadedEvent;
+}
+
+export interface PlaneWithHtmlEventMap extends Object3DEventMap {
+    "loaded": LoadedEvent;
+}
+
+export interface InstancedMeshBaseEventMap extends Object3DEventMap {
+    "loaded": LoadedEvent;
+}
+
+// ───────────────────────────────────────
+// Helper: type-safe custom-event dispatch
+// ───────────────────────────────────────
+
+/**
+ * Dispatch a custom-typed event on any Three.js object.
+ *
+ * Why a helper instead of overriding `dispatchEvent` on every class?
+ * Three.js `Object3D.dispatchEvent` is declared as:
+ *   <T extends keyof Object3DEventMap>(event: BaseEvent<T> & …) => void
+ * Overriding it to accept `{ type: "foo" }` breaks the method signature
+ * and causes cascading errors.  This helper sidesteps the issue cleanly
+ * by doing a single type assertion internally.
+ */
+export function dispatchCustomEvent<TEvt extends { type: string }>(
+    target: { dispatchEvent(event: { type: string }): void },
+    event: TEvt,
+): void {
+    // Single type assertion - unavoidable because Three.js types are strict
+    target.dispatchEvent(event as unknown as { type: string });
+}

package/EventMesh.ts

@@ -0,0 +1,60 @@
+/*
+ * @Author: xiaosihan
+ * @Date: 2022-03-20 12:55:37
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2023-02-07 11:19:56
+ */
+import { BoxGeometry, BufferGeometry, CylinderGeometry, DoubleSide, Material, Mesh, MeshBasicMaterial, MeshNormalMaterial } from "three";
+import threeUtils from "./threeUtils";
+
+// 碰撞的形状
+export enum CollisionShaere {
+    cube = "cube",// 正方体
+    cylinder = "cylinder" // 圆柱体
+}
+
+/**
+ * 碰撞检测用的模型
+ */
+export default class EventMesh extends Mesh<BufferGeometry, Material> {
+    constructor(type: CollisionShaere = CollisionShaere.cube) {
+        super();
+        this.material = EventMesh.material;
+        this.setType(type);
+        // 生产环境 不用渲染
+        if (threeUtils.isProd) {
+            this.material = new MeshBasicMaterial({
+                side: DoubleSide,
+                transparent: true,
+                opacity: 0.25,
+                alphaTest: 1
+            });
+        }
+    }
+    static type: typeof CollisionShaere = CollisionShaere;
+    static material: MeshNormalMaterial = new MeshNormalMaterial({
+        side: DoubleSide,
+        transparent: true,
+        opacity: 0.3,
+    });
+    renderOrder: number = 99;
+    // 正方体 网格模型
+    static cubeGeo: BoxGeometry = new BoxGeometry(1, 1, 1, 1, 1, 1);
+    // 圆柱体 网格模型
+    static cylinderGeo: CylinderGeometry = new CylinderGeometry(1, 1, 1, 50, 1, false, 0, Math.PI * 2);
+    // 是否是碰撞检测专用的模型
+    isEventMesh: boolean = true;
+    setType(type: CollisionShaere): void {
+        switch (type) {
+            case EventMesh.type.cube:
+                this.geometry = EventMesh.cubeGeo;
+                break;
+            case EventMesh.type.cylinder:
+                this.geometry = EventMesh.cylinderGeo;
+                break;
+            default:
+                break;
+        }
+        this.geometry.computeVertexNormals();
+    }
+}

package/ExtrudeMesh.js

@@ -2,7 +2,7 @@
  * @Author: xiaosihan
  * @Date: 2022-06-08 14:20:52
  * @Last Modified by: xiaosihan
- * @Last Modified time: 2025-01-17 20:42:22
+ * @Last Modified time: 2025-06-25
  */
 import { clamp, cloneDeep, filter, first, get, isNumber, last } from "lodash";
 import { BufferAttribute, BufferGeometry, Matrix4, Mesh, Vector2, Vector3 } from "three";
@@ -238,18 +238,6 @@ export default class ExtrudeMesh extends Mesh {
                 }
             } // else
         });
-        // 清理圆角路径, 如果2个点相距0.001以内就删除一个点
-        // for (let i = 0; i < this.pointerWidthRadius.length; i++) {
-        //     while (
-        //         this.pointerWidthRadius[i] &&
-        //         this.pointerWidthRadius[i + 1] &&
-        //         this.computerPathLength(
-        //             this.pointerWidthRadius.slice(i, i + 2).map(p => p.vector3)
-        //         ) < 0.001
-        //     ) {
-        //         this.pointerWidthRadius.splice(i, 1);
-        //     }
-        // }
     }
     // 计算三维路径的总长度
     computerPathLength(points) {
@@ -270,8 +258,6 @@ export default class ExtrudeMesh extends Mesh {
     endMatrix4, // 终点位置的矩阵
     uvx, // uv.x 的起始位置
     shapePath) {
-        // // 反转路径, 这样uv 坐标看起来习惯一些
-        // shapePath = cloneDeep(shapePath).reverse();
         // 计算二维路径的总长度 作为uv坐标的边长
         let shapePathLength = this.computerPathLength(shapePath.map(p => [...p, 0]));
         // 挤出长度
@@ -283,11 +269,6 @@ export default class ExtrudeMesh extends Mesh {
         shapePath.map((P, index) => {
             if (index < shapePath.length - 1) {
                 // 计算出矩形面的4个顶点
-                //[pa....Pd]
-                //[.      .]
-                //[.      .]
-                //[.      .]
-                //[Pb....Pc]
                 let Pa = ExtrudeMesh.tempVector3
                     .set(0, P[1], -P[0])
                     .applyMatrix4(ExtrudeMesh.temp1Matrix4.set(...startMatrix4))
@@ -311,11 +292,6 @@ export default class ExtrudeMesh extends Mesh {
                 // 组成矩形的2个三角面
                 geometryPoint.push(...Pa, ...Pb, ...Pc, ...Pa, ...Pc, ...Pd);
                 // 计算出矩形面的4个顶点的uv坐标
-                //[Pauv..Pcuv]
-                //[.        .]
-                //[.        .]
-                //[.        .]
-                //[Pbuv..Pduv]
                 // 当前位置的 uv.y 位置
                 let currentUvy = this.computerPathLength([first(shapePath), ...shapePath.slice(0, index + 1)].map(sP => [...sP, 0])) / shapePathLength;
                 // 下一个坐标的 uv.y 位置