three-base 2.0.137 → 2.0.142

package/README.md

@@ -1,108 +1,139 @@
-```tsx
+# three-base
+
+一个基于 Three.js 的扩展库，提供常用的 3D 组件、动画、材质和后处理特效。
+
+## 特性
+
+- 🎨 **常用 3D 组件**：MeshBase、InstancedChild（实例化网格自动合并）、Text3D、SpriteText、PlaneText 等
+- 📦 **模型加载器**：支持 GLTF、FBX、OBJ、STL、PLY、USDZ 等格式
+- 🎮 **交互控制**：键盘控制、FPS 控制、轨道控制
+- ✨ **粒子特效**：火焰、水面、草地等
+- 🌟 **后处理特效**：Bloom、发光、描边、磨砂玻璃、SSAO 等
+- 📐 **工具类**：Transition 动画、ThreeUtils 工具函数等
+
+## 安装
+
+```bash
+npm install three-base
+```
 
-.创建一个 homeRender.ts 模块
-import { AmbientLight, BoxGeometry, Mesh, MeshLambertMaterial, PointLight } from "three";
+## 使用示例
+
+### 基础使用
+
+```tsx
 import ThreeBase from "three-base";
-import Transition from "three-base/Transition";
-import Fire from "three-base/Fire";
+import { Vector3 } from "three";
+
+// 创建渲染器
+const app = new ThreeBase();
 
-//qq389652405
-class HomeRender extends ThreeBase {
+// 设置容器
+app.setContainer(document.getElementById("canvas"));
 
-    constructor() {
-        super();
-    }
+// 设置相机位置
+app.resetLookAt({
+    center: new Vector3(0, 0, 0),
+    position: new Vector3(10, 10, 10)
+});
+```
 
-    // 环境光
-    ambientLight = (() => {
-        const ambientLight = new AmbientLight("#fff", 0.4);
-        this.scene.add(ambientLight);
-        return ambientLight;
-    })();
+### 创建动画对象
 
-    //点光源
-    pointLight = (() => {
-        const pointLight = new PointLight("#fff", 0.4);
-        pointLight.position.set(50, 40, 50);
-        this.scene.add(pointLight);
-        return pointLight;
-    })();
+```tsx
+import Transition from "three-base/Transition";
 
-    init() {
-        super.init();
-	// 使用这个方法来初始化相机的位置和朝向
-        this.resetLookAt({
-            center: new Vector3(0, 0, 0),
-            position: new Vector3(10.954, 19.452, 39.811)
-        });
+// 创建动画对象
+const transition = new Transition(
+    { x: 0, y: 0 }, // 初始值
+    [0.8, 0, 0.2, 1], // 贝塞尔曲线
+    1000 // 过渡时间
+);
 
-    }
+// 监听变化
+transition.onChange(({ x, y }) => {
+    mesh.position.set(x, y, 0);
+});
 
-    //火焰
-    fire = (() => {
-        const fire = new Fire();
-        fire.fireColor = "#ff2200";// 火焰的颜色
-        fire.fireScale = 1;// 火焰的整体缩放值
-        fire.fireRadius = 0.5;// 火焰的燃烧半径
-        fire.fireHeight = 3;// 火焰的高度
-        fire.position.set(0, 5, 0);
-        this.scene.add(fire);
-        return fire;
-    })();
+// 修改值（自动过渡动画）
+transition.set({ x: 10, y: 5 });
+```
 
-    box = (() => {
-        const geometry = new BoxGeometry(10, 10, 10);
-        const matearil = new MeshLambertMaterial({ color: 0xfff });
-        const mesh = new Mesh(geometry, matearil);
+### 加载模型
 
-	//创建一个动画对象
-        const transition = new Transition({ rotationY: 0 });
+```tsx
+import MeshBase from "three-base";
 
-        // 动画对象播放回调
-        transition.onChange(({ rotationY }) => {
-            mesh.rotation.y = rotationY;
-        });
+// 创建模型对象
+const model = new MeshBase("model.glb");
 
-        mesh.position.set(0, 0, 0);
-        mesh.userData = { cursor: "pointer", enableEvent: true };
+// 监听加载完成
+model.addEventListener("loaded", () => {
+    console.log("模型加载完成！");
+});
 
-        // 提供了常用的鼠标事件
-        mesh.addEventListener("click", e => { });
-        mesh.addEventListener("dbclick", e => { });
+// 添加到场景
+app.scene.add(model);
+```
 
-        mesh.addEventListener("leftclick", e => {
-            transition.set({ rotationY: Math.random() * 5 });
-        });
-        mesh.addEventListener("rightclick", e => { });
-        mesh.addEventListener("mouseenter", e => { });
-        mesh.addEventListener("mouseleave", e => { });
-        mesh.addEventListener("mousemove", e => { });
-        mesh.addEventListener("mousedown", e => { });
-        mesh.addEventListener("mouseup", e => { });
+### 火焰特效
 
-        this.scene.add(mesh);
-        return mesh;
-    })();
+```tsx
+import Fire from "three-base/Fire";
 
-}
+const fire = new Fire();
+fire.fireColor = "#ff2200";
+fire.fireScale = 1;
+fire.position.set(0, 5, 0);
+app.scene.add(fire);
+```
 
+## API 文档
 
-const homeRenderer = new HomeRender();
+### 核心类
 
-// 导出这个单例对象
-export default homeRenderer;
+- **ThreeBase**：基础渲染器类，封装了 WebGLRenderer、相机、场景等
+- **MeshBase**：模型基类，提供模型加载、动画播放等功能
+- **InstancedChild**：实例化网格自动合并基类（推荐），继承后框架每帧自动把同类实例合并进 InstancedMesh 批量渲染，支持内置几何 / GLB 多 submesh / GLB 骨骼动画共享姿态
+- **InstancedMeshBase**：底层手动实例缓冲工具，供生产代码使用
+- **Transition**：过渡动画类，提供平滑的数值过渡动画
 
+### 组件类
 
+- **Text3D**：3D 文字组件
+- **SpriteText / SpriteText2**：精灵文字组件
+- **PlaneText**：平面文字组件
+- **SpriteWithHtml / PlaneWithHtml**：支持 HTML 内容的组件
+- **SpriteModal1 / PlaneModal1**：弹窗组件
 
-2.添加到div里面
-import homeRenderer form "./homeRenderer.ts";
-homeRenderer.setContainer( document.getElementById("div") );
+### 特效类
 
+- **Fire**：火焰粒子特效
+- **Water**：水面特效
+- **Grass**：草地特效
+- **Mirror**：镜面反射
 
+### 后处理 Pass
 
+- **bloom_pass**：泛光特效
+- **glow_pass**：发光特效
+- **stroke_pass**：描边特效
+- **cover_pass**：颜色覆盖
+- **frosted_glass_pass**：磨砂玻璃特效
+- **ssao_pass**：屏幕空间环境光遮蔽
 
-```
+## 浏览器支持
+
+- Chrome (推荐)
+- Firefox
+- Safari
+- Edge
+
+## 许可证
+
+[MIT](./LICENSE)
 
-请尽量使用 vite 来打包
+## 相关链接
 
-代码: https://gitee.com/drm/vite_react_mobx_threebase
+- 示例代码：https://gitee.com/drm/vite_react_mobx_threebase
+- Three.js 文档：https://threejs.org/docs/

package/Sky/Sky.d.ts

@@ -1,9 +1,9 @@
-import { Mesh, MeshBasicMaterial, SphereGeometry } from "three";
-/**
- * 天空球
- */
-export default class Sky extends Mesh {
-    constructor();
-    static geometry: SphereGeometry;
-    material: MeshBasicMaterial;
-}
+import { Mesh, MeshBasicMaterial, SphereGeometry } from "three";
+/**
+ * 天空球
+ */
+export default class Sky extends Mesh {
+    constructor();
+    static geometry: SphereGeometry;
+    material: MeshBasicMaterial;
+}

package/Sky/Sky.js

@@ -1,22 +1,22 @@
-/*
- * @Author: xiaosihan
- * @Date: 2022-05-20 18:03:58
- * @Last Modified by: xiaosihan
- * @Last Modified time: 2022-12-27 09:54:23
- */
-import { DoubleSide, Mesh, MeshBasicMaterial, SphereGeometry } from "three";
-import threeLoader from "../threeLoader";
-import skyMapPNG from "./skyMap.png";
-/**
- * 天空球
- */
-export default class Sky extends Mesh {
-    constructor() {
-        super(Sky.geometry);
-    }
-    static geometry = new SphereGeometry(5000, 100, 100);
-    material = new MeshBasicMaterial({
-        side: DoubleSide,
-        map: threeLoader.getTexture(skyMapPNG),
-    });
-}
+/*
+ * @Author: xiaosihan
+ * @Date: 2022-05-20 18:03:58
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2022-12-27 09:54:23
+ */
+import { DoubleSide, Mesh, MeshBasicMaterial, SphereGeometry } from "three";
+import threeLoader from "../threeLoader";
+import skyMapPNG from "./skyMap.png";
+/**
+ * 天空球
+ */
+export default class Sky extends Mesh {
+    constructor() {
+        super(Sky.geometry);
+    }
+    static geometry = new SphereGeometry(5000, 100, 100);
+    material = new MeshBasicMaterial({
+        side: DoubleSide,
+        map: threeLoader.getTexture(skyMapPNG),
+    });
+}

package/Sky/Sky.ts

@@ -0,0 +1,22 @@
+/*
+ * @Author: xiaosihan
+ * @Date: 2022-05-20 18:03:58
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2022-12-27 09:54:23
+ */
+import { DoubleSide, Mesh, MeshBasicMaterial, SphereGeometry } from "three";
+import threeLoader from "../threeLoader";
+import skyMapPNG from "./skyMap.png";
+/**
+ * 天空球
+ */
+export default class Sky extends Mesh {
+    constructor() {
+        super(Sky.geometry);
+    }
+    static geometry: SphereGeometry = new SphereGeometry(5000, 100, 100);
+    material: MeshBasicMaterial = new MeshBasicMaterial({
+        side: DoubleSide,
+        map: threeLoader.getTexture(skyMapPNG),
+    });
+}

package/Sky/index.d.ts

@@ -1 +1 @@
-export { default } from "./Sky";
+export { default } from "./Sky";

package/Sky/index.js

@@ -1 +1 @@
-export { default } from "./Sky";
+export { default } from "./Sky";

package/Sky/index.ts

@@ -0,0 +1 @@
+export { default } from "./Sky";

package/SpotLight.d.ts

@@ -1,6 +1,6 @@
-import { SpotLight as THREESpotLight } from "three";
-/** 聚光灯（dev 模式显示光锥线框 + 灯体圆柱） */
-export default class SpotLight extends THREESpotLight {
-    constructor(color?: string, intensity?: number, distance?: number, angle?: number, penumbra?: number);
-    private _devGroup;
-}
+import { SpotLight as THREESpotLight, Group, Object3DEventMap } from "three";
+/** 聚光灯（dev 模式显示光锥线框 + 灯体圆柱） */
+export default class SpotLight extends THREESpotLight {
+    constructor(color?: string, intensity?: number, distance?: number, angle?: number, penumbra?: number);
+    _devGroup: Group<Object3DEventMap> | false;
+}

package/SpotLight.js

@@ -1,72 +1,72 @@
-/*
- * @Author: xiaosihan
- * @Date: 2024-06-08 14:00:00
- * @Last Modified by: xiaosihan
- * @Last Modified time: 2024-06-08 14:00:00
- */
-import { SpotLight as THREESpotLight, Group, BufferGeometry, BufferAttribute, LineBasicMaterial, LineSegments, CylinderGeometry, MeshBasicMaterial, Mesh, } from "three";
-import threeUtils from "./threeUtils";
-import SpriteText from "./SpriteText";
-/** 聚光灯（dev 模式显示光锥线框 + 灯体圆柱） */
-export default class SpotLight extends THREESpotLight {
-    constructor(color = "#fff", intensity = 1, distance = 10, angle = Math.PI / 6, penumbra = 0) {
-        super(color, intensity, distance, angle, penumbra);
-    }
-    /* ============ dev 模式可视化 ============ */
-    _devGroup = threeUtils.isDev && (() => {
-        const group = new Group();
-        // ——— 灯体圆柱 ———
-        const body = new Mesh(new CylinderGeometry(0.15, 0.2, 0.6, 12), new MeshBasicMaterial({ color: this.color, depthTest: false, wireframe: true }));
-        group.add(body);
-        // ——— 光锥线框 ———
-        const coneAngle = this.angle;
-        const coneDist = Math.min(this.distance || 10, 10);
-        const topR = 0.01;
-        const bottomR = Math.tan(coneAngle) * coneDist;
-        const coneVerts = [];
-        const rings = 8;
-        const segs = 24;
-        for (let r = 0; r <= rings; r++) {
-            const t = r / rings;
-            const z = -0.3 - t * coneDist;
-            const radius = topR + (bottomR - topR) * t;
-            for (let i = 0; i < segs; i++) {
-                const a0 = (i / segs) * Math.PI * 2;
-                const a1 = ((i + 1) / segs) * Math.PI * 2;
-                const x0 = Math.cos(a0) * radius, y0 = Math.sin(a0) * radius;
-                const x1 = Math.cos(a1) * radius, y1 = Math.sin(a1) * radius;
-                coneVerts.push(x0, y0, z, x1, y1, z);
-                if (r < rings) {
-                    const z2 = -0.3 - ((r + 1) / rings) * coneDist;
-                    const r2 = topR + (bottomR - topR) * ((r + 1) / rings);
-                    const x2 = Math.cos(a0) * r2, y2 = Math.sin(a0) * r2;
-                    coneVerts.push(x0, y0, z, x2, y2, z2);
-                }
-            }
-        }
-        const coneGeo = new BufferGeometry();
-        coneGeo.setAttribute("position", new BufferAttribute(new Float32Array(coneVerts), 3));
-        const coneLine = new LineSegments(coneGeo, new LineBasicMaterial({
-            color: this.color, depthTest: false,
-        }));
-        group.add(coneLine);
-        // ——— 标签 ———
-        const label = new SpriteText("聚光灯\n\n");
-        label.renderOrder = Infinity;
-        label.padding = 4;
-        label.strokeColor = "#333";
-        label.strokeWidth = 2;
-        label.position.set(0, -1, 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;
-    })();
-}
+/*
+ * @Author: xiaosihan
+ * @Date: 2024-06-08 14:00:00
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2024-06-08 14:00:00
+ */
+import { SpotLight as THREESpotLight, Group, BufferGeometry, BufferAttribute, LineBasicMaterial, LineSegments, CylinderGeometry, MeshBasicMaterial, Mesh } from "three";
+import threeUtils from "./threeUtils";
+import SpriteText from "./SpriteText";
+/** 聚光灯（dev 模式显示光锥线框 + 灯体圆柱） */
+export default class SpotLight extends THREESpotLight {
+    constructor(color = "#fff", intensity = 1, distance = 10, angle = Math.PI / 6, penumbra = 0) {
+        super(color, intensity, distance, angle, penumbra);
+    }
+    /* ============ dev 模式可视化 ============ */
+    _devGroup = threeUtils.isDev && (() => {
+        const group = new Group();
+        // ——— 灯体圆柱 ———
+        const body = new Mesh(new CylinderGeometry(0.15, 0.2, 0.6, 12), new MeshBasicMaterial({ color: this.color, depthTest: false, wireframe: true }));
+        group.add(body);
+        // ——— 光锥线框 ———
+        const coneAngle = this.angle;
+        const coneDist = Math.min(this.distance || 10, 10);
+        const topR = 0.01;
+        const bottomR = Math.tan(coneAngle) * coneDist;
+        const coneVerts = [];
+        const rings = 8;
+        const segs = 24;
+        for (let r = 0; r <= rings; r++) {
+            const t = r / rings;
+            const z = -0.3 - t * coneDist;
+            const radius = topR + (bottomR - topR) * t;
+            for (let i = 0; i < segs; i++) {
+                const a0 = (i / segs) * Math.PI * 2;
+                const a1 = ((i + 1) / segs) * Math.PI * 2;
+                const x0 = Math.cos(a0) * radius, y0 = Math.sin(a0) * radius;
+                const x1 = Math.cos(a1) * radius, y1 = Math.sin(a1) * radius;
+                coneVerts.push(x0, y0, z, x1, y1, z);
+                if (r < rings) {
+                    const z2 = -0.3 - ((r + 1) / rings) * coneDist;
+                    const r2 = topR + (bottomR - topR) * ((r + 1) / rings);
+                    const x2 = Math.cos(a0) * r2, y2 = Math.sin(a0) * r2;
+                    coneVerts.push(x0, y0, z, x2, y2, z2);
+                }
+            }
+        }
+        const coneGeo = new BufferGeometry();
+        coneGeo.setAttribute("position", new BufferAttribute(new Float32Array(coneVerts), 3));
+        const coneLine = new LineSegments(coneGeo, new LineBasicMaterial({
+            color: this.color, depthTest: false,
+        }));
+        group.add(coneLine);
+        // ——— 标签 ———
+        const label = new SpriteText("聚光灯\n\n");
+        label.renderOrder = Infinity;
+        label.padding = 4;
+        label.strokeColor = "#333";
+        label.strokeWidth = 2;
+        label.position.set(0, -1, 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/SpotLight.ts

@@ -0,0 +1,74 @@
+/*
+ * @Author: xiaosihan
+ * @Date: 2024-06-08 14:00:00
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2024-06-08 14:00:00
+ */
+import { SpotLight as THREESpotLight, Group, BufferGeometry, BufferAttribute, LineBasicMaterial, LineSegments, CylinderGeometry, MeshBasicMaterial, Mesh, Object3DEventMap } from "three";
+import threeUtils from "./threeUtils";
+import SpriteText from "./SpriteText";
+
+/** 聚光灯（dev 模式显示光锥线框 + 灯体圆柱） */
+export default class SpotLight extends THREESpotLight {
+    constructor(color: string = "#fff", intensity: number = 1, distance: number = 10, angle: number = Math.PI / 6, penumbra: number = 0) {
+        super(color, intensity, distance, angle, penumbra);
+    }
+
+    /* ============ dev 模式可视化 ============ */
+    _devGroup: Group<Object3DEventMap> | false = threeUtils.isDev && (() => {
+        const group = new Group();
+        // ——— 灯体圆柱 ———
+        const body = new Mesh(new CylinderGeometry(0.15, 0.2, 0.6, 12), new MeshBasicMaterial({ color: this.color, depthTest: false, wireframe: true }));
+        group.add(body);
+        // ——— 光锥线框 ———
+        const coneAngle = this.angle;
+        const coneDist = Math.min(this.distance || 10, 10);
+        const topR = 0.01;
+        const bottomR = Math.tan(coneAngle) * coneDist;
+        const coneVerts: number[] = [];
+        const rings = 8;
+        const segs = 24;
+        for (let r = 0; r <= rings; r++) {
+            const t = r / rings;
+            const z = -0.3 - t * coneDist;
+            const radius = topR + (bottomR - topR) * t;
+            for (let i = 0; i < segs; i++) {
+                const a0 = (i / segs) * Math.PI * 2;
+                const a1 = ((i + 1) / segs) * Math.PI * 2;
+                const x0 = Math.cos(a0) * radius, y0 = Math.sin(a0) * radius;
+                const x1 = Math.cos(a1) * radius, y1 = Math.sin(a1) * radius;
+                coneVerts.push(x0, y0, z, x1, y1, z);
+                if (r < rings) {
+                    const z2 = -0.3 - ((r + 1) / rings) * coneDist;
+                    const r2 = topR + (bottomR - topR) * ((r + 1) / rings);
+                    const x2 = Math.cos(a0) * r2, y2 = Math.sin(a0) * r2;
+                    coneVerts.push(x0, y0, z, x2, y2, z2);
+                }
+            }
+        }
+        const coneGeo = new BufferGeometry();
+        coneGeo.setAttribute("position", new BufferAttribute(new Float32Array(coneVerts), 3));
+        const coneLine = new LineSegments(coneGeo, new LineBasicMaterial({
+            color: this.color, depthTest: false,
+        }));
+        group.add(coneLine);
+        // ——— 标签 ———
+        const label = new SpriteText("聚光灯\n\n");
+        label.renderOrder = Infinity;
+        label.padding = 4;
+        label.strokeColor = "#333";
+        label.strokeWidth = 2;
+        label.position.set(0, -1, 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/SpriteModal1/SpriteModal1.d.ts

@@ -1,30 +1,33 @@
-import { Sprite, Raycaster, Intersection } from "three";
-export type SpritModal1Config = {
-    size?: number;
-    title?: string;
-    titleColor?: string;
-    texts?: Array<{
-        text?: string;
-        color?: string;
-        size?: number;
-    }>;
-};
-export default class SpritModal1 extends Sprite {
-    constructor(config?: SpritModal1Config);
-    static img: HTMLImageElement;
-    canvas: HTMLCanvasElement;
-    context: CanvasRenderingContext2D;
-    texture: import("three").Texture;
-    _config: {
-        size: number;
-        title: string;
-        titleColor: string;
-        texts: Array<{
-            text: string;
-            color: string;
-            size: number;
-        }>;
-    };
-    updata(config: SpritModal1Config): Promise<void>;
-    raycast(raycaster: Raycaster, intersects: Intersection[]): void;
-}
+import { Sprite, Texture, Raycaster, Intersection } from "three";
+export type SpritModal1Config = {
+    size?: number;
+    title?: string;
+    titleColor?: string;
+    texts?: Array<{
+        text?: string;
+        color?: string;
+        size?: number;
+    }>;
+};
+type TextItem = {
+    text: string;
+    color: string;
+    size: number;
+};
+type ConfigType = {
+    size: number;
+    title: string;
+    titleColor: string;
+    texts: TextItem[];
+};
+export default class SpritModal1 extends Sprite {
+    constructor(config?: SpritModal1Config);
+    static img: HTMLImageElement;
+    canvas: HTMLCanvasElement;
+    context: CanvasRenderingContext2D | null;
+    texture: Texture;
+    _config: ConfigType;
+    updata(config: SpritModal1Config): Promise<void>;
+    raycast(raycaster: Raycaster, intersects: Intersection[]): void;
+}
+export {};