three-base 2.0.190 → 2.0.193

package/EventMap.d.ts

@@ -8,6 +8,12 @@ export interface LoadingEvent {
 export interface OnLoadEvent {
     type: "onLoad";
 }
+export interface LoaderProgressEvent {
+    type: "progress";
+    url: string;
+    loaded: number;
+    total: number;
+}
 export interface BeforeRenderEvent {
     type: "beforeRender";
 }
@@ -53,6 +59,7 @@ export interface MeshBaseEventMap extends Object3DEventMap {
 export interface ThreeLoaderEventMap extends Object3DEventMap {
     "loadding": LoadingEvent;
     "onLoad": OnLoadEvent;
+    "progress": LoaderProgressEvent;
 }
 export interface ThreeBaseEventTypeMap extends Object3DEventMap {
     "loadding": LoadingEvent;

package/EventMap.ts

@@ -29,6 +29,13 @@ import type { Object3DEventMap, Vector3 } from "three";
 export interface LoadedEvent { type: "loaded"; }
 export interface LoadingEvent { type: "loadding"; }
 export interface OnLoadEvent { type: "onLoad"; }
+// 资源加载进度：`DefaultLoadingManager.onProgress` 的三个数原样带出（url / 已完成项数 / 总项数）
+export interface LoaderProgressEvent {
+    type: "progress";
+    url: string;
+    loaded: number;
+    total: number;
+}
 export interface BeforeRenderEvent { type: "beforeRender"; }
 export interface AfterRenderEvent { type: "afterRender"; }
 
@@ -77,6 +84,7 @@ export interface MeshBaseEventMap extends Object3DEventMap {
 export interface ThreeLoaderEventMap extends Object3DEventMap {
     "loadding": LoadingEvent;
     "onLoad": OnLoadEvent;
+    "progress": LoaderProgressEvent;
 }
 
 export interface ThreeBaseEventTypeMap extends Object3DEventMap {

package/MeshBase.d.ts

@@ -12,6 +12,29 @@ export default class MeshBase extends Group {
     };
     getSuffix(filename: string): string;
     reset(...object: Object3D[]): this;
+    /** 「压着等放行」的内容子对象在册表（摘牌 = 从这里删掉，放行那一拍便不再写它的 `visible`） */
+    private readonly _revealPending;
+    /**
+     * ⭐ 2026-10-28「这个方案也可以用在 MeshBase 对象上面，让每个模型对象都逐帧显示出来，就不用一起阻塞了」：
+     *   刚进场景图的这几颗内容先压住，再交给 `threeUtils` 的全局队列 —— 那一拍每帧只跑一项
+     *   （`requestAnimationFrame()` 里 `workList.splice(0, 1)`），且派发点在渲染之后 ⇒ 一帧只放行一个对象，
+     *   它下一帧才被真画出来。几十只模型同时落地时，「顶点缓冲上传 + 首次 program 编译」（都发生在真被画的
+     *   那一帧）就摊到几十帧上，不再是进门那一下的一整卡。
+     * ⚠️ 压的是**内容子对象**的 `visible`，⛔ 不是 MeshBase 自己：`ManyModelGroup.setDatas` 拿 MeshBase 的
+     *   `visible` 当「这条数据还在不在」的筛子 ⇒ 那个旋钮归消费者，这里不许占用。
+     * ⚠️ 只压「这一次新加进来的」那几颗 ⇒ 换模型（`reset`）时不会把旁边早已点亮的内容一起按下去。
+     * ⚠️ ⛔ 别改成「每颗在自己的 `onBeforeRender` 里轮询 loaded」：three 的 `projectObject` 第一句就是
+     *   `if (object.visible === false) return;`（`node_modules/three/build/three.module.js:29837`）⇒
+     *   隐形对象一次回调都收不到，自己等自己 = 永远不亮。
+     * ⚠️ `visible` 是业务的旋钮，这里只是**借一下**：进场时就压着的那几颗⛔ 不收进这一轮（不替别人放开）；
+     *   要在放行之前接管某颗，调 `releaseReveal(item)` 摘牌 ⇒ 放行那一拍跳过它，`visible` 归调用方。
+     */
+    protected revealSoon(items: Object3D[]): void;
+    /**
+     * 把某颗内容的显隐控制权交回调用方（2026-10-28：`visible` 上有业务在用，加载窗口期内写的那一笔⛔ 不能被
+     * 放行那一拍覆盖）。摘牌后它**仍是压着的**（`false`），要它可见就自己写 `true`。
+     */
+    releaseReveal(item: Object3D): void;
     protected ensureNormals(root: Object3D): void;
     loadModel(url: string | File | Array<File>, filename?: string): Promise<void>;
     frustumCulled: boolean;

package/MeshBase.js

@@ -44,6 +44,49 @@ export default class MeshBase extends Group {
         }
         return this;
     }
+    /** 「压着等放行」的内容子对象在册表（摘牌 = 从这里删掉，放行那一拍便不再写它的 `visible`） */
+    _revealPending = new Set();
+    /**
+     * ⭐ 2026-10-28「这个方案也可以用在 MeshBase 对象上面，让每个模型对象都逐帧显示出来，就不用一起阻塞了」：
+     *   刚进场景图的这几颗内容先压住，再交给 `threeUtils` 的全局队列 —— 那一拍每帧只跑一项
+     *   （`requestAnimationFrame()` 里 `workList.splice(0, 1)`），且派发点在渲染之后 ⇒ 一帧只放行一个对象，
+     *   它下一帧才被真画出来。几十只模型同时落地时，「顶点缓冲上传 + 首次 program 编译」（都发生在真被画的
+     *   那一帧）就摊到几十帧上，不再是进门那一下的一整卡。
+     * ⚠️ 压的是**内容子对象**的 `visible`，⛔ 不是 MeshBase 自己：`ManyModelGroup.setDatas` 拿 MeshBase 的
+     *   `visible` 当「这条数据还在不在」的筛子 ⇒ 那个旋钮归消费者，这里不许占用。
+     * ⚠️ 只压「这一次新加进来的」那几颗 ⇒ 换模型（`reset`）时不会把旁边早已点亮的内容一起按下去。
+     * ⚠️ ⛔ 别改成「每颗在自己的 `onBeforeRender` 里轮询 loaded」：three 的 `projectObject` 第一句就是
+     *   `if (object.visible === false) return;`（`node_modules/three/build/three.module.js:29837`）⇒
+     *   隐形对象一次回调都收不到，自己等自己 = 永远不亮。
+     * ⚠️ `visible` 是业务的旋钮，这里只是**借一下**：进场时就压着的那几颗⛔ 不收进这一轮（不替别人放开）；
+     *   要在放行之前接管某颗，调 `releaseReveal(item)` 摘牌 ⇒ 放行那一拍跳过它，`visible` 归调用方。
+     */
+    revealSoon(items) {
+        const held = [];
+        for (const item of items) {
+            if (!item.visible)
+                continue; // 本来就压着 ⇒ 显隐归业务，⛔ 不收进这一轮、也不替它放开
+            item.visible = false;
+            this._revealPending.add(item);
+            held.push(item);
+        }
+        if (!held.length)
+            return;
+        threeUtils.addWork(() => {
+            for (const item of held) {
+                if (!this._revealPending.delete(item))
+                    continue; // 已被摘牌 ⇒ 这一拍不碰它的 visible
+                item.visible = true;
+            }
+        });
+    }
+    /**
+     * 把某颗内容的显隐控制权交回调用方（2026-10-28：`visible` 上有业务在用，加载窗口期内写的那一笔⛔ 不能被
+     * 放行那一拍覆盖）。摘牌后它**仍是压着的**（`false`），要它可见就自己写 `true`。
+     */
+    releaseReveal(item) {
+        this._revealPending.delete(item);
+    }
     // 兜底：为缺失顶点法线的几何体计算法线。
     // 某些 glb/stl 模型仅有 POSITION 没有 NORMAL（如 public/models/bottle.glb），
     // 会让法线 pass 输出零向量 -> AO 算出 NaN -> 整片被乘黑，且 PBR 金属材质无法正确受光 -> 发黑。
@@ -122,9 +165,12 @@ export default class MeshBase extends Group {
                     this.animationActions[animation.name] = animationAction;
                 });
                 this.reset(model);
+                this.revealSoon([model]);
             }
             else {
-                this.reset(mesh.clone(true));
+                const clone = mesh.clone(true);
+                this.reset(clone);
+                this.revealSoon([clone]);
             }
         }
         // ⭐ 2026-10-09 皇上旨：走 threeUtils 公共 rAF 链，不再另起独立 rAF 回调