three-base 2.0.195 → 2.0.197

package/MktMesh/panoTileStitcher.ts

@@ -177,6 +177,29 @@ function grayToSrgbVec3(hex: string): Vector3 {
     return new Vector3(byte(0), byte(2), byte(4));
 }
 
+/** 「这张槽还没有任何内容」时交出去的**共享**素色纹理（2026-11-01 需求「进厅不要卡一下」）。
+ *
+ *  为什么不是「先建一张全尺寸 RT、整张涂灰、再交出去」：那条路在消费方点到某个还没画过的槽时就跑一次，
+ *  而一次点屏会把名册那 8 个景点 × 每点 2 槽 = 16 个槽全点一遍 ⇒ 同一帧里建出 16 张 6144×6144 的渲染目标
+ *  （单张 151MB 显存，含 mipmap ≈201MB；外加 16 次整张预涂 = 约 6 亿像素填充 + 16 条 mipmap 链）。
+ *  而这一刻屏幕上要的**只是一片素色灰**，逐像素根本看不出尺寸 ⇒ 交这张 1×1 的：
+ *  字节 = `MISSING_TILE_GRAY`（与「新建 RT 整张预涂灰」落进显存的字节逐字相同），标 `SRGBColorSpace`
+ *  ⇒ 采样出来的线性值与采那张灰 RT 完全一致 ⇒ 屏幕上同一色，显存与那一帧的填充归零。
+ *  真正的 RT 退回**懒建**：`_drawPass` 画进该槽第一格瓦片时才建（建好仍立刻整张涂灰，未定义像素那条规矩一字未动）。 */
+function createGrayStandIn(): DataTexture {
+    const s = MISSING_TILE_GRAY.replace("#", "");
+    const byte = (i: number) => parseInt(s.slice(i, i + 2), 16);
+    const tex = new DataTexture(new Uint8Array([byte(0), byte(2), byte(4), 255]), 1, 1, RGBAFormat, UnsignedByteType);
+    tex.colorSpace = SRGBColorSpace;
+    tex.wrapS = ClampToEdgeWrapping;
+    tex.wrapT = ClampToEdgeWrapping;
+    tex.minFilter = LinearFilter;
+    tex.magFilter = LinearFilter;
+    tex.generateMipmaps = false;
+    tex.needsUpdate = true;
+    return tex;
+}
+
 /** 全屏 quad 的片元：只干「把一片瓦片的**中间那块**原样搬进 RT 的一格」。
  *  ⛔ 不加色彩转换、不加 tone mapping（见文件头画质第 2 条）。 */
 const STITCH_VERT = /* glsl */ `
@@ -258,17 +281,20 @@ export interface PanoStitcher {
     prioritize(urls: string[], layout?: TileLayout): void;
     /**
      * 取某一拼合槽的纹理。**画过 ≥1 格就返回**（同日旨「需要先喂给 shader」）。
-     * ⭐ 2026-10-09 皇上旨「切换全景时上一个全景的内容要渲染成深灰」：**传了 `renderer` 且该槽一格都还没画时，
-     *   先把 RT 建出来（建完即整张涂 `MISSING_TILE_GRAY` 缺失灰）并返回它** ⇒ 调用方切批次的那一帧
+     * ⭐ 2026-10-09 需求「切换全景时上一个全景的内容要渲染成深灰」：**传了 `renderer` 且该槽一格都还没画时
+     *   返回共享的 1×1 缺失灰纹理**（屏幕上与「刚整张涂过灰的那张 RT」逐字节同色）⇒ 调用方切批次的那一帧
      *   拿到的就是**深灰底**而非 null（null 会让它沿用上一批 ⇒ 墙上闪上一个全景）。
-     *   ⛔ 没传 `renderer`（诊断/测试路径）仍旧返回 null —— 不能在无 GL 上下文时凭空建 RT。
+     *   ⚠️ 2026-11-01：这一支原先是**当场建一张 6144×6144 的 RT** 再交出去 ⇒ 名册 8 点 × 2 槽 = 同一帧 16 张
+     *   （≈3.2GB 显存 + 约 6 亿像素预涂），是「进厅那一下卡」的本体；现在 RT 退回 `_drawPass` 画第一格时懒建。
+     *   ⛔ 没传 `renderer`（诊断/测试路径）仍旧返回 null。
      */
     peek(batch: string, slot: number, renderer?: WebGLRenderer | null): Texture | null;
     /** 每帧驱动（消费方每帧只调一次）。`renderer` = 调用方当前的 WebGLRenderer，还没捕获到就传 null
      *  ⇒ 这一帧什么都不画（⛔ 不打假读数，也⛔ 不退回任何 CPU 拼合路径）。 */
     pump(renderer: WebGLRenderer | null): void;
-    /** 这张槽纹理是否**已经在 GPU 上**（RT 版恒 true）：消费方据此跳过「每 tick 一张」预上传闸。
-     *  ⚠️ 返回 true 的纹理绝不能喂给 `renderer.initTexture` —— 它不是普通纹理，是 three 自己管的渲染目标附件。 */
+    /** 这张槽纹理是否**不需要走「每 tick 一张上传」那道闸**（RT 附件与共享的 1×1 缺失灰都算）：
+     *  消费方据此直接绑定，不再排预上传队列。
+     *  ⚠️ 返回 true 的纹理绝不能喂给 `renderer.initTexture` —— 前者是 three 自己管的渲染目标附件。 */
     resident(tex: Texture): boolean;
     /** 该批次是否已在册（诊断/测试用） */
     has(batch: string): boolean;
@@ -331,6 +357,8 @@ private _uploadQueued: Set<TileRec> = new Set();
     private _blank: DataTexture = new DataTexture(new Uint8Array([0, 0, 0, 255]), 1, 1);
     /** 本拼合器发出去的槽纹理 = RT 附件（`resident()` 认它）；⛔ 不许喂给 `renderer.initTexture` */
     private _rtTextures: WeakSet<Texture> = new WeakSet();
+    /** 「还没画过」那一路交出去的共享 1×1 素色纹理（见 `createGrayStandIn`）：一座拼合器一份，⛔ 不随组建/拆 */
+    private _grayStandIn: DataTexture = createGrayStandIn();
 
     constructor() {
         this._quad.frustumCulled = false; // 正交相机 + 手工摆位，⛔ 别按包围球把格子剔没了
@@ -403,30 +431,34 @@ private _uploadQueued: Set<TileRec> = new Set();
     }
 
     /** 取某一拼合槽的纹理：**画过 ≥1 格就交出去**（同日旨「需要先喂给 shader」⇒ 不再等 `cellsPerSlot` 格画满）。
-     *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。 */
+     *  RT 建好时整张涂过缺失灰 ⇒ 交出去的那张里**没有未定义像素**，观感 = 该象限逐格显影。
+     *  还没画过任何格时交的是**共享的 1×1 素色纹理**（屏幕上与「刚涂满缺失灰的那张 RT」同色，见 `createGrayStandIn`），
+     *  ⛔ 不再为「垫一片灰」当场建一张 6144×6144 的渲染目标。 */
     peek(batch: string, slot: number, renderer?: WebGLRenderer | null): Texture | null {
         const g = this._groups.get(batch);
         if (!g) return null;
         if (!g.drawnCount[slot]) {
-            // ⭐ 皇上 2026-10-09 旨「切换全景时上一个全景的内容要渲染成深灰」：
+            // 需求（2026-10-09）「切换全景时上一个全景的内容要渲染成深灰」：
             //   换批次的瞬间新全景还没画进任何格，若此处照旧返回 null，消费方 `panoSlotBind` 会
-            //   **沿用上一批的 RT 纹理** ⇒ 墙上继续显示上一个全景（皇上报的现象）。
-            //   这里改为：只要调用方给了 renderer，就**先把这张 RT 建出来**（`_ensureRt` 建完立刻
-            //   整张涂 `MISSING_TILE_GRAY` 缺失灰）并交出去 ⇒ 切换瞬间该象限就是**深灰底**，
-            //   随后随`pump` 逐格显影。观感 = 深灰 → 逐格填图，不再闪上一个全景的内容。
-            //   ⛔ 没给 renderer（诊断/测试路径）仍旧返回 null —— 不能在无 GL 上下文时凭空建 RT。
+            //   **沿用上一批的 RT 纹理** ⇒ 墙上继续显示上一个全景（报上来的现象）。
+            //   所以这一支仍要**交出点东西**：现在交的是共享那张 1×1 素色（与缺失灰逐字节同值），
+            //   随后随 `pump` 逐格显影。观感 = 深灰 → 逐格填图，一字未变；变的是「不再为一片灰建整张 RT」。
+            //   ⚠️ 2026-11-01：这一支原先是 `this._ensureRt(...)` ⇒ 一次点屏（名册 8 点 × 2 槽）就在同一帧
+            //     建出 16 张 6144² 渲染目标（≈3.2GB 显存 + 6 亿像素预涂），正是「进厅那一下卡」的本体。
+            //   ⛔ 没给 renderer（诊断/测试路径）仍旧返回 null，与消费方约定的「问不到就是没就绪」一致。
             if (!renderer) return null;
             if (!this._renderer) return null;
-            return this._ensureRt(this._renderer, g, slot).texture;
+            return this._grayStandIn;
         }
         const rt = g.rts[slot];
         return rt ? rt.texture : null;
     }
 
     /** ⭐ 这条路交出去的槽纹理本来就是 GL 渲染目标的附件 —— 像素已经在显存里，没有「上传」这一步。
-     *  消费方（`MktMesh._peekTileAt` / 编辑器 `_peekTileAt`）据此**跳过**「每 tick 一张 `initTexture`」那道闸。 */
+     *  消费方（`MktMesh._peekTileAt` / 编辑器 `_peekTileAt`）据此**跳过**「每 tick 一张 `initTexture`」那道闸。
+     *  「还没画过」那一路交的共享 1×1 素色同样认（它本来就只是给 sampler 垫一个合法纹理，⛔ 别把它排进上传队列）。 */
     resident(tex: Texture): boolean {
-        return this._rtTextures.has(tex);
+        return this._rtTextures.has(tex) || tex === this._grayStandIn;
     }
 
     has(batch: string): boolean {
@@ -476,6 +508,7 @@ private _uploadQueued: Set<TileRec> = new Set();
         this._quad.geometry.dispose();
         this._mat.dispose();
         this._blank.dispose();
+        this._grayStandIn.dispose();
         this._scene.remove(this._quad);
     }
 

package/package.json

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

package/threeLoader.d.ts

@@ -9,6 +9,20 @@ import { PLYLoader } from "three/examples/jsm/Addons";
 import type { ThreeLoaderEventMap } from "./EventMap";
 declare class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
     constructor();
+    /** 已经报过的失败地址（去重只服务「计数」，不影响事件本身 —— 事件仍每次发，页面可按 `isNew` 决定要不要提示） */
+    private _failedUrls;
+    /** 全站累计**失败地址数**（与 manager 的 itemsTotal/itemsLoaded 同口径：累加、永不清零 ⇒ 页面自己算「本次」） */
+    loadErrorCount: number;
+    /** 地址 → 服务端回的状态码。只有**拿到过回复**的那两路写得进来：`loadPanoTexture` 的非 2xx（全景整图/32 片切片、平面 4 片）
+     *  与 `loadModel` 的下载失败（GLB 等）。用来把「服务器明说没有」和「断网 / 解码失败」分开 —— 前者页面才敢删数据。 */
+    private _urlStatus;
+    /** 记下一个地址的服务端状态码（键必须与失败上报用的那一个地址串一致） */
+    markUrlStatus(url: string, status: number): void;
+    /** 失败的唯一上报口：`DefaultLoadingManager.onError`（素材那一路）与 `ModelSlot` 那颗 GLB 没出来（模型那一路）都走这里。 */
+    reportLoadError(url: string, kind: "asset" | "model", label?: string): void;
+    /** 从加载器抛出的错误里取 HTTP 状态码，记在**调用方那一个地址**上（`url` 原样，不是内部补全后的地址）。
+     *  three 的 `FileLoader` 非 2xx 抛 `HttpError`（`err.response.status`），个别加载器只把码写进 message。 */
+    private _noteErrStatus;
     getFilename(url: string): string;
     uuid: string;
     anisotropy: number;

package/threeLoader.js

@@ -40,6 +40,12 @@ class ThreeLoader extends EventDispatcher {
         DefaultLoadingManager.onLoad = () => {
             this.onload = true;
         };
+        // 资源加载失败：走 manager 计数的每一条（全景整图/32 片切片、图片平面 4 片、GLB 下载与内嵌贴图）
+        // 都只从这里出，页面侧仍只订本类这一个出口（与 onProgress 同规矩，⛔ 页面不许自己占 manager 的槽位）。
+        // 同一地址去重：全景/平面那两路失败会每帧重发请求 ⇒ 不去重「失败数」会被刷成无穷大。
+        DefaultLoadingManager.onError = (url) => {
+            this.reportLoadError(url, "asset");
+        };
         // 资源替换
         DefaultLoadingManager.setURLModifier((url) => {
             //全路径匹配资源
@@ -58,6 +64,40 @@ class ThreeLoader extends EventDispatcher {
             return new_url;
         });
     }
+    /** 已经报过的失败地址（去重只服务「计数」，不影响事件本身 —— 事件仍每次发，页面可按 `isNew` 决定要不要提示） */
+    _failedUrls = new Set();
+    /** 全站累计**失败地址数**（与 manager 的 itemsTotal/itemsLoaded 同口径：累加、永不清零 ⇒ 页面自己算「本次」） */
+    loadErrorCount = 0;
+    /** 地址 → 服务端回的状态码。只有**拿到过回复**的那两路写得进来：`loadPanoTexture` 的非 2xx（全景整图/32 片切片、平面 4 片）
+     *  与 `loadModel` 的下载失败（GLB 等）。用来把「服务器明说没有」和「断网 / 解码失败」分开 —— 前者页面才敢删数据。 */
+    _urlStatus = new Map();
+    /** 记下一个地址的服务端状态码（键必须与失败上报用的那一个地址串一致） */
+    markUrlStatus(url, status) {
+        if (url)
+            this._urlStatus.set(url, status);
+    }
+    /** 失败的唯一上报口：`DefaultLoadingManager.onError`（素材那一路）与 `ModelSlot` 那颗 GLB 没出来（模型那一路）都走这里。 */
+    reportLoadError(url, kind, label) {
+        const isNew = !this._failedUrls.has(url);
+        if (isNew) {
+            this._failedUrls.add(url);
+            this.loadErrorCount++;
+        }
+        const status = this._urlStatus.get(url);
+        // 403 与 404 并一档：OSS 私有桶里「key 不存在」回的正是 403（AccessDenied 用来不泄露对象是否存在）。
+        const missing = status === 404 || status === 403;
+        this.dispatchEvent({ type: "loadError", url, kind, label, status, missing, failed: this.loadErrorCount, isNew });
+    }
+    /** 从加载器抛出的错误里取 HTTP 状态码，记在**调用方那一个地址**上（`url` 原样，不是内部补全后的地址）。
+     *  three 的 `FileLoader` 非 2xx 抛 `HttpError`（`err.response.status`），个别加载器只把码写进 message。 */
+    _noteErrStatus(url, err) {
+        if (!isString(url))
+            return;
+        const e = err;
+        const raw = e?.status ?? e?.response?.status ?? Number(/(?:responded with|HTTP) (\d{3})/.exec(e?.message ?? "")?.[1]);
+        if (Number.isFinite(raw))
+            this.markUrlStatus(url, raw);
+    }
     // 从url 中提取文件名
     getFilename(url) {
         // 移除URL的查询字符串和哈希部分
@@ -364,7 +404,8 @@ class ThreeLoader extends EventDispatcher {
                     });
                     return res;
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                    this._noteErrStatus(url, err);
                     console.error(`${url},加载失败`);
                     return undefined;
                 });
@@ -381,6 +422,7 @@ class ThreeLoader extends EventDispatcher {
                     return res.scene;
                 })
                     .catch((err) => {
+                    this._noteErrStatus(url, err);
                     // 打印详细错误信息，方便调试
                     console.error(`${url},加载失败`, err);
                     return undefined;
@@ -398,7 +440,8 @@ class ThreeLoader extends EventDispatcher {
                         roughness: 0.5,
                     }));
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                    this._noteErrStatus(url, err);
                     console.error(`${url},加载失败`);
                     return undefined;
                 });
@@ -434,7 +477,8 @@ class ThreeLoader extends EventDispatcher {
                     }
                     return plyMesh;
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                    this._noteErrStatus(url, err);
                     console.error(`${url},加载失败`);
                     return undefined;
                 });
@@ -462,6 +506,7 @@ class ThreeLoader extends EventDispatcher {
                     return res;
                 })
                     .catch((err) => {
+                    this._noteErrStatus(url, err);
                     console.error(`${url},加载失败`, err);
                     return undefined;
                 });

package/threeLoader.ts

@@ -44,6 +44,12 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
         DefaultLoadingManager.onLoad = () => {
             this.onload = true;
         };
+        // 资源加载失败：走 manager 计数的每一条（全景整图/32 片切片、图片平面 4 片、GLB 下载与内嵌贴图）
+        // 都只从这里出，页面侧仍只订本类这一个出口（与 onProgress 同规矩，⛔ 页面不许自己占 manager 的槽位）。
+        // 同一地址去重：全景/平面那两路失败会每帧重发请求 ⇒ 不去重「失败数」会被刷成无穷大。
+        DefaultLoadingManager.onError = (url: string) => {
+            this.reportLoadError(url, "asset");
+        };
         // 资源替换
         DefaultLoadingManager.setURLModifier((url: string) => {
             //全路径匹配资源
@@ -62,6 +68,37 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
             return new_url;
         });
     }
+    /** 已经报过的失败地址（去重只服务「计数」，不影响事件本身 —— 事件仍每次发，页面可按 `isNew` 决定要不要提示） */
+    private _failedUrls: Set<string> = new Set();
+    /** 全站累计**失败地址数**（与 manager 的 itemsTotal/itemsLoaded 同口径：累加、永不清零 ⇒ 页面自己算「本次」） */
+    loadErrorCount: number = 0;
+    /** 地址 → 服务端回的状态码。只有**拿到过回复**的那两路写得进来：`loadPanoTexture` 的非 2xx（全景整图/32 片切片、平面 4 片）
+     *  与 `loadModel` 的下载失败（GLB 等）。用来把「服务器明说没有」和「断网 / 解码失败」分开 —— 前者页面才敢删数据。 */
+    private _urlStatus: Map<string, number> = new Map();
+    /** 记下一个地址的服务端状态码（键必须与失败上报用的那一个地址串一致） */
+    markUrlStatus(url: string, status: number): void {
+        if (url) this._urlStatus.set(url, status);
+    }
+    /** 失败的唯一上报口：`DefaultLoadingManager.onError`（素材那一路）与 `ModelSlot` 那颗 GLB 没出来（模型那一路）都走这里。 */
+    reportLoadError(url: string, kind: "asset" | "model", label?: string): void {
+        const isNew = !this._failedUrls.has(url);
+        if (isNew) {
+            this._failedUrls.add(url);
+            this.loadErrorCount++;
+        }
+        const status = this._urlStatus.get(url);
+        // 403 与 404 并一档：OSS 私有桶里「key 不存在」回的正是 403（AccessDenied 用来不泄露对象是否存在）。
+        const missing = status === 404 || status === 403;
+        this.dispatchEvent({ type: "loadError", url, kind, label, status, missing, failed: this.loadErrorCount, isNew });
+    }
+    /** 从加载器抛出的错误里取 HTTP 状态码，记在**调用方那一个地址**上（`url` 原样，不是内部补全后的地址）。
+     *  three 的 `FileLoader` 非 2xx 抛 `HttpError`（`err.response.status`），个别加载器只把码写进 message。 */
+    private _noteErrStatus(url: string | File | Array<File>, err: unknown): void {
+        if (!isString(url)) return;
+        const e = err as { status?: number; response?: { status?: number }; message?: string };
+        const raw = e?.status ?? e?.response?.status ?? Number(/(?:responded with|HTTP) (\d{3})/.exec(e?.message ?? "")?.[1]);
+        if (Number.isFinite(raw)) this.markUrlStatus(url, raw);
+    }
     // 从url 中提取文件名
     getFilename(url: string): string {
         // 移除URL的查询字符串和哈希部分
@@ -370,7 +407,8 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
                     });
                     return res;
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                        this._noteErrStatus(url, err);
                         console.error(`${url},加载失败`);
                         return undefined;
                     });
@@ -387,6 +425,7 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
                     return res.scene;
                 })
                     .catch((err) => {
+                        this._noteErrStatus(url, err);
                         // 打印详细错误信息，方便调试
                         console.error(`${url},加载失败`, err);
                         return undefined;
@@ -404,7 +443,8 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
                         roughness: 0.5,
                     }));
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                        this._noteErrStatus(url, err);
                         console.error(`${url},加载失败`);
                         return undefined;
                     });
@@ -440,7 +480,8 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
                     }
                     return plyMesh;
                 })
-                    .catch(() => {
+                    .catch((err) => {
+                        this._noteErrStatus(url, err);
                         console.error(`${url},加载失败`);
                         return undefined;
                     });
@@ -467,6 +508,7 @@ class ThreeLoader extends EventDispatcher<ThreeLoaderEventMap> {
                     return res;
                 })
                     .catch((err) => {
+                        this._noteErrStatus(url, err);
                         console.error(`${url},加载失败`, err);
                         return undefined;
                     });