three-base 2.0.190 → 2.0.193

package/MktMesh/panoTileStitcher.js

@@ -220,7 +220,7 @@ export class PanoTileStitcher {
      *  ⚠️ 唯一按张数**能混进来**的是 10-06 那版同为 32 片的老档（切片顺序与槽分组两版一致 ⇒ 不会错位），
      *  但它的瓦片是 1024²、被画进 1536² 的格子 = 1.5× 放大 ⇒ 发虚，那类老点仍要重传一次。
      *  ⚠️ 每槽数组长度由 `RT_STITCH_SLOT_COUNT` 派生（⛔ 不许手写 `[null,null]` —— 槽数再变会漏改）。 */
-    ensure(urls, layout) {
+    ensure(urls, layout, front = false) {
         const L = layout ?? PANO_TILE_LAYOUT;
         const maxTiles = tilesPerBatchOf(L);
         if (!urls || urls.length === 0 || urls.length > maxTiles)
@@ -229,8 +229,11 @@ export class PanoTileStitcher {
         while (u.length < maxTiles)
             u.push("");
         const batch = rtStitchBatchOf(u);
-        if (this._groups.has(batch))
+        if (this._groups.has(batch)) {
+            if (front)
+                this._toFront(batch);
             return;
+        }
         const slotCount = L.slotCount;
         const cellsPerSlot = cellsPerSlotOf(L);
         this._groups.set(batch, {
@@ -244,8 +247,26 @@ export class PanoTileStitcher {
             drawnCount: Array.from({ length: slotCount }, () => 0),
             pending: slotCount,
         });
+        if (front)
+            this._toFront(batch);
         this._stamp++;
     }
+    /** 把一批挪到在册顺序的**最前**（只动 Map 的顺序，⛔ 不动组里任何东西：RT、已画格子、瓦片账本原样）。
+     *  已在最前 ⇒ 一次 `keys().next()` 就返回（每帧点名走的就是这条零成本支路）。 */
+    _toFront(batch) {
+        const g = this._groups.get(batch);
+        if (!g)
+            return;
+        const head = this._groups.keys().next();
+        if (!head.done && head.value === batch)
+            return;
+        const rest = [...this._groups.entries()];
+        this._groups.clear();
+        this._groups.set(batch, g);
+        for (const [k, v] of rest)
+            if (k !== batch)
+                this._groups.set(k, v);
+    }
     /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 `cellsPerSlot` 格画满）。
      *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
     peek(batch, slot, renderer) {

package/MktMesh/panoTileStitcher.ts

@@ -238,8 +238,11 @@ interface StitchGroup {
 export interface PanoStitcher {
     /** 确保批次已在册并发起瓦片加载（幂等；同批已在册 ⇒ 什么都不做）。
      *  新增可选 `layout` 参数：缺省 = PANO_TILE_LAYOUT（全景 8×4 / 2 槽 / 6144×6144，2026-10-27 需求）；
-     *  图片平面传 `imageTileLayout(natW, natH)`（2×2 / 1 槽 / RT 宽高比=原图）。 */
-    ensure(urls: string[], layout?: TileLayout): void;
+     *  图片平面传 `imageTileLayout(natW, natH)`（2×2 / 1 槽 / RT 宽高比=原图）。
+     *  新增可选 `front` 参数（2026-10-29 需求）：`true` ⇒ 这一批**挪到在册顺序最前** = 每帧那三道工序
+     *  先取它的料（下载额度「每帧 2 张」先归它）。消费方每帧点一次 ⇒ 换渲染器那次整份作废后，
+     *  下一帧又把头名抢回来（⛔ 光靠「先入册」做不到，见 `MktMesh.prefetchHeadPanoramas` 的说明）。 */
+    ensure(urls: string[], layout?: TileLayout, front?: boolean): void;
     /**
      * 取某一拼合槽的纹理。**画过 ≥1 格就返回**（同日旨「需要先喂给 shader」）。
      * ⭐ 2026-10-09 皇上旨「切换全景时上一个全景的内容要渲染成深灰」：**传了 `renderer` 且该槽一格都还没画时，
@@ -326,14 +329,17 @@ private _uploadQueued: Set<TileRec> = new Set();
      *  ⚠️ 唯一按张数**能混进来**的是 10-06 那版同为 32 片的老档（切片顺序与槽分组两版一致 ⇒ 不会错位），
      *  但它的瓦片是 1024²、被画进 1536² 的格子 = 1.5× 放大 ⇒ 发虚，那类老点仍要重传一次。
      *  ⚠️ 每槽数组长度由 `RT_STITCH_SLOT_COUNT` 派生（⛔ 不许手写 `[null,null]` —— 槽数再变会漏改）。 */
-    ensure(urls: string[], layout?: TileLayout): void {
+    ensure(urls: string[], layout?: TileLayout, front = false): void {
         const L = layout ?? PANO_TILE_LAYOUT;
         const maxTiles = tilesPerBatchOf(L);
         if (!urls || urls.length === 0 || urls.length > maxTiles) return;
         const u = urls.slice();
         while (u.length < maxTiles) u.push("");
         const batch = rtStitchBatchOf(u);
-        if (this._groups.has(batch)) return;
+        if (this._groups.has(batch)) {
+            if (front) this._toFront(batch);
+            return;
+        }
         const slotCount = L.slotCount;
         const cellsPerSlot = cellsPerSlotOf(L);
         this._groups.set(batch, {
@@ -347,9 +353,23 @@ private _uploadQueued: Set<TileRec> = new Set();
             drawnCount: Array.from({ length: slotCount }, () => 0),
             pending: slotCount,
         });
+        if (front) this._toFront(batch);
         this._stamp++;
     }
 
+    /** 把一批挪到在册顺序的**最前**（只动 Map 的顺序，⛔ 不动组里任何东西：RT、已画格子、瓦片账本原样）。
+     *  已在最前 ⇒ 一次 `keys().next()` 就返回（每帧点名走的就是这条零成本支路）。 */
+    private _toFront(batch: string): void {
+        const g = this._groups.get(batch);
+        if (!g) return;
+        const head = this._groups.keys().next();
+        if (!head.done && head.value === batch) return;
+        const rest = [...this._groups.entries()];
+        this._groups.clear();
+        this._groups.set(batch, g);
+        for (const [k, v] of rest) if (k !== batch) this._groups.set(k, v);
+    }
+
     /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 `cellsPerSlot` 格画满）。
      *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
     peek(batch: string, slot: number, renderer?: WebGLRenderer | null): Texture | null {

package/MktMesh/types.d.ts

@@ -1,6 +1,7 @@
 import type { Matrix4 } from "three";
 import type { ImagePlaneData } from "./imagePlane";
 import type { ModelSlotData } from "./modelSlot";
+import type { GlassPaneData } from "./glassPane";
 /**
  * 单个纹理的运行时信息：url + 矩阵（位置 + 旋转，缩放忽略）。
  * ⚠️ 这个矩阵记在 MktMesh **自身局部（制图）空间**，与 `wallPoints` 同一空间 —— 不是世界矩阵：
@@ -87,4 +88,9 @@ export interface MktMeshData {
     images?: ImagePlaneData[];
     /** 模型槽层（同一道旨）：`url` 是 .glb 的相对地址；空串 = 还没上传 ⇒ 显示占位小立方体 */
     models?: ModelSlotData[];
+    /**
+     * 玻璃面层（2026-10-28 需求「正方的面」）：正方形、双面、transmission 折射，反射环境取运行时第一个全景。
+     * ⛔ 这一层不落任何素材地址 ⇒ 既不过 `stripAssetHost` 也不过 `absAssetUrl`，只有位置/旋转/边长。
+     */
+    glass?: GlassPaneData[];
 }

package/MktMesh/types.ts

@@ -8,6 +8,7 @@
 import type { Matrix4 } from "three";
 import type { ImagePlaneData } from "./imagePlane";
 import type { ModelSlotData } from "./modelSlot";
+import type { GlassPaneData } from "./glassPane";
 
 /**
  * 单个纹理的运行时信息：url + 矩阵（位置 + 旋转，缩放忽略）。
@@ -99,4 +100,9 @@ export interface MktMeshData {
     images?: ImagePlaneData[];
     /** 模型槽层（同一道旨）：`url` 是 .glb 的相对地址；空串 = 还没上传 ⇒ 显示占位小立方体 */
     models?: ModelSlotData[];
+    /**
+     * 玻璃面层（2026-10-28 需求「正方的面」）：正方形、双面、transmission 折射，反射环境取运行时第一个全景。
+     * ⛔ 这一层不落任何素材地址 ⇒ 既不过 `stripAssetHost` 也不过 `absAssetUrl`，只有位置/旋转/边长。
+     */
+    glass?: GlassPaneData[];
 }

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.193",
   "description": "A Three.js extension library providing common 3D components, animations, materials, and utilities",
   "author": "xiaosihan",
   "publishConfig": {
@@ -47,6 +47,11 @@
       "import": "./MktMesh/modelSlot.js",
       "require": "./MktMesh/modelSlot.js"
     },
+    "./MktMesh/glassPane": {
+      "types": "./MktMesh/glassPane.d.ts",
+      "import": "./MktMesh/glassPane.js",
+      "require": "./MktMesh/glassPane.js"
+    },
     "./MktMesh/boxLine2": {
       "types": "./MktMesh/boxLine2.d.ts",
       "import": "./MktMesh/boxLine2.js",

package/threeLoader.js

@@ -28,6 +28,8 @@ class ThreeLoader extends EventDispatcher {
         };
         // 资源加载进度
         DefaultLoadingManager.onProgress = (url, loaded, total) => {
+            // 三个数一并转发：首页只认「还在不在加载」，弹窗一类要看进度
+            this.dispatchEvent({ type: "progress", url, loaded, total });
             if (loaded < total) {
                 this.dispatchEvent({ type: "loadding" });
             }

package/threeLoader.ts

@@ -32,6 +32,8 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
         };
         // 资源加载进度
         DefaultLoadingManager.onProgress = (url: string, loaded: number, total: number) => {
+            // 三个数一并转发：首页只认「还在不在加载」，弹窗一类要看进度
+            this.dispatchEvent({ type: "progress", url, loaded, total });
             if (loaded < total) {
                 this.dispatchEvent({ type: "loadding" });
             }