three-base 2.0.142 → 2.0.166

package/MeshBase.js

@@ -1,247 +1,251 @@
-/*
- * @Author: xiaosihan
- * @Date: 2022-02-24 22:49:42
- * @Last Modified by: xiaosihan
- * @Last Modified time: 2025-06-25
- */
-import { AnimationMixer, Clock, Group, Mesh, Vector3 } from "three";
-import threeUtils from "./threeUtils";
-import threeLoader from "./threeLoader";
-import * as SkeletonUtils from "three/examples/jsm/utils/SkeletonUtils";
-import { isString } from "lodash";
-import { dispatchCustomEvent } from "./EventMap";
-// 模型基类
-export default class MeshBase extends Group {
-    constructor(url) {
-        super();
-        url && this.loadModel(url);
-    }
-    url = "";
-    // 模型对象
-    static models = new Map();
-    // 模型是否在加载中
-    static loadModeling = new Map();
-    // 加载完成
-    loaded = false;
-    // 是否有动画
-    hasAnimation = false;
-    //动画混合器
-    mixer;
-    //动画剪辑对象数组
-    animationActions = {};
-    // 获取文件名的后缀
-    getSuffix(filename) {
-        const match = filename.match(/\.([^\.]+)$/);
-        return match ? match[1].toLowerCase() : "";
-    }
-    reset(...object) {
-        threeUtils.dipose(this);
-        for (const child of this.children) {
-            child.parent = null;
-        }
-        for (const item of object) {
-            this.add(item);
-        }
-        return this;
-    }
-    // 兜底：为缺失顶点法线的几何体计算法线。
-    // 某些 glb/stl 模型仅有 POSITION 没有 NORMAL（如 public/models/bottle.glb），
-    // 会让法线 pass 输出零向量 -> AO 算出 NaN -> 整片被乘黑，且 PBR 金属材质无法正确受光 -> 发黑。
-    // 在加载完成后统一兜底，保证光照与 AO 都正确；已含法线的模型不受影响。
-    ensureNormals(root) {
-        root.traverse((obj) => {
-            if (obj instanceof Mesh && obj.geometry && !obj.geometry.getAttribute("normal")) {
-                obj.geometry.computeVertexNormals();
-            }
-        });
-    }
-    // 如果url 是blob地址的话,就用suffix字段来制定模型的类型
-    async loadModel(url, filename = "") {
-        //获取模型文件的地址
-        const modelurl = await (async () => {
-            if (isString(url)) {
-                return url;
-            }
-            else if (url instanceof File) {
-                return url.name;
-            }
-            else if (url instanceof Array) {
-                let modelurl = "";
-                const suffixs = [
-                    "zip",
-                    "obj",
-                    "glb",
-                    "gltf",
-                    "fbx",
-                    "dae",
-                    "stl",
-                    "usdz",
-                ];
-                for (let file of url) {
-                    if (suffixs.includes(threeUtils.getSuffix(file.name))) {
-                        modelurl = file.name;
-                    }
-                }
-                return modelurl;
-            }
-            return "";
-        })();
-        this.url = modelurl || "";
-        if (!modelurl) {
-            return;
-        }
-        this.loaded = false;
-        // 没有模型并且没有加载任务时就去加载模型
-        if (!MeshBase.models.get(modelurl) &&
-            !MeshBase.loadModeling.get(modelurl)) {
-            MeshBase.loadModeling.set(modelurl, true);
-            // 万能加载器
-            let modal = await threeLoader.loadModel(url, filename);
-            MeshBase.models.set(modelurl, modal);
-            MeshBase.loadModeling.set(modelurl, false);
-        }
-        // 如果模型还在加载中, 就等待模型加载完成
-        do {
-            await new Promise((resolve) => setTimeout(resolve, 50));
-        } while (MeshBase.loadModeling.get(modelurl));
-        if (MeshBase.models.get(modelurl)) {
-            const mesh = MeshBase.models.get(modelurl);
-            // 兜底：为缺失顶点法线的几何体补算法线。某些 glb/stl 模型只有 POSITION，
-            // 没有 NORMAL，会导致：① 法线 pass 输出零向量 -> AO 算出 NaN -> 整片被乘黑；
-            // ② PBR 金属材质无法正确光照 -> 颜色发黑。统一在加载后兜底，光照与 AO 都正确。
-            this.ensureNormals(mesh);
-            // 判断是否有动画
-            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.reset(model);
-            }
-            else {
-                this.reset(mesh.clone(true));
-            }
-        }
-        await new Promise((resolve) => requestAnimationFrame(resolve));
-        this.loaded = true;
-        // 加载完成事件
-        dispatchCustomEvent(this, { type: "loaded" });
-    }
-    // 超出绘制区域时不绘制
-    frustumCulled = false;
-    // 创建阴影
-    castShadow = false;
-    // 接受阴影
-    receiveShadow = false;
-    // promise.resole 队列
-    resoles = [];
-    // 等待加载加载完成
-    async awaitLoaded() {
-        if (!this.loaded) {
-            await new Promise((resolve) => {
-                if (this.resoles.length === 0) {
-                    (async () => {
-                        while (!this.loaded) {
-                            await new Promise((resolve) => requestAnimationFrame(resolve));
-                        }
-                        while (this.resoles.length > 0) {
-                            const resole = this.resoles.pop();
-                            resole && resole();
-                        }
-                    })();
-                }
-                this.resoles.unshift(resolve);
-            });
-        }
-    }
-    //遍历模型
-    async traverseMesh(callback) {
-        // 等待加载完成
-        await this.awaitLoaded();
-        this.traverse((obj) => {
-            if (obj instanceof Mesh) {
-                callback(obj);
-            }
-        });
-    }
-    clock = new Clock();
-    //设置动画的权重
-    async setClipActionWeight(weights = {}) {
-        // 等待加载完成
-        await this.awaitLoaded();
-        for (let key in this.animationActions) {
-            this.animationActions[key].weight = weights[key] || 0;
-        }
-    }
-    //获取动画列表
-    getAnimas() {
-        return Object.keys(this.animationActions);
-    }
-    //播放指定动画
-    setAnimas(anima = "") {
-        this.setClipActionWeight({ [anima]: 1 });
-    }
-    //停止所有动画
-    stop() {
-        this.setClipActionWeight();
-    }
-    updateMatrix() {
-        //播放动画
-        if (this.mixer) {
-            this.mixer.update(this.clock.getDelta());
-        }
-        // 深度应用属性
-        this.traverse((obj) => {
-            if (obj instanceof Mesh) {
-                obj.frustumCulled = this.frustumCulled;
-                obj.castShadow = this.castShadow;
-                obj.receiveShadow = this.receiveShadow;
-            }
-        });
-        super.updateMatrix();
-    }
-    // 获取模型的尺寸
-    async getSize() {
-        await this.awaitLoaded();
-        return threeUtils.getSize(this);
-    }
-    // 居中
-    async center() {
-        await this.awaitLoaded();
-        threeUtils.center(this);
-    }
-    //底对齐
-    async alignBottom(y = 0) {
-        await this.awaitLoaded();
-        threeUtils.alignBottom(this, y);
-    }
-    // 放大到指定尺寸
-    async scaleTo(size = 1, key = ["x", "y", "z"]) {
-        await this.awaitLoaded();
-        threeUtils.scaleTo(this, size, key);
-    }
-    //按照法线拓展
-    expandBynormal(length) {
-        this.traverseMesh((mesh) => {
-            // 没有法线就计算法线
-            mesh.geometry = mesh.geometry.clone();
-            if (!mesh.geometry.getAttribute("normal")) {
-                mesh.geometry.computeVertexNormals();
-            }
-            const normal = mesh.geometry.getAttribute("normal");
-            const position = mesh.geometry.getAttribute("position");
-            const v3 = new Vector3(0, 0, 0);
-            for (let i = 0; i < position.count; i++) {
-                v3.set(normal.getX(i), normal.getY(i), normal.getZ(i));
-                v3.setLength(length);
-                position.setXYZ(i, position.getX(i) + v3.x, position.getY(i) + v3.y, position.getZ(i) + v3.z);
-            }
-            position.needsUpdate = true;
-        });
-    }
-}
+/*
+ * @Author: xiaosihan
+ * @Date: 2022-02-24 22:49:42
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2025-06-25
+ */
+import { AnimationMixer, Clock, Group, Mesh, Vector3 } from "three";
+import threeUtils from "./threeUtils";
+import threeLoader from "./threeLoader";
+import * as SkeletonUtils from "three/examples/jsm/utils/SkeletonUtils";
+import { isString } from "lodash";
+import { dispatchCustomEvent } from "./EventMap";
+// 模型基类
+export default class MeshBase extends Group {
+    constructor(url) {
+        super();
+        url && this.loadModel(url);
+    }
+    url = "";
+    // 模型对象
+    static models = new Map();
+    // 模型是否在加载中
+    static loadModeling = new Map();
+    // 加载完成
+    loaded = false;
+    // 是否有动画
+    hasAnimation = false;
+    //动画混合器
+    mixer;
+    //动画剪辑对象数组
+    animationActions = {};
+    // 获取文件名的后缀
+    getSuffix(filename) {
+        const match = filename.match(/\.([^\.]+)$/);
+        return match ? match[1].toLowerCase() : "";
+    }
+    reset(...object) {
+        threeUtils.dipose(this);
+        for (const child of this.children) {
+            child.parent = null;
+        }
+        for (const item of object) {
+            this.add(item);
+        }
+        return this;
+    }
+    // 兜底：为缺失顶点法线的几何体计算法线。
+    // 某些 glb/stl 模型仅有 POSITION 没有 NORMAL（如 public/models/bottle.glb），
+    // 会让法线 pass 输出零向量 -> AO 算出 NaN -> 整片被乘黑，且 PBR 金属材质无法正确受光 -> 发黑。
+    // 在加载完成后统一兜底，保证光照与 AO 都正确；已含法线的模型不受影响。
+    ensureNormals(root) {
+        root.traverse((obj) => {
+            if (obj instanceof Mesh && obj.geometry && !obj.geometry.getAttribute("normal")) {
+                obj.geometry.computeVertexNormals();
+            }
+        });
+    }
+    // 如果url 是blob地址的话,就用suffix字段来制定模型的类型
+    async loadModel(url, filename = "") {
+        //获取模型文件的地址
+        const modelurl = await (async () => {
+            if (isString(url)) {
+                return url;
+            }
+            else if (url instanceof File) {
+                return url.name;
+            }
+            else if (url instanceof Array) {
+                let modelurl = "";
+                const suffixs = [
+                    "zip",
+                    "obj",
+                    "glb",
+                    "gltf",
+                    "fbx",
+                    "dae",
+                    "stl",
+                    "usdz",
+                ];
+                for (let file of url) {
+                    if (suffixs.includes(threeUtils.getSuffix(file.name))) {
+                        modelurl = file.name;
+                    }
+                }
+                return modelurl;
+            }
+            return "";
+        })();
+        this.url = modelurl || "";
+        if (!modelurl) {
+            return;
+        }
+        this.loaded = false;
+        // 没有模型并且没有加载任务时就去加载模型
+        if (!MeshBase.models.get(modelurl) &&
+            !MeshBase.loadModeling.get(modelurl)) {
+            MeshBase.loadModeling.set(modelurl, true);
+            // 万能加载器
+            let modal = await threeLoader.loadModel(url, filename);
+            MeshBase.models.set(modelurl, modal);
+            MeshBase.loadModeling.set(modelurl, false);
+        }
+        // 如果模型还在加载中, 就等待模型加载完成
+        do {
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        } while (MeshBase.loadModeling.get(modelurl));
+        if (MeshBase.models.get(modelurl)) {
+            const mesh = MeshBase.models.get(modelurl);
+            // 兜底：为缺失顶点法线的几何体补算法线。某些 glb/stl 模型只有 POSITION，
+            // 没有 NORMAL，会导致：① 法线 pass 输出零向量 -> AO 算出 NaN -> 整片被乘黑；
+            // ② PBR 金属材质无法正确光照 -> 颜色发黑。统一在加载后兜底，光照与 AO 都正确。
+            this.ensureNormals(mesh);
+            // 判断是否有动画
+            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.reset(model);
+            }
+            else {
+                this.reset(mesh.clone(true));
+            }
+        }
+        // ⭐ 2026-10-09 皇上旨：走 threeUtils 公共 rAF 链，不再另起独立 rAF 回调
+        await threeUtils.waitNextFrame();
+        this.loaded = true;
+        // 加载完成事件
+        dispatchCustomEvent(this, { type: "loaded" });
+    }
+    // 超出绘制区域时不绘制
+    frustumCulled = false;
+    // 创建阴影
+    castShadow = false;
+    // 接受阴影
+    receiveShadow = false;
+    // promise.resole 队列
+    resoles = [];
+    // 等待加载加载完成
+    async awaitLoaded() {
+        if (!this.loaded) {
+            await new Promise((resolve) => {
+                if (this.resoles.length === 0) {
+                    (async () => {
+                        while (!this.loaded) {
+                            //⭐ 2026-10-09 皇上旨「整条 rAF 链只走 threeUtils 一条」：
+                            //   原生 rAF 是**独立于主循环的另一个回调**，同一帧并行跑；
+                            //   模型多时（十几个 GLB 同时 awaitLoaded）每帧多十几个回调 ⇒ 卡顿。
+                            await threeUtils.waitNextFrame();
+                        }
+                        while (this.resoles.length > 0) {
+                            const resole = this.resoles.pop();
+                            resole && resole();
+                        }
+                    })();
+                }
+                this.resoles.unshift(resolve);
+            });
+        }
+    }
+    //遍历模型
+    async traverseMesh(callback) {
+        // 等待加载完成
+        await this.awaitLoaded();
+        this.traverse((obj) => {
+            if (obj instanceof Mesh) {
+                callback(obj);
+            }
+        });
+    }
+    clock = new Clock();
+    //设置动画的权重
+    async setClipActionWeight(weights = {}) {
+        // 等待加载完成
+        await this.awaitLoaded();
+        for (let key in this.animationActions) {
+            this.animationActions[key].weight = weights[key] || 0;
+        }
+    }
+    //获取动画列表
+    getAnimas() {
+        return Object.keys(this.animationActions);
+    }
+    //播放指定动画
+    setAnimas(anima = "") {
+        this.setClipActionWeight({ [anima]: 1 });
+    }
+    //停止所有动画
+    stop() {
+        this.setClipActionWeight();
+    }
+    updateMatrix() {
+        //播放动画
+        if (this.mixer) {
+            this.mixer.update(this.clock.getDelta());
+        }
+        // 深度应用属性
+        this.traverse((obj) => {
+            if (obj instanceof Mesh) {
+                obj.frustumCulled = this.frustumCulled;
+                obj.castShadow = this.castShadow;
+                obj.receiveShadow = this.receiveShadow;
+            }
+        });
+        super.updateMatrix();
+    }
+    // 获取模型的尺寸
+    async getSize() {
+        await this.awaitLoaded();
+        return threeUtils.getSize(this);
+    }
+    // 居中
+    async center() {
+        await this.awaitLoaded();
+        threeUtils.center(this);
+    }
+    //底对齐
+    async alignBottom(y = 0) {
+        await this.awaitLoaded();
+        threeUtils.alignBottom(this, y);
+    }
+    // 放大到指定尺寸
+    async scaleTo(size = 1, key = ["x", "y", "z"]) {
+        await this.awaitLoaded();
+        threeUtils.scaleTo(this, size, key);
+    }
+    //按照法线拓展
+    expandBynormal(length) {
+        this.traverseMesh((mesh) => {
+            // 没有法线就计算法线
+            mesh.geometry = mesh.geometry.clone();
+            if (!mesh.geometry.getAttribute("normal")) {
+                mesh.geometry.computeVertexNormals();
+            }
+            const normal = mesh.geometry.getAttribute("normal");
+            const position = mesh.geometry.getAttribute("position");
+            const v3 = new Vector3(0, 0, 0);
+            for (let i = 0; i < position.count; i++) {
+                v3.set(normal.getX(i), normal.getY(i), normal.getZ(i));
+                v3.setLength(length);
+                position.setXYZ(i, position.getX(i) + v3.x, position.getY(i) + v3.y, position.getZ(i) + v3.z);
+            }
+            position.needsUpdate = true;
+        });
+    }
+}

package/MeshBase.ts

@@ -131,7 +131,8 @@ export default class MeshBase extends Group {
                 this.reset(mesh.clone(true));
             }
         }
-        await new Promise((resolve) => requestAnimationFrame(resolve));
+        // ⭐ 2026-10-09 皇上旨：走 threeUtils 公共 rAF 链，不再另起独立 rAF 回调
+        await threeUtils.waitNextFrame();
         this.loaded = true;
         // 加载完成事件
         dispatchCustomEvent(this, { type: "loaded" });
@@ -151,7 +152,10 @@ export default class MeshBase extends Group {
                 if (this.resoles.length === 0) {
                     (async () => {
                         while (!this.loaded) {
-                            await new Promise((resolve) => requestAnimationFrame(resolve));
+                            //⭐ 2026-10-09 皇上旨「整条 rAF 链只走 threeUtils 一条」：
+                            //   原生 rAF 是**独立于主循环的另一个回调**，同一帧并行跑；
+                            //   模型多时（十几个 GLB 同时 awaitLoaded）每帧多十几个回调 ⇒ 卡顿。
+                            await threeUtils.waitNextFrame();
                         }
                         while (this.resoles.length > 0) {
                             const resole = this.resoles.pop();

package/Mirror.d.ts

@@ -1,25 +1,25 @@
-import { Matrix4, Mesh, PerspectiveCamera, Plane, PlaneGeometry, ShaderMaterial, Vector3, Vector4, WebGLRenderTarget, WebGLRenderer, Scene, Camera, BufferGeometry, Material, Group, Texture } from "three";
-export default class Mirror extends Mesh {
-    constructor(geometry?: BufferGeometry);
-    static geometry: PlaneGeometry;
-    isReflector: boolean;
-    type: string;
-    camera: PerspectiveCamera;
-    reflectorPlane: Plane;
-    normal: Vector3;
-    reflectorWorldPosition: Vector3;
-    cameraWorldPosition: Vector3;
-    rotationMatrix: Matrix4;
-    lookAtPosition: Vector3;
-    clipPlane: Vector4;
-    view: Vector3;
-    target: Vector3;
-    q: Vector4;
-    textureMatrix: Matrix4;
-    virtualCamera: PerspectiveCamera;
-    renderTarget: WebGLRenderTarget<Texture>;
-    material: ShaderMaterial;
-    onBeforeRender: (renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry, material: Material, group: Group) => void;
-    getRenderTarget(): WebGLRenderTarget<Texture>;
-    dispose(): void;
-}
+import { Matrix4, Mesh, PerspectiveCamera, Plane, PlaneGeometry, ShaderMaterial, Vector3, Vector4, WebGLRenderTarget, WebGLRenderer, Scene, Camera, BufferGeometry, Material, Group, Texture } from "three";
+export default class Mirror extends Mesh {
+    constructor(geometry?: BufferGeometry);
+    static geometry: PlaneGeometry;
+    isReflector: boolean;
+    type: string;
+    camera: PerspectiveCamera;
+    reflectorPlane: Plane;
+    normal: Vector3;
+    reflectorWorldPosition: Vector3;
+    cameraWorldPosition: Vector3;
+    rotationMatrix: Matrix4;
+    lookAtPosition: Vector3;
+    clipPlane: Vector4;
+    view: Vector3;
+    target: Vector3;
+    q: Vector4;
+    textureMatrix: Matrix4;
+    virtualCamera: PerspectiveCamera;
+    renderTarget: WebGLRenderTarget<Texture>;
+    material: ShaderMaterial;
+    onBeforeRender: (renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry, material: Material, group: Group) => void;
+    getRenderTarget(): WebGLRenderTarget<Texture>;
+    dispose(): void;
+}