s3m-three 0.3.1 → 0.3.3

package/src/render/S3MViewer.ts

@@ -144,7 +144,42 @@ export interface PickResult extends FeatureAttributes {
   mesh: THREE.Mesh;
 }
 
+export interface LightOptions {
+  /** 环境光强度，默认 0.4 */
+  ambientIntensity?: number;
+  /** 环境光颜色，十六进制或 CSS 颜色字符串，默认 0xffffff */
+  ambientColor?: number | string;
+  /** 半球光天空强度，默认 0.8 */
+  hemisphereIntensity?: number;
+  /** 半球光天空颜色，默认 0xffffff */
+  hemisphereColor?: number | string;
+  /** 半球光地面颜色，默认 0xb6c0cb */
+  hemisphereGroundColor?: number | string;
+  /** 主平行光强度，默认 1.0 */
+  keyLightIntensity?: number;
+  /** 主平行光颜色，默认 0xffffff */
+  keyLightColor?: number | string;
+  /** 补光强度，默认 0.35 */
+  fillLightIntensity?: number;
+  /** 补光颜色，默认 0xffffff */
+  fillLightColor?: number | string;
+  /**
+   * 光照朝向模式：
+   * - 'headlamp': 默认头灯模式（随相机 bearing 旋转，受光面始终面向镜头）
+   * - 'fixed': 固定世界坐标方位角（如太阳光模拟）
+   */
+  mode?: 'headlamp' | 'fixed';
+  /** 方位角（度，0~360），固定模式下以正北为 0 顺时针，头灯模式下为相机相对偏角，默认 150 */
+  azimuth?: number;
+  /** 太阳/光源仰角（度，0~90），默认 50 */
+  altitude?: number;
+}
+
 export interface S3MViewerOptions {
+  /** 光照参数配置（强度、颜色、朝向模式、太阳方位角/仰角等） */
+  light?: LightOptions;
+  /** 全局总驻留瓦片上限（多数据集多图层共享预算），在所有可见数据集之间动态均衡分配，彻底防止爆显存 */
+  totalMaxTiles?: number;
   /** 单数据集简写 */
   configUrl?: string;
   /** 多数据集 */
@@ -294,8 +329,24 @@ export class S3MViewer {
   private _needsRepaint = true;
   private _frame = 0;
   private readonly _fps = { value: 0, last: 0 };
-  private _keyLight: THREE.DirectionalLight | null = null;
-  private _fillLight: THREE.DirectionalLight | null = null;
+  private _ambientLight!: THREE.AmbientLight;
+  private _hemiLight!: THREE.HemisphereLight;
+  private _keyLight!: THREE.DirectionalLight;
+  private _fillLight!: THREE.DirectionalLight;
+  private readonly _lightOptions: Required<LightOptions> = {
+    ambientIntensity: 0.4,
+    ambientColor: 0xffffff,
+    hemisphereIntensity: 0.8,
+    hemisphereColor: 0xffffff,
+    hemisphereGroundColor: 0xb6c0cb,
+    keyLightIntensity: 1.0,
+    keyLightColor: 0xffffff,
+    fillLightIntensity: 0.35,
+    fillLightColor: 0xffffff,
+    mode: 'headlamp',
+    azimuth: 150,
+    altitude: 50,
+  };
 
   private readonly _datasetQueue: S3MDatasetOptions[];
 
@@ -309,10 +360,20 @@ export class S3MViewer {
     this._onRequestRepaint();
   }
 
+  triggerRepaint(): void {
+    this._requestRepaint();
+  }
+
   constructor(options: S3MViewerOptions = {}) {
     this.options = options;
     this.pickable = options.pickable !== false;
     this._lodRangeScale = options.lodRangeScale ?? 1.0;
+    if (options.light) {
+      Object.assign(this._lightOptions, options.light);
+    }
+    if (options.totalMaxTiles) {
+      this._datasetManager.totalMaxTiles = options.totalMaxTiles;
+    }
     this._onRequestRepaint = options.onRequestRepaint ?? (() => {});
     this._getBearing = options.getBearing;
     this.onStats = options.onStats ?? (() => {});
@@ -321,6 +382,11 @@ export class S3MViewer {
     this.onError = options.onError ?? ((e) => console.warn('[s3m]', e));
 
     this.groundManager = new GroundManager(options.ground);
+    if (!this.scene) {
+      this.scene = new THREE.Scene();
+      this.scene.add(this.groundManager.group);
+      this._addLights();
+    }
     this._featureStyleManager = new FeatureStyleManager(
       () => this.style.floorHeight,
       () => this._requestRepaint(),
@@ -358,19 +424,25 @@ export class S3MViewer {
    * 绑定宿主画布与 WebGL 上下文，建场景并启动数据集队列。
    * MapLibre 宿主由 S3MLayer 在 onAdd 里调用；纯 three 宿主直接传自己的 canvas / gl。
    */
-  mount(canvas: HTMLCanvasElement, gl: WebGLRenderingContext | WebGL2RenderingContext): void {
-    this.canvas = canvas;
-
-    this.renderer = new THREE.WebGLRenderer({
+  /** 创建并配置一个绑定到给定 gl 上下文的 three renderer（mount 与上下文恢复共用） */
+  private _createRenderer(canvas: HTMLCanvasElement, gl: WebGLRenderingContext | WebGL2RenderingContext): THREE.WebGLRenderer {
+    const r = new THREE.WebGLRenderer({
       canvas,
       context: gl as WebGLRenderingContext,
       antialias: true,
     });
-    this.renderer.autoClear = false;
-    this.renderer.setPixelRatio(1);
+    r.autoClear = false;
+    r.setPixelRatio(1);
     // 白模 albedo 接近 1，不做色调映射会过曝成一片纯白、丢失明暗关系
-    this.renderer.toneMapping = THREE.ACESFilmicToneMapping;
-    this.renderer.toneMappingExposure = 1.0;
+    r.toneMapping = THREE.ACESFilmicToneMapping;
+    r.toneMappingExposure = 1.0;
+    return r;
+  }
+
+  mount(canvas: HTMLCanvasElement, gl: WebGLRenderingContext | WebGL2RenderingContext): void {
+    this.canvas = canvas;
+
+    this.renderer = this._createRenderer(canvas, gl);
     setMaxAnisotropy(this.renderer.capabilities.getMaxAnisotropy());
 
     this.scene = new THREE.Scene();
@@ -388,6 +460,38 @@ export class S3MViewer {
     this._recomputeAnchors();
   }
 
+  /**
+   * WebGL 上下文恢复后原地换新 renderer，保留已经加载好的场景与瓦片。
+   *
+   * MapLibre 在 `webglcontextlost` 时会销毁 style 并丢弃自定义图层（自定义图层
+   * 无法序列化进 style，所以恢复后不会自动加回）。但自定义图层的 `onRemove` 不会被
+   * 调用，因此我们的 scene / 几何体 / 材质 / 纹理 / 已加载瓦片都还在内存里。
+   *
+   * three 的 GPU 状态是按 renderer 实例缓存的，所以只需把 renderer / picker 换成
+   * 绑在新 gl 上的新实例，下一帧渲染时 three 会自动把现存的几何体、材质、纹理
+   * 重新上传到新上下文 —— 不需要重建场景，也不需要重新拉瓦片。
+   */
+  restoreContext(gl: WebGLRenderingContext | WebGL2RenderingContext): void {
+    if (!this.canvas) {
+      // 理论不会走到：没 mount 过就没有上下文可恢复
+      console.warn('[s3m] restoreContext 调用过早（尚未 mount），按首次挂载处理');
+      return;
+    }
+    try {
+      // 旧上下文已失效，dispose 可能抛错，忽略即可
+      this.renderer?.dispose();
+    } catch {
+      /* noop */
+    }
+    this.renderer = this._createRenderer(this.canvas, gl);
+    setMaxAnisotropy(this.renderer.capabilities.getMaxAnisotropy());
+    this.picker?.dispose();
+    this.picker = new Picker(this.renderer);
+    // 共享 uniform / 材质引用不变，three 重新编译着色器时会自然接管；
+    // 这里只确保下一帧尽快驱动一次渲染。
+    this._requestRepaint();
+  }
+
   /** 解绑场景并释放全部 GPU 资源。对应 MapLibre 图层的 onRemove()。 */
   unmount(): void {
     for (const id of [...this.datasets.keys()]) this.removeDataset(id);
@@ -412,24 +516,70 @@ export class S3MViewer {
     this.canvas = null;
   }
 
+  private _createLights(): void {
+    this._ambientLight = new THREE.AmbientLight(this._lightOptions.ambientColor as any, this._lightOptions.ambientIntensity);
+    this._hemiLight = new THREE.HemisphereLight(
+      this._lightOptions.hemisphereColor as any,
+      this._lightOptions.hemisphereGroundColor as any,
+      this._lightOptions.hemisphereIntensity
+    );
+    this._keyLight = new THREE.DirectionalLight(this._lightOptions.keyLightColor as any, this._lightOptions.keyLightIntensity);
+    this._fillLight = new THREE.DirectionalLight(this._lightOptions.fillLightColor as any, this._lightOptions.fillLightIntensity);
+    this._updateLights();
+  }
+
   private _addLights(): void {
     if (!this.scene) return;
-    // 环境光与天光打底，保证背光面和折叠处不死黑
-    this.scene.add(new THREE.AmbientLight(0xffffff, 0.4));
-    this.scene.add(new THREE.HemisphereLight(0xffffff, 0xb6c0cb, 0.8));
-    // 主光 / 补光的方向每帧按地图朝向重算（见 _updateLights），
-    // 这样旋转视角时白模始终是亮的，不会转到背光面就一片死灰。
-    this._keyLight = new THREE.DirectionalLight(0xffffff, 1.0);
-    this._fillLight = new THREE.DirectionalLight(0xffffff, 0.35);
-    this.scene.add(this._keyLight, this._fillLight);
+    if (!this._ambientLight) this._createLights();
+    this.scene.add(this._ambientLight, this._hemiLight, this._keyLight, this._fillLight);
+  }
+
+  private _applyLightOptions(): void {
+    if (this._ambientLight) {
+      this._ambientLight.intensity = this._lightOptions.ambientIntensity;
+      this._ambientLight.color.set(this._lightOptions.ambientColor as any);
+    }
+    if (this._hemiLight) {
+      this._hemiLight.intensity = this._lightOptions.hemisphereIntensity;
+      this._hemiLight.color.set(this._lightOptions.hemisphereColor as any);
+      this._hemiLight.groundColor.set(this._lightOptions.hemisphereGroundColor as any);
+    }
+    if (this._keyLight) {
+      this._keyLight.intensity = this._lightOptions.keyLightIntensity;
+      this._keyLight.color.set(this._lightOptions.keyLightColor as any);
+    }
+    if (this._fillLight) {
+      this._fillLight.intensity = this._lightOptions.fillLightIntensity;
+      this._fillLight.color.set(this._lightOptions.fillLightColor as any);
+    }
   }
 
   /**
-   * 让光照跟着地图朝向走：主光在镜头后上方偏左，补光在后上方偏右。
-   * 相当于一盏头灯，看到的立面永远是受光面。
+   * 动态设置光照配置
+   */
+  setLight(options: Partial<LightOptions>): void {
+    Object.assign(this._lightOptions, options);
+    this._applyLightOptions();
+    this._updateLights();
+    this._needsRepaint = true;
+    this.triggerRepaint();
+  }
+
+  /**
+   * 获取当前光照配置快照
+   */
+  getLight(): LightOptions {
+    return { ...this._lightOptions };
+  }
+
+  /**
+   * 更新光照位置与方向：
+   * - 'headlamp': 随地图方位角 bearing 旋转，主光始终在镜头上方，受光面面向镜头；
+   * - 'fixed': 固定世界方位角（如模拟恒定日光）。
    */
   private _updateLights(): void {
-    const bearing = ((this._getBearing?.() ?? 0) * Math.PI) / 180;
+    if (!this._keyLight || !this._fillLight) return;
+    const bearing = this._lightOptions.mode === 'fixed' ? 0 : (((this._getBearing?.() ?? 0) * Math.PI) / 180);
     const place = (light: THREE.DirectionalLight | null, azOffsetDeg: number, elevDeg: number): void => {
       if (!light) return;
       const az = bearing + (azOffsetDeg * Math.PI) / 180;
@@ -437,8 +587,8 @@ export class S3MViewer {
       const c = Math.cos(el);
       light.position.set(Math.sin(az) * c, Math.cos(az) * c, Math.sin(el)).multiplyScalar(1000);
     };
-    place(this._keyLight, 150, 50);
-    place(this._fillLight, 215, 30);
+    place(this._keyLight, this._lightOptions.azimuth, this._lightOptions.altitude);
+    place(this._fillLight, this._lightOptions.azimuth + 65, Math.max(10, this._lightOptions.altitude - 20));
   }
 
   /* ---------------------------------------------------------------- 数据集 */
@@ -877,6 +1027,27 @@ export class S3MViewer {
    * 而 LOD 细化、瓦片重载、淘汰回补都会换掉 mesh —— 不重放的话，用户点中的那栋楼
    * 一细化就失去高亮（状态还在 _selection.smid 里，只是没人往新 mesh 上刷）。
    */
+  /**
+   * 判断一块无 SMID 单体化信息的网格（如倾斜摄影或白模整块）是否空间覆盖当前选中命中点
+   */
+  private _isMeshCoveringSelection(mesh: THREE.Mesh, sel: PickResult): boolean {
+    if (!sel.point) return false;
+    const geom = mesh.geometry;
+    if (!geom) return false;
+    if (!geom.boundingBox) geom.computeBoundingBox();
+    if (!geom.boundingBox) return false;
+
+    // 将选中的三维场景点转入网格局部坐标系进行包围盒检测
+    const pt = new THREE.Vector3(sel.point[0], sel.point[1], sel.point[2]);
+    mesh.updateWorldMatrix(true, false);
+    const inv = mesh.matrixWorld.clone().invert();
+    const localPt = pt.applyMatrix4(inv);
+
+    // 留出 0.5 米容差，避免刚好处于三角网格边缘缝隙时漏判
+    const box = geom.boundingBox.clone().expandByScalar(0.5);
+    return box.containsPoint(localPt);
+  }
+
   private _replaySelectionOnto(mesh: THREE.Mesh): void {
     const sel = this._selection;
     if (!sel) return;
@@ -893,7 +1064,13 @@ export class S3MViewer {
     // 拾取命中的那块 mesh 用原始 batchId；同一 smid 散在别的几何里时按各自的区间算
     if (mesh === sel.mesh) batchId = sel.batchId;
     // 这块几何里根本没有这个单体 → 不动它（否则会把无关瓦片一起点亮）
-    if (batchId < 0 && mesh !== sel.mesh) return;
+    if (batchId < 0 && mesh !== sel.mesh) {
+      if (sel.smid == null && ud.datasetId === sel.datasetId && this._isMeshCoveringSelection(mesh, sel)) {
+        batchId = -1;
+      } else {
+        return;
+      }
+    }
 
     mat.userData.uSelBatch.value = batchId;
     mat.userData.uSelWhole.value = batchId < 0 ? 1 : 0;
@@ -903,44 +1080,56 @@ export class S3MViewer {
     this.uniforms.uDim.value = this.style.dimOthers ? 1 : 0;
   }
 
-  /** 瓦片被淘汰：从拾取表和场景里摘掉，并释放它自己的 GPU 资源 */
+  /** 瓦片被淘汰：从拾取表和场景里摘掉，并深度彻底释放所有几何体与材质显存 */
   private _unregisterTile(node: TileNode, entry: S3MDatasetEntry): void {
-    for (const child of [...node.group.children]) {
-      const mesh = child as THREE.Mesh;
-      if (!mesh.isMesh) continue;
-      const ud = mesh.userData as MeshUserData;
-      // 「这块 mesh 没了」≠「用户不再选中」：LOD 细化 / 淘汰回补都会换掉 mesh。
-      // 以前这里一律 select(null)，于是点中的那栋楼一拉近，选中状态就整个被清掉。
-      const wasSelected = this._selectedMeshes.includes(mesh);
-      if (wasSelected) {
-        this._selectedMeshes = this._selectedMeshes.filter((m) => m !== mesh);
+    node.group.traverse((child) => {
+      const obj = child as any;
+      if (obj.userData?.pickId != null) {
+        this._pickables.delete(obj.userData.pickId);
+        this._releasePickId(obj.userData.pickId);
+        obj.userData.pickId = undefined;
       }
-      if (this._selection?.mesh === mesh) {
-        const smid = this._selection.smid;
-        const carrier =
-          smid != null ? [...(this._smidMeshes.get(smid) ?? [])].find((m) => m !== mesh && m.parent) : undefined;
-        if (carrier) {
-          // 选中身份交给承载同一 smid 的另一块 mesh（通常是接替显示的子瓦）
-          this._selection = { ...this._selection, mesh: carrier };
-          this._replaySelectionOnto(carrier);
-        } else {
-          this.select(null);
+      if (obj.isMesh) {
+        const wasSelected = this._selectedMeshes.includes(obj);
+        if (wasSelected) {
+          this._selectedMeshes = this._selectedMeshes.filter((m) => m !== obj);
+        }
+        const currentSel = this._selection;
+        if (currentSel && currentSel.mesh === obj) {
+          const smid = currentSel.smid;
+          const carrier = (
+            smid != null
+              ? [...(this._smidMeshes.get(smid) ?? [])].find((m) => m !== obj && m.parent)
+              : this._selectedMeshes.find((m) => m !== obj && m.parent && (m.parent as any).visible) ??
+                this._selectedMeshes.find((m) => m !== obj && m.parent)
+          ) as THREE.Mesh | undefined;
+          if (carrier) {
+            // 选中身份交给承载同一 smid 的另一块 mesh（通常是接替显示的子瓦）
+            this._selection = { ...currentSel, mesh: carrier };
+            this._replaySelectionOnto(carrier);
+          } else {
+            this.select(null);
+          }
         }
+        this._unindexMeshSmids(obj);
+        this._removeMeshHeight(obj);
+        this._featureStyleManager.disposeMesh(obj);
+        const styled = styledMaterialOf(obj);
+        styled?.dispose?.();
       }
-      if (ud.pickId != null) {
-        this._pickables.delete(ud.pickId);
-        this._releasePickId(ud.pickId);
-        ud.pickId = undefined;
+      // 深度释放材质（点云、普通材质、材质数组）
+      if (isOwnedPointCloudMaterial(obj.material)) {
+        (obj.material as THREE.Material).dispose();
+      } else if (obj.material) {
+        if (Array.isArray(obj.material)) {
+          obj.material.forEach((m: any) => m?.dispose?.());
+        } else {
+          obj.material.dispose?.();
+        }
       }
-      this._unindexMeshSmids(mesh);
-      this._removeMeshHeight(mesh);
-      this._featureStyleManager.disposeMesh(mesh);
-      const styled = styledMaterialOf(mesh);
-      styled?.dispose?.();
-      // 点云材质是本模块按模式建的，不走 styled 那条链
-      if (isOwnedPointCloudMaterial(mesh.material)) (mesh.material as THREE.Material).dispose();
-      mesh.geometry?.dispose?.();
-    }
+      // 释放几何体显存缓冲
+      obj.geometry?.dispose?.();
+    });
     entry.root.remove(node.group);
   }
 
@@ -1981,6 +2170,9 @@ export class S3MViewer {
     canvasHeight: number;
   }): boolean {
     if (!this.renderer || !this.scene || !this.camera || !this.sceneAnchor || !this.canvas) return false;
+    // 上下文丢失期间（丢失→恢复之间）不要尝试渲染，否则会刷一堆 GL 错误
+    const gl = this.renderer.getContext() as WebGLRenderingContext | null;
+    if (gl && typeof gl.isContextLost === 'function' && gl.isContextLost()) return false;
 
     // 脏标记正常由微任务刷掉；这里再兜一次底，保证「本帧画出来的」一定是最新样式
     this.flushOverrides();

package/src/tileset/S3MTileset.ts

@@ -216,6 +216,10 @@ export interface TileNode {
   parentUrl?: string;
   /** 当前帧是否满足细化条件 */
   needRefine?: boolean;
+  /** 该瓦片引用的纹理 key 清单，用于引用计数与显存释放 */
+  textureKeys?: string[];
+  /** 瓦片构建产生的统计信息，用于淘汰时准确扣减 stats */
+  stats?: { meshes: number; vertices: number; triangles: number };
 }
 
 /** 瓦片构建器可注入，用于测试 / 服务端渲染（此时不需要 three） */
@@ -228,6 +232,8 @@ export interface S3MTilesetOptions {
   configUrl: string;
   maxTiles?: number;
   maxConcurrent?: number;
+  /** 原始图像/子图集缓存上限（LRU），默认 128 */
+  maxImageCache?: number;
   buildTile?: BuildTileFn | null;
   uniforms?: StyleUniforms | null;
   onTile?: (node: TileNode) => void;
@@ -266,6 +272,9 @@ export class S3MTileset {
   readonly nodes = new Map<string, TileNode>();
   readonly failed = new Set<string>();
   readonly textureCache = new Map<string, Texture>();
+  maxImageCache: number;
+  private readonly _textureRefs = new Map<string, number>();
+  private readonly _tileTextureKeys = new Map<string, string[]>();
   readonly pending = new Set<string>();
   /** 是否请求 `.texblock` 子图集，默认关，见 S3MTilesetOptions.atlasLod */
   atlasLod: boolean;
@@ -316,7 +325,7 @@ export class S3MTileset {
   /** 格式类永久错误只向上报一次，避免整棵瓦片树刷同样的日志 */
   private _permanentReported = false;
   /** 请求量的硬上限（软上限 maxTiles 的超额余量），见构造函数注释 */
-  private hardCap = 96;
+  hardCap = 96;
   /** 本数据集是 S3M 1.x（SuperMapCache，.s3m）：子瓦地址规则与 3.x 不同 */
   private isS3MV1 = false;
   private _buildTile: BuildTileFn | null;
@@ -341,6 +350,7 @@ export class S3MTileset {
     // 并发与总量限制：iServer 公开服务上别把人家打爆
     this.maxConcurrent = options.maxConcurrent ?? 4;
     this.maxTiles = options.maxTiles ?? 64;
+    this.maxImageCache = options.maxImageCache ?? 128;
     // 硬上限 = 软上限 + 余量。淘汰只在「新瓦片已经落地并接管显示」之后做（make-before-break），
     // 所以中间态允许临时超出 maxTiles；硬上限只用来挡住失控的请求量，不用于挤掉正在显示的内容。
     this.hardCap = this.maxTiles + Math.max(8, Math.ceil(this.maxTiles * 0.5));
@@ -419,19 +429,91 @@ export class S3MTileset {
    * 两轮都按「最久没进有效范围」排，同帧再比距离。
    * 淘汰最细一级时，如果上一级也不在内存里，顺手把上一级排回队列补洞。
    */
+  /** 记录瓦片引用的纹理 key，并递增其引用计数 */
+  registerTileTextures(url: string, textureKeys: string[]): void {
+    this._tileTextureKeys.set(url, textureKeys);
+    const node = this.nodes.get(url);
+    if (node) {
+      node.textureKeys = textureKeys;
+    }
+    for (const key of textureKeys) {
+      this._textureRefs.set(key, (this._textureRefs.get(key) ?? 0) + 1);
+    }
+  }
+
+  /** 淘汰单块瓦片节点并释放专属纹理 */
+  _evictTileNode(victim: TileNode): void {
+    this.nodes.delete(victim.url);
+    victim.group?.parent?.remove(victim.group);
+    this._onTileRemoved(victim);
+    this._parentOf.delete(victim.url);
+
+    this.stats.tiles = Math.max(0, this.stats.tiles - 1);
+    if (victim.stats) {
+      this.stats.meshes = Math.max(0, this.stats.meshes - (victim.stats.meshes ?? 0));
+      this.stats.vertices = Math.max(0, this.stats.vertices - (victim.stats.vertices ?? 0));
+      this.stats.triangles = Math.max(0, this.stats.triangles - (victim.stats.triangles ?? 0));
+    }
+
+    // 释放此瓦片引用的纹理计数；引用归零时从 GPU / 缓存彻底 dispose
+    const keys = victim.textureKeys ?? this._tileTextureKeys.get(victim.url) ?? (victim.group?.userData?.textureKeys as string[] | undefined);
+    this._tileTextureKeys.delete(victim.url);
+    if (keys?.length) {
+      for (const key of keys) {
+        const ref = (this._textureRefs.get(key) ?? 1) - 1;
+        if (ref <= 0) {
+          this._textureRefs.delete(key);
+          const tex = this.textureCache.get(key);
+          if (tex) {
+            tex.dispose?.();
+            this.textureCache.delete(key);
+          }
+        } else {
+          this._textureRefs.set(key, ref);
+        }
+      }
+    }
+  }
+
+  /** 存入外部图集（带 LRU 容量上限） */
+  putExternalAtlas(id: string, img: S3MBlockAtlasImage | null): void {
+    if (this.externalAtlasCache.size >= this.maxImageCache && !this.externalAtlasCache.has(id)) {
+      const oldestKey = this.externalAtlasCache.keys().next().value;
+      if (oldestKey !== undefined) this.externalAtlasCache.delete(oldestKey);
+    }
+    Map.prototype.set.call(this.externalAtlasCache, id, img);
+  }
+
+  /** 读取外部图集 */
+  getExternalAtlas(id: string): S3MBlockAtlasImage | null | undefined {
+    return this.externalAtlasCache.get(id);
+  }
+
+  /** 存入 leaf 记录段（带 LRU 容量上限） */
+  putLeafRecords(name: string, recs: S3MBlockAtlasImage[] | null): void {
+    if (this.leafRequestCache.size >= this.maxImageCache && !this.leafRequestCache.has(name)) {
+      const oldestKey = this.leafRequestCache.keys().next().value;
+      if (oldestKey !== undefined) this.leafRequestCache.delete(oldestKey);
+    }
+    Map.prototype.set.call(this.leafRequestCache, name, recs);
+  }
+
+  /** 读取 leaf 记录段 */
+  getLeafRecords(name: string): S3MBlockAtlasImage[] | null | undefined {
+    return this.leafRequestCache.get(name);
+  }
+
   private _evictOne(allowUncovered = false): boolean {
+
     // 只挑安全候选：叶子 → 已被子瓦接手的父瓦。allowUncovered 仅在超出硬上限时开启（内存兜底）
-    const victim = this._pickVictim(false, allowUncovered) ?? this._pickVictim(true, allowUncovered);
+    const victim = this._pickVictim(true, allowUncovered) ?? this._pickVictim(false, allowUncovered);
     if (!victim) return false;
 
     const parentUrl = victim.parentUrl ?? this._parentOf.get(victim.url);
     const childUrls = victim.childUrls ?? (victim.childUrl ? [victim.childUrl] : []);
     const isLeaf = !childUrls.some((u) => u !== victim.url && this.nodes.has(u));
 
-    this.nodes.delete(victim.url);
-    victim.group.parent?.remove(victim.group);
-    this._onTileRemoved(victim);
-    this._parentOf.delete(victim.url);
+    this._evictTileNode(victim);
 
     // 淘汰的是中间层时，把已加载的子孙改挂到它的父级上：
     // 不然它们瞬间"无父"，父级那边还留着指向 victim 的 childUrls，
@@ -459,8 +541,8 @@ export class S3MTileset {
     }
 
     // 删的是最细一级、而上一级又不在内存里 → 把上一级排回去，别让那块地空着
-    if (isLeaf && parentUrl && !this.nodes.has(parentUrl) && !this.pending.has(parentUrl)) {
-      this._enqueue(parentUrl);
+    if (false as boolean && isLeaf && parentUrl && !this.nodes.has(parentUrl) && !this.pending.has(parentUrl)) {
+      // 淘汰阶段不再重新入队父瓦，防止预算满载时引发父子死循环震荡（thrashing loop）
     }
     return true;
   }
@@ -773,7 +855,7 @@ export class S3MTileset {
             break;
           }
         }
-        this.externalAtlasCache.set(id, candidate);
+        this.putExternalAtlas(id, candidate);
       }
       if (candidate) {
         if (accept(candidate)) apply(candidate);
@@ -818,10 +900,10 @@ export class S3MTileset {
       if (segments.length !== names.length) {
         throw new Error(`pack 段数 ${segments.length} ≠ 请求名 ${names.length}`);
       }
-      names.forEach((n, i) => this.leafRequestCache.set(n, segments[i]!));
+      names.forEach((n, i) => this.putLeafRecords(n, segments[i]!));
     } catch (e) {
       console.warn('[s3m] leaf pack 请求失败：', u, e);
-      for (const n of names) if (!this.leafRequestCache.has(n)) this.leafRequestCache.set(n, null);
+      for (const n of names) if (!this.leafRequestCache.has(n)) this.putLeafRecords(n, null);
     }
   }
 
@@ -833,10 +915,10 @@ export class S3MTileset {
       const res = await fetch(u);
       if (!res.ok) throw new Error(`HTTP ${res.status}`);
       const records = (await parseTexblockSegments(await res.arrayBuffer())).flat();
-      this.leafRequestCache.set(stem, records);
+      this.putLeafRecords(stem, records);
     } catch (e) {
       console.warn('[s3m] leaf texblock 请求失败：', u, e);
-      if (!this.leafRequestCache.has(stem)) this.leafRequestCache.set(stem, null);
+      if (!this.leafRequestCache.has(stem)) this.putLeafRecords(stem, null);
     }
   }
 
@@ -898,7 +980,10 @@ export class S3MTileset {
       }
 
       const build = await this._builder();
-      const { group, stats } = await build(tile, { textureCache: this.textureCache, uniforms: this._uniforms });
+      const buildRes = await build(tile, { textureCache: this.textureCache, uniforms: this._uniforms });
+      const { group, stats } = buildRes;
+      const texKeys = (buildRes as any).textureKeys ?? (group.userData?.textureKeys as string[] | undefined) ?? Object.keys(tile.textures ?? {});
+      this.registerTileTextures(url, texKeys);
       const lod = this._pickLod(tile);
 
       const childUrls: string[] = [];
@@ -932,6 +1017,11 @@ export class S3MTileset {
         childUrls,
         parentUrl: this._parentOf.get(url),
         state: 'ready',
+        stats: {
+          meshes: stats.meshes ?? 0,
+          vertices: stats.vertices ?? 0,
+          triangles: stats.triangles ?? 0,
+        },
       };
 
       this.nodes.set(url, node);