three-base 2.0.188 → 2.0.192

package/MktMesh/MktMesh.d.ts

@@ -100,7 +100,7 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     private _ossSizeDepKeys;
     /** 渲染器：由 `onBeforeRender` 每帧捕获，预上传走它的 `initTexture`；没捕获到就退回 three 的自绑路径（不报错） */
     private _glRenderer;
-    /** ⭐ 32 瓦片（横 8 × 竖 4 切片）离屏拼合器：左右 2 槽纹理由它逐格拼出（每帧一张新纹理进 GPU + 已进 GPU 的逐格画）。
+    /** ⭐ 32 瓦片（横 8 × 竖 4 切片，每槽 4×4=16 格、槽纹理 6144×6144）离屏拼合器：左右 2 槽纹理由它逐格拼出（每帧一张新纹理进 GPU + 已进 GPU 的逐格画）。
      *  编辑器渲染器经 `panoStitcher` 复用同一实例（同一份槽纹理缓存，⛔ 不另建第二份显存）。
      *  皇上旨 2026-10-06「不用 canvas 2D 的 drawImage 拼合, 用一个 shader 一个一个渲染到 RT 上面去」
      *  +「canvas 是什么意思, 按照我的想法, 不应该有 canvas 才对啊」⇒ **只此一份实现**：旧的 canvas 2D
@@ -113,7 +113,7 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     /** 纹理 OSS 缩放尺寸（1024 / 2048 / 空=原图），由外部 setOssSize 注入；默认 1024 保持旧行为。
      *  编辑器渲染器与预览渲染器各自把 store.ossSize 推下来，使全景球/预览按该尺寸加载。 */
     private _ossSize;
-    /** 全景纹理形态：tiled=左右 2 槽各装一张**拼合槽纹理**（该点 32 片 横 8 × 竖 4 → 2 张 4096×4096，10-06 晚旨）
+    /** 全景纹理形态：tiled=左右 2 槽各装一张**拼合槽纹理**（该点 32 片 横 8 × 竖 4 → 2 张 6144×6144；形态是 10-06 晚立的，槽尺寸 10-26 起是 6144²，2026-10-27 的切档一字未动）
      *  / whole=2 槽同为一张完整等距柱状原图。
      *  由外部 setPanoTexMode 注入（与 _ossSize 同一套注入路径），默认 tiled 保持改造前行为。 */
     private _panoTexMode;
@@ -147,6 +147,20 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      * 一帧只有一颗进 `_contentRoot`（进图那一拍要重算包围盒 + 排布 + 首次把几何送上 GPU）。
      */
     private _modelMountQueued;
+    /**
+     * 「压着不亮、等内容落定后一帧放一颗」的在册表（2026-10-28 需求：进展厅时平面图与 GLB 全在同几帧里
+     * 首次送 GPU —— 顶点缓冲上传 + program 编译都在「亮出来的那一帧」，几十颗挤一起就是那一下卡）。
+     *
+     * ⚠️ 为什么闸口在**本对象的 `onBeforeRender`**、不在这颗平面/模型自己的：three 遍历场景图的第一句就是
+     *   `if ( object.visible === false ) return;`（`node_modules/three/build/three.module.js:29837`），
+     *   它和整棵子树当帧直接跳过 ⇒ 隐形对象**一次都不会**收到 `onBeforeRender`，挂在自己身上 = 永远不亮。
+     *   墙（本对象）每帧都进渲染列表，所以闸口设在这座上，在册表里逐帧放行。
+     * ⚠️ 单颗新增那两路（编辑态双击落点 / 复制 / 上传）⛔ 不进这张表 —— 刚加的东西必须当场看得见。
+     * ⚠️ `visible` 本是业务的旋钮，这里只是**借一帧**：整层重建那两路的对象是当场新建的（默认可见），所以进表前
+     *    不需要再看它一眼；但**放行那一拍之前**要接管某颗的显隐，必须调 `releaseReveal(o)` 摘牌，
+     *    否则它会在轮到自身那一帧被写回可见（`boolean` 只有一个位，放行那里分不出这笔是谁写的）。
+     */
+    private _revealPending;
     constructor(opts?: {
         wallHeight?: number;
         wallClosed?: boolean;
@@ -327,10 +341,17 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     addImagePlane(ip: ImagePlane): ImagePlane;
     /** 摘掉一颗并释放它自己的几何/材质；那 4 张瓦片纹理归 `_imgTileLoader` 管 ⇒ ⛔ 不在这里 dispose */
     removeImagePlane(ip: ImagePlane): void;
-    /** 单颗模型槽入层（编辑态双击落点、以及「复制模型」用） */
+    /** 单颗模型槽入层（编辑态双击落点、以及「复制模型」用）：⛔ 不压点亮 —— 刚加的必须当场看得见 */
     addModel(ms: ModelSlot): ModelSlot;
     /** 摘掉一槽并释放（子树里的几何/材质/贴图由 `ModelSlot.dispose` 自己收尾；排在后头的挂载帧靠「不在册」早退） */
     removeModel(ms: ModelSlot): void;
+    /** 出「逐帧点亮」那张在册表（删除 / 整层重建旧的一批都走这里，⛔ 不许留已经 dispose 的对象） */
+    private _dropReveal;
+    /**
+     * 把某颗平面/模型的显隐控制权交回调用方（2026-10-28：`visible` 上有业务在用，点亮那一拍⛔ 不能覆盖
+     * 放行之前写下的那一笔）。摘牌后它**仍是压着的**（整层重建那一路进来就是 `false`），要它可见就自己写 `true`。
+     */
+    releaseReveal(o: ImagePlane | ModelSlot): void;
     /**
      * 整层重建图片平面（`importData` 与预览那一路）。
      * ⚠️ 进来的地址必须是**已补回域名**的绝对形态：补域名只有 `importData` 那一处（与 `textures` 同一把 `assetUrl` 尺），
@@ -344,6 +365,9 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      * 2026-10-26 决定：取回与「挂进父元素」分两拍 —— 地址一次性全交给下载（网络 + 解析不占渲染帧），
      *   真正进场景图那一步交给 `threeUtils.addWork` ⇒ 全局 rAF 每拍只跑一项 = **一帧只挂一颗槽**
      *   （挂载那一拍要重算包围盒 + 排布 + 首次把整棵子树的几何送上 GPU，十几颗挤在同一帧就是他要拆掉的那一卡）。
+     * 2026-10-28 再加第三拍「点亮」：挂载那一拍走的是 setTimeout 链，主线程被几十次 GLB 解析压住时渲染帧会滞后，
+     *   于是好几颗在同一记 render 里首次上 GPU ⇒ 整层重建出来的槽先压着不亮，由 `tickProgressiveReveal`
+     *   **一帧只放一颗**（那一下顶点缓冲上传 + program 编译才真正摊到 N 帧上）。单颗那两路（落点新增 / 复制 / 上传）不受这一拍管。
      */
     setModels(datas: ModelSlotData[], onEachLoad?: () => void): void;
     /** 把「备好待挂」的那一槽交给全局队列；⛔ 去重闸门自备（`addWork` 按闭包引用判重，新闭包它判不出来） */
@@ -365,6 +389,15 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     private _queueImagePlaneBind;
     /** 队列里的一格：只绑**这一颗**平面里已就绪的那几格；还有在途的就重新排队，⛔ 不在这里等、也⛔ 不顺手把别的平面一起做完。 */
     private _bindImagePlaneStep;
+    /**
+     * 逐帧点亮：每帧从在册表里放行**一颗**（内容已落定的第一颗），亮完就把这一颗出册。
+     * ⚠️ 一记只放一颗 ⇒ 顶点缓冲上传与首次 program 编译被摊到 N 帧，而不是同几帧里全上（那一下卡）。
+     * ⚠️ 由 `onBeforeRender` 每帧调（编辑态那份在 `MktDevMesh`，覆写时⛔ 不许漏掉这一句）；
+     *    表空了它就是一句 `length` 判断，⛔ 不需要再像旧写法那样把钩子置 null（钩子上还挂着全景投影那三件事）。
+     * ⚠️ 这里写的 `visible` 只针对**自己压进表的那几颗** ⇒ 表外的对象（单颗新增、已 dispose、被 `releaseReveal`
+     *    摘牌的）一律不碰；要在放行前接管某颗，调 `releaseReveal(o)`。
+     */
+    tickProgressiveReveal(): void;
     /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
      *  @param projName 项目名（可选，优先于 `setProjectName` 注入的那个）——图片地址落成 `{项目名}/xxx.jpg` */
     exportData(projName?: string): MktMeshData;

package/MktMesh/MktMesh.js

@@ -150,7 +150,7 @@ export default class MktMesh extends Mesh {
     _ossSizeDepKeys = new Set();
     /** 渲染器：由 `onBeforeRender` 每帧捕获，预上传走它的 `initTexture`；没捕获到就退回 three 的自绑路径（不报错） */
     _glRenderer = null;
-    /** ⭐ 32 瓦片（横 8 × 竖 4 切片）离屏拼合器：左右 2 槽纹理由它逐格拼出（每帧一张新纹理进 GPU + 已进 GPU 的逐格画）。
+    /** ⭐ 32 瓦片（横 8 × 竖 4 切片，每槽 4×4=16 格、槽纹理 6144×6144）离屏拼合器：左右 2 槽纹理由它逐格拼出（每帧一张新纹理进 GPU + 已进 GPU 的逐格画）。
      *  编辑器渲染器经 `panoStitcher` 复用同一实例（同一份槽纹理缓存，⛔ 不另建第二份显存）。
      *  皇上旨 2026-10-06「不用 canvas 2D 的 drawImage 拼合, 用一个 shader 一个一个渲染到 RT 上面去」
      *  +「canvas 是什么意思, 按照我的想法, 不应该有 canvas 才对啊」⇒ **只此一份实现**：旧的 canvas 2D
@@ -167,7 +167,7 @@ export default class MktMesh extends Mesh {
     /** 纹理 OSS 缩放尺寸（1024 / 2048 / 空=原图），由外部 setOssSize 注入；默认 1024 保持旧行为。
      *  编辑器渲染器与预览渲染器各自把 store.ossSize 推下来，使全景球/预览按该尺寸加载。 */
     _ossSize = "1024";
-    /** 全景纹理形态：tiled=左右 2 槽各装一张**拼合槽纹理**（该点 32 片 横 8 × 竖 4 → 2 张 4096×4096，10-06 晚旨）
+    /** 全景纹理形态：tiled=左右 2 槽各装一张**拼合槽纹理**（该点 32 片 横 8 × 竖 4 → 2 张 6144×6144；形态是 10-06 晚立的，槽尺寸 10-26 起是 6144²，2026-10-27 的切档一字未动）
      *  / whole=2 槽同为一张完整等距柱状原图。
      *  由外部 setPanoTexMode 注入（与 _ossSize 同一套注入路径），默认 tiled 保持改造前行为。 */
     _panoTexMode = "tiled";
@@ -204,6 +204,20 @@ export default class MktMesh extends Mesh {
      * 一帧只有一颗进 `_contentRoot`（进图那一拍要重算包围盒 + 排布 + 首次把几何送上 GPU）。
      */
     _modelMountQueued = new Set();
+    /**
+     * 「压着不亮、等内容落定后一帧放一颗」的在册表（2026-10-28 需求：进展厅时平面图与 GLB 全在同几帧里
+     * 首次送 GPU —— 顶点缓冲上传 + program 编译都在「亮出来的那一帧」，几十颗挤一起就是那一下卡）。
+     *
+     * ⚠️ 为什么闸口在**本对象的 `onBeforeRender`**、不在这颗平面/模型自己的：three 遍历场景图的第一句就是
+     *   `if ( object.visible === false ) return;`（`node_modules/three/build/three.module.js:29837`），
+     *   它和整棵子树当帧直接跳过 ⇒ 隐形对象**一次都不会**收到 `onBeforeRender`，挂在自己身上 = 永远不亮。
+     *   墙（本对象）每帧都进渲染列表，所以闸口设在这座上，在册表里逐帧放行。
+     * ⚠️ 单颗新增那两路（编辑态双击落点 / 复制 / 上传）⛔ 不进这张表 —— 刚加的东西必须当场看得见。
+     * ⚠️ `visible` 本是业务的旋钮，这里只是**借一帧**：整层重建那两路的对象是当场新建的（默认可见），所以进表前
+     *    不需要再看它一眼；但**放行那一拍之前**要接管某颗的显隐，必须调 `releaseReveal(o)` 摘牌，
+     *    否则它会在轮到自身那一帧被写回可见（`boolean` 只有一个位，放行那里分不出这笔是谁写的）。
+     */
+    _revealPending = [];
     constructor(opts = {}) {
         // 发布/预览态墙：**固定**用「全景序号直取」着色器（皇上旨 2026-09-29：mktmesh 就只有按照 attribute
         // 配置来显示全景这一种固定的 shader——每帧由 feedFaceMapping 按 panoFaceMapping 把被引用的全景
@@ -234,6 +248,7 @@ export default class MktMesh extends Mesh {
             this.syncProjInvMatrix();
             this.updateTexture(camera);
             this.feedFaceMapping();
+            this.tickProgressiveReveal();
         };
     }
     // ───────────────────────── 墙体几何（由点位挤出） ─────────────────────────
@@ -1055,10 +1070,11 @@ export default class MktMesh extends Mesh {
             this.imagePlanes.splice(i, 1);
         this._imgBindQueued.delete(ip);
         this._imgBindDone.delete(ip);
+        this._dropReveal(ip);
         this.remove(ip);
         ip.dispose();
     }
-    /** 单颗模型槽入层（编辑态双击落点、以及「复制模型」用） */
+    /** 单颗模型槽入层（编辑态双击落点、以及「复制模型」用）：⛔ 不压点亮 —— 刚加的必须当场看得见 */
     addModel(ms) {
         this.models.push(ms);
         this.add(ms);
@@ -1070,9 +1086,23 @@ export default class MktMesh extends Mesh {
         if (i >= 0)
             this.models.splice(i, 1);
         this._modelMountQueued.delete(ms);
+        this._dropReveal(ms);
         this.remove(ms);
         ms.dispose();
     }
+    /** 出「逐帧点亮」那张在册表（删除 / 整层重建旧的一批都走这里，⛔ 不许留已经 dispose 的对象） */
+    _dropReveal(o) {
+        const i = this._revealPending.indexOf(o);
+        if (i >= 0)
+            this._revealPending.splice(i, 1);
+    }
+    /**
+     * 把某颗平面/模型的显隐控制权交回调用方（2026-10-28：`visible` 上有业务在用，点亮那一拍⛔ 不能覆盖
+     * 放行之前写下的那一笔）。摘牌后它**仍是压着的**（整层重建那一路进来就是 `false`），要它可见就自己写 `true`。
+     */
+    releaseReveal(o) {
+        this._dropReveal(o);
+    }
     /**
      * 整层重建图片平面（`importData` 与预览那一路）。
      * ⚠️ 进来的地址必须是**已补回域名**的绝对形态：补域名只有 `importData` 那一处（与 `textures` 同一把 `assetUrl` 尺），
@@ -1082,6 +1112,7 @@ export default class MktMesh extends Mesh {
         this._imgBindQueued.clear();
         this._imgBindDone.clear();
         for (const ip of this.imagePlanes) {
+            this._dropReveal(ip);
             this.remove(ip);
             ip.dispose();
         }
@@ -1091,6 +1122,12 @@ export default class MktMesh extends Mesh {
             ip.applyData(d);
             this.imagePlanes.push(ip);
             this.add(ip);
+            // 压着等点亮：4 格地址齐全才有东西可画（片数那把尺 = 下面 `_queueImagePlaneBind` 的 `tiles.length !== 4`，
+            // ⛔ 不是这里另立一份）；不齐的那一档本来就整片 discard、永远落不定 ⇒ 不压（省得白占一帧在册表）。
+            if (d.tiles && d.tiles.length === 4) {
+                ip.visible = false;
+                this._revealPending.push(ip);
+            }
         }
         // 整层重建完立刻起排：地址一次性全交给下载、绑材质逐帧一记 ⇒ 宿主不驱动这一层也长得出来
         this.feedImagePlaneTiles();
@@ -1102,10 +1139,14 @@ export default class MktMesh extends Mesh {
      * 2026-10-26 决定：取回与「挂进父元素」分两拍 —— 地址一次性全交给下载（网络 + 解析不占渲染帧），
      *   真正进场景图那一步交给 `threeUtils.addWork` ⇒ 全局 rAF 每拍只跑一项 = **一帧只挂一颗槽**
      *   （挂载那一拍要重算包围盒 + 排布 + 首次把整棵子树的几何送上 GPU，十几颗挤在同一帧就是他要拆掉的那一卡）。
+     * 2026-10-28 再加第三拍「点亮」：挂载那一拍走的是 setTimeout 链，主线程被几十次 GLB 解析压住时渲染帧会滞后，
+     *   于是好几颗在同一记 render 里首次上 GPU ⇒ 整层重建出来的槽先压着不亮，由 `tickProgressiveReveal`
+     *   **一帧只放一颗**（那一下顶点缓冲上传 + program 编译才真正摊到 N 帧上）。单颗那两路（落点新增 / 复制 / 上传）不受这一拍管。
      */
     setModels(datas, onEachLoad) {
         this._modelMountQueued.clear();
         for (const ms of this.models) {
+            this._dropReveal(ms);
             this.remove(ms);
             ms.dispose();
         }
@@ -1114,9 +1155,15 @@ export default class MktMesh extends Mesh {
             const ms = new ModelSlot(d.name);
             ms.applyData(d);
             this.models.push(ms);
-            this.add(ms); // 槽本体（占位小立方体）当场进图 ⇒ GLB 在路上时这一槽不凭空消失
-            if (d.url)
+            // 槽本体（占位小立方体）当场进图：在册表、射线拾取、`exportData` 都立刻认它
+            this.add(ms);
+            if (d.url) {
+                // 压着等点亮：GLB 落进 `_contentRoot` 那一拍之后，还要再等一次「一帧一颗」的放行才上 GPU
+                //（⚠️ 与旧的「GLB 在路上时这一槽露出占位方块」不同：整层重建这一路一颗都不露，直到轮到自己亮）
+                ms.visible = false;
+                this._revealPending.push(ms);
                 void ms.loadModel(d.url).then(() => this._queueModelMount(ms, onEachLoad));
+            }
         }
     }
     /** 把「备好待挂」的那一槽交给全局队列；⛔ 去重闸门自备（`addWork` 按闭包引用判重，新闭包它判不出来） */
@@ -1202,6 +1249,25 @@ export default class MktMesh extends Mesh {
         }
         this._imgBindDone.set(ip, sig); // 全部落定（含下载失败那格：它留 null，那一格就永久 discard）
     }
+    /**
+     * 逐帧点亮：每帧从在册表里放行**一颗**（内容已落定的第一颗），亮完就把这一颗出册。
+     * ⚠️ 一记只放一颗 ⇒ 顶点缓冲上传与首次 program 编译被摊到 N 帧，而不是同几帧里全上（那一下卡）。
+     * ⚠️ 由 `onBeforeRender` 每帧调（编辑态那份在 `MktDevMesh`，覆写时⛔ 不许漏掉这一句）；
+     *    表空了它就是一句 `length` 判断，⛔ 不需要再像旧写法那样把钩子置 null（钩子上还挂着全景投影那三件事）。
+     * ⚠️ 这里写的 `visible` 只针对**自己压进表的那几颗** ⇒ 表外的对象（单颗新增、已 dispose、被 `releaseReveal`
+     *    摘牌的）一律不碰；要在放行前接管某颗，调 `releaseReveal(o)`。
+     */
+    tickProgressiveReveal() {
+        const q = this._revealPending;
+        for (let i = 0; i < q.length; i++) {
+            const o = q[i];
+            if (!o.loaded)
+                continue; // 内容还在路上 ⇒ 这一颗继续压着，先看后面已经落定的
+            q.splice(i, 1);
+            o.visible = true;
+            return;
+        }
+    }
     /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
      *  @param projName 项目名（可选，优先于 `setProjectName` 注入的那个）——图片地址落成 `{项目名}/xxx.jpg` */
     exportData(projName) {
@@ -1322,6 +1388,7 @@ export default class MktMesh extends Mesh {
         this._imgBindQueued.clear();
         this._imgBindDone.clear();
         this._modelMountQueued.clear();
+        this._revealPending = [];
         this._stitcher.dispose();
         this._glRenderer = null;
         if (this._placeholder)