three-base 2.0.190 → 2.0.192

package/MktMesh/imagePlane.d.ts

@@ -37,9 +37,13 @@ export declare class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
     private _uInset;
     private _uValid;
     private _data;
+    /** 内容是否已落定：4 格里至少有一格真的绑上了纹理。**只朝 true 翻一次**（之后逐张显影继续，但不再回退成「没内容」）。 */
+    private _loaded;
     constructor(name?: string);
     get imageWidth(): number;
     get imageHeight(): number;
+    /** 这一颗的内容落定没有 —— 库的逐帧点亮闸只认这一条（`MktMesh.tickProgressiveReveal`）。 */
+    get loaded(): boolean;
     setPlaneSize(w: number, h: number): void;
     setPlaneData(d: Pick<ImagePlaneData, "url" | "tiles" | "naturalW" | "naturalH">): void;
     get tiles(): string[];

package/MktMesh/imagePlane.js

@@ -70,6 +70,8 @@ export class ImagePlane extends Mesh {
         url: "",
         tiles: [],
     };
+    /** 内容是否已落定：4 格里至少有一格真的绑上了纹理。**只朝 true 翻一次**（之后逐张显影继续，但不再回退成「没内容」）。 */
+    _loaded = false;
     constructor(name) {
         const geo = new PlaneGeometry(DEFAULT_WIDTH, DEFAULT_HEIGHT);
         const mat = new MeshBasicMaterial({
@@ -108,6 +110,8 @@ export class ImagePlane extends Mesh {
     }
     get imageWidth() { return this.geometry.parameters.width; }
     get imageHeight() { return this.geometry.parameters.height; }
+    /** 这一颗的内容落定没有 —— 库的逐帧点亮闸只认这一条（`MktMesh.tickProgressiveReveal`）。 */
+    get loaded() { return this._loaded; }
     setPlaneSize(w, h) {
         this.geometry.dispose();
         this.geometry = new PlaneGeometry(w, h);
@@ -127,6 +131,10 @@ export class ImagePlane extends Mesh {
             if (insets[i])
                 this._uInset.value[i].copy(insets[i]);
             this._uValid.value[i] = t ? 1 : 0;
+            // 第一格就绪 = 这一颗有东西可画了 ⇒ 落定（点亮闸认的就是这一条，⛔ 不是「4 格全到齐」：
+            // 「逐张就绪逐张显影」是本文件 10-22 晚定下的口径，等到全到齐会让先到的那几格白等几帧）。
+            if (t)
+                this._loaded = true;
         }
     }
     /** 只读「此刻材质里绑了什么」的戳记：4 格就绪位 + 已绑纹理的版本号。

package/MktMesh/imagePlane.ts

@@ -102,6 +102,8 @@ export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
         url: "",
         tiles: [],
     };
+    /** 内容是否已落定：4 格里至少有一格真的绑上了纹理。**只朝 true 翻一次**（之后逐张显影继续，但不再回退成「没内容」）。 */
+    private _loaded = false;
 
     constructor(name?: string) {
         const geo = new PlaneGeometry(DEFAULT_WIDTH, DEFAULT_HEIGHT);
@@ -145,6 +147,8 @@ export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
 
     get imageWidth(): number { return (this.geometry as PlaneGeometry).parameters.width; }
     get imageHeight(): number { return (this.geometry as PlaneGeometry).parameters.height; }
+    /** 这一颗的内容落定没有 —— 库的逐帧点亮闸只认这一条（`MktMesh.tickProgressiveReveal`）。 */
+    get loaded(): boolean { return this._loaded; }
 
     setPlaneSize(w: number, h: number): void {
         this.geometry.dispose();
@@ -167,6 +171,9 @@ export class ImagePlane extends Mesh<PlaneGeometry, MeshBasicMaterial> {
             this._uTiles.value[i] = t || PLACEHOLDER_TEX;
             if (insets[i]) this._uInset.value[i].copy(insets[i]);
             this._uValid.value[i] = t ? 1 : 0;
+            // 第一格就绪 = 这一颗有东西可画了 ⇒ 落定（点亮闸认的就是这一条，⛔ 不是「4 格全到齐」：
+            // 「逐张就绪逐张显影」是本文件 10-22 晚定下的口径，等到全到齐会让先到的那几格白等几帧）。
+            if (t) this._loaded = true;
         }
     }
 

package/MktMesh/modelSlot.d.ts

@@ -66,6 +66,12 @@ export declare class ModelSlot extends Group {
     private _staged;
     /** 载入令牌：换地址/删除后迟到的回调靠它作废（否则旧模型会挂进新槽） */
     private _loadToken;
+    /**
+     * 内容是否已落定：真模型挂进了 `_contentRoot`，或这一颗压根没在等什么（空地址 / 取回失败 ⇒ 停在占位小立方体）。
+     * ⚠️ 落定**不等于**已经画进 GPU —— 顶点缓冲与首次 program 编译发生在「亮出来的那一帧」，
+     *   所以逐帧限流必须闸在点亮这一下（`MktMesh.tickProgressiveReveal`），闸在挂载那一下拦不住 GPU 侧的账。
+     */
+    private _loaded;
     private _disposed;
     constructor(name?: string);
     get size(): number;
@@ -78,6 +84,8 @@ export declare class ModelSlot extends Group {
     } | undefined;
     /** 是否已经挂上真模型（false = 仍是占位小立方体） */
     get hasModel(): boolean;
+    /** 这一颗的内容落定没有 —— 库的逐帧点亮闸只认这一条（`MktMesh.tickProgressiveReveal`）。 */
+    get loaded(): boolean;
     /** 改尺寸档（米，最长边）：立刻重缩内容 */
     setSize(size: number): void;
     /**

package/MktMesh/modelSlot.js

@@ -107,6 +107,12 @@ export class ModelSlot extends Group {
     _staged = null;
     /** 载入令牌：换地址/删除后迟到的回调靠它作废（否则旧模型会挂进新槽） */
     _loadToken = 0;
+    /**
+     * 内容是否已落定：真模型挂进了 `_contentRoot`，或这一颗压根没在等什么（空地址 / 取回失败 ⇒ 停在占位小立方体）。
+     * ⚠️ 落定**不等于**已经画进 GPU —— 顶点缓冲与首次 program 编译发生在「亮出来的那一帧」，
+     *   所以逐帧限流必须闸在点亮这一下（`MktMesh.tickProgressiveReveal`），闸在挂载那一下拦不住 GPU 侧的账。
+     */
+    _loaded = false;
     _disposed = false;
     constructor(name) {
         super();
@@ -126,6 +132,8 @@ export class ModelSlot extends Group {
     get naturalSize() { return this._naturalSize; }
     /** 是否已经挂上真模型（false = 仍是占位小立方体） */
     get hasModel() { return this._model !== null; }
+    /** 这一颗的内容落定没有 —— 库的逐帧点亮闸只认这一条（`MktMesh.tickProgressiveReveal`）。 */
+    get loaded() { return this._loaded; }
     /** 改尺寸档（米，最长边）：立刻重缩内容 */
     setSize(size) {
         this._size = size > 0 ? size : this._size;
@@ -161,13 +169,25 @@ export class ModelSlot extends Group {
     async loadModel(url) {
         this._url = url;
         const token = ++this._loadToken;
+        this._loaded = false;
         this._detachModel();
         // 先立刻退回占位小立方体：GLB 在路上那段窗口（慢网/大模型）⛔ 不许让这一槽凭空消失
         //   （取回失败那条支路本来也是停在占位上，两段时间里画面一致）
         this._layout();
-        if (!url)
+        if (!url) {
+            // 空地址 = 这一颗压根没在等什么 ⇒ 当场落定（占位小立方体就是它的最终内容）
+            this._loaded = true;
             return true;
-        const obj = await threeLoader.loadModel(url);
+        }
+        // 取回失败（404 / 解析报错都从这一档走）：`threeLoader.loadModel` 是会 reject 的，⚠️ 必须当「落定在占位方块」处理
+        //   —— 整层重建时这一颗是压着不亮的，不落定就永远隐形（旧写法里它至少还露得出占位方块）。
+        let obj;
+        try {
+            obj = await threeLoader.loadModel(url);
+        }
+        catch {
+            obj = undefined;
+        }
         // 迟到回调：这一槽已经改指向别的地址、或已经删除 ⇒ 当场释放，别留一份没人认领的显存
         if (this._disposed || token !== this._loadToken) {
             if (obj)
@@ -175,6 +195,7 @@ export class ModelSlot extends Group {
             return false;
         }
         if (!obj) {
+            this._loaded = true;
             this._layout();
             return false;
         }
@@ -189,6 +210,7 @@ export class ModelSlot extends Group {
         this._staged = null;
         this._model = obj;
         this._contentRoot.add(obj);
+        this._loaded = true;
         this._layout();
         return true;
     }
@@ -220,6 +242,8 @@ export class ModelSlot extends Group {
         this._size = d.size > 0 ? d.size : MODEL_SLOT_DEFAULT_SIZE;
         this._naturalSize = d.naturalSize;
         this._url = d.url || "";
+        // 落定判据跟着地址走：空地址 = 没在等什么（占位方块就是最终内容）；有地址 = 等 GLB 那一拍
+        this._loaded = !this._url;
         if (!this._url)
             this._detachModel();
         this._layout();

package/MktMesh/modelSlot.ts

@@ -137,6 +137,12 @@ export class ModelSlot extends Group {
     private _staged: Object3D | null = null;
     /** 载入令牌：换地址/删除后迟到的回调靠它作废（否则旧模型会挂进新槽） */
     private _loadToken = 0;
+    /**
+     * 内容是否已落定：真模型挂进了 `_contentRoot`，或这一颗压根没在等什么（空地址 / 取回失败 ⇒ 停在占位小立方体）。
+     * ⚠️ 落定**不等于**已经画进 GPU —— 顶点缓冲与首次 program 编译发生在「亮出来的那一帧」，
+     *   所以逐帧限流必须闸在点亮这一下（`MktMesh.tickProgressiveReveal`），闸在挂载那一下拦不住 GPU 侧的账。
+     */
+    private _loaded = false;
     private _disposed = false;
 
     constructor(name?: string) {
@@ -164,6 +170,8 @@ export class ModelSlot extends Group {
     get naturalSize(): { x: number; y: number; z: number } | undefined { return this._naturalSize; }
     /** 是否已经挂上真模型（false = 仍是占位小立方体） */
     get hasModel(): boolean { return this._model !== null; }
+    /** 这一颗的内容落定没有 —— 库的逐帧点亮闸只认这一条（`MktMesh.tickProgressiveReveal`）。 */
+    get loaded(): boolean { return this._loaded; }
 
     /** 改尺寸档（米，最长边）：立刻重缩内容 */
     setSize(size: number): void {
@@ -201,18 +209,31 @@ export class ModelSlot extends Group {
     async loadModel(url: string): Promise<boolean> {
         this._url = url;
         const token = ++this._loadToken;
+        this._loaded = false;
         this._detachModel();
         // 先立刻退回占位小立方体：GLB 在路上那段窗口（慢网/大模型）⛔ 不许让这一槽凭空消失
         //   （取回失败那条支路本来也是停在占位上，两段时间里画面一致）
         this._layout();
-        if (!url) return true;
-        const obj = await threeLoader.loadModel(url);
+        if (!url) {
+            // 空地址 = 这一颗压根没在等什么 ⇒ 当场落定（占位小立方体就是它的最终内容）
+            this._loaded = true;
+            return true;
+        }
+        // 取回失败（404 / 解析报错都从这一档走）：`threeLoader.loadModel` 是会 reject 的，⚠️ 必须当「落定在占位方块」处理
+        //   —— 整层重建时这一颗是压着不亮的，不落定就永远隐形（旧写法里它至少还露得出占位方块）。
+        let obj: Object3D | undefined;
+        try {
+            obj = await threeLoader.loadModel(url);
+        } catch {
+            obj = undefined;
+        }
         // 迟到回调：这一槽已经改指向别的地址、或已经删除 ⇒ 当场释放，别留一份没人认领的显存
         if (this._disposed || token !== this._loadToken) {
             if (obj) disposeSubtree(obj);
             return false;
         }
         if (!obj) {
+            this._loaded = true;
             this._layout();
             return false;
         }
@@ -227,6 +248,7 @@ export class ModelSlot extends Group {
         this._staged = null;
         this._model = obj;
         this._contentRoot.add(obj);
+        this._loaded = true;
         this._layout();
         return true;
     }
@@ -257,6 +279,8 @@ export class ModelSlot extends Group {
         this._size = d.size > 0 ? d.size : MODEL_SLOT_DEFAULT_SIZE;
         this._naturalSize = d.naturalSize;
         this._url = d.url || "";
+        // 落定判据跟着地址走：空地址 = 没在等什么（占位方块就是最终内容）；有地址 = 等 GLB 那一拍
+        this._loaded = !this._url;
         if (!this._url) this._detachModel();
         this._layout();
     }

package/instanced/InstancedMeshBase.js

@@ -122,6 +122,9 @@ export default class InstancedMeshBase extends MeshBase {
                 instanceCollect[uuid] = instancedMesh;
                 this.add(instancedMesh);
             });
+            // ⭐ 2026-10-28「每个模型对象逐帧显示出来」：这一组 InstancedMesh 是**一个对象**的内容 ⇒ 一次放行
+            //   （一帧一个对象，⛔ 不是一个对象里的几十块零件排几十帧，那会变成零件逐块拼装）
+            this.revealSoon(this.children.slice());
             // 加载完成事件
             await new Promise((resolve) => setTimeout(resolve, 30));
             this.loaded = true;

package/instanced/InstancedMeshBase.ts

@@ -124,6 +124,9 @@ export default class InstancedMeshBase extends MeshBase {
                 instanceCollect[uuid] = instancedMesh;
                 this.add(instancedMesh);
             });
+            // ⭐ 2026-10-28「每个模型对象逐帧显示出来」：这一组 InstancedMesh 是**一个对象**的内容 ⇒ 一次放行
+            //   （一帧一个对象，⛔ 不是一个对象里的几十块零件排几十帧，那会变成零件逐块拼装）
+            this.revealSoon(this.children.slice());
             // 加载完成事件
             await new Promise((resolve) => setTimeout(resolve, 30));
             this.loaded = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-base",
-  "version": "2.0.190",
+  "version": "2.0.192",
   "description": "A Three.js extension library providing common 3D components, animations, materials, and utilities",
   "author": "xiaosihan",
   "publishConfig": {