three-base 2.0.196 → 2.0.198

package/EventMap.d.ts

@@ -20,6 +20,22 @@ export interface BeforeRenderEvent {
 export interface AfterRenderEvent {
     type: "afterRender";
 }
+export interface LoadErrorEvent {
+    type: "loadError";
+    url: string;
+    /** asset = 走 manager 计数的素材（全景整图/切片、平面瓦片、模型内嵌贴图）；model = 模型槽那颗 GLB 整体没出来 */
+    kind: "asset" | "model";
+    /** 仅 kind="model"：那一颗模型槽的名字，页面据此点名是哪一颗没出来 */
+    label?: string;
+    /** 全站累计失败地址数（与 manager 的 itemsTotal/itemsLoaded 同口径：累加、永不清零） */
+    failed: number;
+    /** 这个地址是不是第一次失败（同地址的后续重试仍发事件，但 isNew=false、不计数） */
+    isNew: boolean;
+    /** 服务端回的状态码（只在真的拿到过回复时有：全景/平面瓦片的 fetch 非 2xx、GLB 下载失败）；网络层失败为 undefined */
+    status?: number;
+    /** 服务端**明说这个地址没有**（404 / 403）⇒ 页面据此把引用它的那条数据整条删掉；断网一类没有回复的失败不算 */
+    missing: boolean;
+}
 export interface RAFEvent {
     type: "requestAnimationFrame";
     timeTemp: number;
@@ -60,6 +76,7 @@ export interface ThreeLoaderEventMap extends Object3DEventMap {
     "loadding": LoadingEvent;
     "onLoad": OnLoadEvent;
     "progress": LoaderProgressEvent;
+    "loadError": LoadErrorEvent;
 }
 export interface ThreeBaseEventTypeMap extends Object3DEventMap {
     "loadding": LoadingEvent;

package/EventMap.ts

@@ -38,6 +38,24 @@ export interface LoaderProgressEvent {
 }
 export interface BeforeRenderEvent { type: "beforeRender"; }
 export interface AfterRenderEvent { type: "afterRender"; }
+// 资源加载失败：`DefaultLoadingManager.onError`（素材那一路）与模型槽取回失败（GLB 那一路）都汇到这一个出口。
+// `url` 同一地址只计一次数（全景/平面瓦片失败会每帧重试 ⇒ 不去重会把失败数刷成无穷大）。
+export interface LoadErrorEvent {
+    type: "loadError";
+    url: string;
+    /** asset = 走 manager 计数的素材（全景整图/切片、平面瓦片、模型内嵌贴图）；model = 模型槽那颗 GLB 整体没出来 */
+    kind: "asset" | "model";
+    /** 仅 kind="model"：那一颗模型槽的名字，页面据此点名是哪一颗没出来 */
+    label?: string;
+    /** 全站累计失败地址数（与 manager 的 itemsTotal/itemsLoaded 同口径：累加、永不清零） */
+    failed: number;
+    /** 这个地址是不是第一次失败（同地址的后续重试仍发事件，但 isNew=false、不计数） */
+    isNew: boolean;
+    /** 服务端回的状态码（只在真的拿到过回复时有：全景/平面瓦片的 fetch 非 2xx、GLB 下载失败）；网络层失败为 undefined */
+    status?: number;
+    /** 服务端**明说这个地址没有**（404 / 403）⇒ 页面据此把引用它的那条数据整条删掉；断网一类没有回复的失败不算 */
+    missing: boolean;
+}
 
 export interface RAFEvent {
     type: "requestAnimationFrame";
@@ -85,6 +103,7 @@ export interface ThreeLoaderEventMap extends Object3DEventMap {
     "loadding": LoadingEvent;
     "onLoad": OnLoadEvent;
     "progress": LoaderProgressEvent;
+    "loadError": LoadErrorEvent;
 }
 
 export interface ThreeBaseEventTypeMap extends Object3DEventMap {

package/MktMesh/MktMesh.d.ts

@@ -121,6 +121,12 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
     /** 当前全景纹理形态（只读）。消费方（预览立方体等自持材质的路径）据此算 `mktPanoTiledFlag`，
      *  必须与基类喂纹理处用同一个值，否则标记与地址不同源 ⇒ 整图被按 1/2 横向铺满球面（10-06 晚起纵向不分块，四槽时代是 1/4）。 */
     get panoTexMode(): PanoTexMode;
+    /** 优先加载的全景个数（存档 `textures` 的前 n 项）：**-1 = 全部、0 = 一个都不提前、n = 前 n 个**（2026-11-05 需求）。
+     *  默认取 `PANO_IMPORT_PRIORITY_DEFAULT`（=4）；宿主想换档在渲染循环跑起来之前 `setPanoPriorityCount(-1)` 一行即可
+     *  （与 `_ossSize`、`_panoTexMode` 同一套注入路径 ⇒ 编辑器与预览各自的配置各自推下来）。 */
+    private _panoPriorityCount;
+    /** 当前优先加载个数（只读，回显用）。 */
+    get panoPriorityCount(): number;
     private _tmpV3;
     /**
      * 图片平面层（⭐ 10-26 旨入库）：对象挂在**本 MktMesh 的子树**里，⛔ 不是场景根
@@ -163,14 +169,19 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      */
     private _revealPending;
     /**
-     * 隐藏期 GPU 预热的在册清单（元素 = 一个「材质 × 几何」组合，也就是一个会进渲染列表的物件）。
+     * 隐藏期 GPU 预热的在册清单（元素 = 一个「会进渲染列表的物件」，即它的材质组合 × 几何）。
      * null = 没在预热（未启动 / 已跑完 / `stopGpuPrewarm` / `dispose` 四种都是它）。
      */
     private _warmItems;
-    /** 预热用的小场景：只装 `_warmProxy` 一颗，宿主场景的 `fog` 抄过来（fog 进 program 缓存键） */
+    /** 已收过的去重键（`几何 × 材质数组 × 各材质的 map`）⇒ 跨轮次只补收新出现的组合，不重复编同一条 GL 路径。
+     *  自然收尾时**故意留着**（晚到的内容补排时靠它跳过旧档）；只有 `stopGpuPrewarm`/`dispose` 把它归 null = 摘牌。 */
+    private _warmSeen;
+    /** 预热用的小场景：只挂当前这一件的替身 + 宿主灯光的克隆，`fog`/`environment` 照抄（都进 program 缓存键） */
     private _warmScene;
-    /** 预热用的替身物件：每次把在册那一件的 `material`/`geometry` 原对象赋给它再画一次 */
-    private _warmProxy;
+    /** 此刻挂在预热小场景里的那一颗替身（一帧只画一件 ⇒ 换件时先把上一颗摘下来） */
+    private _warmActive;
+    /** 预热小场景里的那几盏灯 = 宿主灯的克隆体（各持一份 `shadow` ⇒ 收尾时释放的是它们自己的阴影图，碰不到宿主的） */
+    private _warmLights;
     /** 预热落点：1×1 渲染目标（只有像素不要，要的是「这条 GL 路径确实走完了」），随预热结束/dispose 释放 */
     private _warmRt;
     constructor(opts?: {
@@ -333,6 +344,11 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *     下一帧 `feedFaceMapping` 里共用的那份 binder 见「槽内现有形态 ≠ 目标形态」自动走整档判齐、一次换绑并同帧翻标记。
      *  编辑器 MktDevMesh 走的是自己那路（同一个 binder、同一份策略），本方法对它只是记下形态。 */
     setPanoTexMode(mode: PanoTexMode): void;
+    /** 设置优先加载的全景个数：-1 = 全部 / 0 = 不提前 / n = 存档前 n 个（2026-11-05 需求）。
+     *  收口：负数（含 -2、NaN 一类）一律归到 -1「全加载」，正数向下取整；非有限值回落默认档。
+     *  改档⛔ 需要重新 `importData` —— 名册每帧重排，下一帧 `prefetchHeadPanoramas` 直接用新数点名
+     *  （`prioritize` 幂等 ⇒ 已在队列里的那批不重复投喂，也不会把已出队的旧批再塞回去）。 */
+    setPanoPriorityCount(count: number): void;
     /**
      * 记下「当前激活（名册 0 号槽 = 中心）是第几个全景」。
      * ⭐ 皇上旨 2026-10-03 旨②：预览立方体已与墙**共用同一份材质**，原来那句「把中心那几张抄给立方体单全景材质」
@@ -411,7 +427,7 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      */
     tickProgressiveReveal(): void;
     /**
-     * 开始隐藏期预热：把「进厅第一帧要现编的那份墙着色器」提前编掉，一帧只放**一件**。
+     * 开始隐藏期预热：把「进厅第一帧要现编的那些 program + 要第一次上传的那些几何/纹理」提前跑掉，一帧只放**一件**。
      *
      * 为什么必须在隐藏期做：`visible = false` 时 three 的遍历第一句就 `if (object.visible === false) return`
      *   （与上面 `tickProgressiveReveal` 注释同一颗雷）⇒ 墙根本进不了渲染列表，那份大 shader 从来没进过
@@ -424,22 +440,67 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *   编出来的正是同一份 program（three 的缓存按 `材质 × 几何属性形态 × 场景光照/雾` 计键），
      *   顶点缓冲也真上了 GPU；那 1×1 的像素直接扔掉，不占显存、不污染画面。
      *
-     * ⚠️ 只收**不带灯**的材质（墙的 mapping ShaderMaterial、图片平面的 MeshBasicMaterial）：预热那间小屋子里没有灯，
-     *   带灯材质（GLB 那些 Lambert/Standard）在这儿编出来的 define 组（方向光数、阴影开关…）与真实场景那份
-     *   不是同一个 program，白编一遍还挤缓存。那一族本来就由 `tickProgressiveReveal` 在进厅后一帧放一颗，
-     *   亮出来的那一帧就是它们的预热帧 ⇒ 这次一字未动。
+     * ⚠️ 2026-11-01 第二版：清单从「只收不带灯」放宽到**全收**，替身从「自造一颗裸 Mesh」换成「原对象自己克隆一颗」。
+     *   量出来的账（本地 dev，进厅三连帧 100/250/234 ms）：进厅那几帧里 89 份几何第一次上传（`bufferData` ×72）、
+     *   504 次 `drawElements`、6 份 program 现编 —— 第一版一道都没挡住：展厅里的展品（`ModelSlot` 那些 GLB 件，
+     *   Lambert/Standard 带灯材质）既没上传也没编，因为它们既不是 ShaderMaterial 也不是 MeshBasicMaterial。
+     *   带灯材质的 program 缓存键里有「方向光/点光/聚光数量 + 阴影档 + 环境图」
+     *   （`three.module.js:20901-20913`：`numDirLights`…`numDirLightShadows`、`shadowMapType`，另有 `envMap`/`fog` 两个位）
+     *   ⇒ 预热那间小屋子把宿主的灯**克隆一份**摆进去、`fog`/`environment` 照抄，否则编出来是另一份 define 组 = 白编。
+     *   替身必须是**克隆**不是裸 Mesh：`instancing`/`skinning`/`morphTargets` 也各占缓存键一个位
+     *   （`getProgramCacheKeyBooleans` 里那段 `_programLayers`）⇒ 拿裸 Mesh 画实例化材质编的是非实例化那一份。
+     *   克隆的灯只活在预热期，收尾时连各自的阴影图一起释放（`light.clone()` 给的是 `shadow.clone()` 的新份，
+     *   实测不与宿主共享 ⇒ 不会误释放宿主那张）；阴影边长压到 `GPU_WARM_SHADOW_MAP_SIZE`，理由写在那颗常量上。
+     *
+     * ⚠️ 一次性清单不等于收工：隐藏期里展厅的内容**还没长齐**（GLB 逐帧各挂一颗、平面的 4 格瓦片逐张就绪逐张绑），
+     *   所以补收有两只手 —— ① 排空那一拍再扫一遍；② 内容落位那两个落点各调一次 `_topUpGpuPrewarm()`
+     *   （GLB 挂进子树、平面绑上瓦片）。去重键 = `几何 id × 材质 id 串 × 各材质的 map id`（平面再带绑定戳记）
+     *   ⇒ 补收只针对「没见过的那一档」，同一件不会被画第二遍。
      *
      * @param renderer 宿主那一份渲染器（隐藏期 `onBeforeRender` 不触发，库里拿不到 ⇒ 必须由宿主交进来；
      *                 站侧的落点就是 `FloorMktBase.preloadFirstPano(renderer)`，它本来就是隐藏期的入口）
      */
     startGpuPrewarm(renderer: WebGLRenderer): void;
-    /** 停止隐藏期预热（宿主进入展厅时调）：剩下的清单直接作废 —— 亮出来那一帧本来就要编要传，不必再抢额度。 */
+    /** 停止隐藏期预热（宿主进入展厅时调）：剩下的清单直接作废并**摘牌** —— 亮出来那一帧本来就要编要传，不必再抢额度；摘牌后晚到的内容也不再来补排。 */
     stopGpuPrewarm(): void;
+    /**
+     * 内容后落位时补排预热（GLB 挂进子树那一拍、平面绑上瓦片纹理那一拍各调一次）。
+     *
+     * 为什么必须有这一颗：预热是隐藏期跑的，而隐藏期里展厅的内容**还没长齐** —— GLB 十几只各走一条异步下载链、
+     *   逐帧只挂一颗，平面那 4 格图也是逐张就绪逐张绑。一次性清单在几拍之内就排空了 ⇒ 晚到的那一族一件都没被画过，
+     *   进厅那一帧照样现编现传（这就是第一版「预热跑了、人还是卡了一下」的根）。
+     *
+     * 只在隐藏期响应：`_warmSeen` 归 null = 宿主已叫停（进厅）⇒ 晚到的东西交给「逐帧点亮」那一拍自己编，⛔ 别再抢额度。
+     */
+    private _topUpGpuPrewarm;
+    /**
+     * 扫一遍本对象的子树，把「还没收过的那一档」压进清单。
+     * @returns 这次新收了几个（0 = 确实没有新东西 ⇒ 调用方据此收尾，⛔ 不是每帧空转）
+     */
+    private _collectWarmItems;
     /** 排下一件：先垫一个空函数占一格（全局队列每 tick 只跑一项 ⇒ 真活落在下一个 tick），与全景上传、平面绑定同一手法。 */
     private _scheduleGpuWarmStep;
     /** 队列回调的全部内容：预热**一件**（一次 1×1 绘制）。清单空了/已被摘牌就收尾。 */
     private _runGpuWarmStep;
-    /** 拆掉预热那套临时资源（1×1 渲染目标 + 小场景 + 替身）；清单本身由调用方置 null。 */
+    /**
+     * 造（并记住）预热那间小屋子：只建一次。
+     * `fog` / `environment` 照抄、宿主的灯**逐盏克隆**摆进来 —— 这三样都进 program 缓存键，
+     *   少一样就是编出一份进厅用不上的 program。
+     */
+    private _ensureWarmScene;
+    /** 沿 `parent` 往上找到的第一个 Scene = 宿主场景（本站是 `largeScreenRender` 那一棵）。 */
+    private _findHostScene;
+    /**
+     * 收尾（跑完 / 进厅 / 宿主叫停 / `dispose` 四条路都汇到这里）：清单作废 + 临时资源拆掉。
+     *
+     * ⚠️ **不动 `_warmSeen`**：自然跑完那一路后面还会有内容落位（GLB、后绑的瓦片），补排时全靠这张表跳过已经画过的旧档
+     *   —— 清掉它等于把同一批东西再画一遍。真正的「摘牌」只有 `stopGpuPrewarm`/`dispose`，它们先把这颗归 null。
+     */
+    private _finishGpuPrewarm;
+    /**
+     * 拆掉预热那套临时资源（1×1 渲染目标 + 克隆的灯 + 小场景）。
+     * 替身只是从小屋子里摘出来 —— 它的 `geometry`/`material` 都是宿主那一份对象 ⇒ ⛔ 在此 dispose，会把展厅要用的资源释放掉。
+     */
     private _releaseWarmHarness;
     /** 导出数据：墙点位 + 墙高 + 是否闭合 + 纹理数组（url + 矩阵）
      *  @param projName 项目名（可选，优先于 `setProjectName` 注入的那个）——图片地址落成 `{项目名}/xxx.jpg` */
@@ -449,11 +510,12 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *  @param onModelLoad 每只 GLB 落地时回调一次（可选）——按需渲染的宿主（编辑器）拿它标脏；每帧真画的预览不传 */
     importData(data: MktMeshData, projName?: string, onModelLoad?: () => void): void;
     /**
-     * 把**存档里前 `PANO_IMPORT_PRIORITY` 个全景**按存档顺序登记进拼合器的**加载任务队列**
+     * 把**存档里前 `panoPriorityCount` 个全景**（-1 = 整份全加载）按存档顺序登记进拼合器的**加载任务队列**
      *（2026-10-29 需求「优先加载前 2 个全景素材」+ 2026-10-30 需求逐字：「给 mktmesh 内部加一个加载任务队列，
      *  把模型和平面图排在最前面，然后按照顺序，依次把前 2 个全景的顺序把瓦片加载任务添加到任务队列里面，
      *  第一个加载完了，就把这个加载任务从任务队列里面去掉，然后加载第二个；
-     *  如果后续再按照距离计算需要加载哪个全景的时候，同样地添加到加载任务队列的后面等待加载」）。
+     *  如果后续再按照距离计算需要加载哪个全景的时候，同样地添加到加载任务队列的后面等待加载」
+     *  + 2026-11-05 需求「提前加载多少个全景改由配置决定，-1 全加载 / 0 不加载 / n 前 n 个，默认 4」）。
      * 由两处渲染循环每帧点一次：基类 `onBeforeRender`（预览弹窗 / 发布页）与编辑器的 `updateFloorTexture`
      *（`MktDevMesh` 覆写了 `onBeforeRender`，只点 `syncProjInvMatrix` + `tickProgressiveReveal`，库内那句在编辑态不跑）。
      *
@@ -462,21 +524,23 @@ export default class MktMesh extends Mesh<BufferGeometry, ShaderMaterial> {
      *      （GLB 逐只 `loadModel` 不 throttle；平面那 4 片一次性 `_imgTileLoader.preload`），
      *      而全景瓦片最早也要等下一帧的 `pump` 才发第一片 ⇒ 发起次序天然是「模型 → 平面图 → 全景」，
      *      ⛔ 这里不再把它们塞进队列重复管一遍（塞了就是第二把尺）。
-     *   ② 本方法把存档 0 号、1 号依次 `prioritize` 进队列 ⇒ 拼合器每帧**只喂队首那一组**，
+     *   ② 本方法把存档 0 号起这 n 号依次 `prioritize` 进队列 ⇒ 拼合器每帧**只喂队首那一组**，
      *      0 号 32 格全落定（画进 RT，或该格本就缺地址/判死）才出队、1 号才开始发第一片。
      *      比 10-29 那版（只是把两批挪到在册顺序前面、额度仍被两批分摊）更硬：**第 1 颗独享额度，最快出全图**。
+     *      n = -1（全加载）时这一条变成「整份存档按存档顺序串行」⇒ 距离名册插不到前面，出清速度取决于总片数。
      *   ③ 名册按距离点到的其他全景走 `feedFaceMapping` 里那句 `ensure(t.tiles)`（不带队列）⇒ 只入册、
      *      排在队列后面等，队列空了才按在册顺序补料（现行口径不变）。
      * ⚠️⚠️ 为什么每帧点而⛔ 只在 `importData` 里点一记：预览每开一次都换渲染器，`_switchRenderer` 把在册组
      *   整份作废（队列里的键也在同一刻失效）；只在载入那次点名等于白点。本方法点在 `pump` 之后、名册逐槽
-     *   `ensure` 之前 ⇒ 每帧把这两记任务补回队列头部（`prioritize` 幂等，已在队列里就不挪，所以 0 号恒在 1 号前）。
+     *   `ensure` 之前 ⇒ 每帧把这几记任务补回队列头部（`prioritize` 幂等，已在队列里就不挪，所以存档次序恒不变）。
      * ⚠️ 代价如实记：
-     *   · 队列非空时**其他全景一片都不发** ⇒ 开机那几秒里，离注视点最近、但不在存档前两颗的那面墙会多灰一会儿。
+     *   · 队列非空时**其他全景一片都不发** ⇒ 开机那几秒里，离注视点最近、但不在存档前 n 颗的那面墙会多灰一会儿。
      *   · 一颗「永远下不完」的瓦片（下载失败还没累计到判死）会压住队列；判死阈值是解码失败 3 次
-     *     （`_dead`），退避重试期间队首不落定 ⇒ 第 2 颗跟着延后。真实数据里缺片是「地址为空/404」，
+     *     （`_dead`），退避重试期间队首不落定 ⇒ 后面几颗跟着延后。真实数据里缺片是「地址为空/404」，
      *     404 走三次即判死、那一格拼合涂灰 ⇒ 队列照样出清。
-     *   · 这两颗全景若本来不在开机那一刻的名册里，它们的瓦片与拼合槽 RT 会被**提前**建出来
-     *     （现行口径每颗全景 2 槽 × 6144² ≈ 384MB 显存）—— 组在运行中不淘汰，走进这两个景点迟早要建。
+     *   · 这批全景若本来不在开机那一刻的名册里，它们的瓦片与拼合槽 RT 会被**提前**建出来
+     *     （现行口径每颗全景 2 槽 × 6144² ≈ 384MB 显存）—— 组在运行中不淘汰，走进这些景点迟早要建；
+     *     ⚠️ n = -1（全加载）时这一条按存档全景总数放大，显存与在途请求都跟着涨。
      * ⚠️ 形态判据读 `this._panoTexMode`（整图形态那一档一张全景只有一张整图，走 `_texCache` 那条路，
      *   走错档就是白下 32 片）⇒ 宿主若用自己那份形态变量（编辑器的 `store.panoTexMode`），
      *   要在调 `importData` 之前先 `setPanoTexMode` 推进来，编辑器那侧已按此接线。