s3m-three 0.3.0 → 0.3.1

package/docs/API.md

@@ -97,6 +97,12 @@ three 场景原点固定在**场景锚点**（第一个成功加载的数据集
 
 锚点来自数据集配置的 `position`，但会做一致性校验：若 `position` 与 `geoBounds` 中心偏差超过 0.5°，判定为生产时的占位脏数据，回退到 `geoBounds` 中心。
 
+回退的前提是 `geoBounds` 本身可用（`usableGeoBounds()`）：字段缺失、非有限值、超出经纬度量级、或**退化成全 0 / 一个点**的都算不可用。这条是踩过坑加的——OSGB 那类配置根本没有经纬度范围，全 0 的框反过来把唯一正确的 `position` 判成异常，结果是视角和模型一起跑到几内亚湾。`getBounds()` 同样只统计可用的框，宁可不移动视角，也不甩到 `(0,0)`。
+
+`position` 有两种写法都认：老数据是 `position.x/y/z` + `units`，v3.01 起改成 `position.point3D.{x,y,z}` + `unit`。第二个键名必须认，否则投影单位是米的数据会被当成度。
+
+OSGB（`SuperMapCache` XML）的配置只给 `<sml:Position>`（经纬度原点）和 `<sml:BoundingBox>`（以原点为中心的**米制**局部盒），解析时按等距圆柱近似反算成 `geoBounds`：`Δlon = x / (111320·cos φ)`、`Δlat = y / 110540`。
+
 ### 瓦片与 LOD
 
 配置里的 `tiles`（桌面导出）或 `rootTiles`（iServer，可多棵）是瓦片树入口。LOD 按规范里的 `RangeMode` 判定：
@@ -105,7 +111,11 @@ three 场景原点固定在**场景锚点**（第一个成功加载的数据集
 |---|---|---|
 | 0 | `Distance_From_EyePoint` | 相机到包围球中心距离 < rangeValue 时细化 |
 | 1 | `Pixel_Size_OnScreen` | 包围球投影像素半径 > rangeValue 时细化 |
-| 2 | `Geometric_Error` | 按屏幕像素半径近似处理 |
+| 2 | `Geometric_Error` | 规范枚举里没有这一档。按屏幕像素半径近似处理 |
+
+关于 2：线上高斯泼溅与点云服务的 pageLOD 全是这一档，且 `rangeValue` 与包围球半径成固定比例（实测根瓦片 `0.664 / 10.455`、子瓦片 `0.332 / 3.7`，比例都约 0.064），更像「相对屏幕的几何误差」而不是绝对像素。按 1 处理方向是对的（近处细化），只是阈值偏小时会多下几层，用 `lodRangeScale` 收。
+
+多骨架瓦片（每块 geode 一个 pageLOD）的 `sphere` / `rangeValue` 取自其中一块，细化判定是整块瓦片共用的；子引用则会把**每个 pageLOD 的 `childTile` 都收集**进 `childUrls`，所以一层细化会正确扇出到 N 块子瓦。
 
 ### 单体化
 
@@ -276,15 +286,20 @@ clearFilter(): void
 ```ts
 setGroundMode(mode: GroundMode): void
 setGroundOpacity(opacity: number): void
+setGroundOcclude(enabled: boolean): void
 setExcavationBounds(bounds: [number, number, number, number] | null): void
 ```
 
 自带的物理地表网格锚定在**场景 ENU 高程**，解决的是「模型自身地上 / 地下结构的物理覆盖与透视关系」（地铁站、基坑这类数据没有真实地表 DEM 可用）：
 
-- `'translucent'` 半透明地表 + `depthWrite = false` ⇒ 地下结构透过地表显现
-- `'excavate'` 基坑范围内片元 `discard` ⇒ 挖空井口
+- `'translucent'` 半透明地表，地下结构透过地表显现（遮挡默认关闭）
+- `'excavate'` 基坑范围内片元 `discard` ⇒ 挖空井口，坑外地下部分被地表挡住（遮挡默认开启）
 
-它与 MapLibre terrain 是**两个正交维度**，不存在替代关系：terrain 解决「真实世界地面的起伏与遮挡」，物理地表解决「模型自身的地上 / 地下语义」。贴地（`setDatasetHeight`）后物理地表网格的高度会跟随主数据集的抬升量自动同步，保证覆盖关系不错位。
+**遮挡是独立开关**（`ground.occlude` / `setGroundOcclude`），且**与地表模式解耦**：`mode: 'none'` 时也可以单独开启 —— 不显示任何地表，只留一块隐形地面把地面以下切掉。它由一块 `colorWrite = false`、`renderOrder = -1000` 的纯深度代理完成——遮挡是在片元绘制那一刻由深度测试决定的，半透明覆盖网格排在 transparent 队列末尾，写不写深度都挡不住已经画完的建筑。开挖模式下代理会在坑口同步开洞，否则井口就白挖了。
+
+**地表高度默认跟随主数据集抬升量**（`ground.trackHeight`，默认 `true`）：贴地时模型整体抬到地面高程，切割面必须跟到同一高程，否则整个模型被齐根切掉。设为 `false` 则钉死在当前高度——高程调整只动模型不动切割面，适合「调埋深 / 控制切掉多少」的交互。
+
+它与 MapLibre terrain 不存在替代关系，但也不是互斥的两套机制：两者都只是往同一个深度缓冲里写深度，谁更近谁赢。terrain 表达「真实世界地面的起伏遮挡」，物理地表代理表达「模型自身的一刀切地上 / 地下语义」——平面表达不了山体那种半山腰遮挡，而地形已写入更近深度的像素上，平面代理也写不进去。贴地（`setDatasetHeight`）后物理地表网格的高度会跟随主数据集的抬升量自动同步，保证覆盖关系不错位。
 
 ### 拾取与空间查询
 
@@ -665,6 +680,25 @@ console.log(tile.version, Object.keys(tile.geoPackage));
 
 解析结果可用 `bytesRead === bytesTotal` 自检——不等说明偏移算错了。
 
+**v3 骨架条目额外暴露 `obb`**（`GeoPackageEntry.obb`，局部 ENU 系的中心 + 三个半轴）。多骨架瓦片里每块 geode 范围各不相同，而 pageLOD 的包围球只取自其中一块，做按块剔除 / 贴地要用条目自带的这个。它是按 `skeletonStreamSize` 定位到「条目末尾 96 字节」读出来的，而不是靠猜——几何段与 OBB 之间可能还有对齐填充（实测高斯泼溅 / 点云多块瓦片里就有块比别的块多 4 字节），靠固定长度往后推会整条流错位，下一块骨架的名字长度会读到垃圾，报出来是「未知骨架标记」。
+
+**S3M 1.x 容器会被识别并抛错**，而不是抛一个看不懂的类型错误：
+
+```ts
+import { parseS3MB, S3MFormatError } from 's3m-three/core';
+
+try {
+  await parseS3MB(buf);
+} catch (e) {
+  if (e instanceof S3MFormatError) {
+    // e.permanent === true：格式层面的永久错误，重试没有意义
+    // 典型是 .s3m（OSGB 转的 SuperMapCache 瓦片，头 4 字节是魔数 "s3m\0" 而不是版本号）
+  }
+}
+```
+
+不识别的话，`s3m\0` 会被 float32 读成 1e-38 的「版本号」，接着把 zlib 头 `78 da cc bd` 当压缩长度，最终报 `RangeError: Invalid typed array length: 3184319096`——完全看不出是格式问题。`S3MTileset` 见到 `permanent` 就不退避重试，同类错误也只上报一次。
+
 ### MeshOpt 压缩几何
 
 v3 瓦片默认用 MeshOpt 压几何。解析器内部按需 `import` 内联的 meshoptimizer wasm 解码器（约 22KB），只有真的遇到 MeshOpt 瓦片才会加载，v1/v2 与未压缩的 v3 不受影响。
@@ -680,11 +714,39 @@ normal   = octDecode(int16 / 32767)
 回归校验（60 个真实瓦片，校验偏移、索引范围、法线归一化、包围盒与 OBB 尺寸）：
 
 ```bash
-npm run test:meshopt
+bun run test:meshopt
 ```
 
 需要 WebAssembly；不支持 wasm 的环境会在遇到 MeshOpt 瓦片时抛明确错误。
 
+**自定义属性流与高斯泼溅属性不再被丢弃**：`CUSTOM0` / `CUSTOM1` / `GS_SCALE` / `GS_ROTATION` 四条语义会原样保留成顶点属性（`custom0` / `custom1` / `gsScale` / `gsRotation`，每点 4 字节），名字到槽位的映射来自数据自带的 `vertexAttributeDescript`（实测高斯服务是 `{"GS_Rotation":1,"GS_Scale":0}`）。以前这几条流解码后直接扔掉，于是 `3DGaussianSplatting` 数据到渲染层只剩「位置 + 颜色」，上层拿不到泼溅的尺寸与朝向。
+
+每块骨架还带一份原始流清单 `vertexPackage.meshOptInfo`（各语义的压缩字节数与解码后每点 stride），排查新数据时先看它，比对着十六进制猜快得多。
+
+**这两条 GS 流的量化格式还没标定**（4 字节 / 点，既不像 3 个 float，也不像明显四元数），所以渲染层目前只是把它们带到顶点属性上备用，没有接进真正的 splat 着色器。
+
+### Draco 点云几何
+
+v3.01 的点云数据还有一条 Draco 压缩分支（骨架 tag = `DRACO`）。接法与 MeshOpt 相同：内联 wasm 解码器（约 266KB）只在真的遇到时动态 `import`，解码后并入同一套 attribute 组装，点云按 `primitiveType = 1` 交给 `THREE.Points`，分类码 / 强度 / 权重三种自定义属性一并解出来。
+
+**这个分支的字段顺序与规范描述对不上，是从真实瓦片逐字节标定的**（偏移以骨架 tag 字段之后为 0）：
+
+```
+u32  payloadSize       // 覆盖「本字段之后 … 条目末尾 OBB 之前」
+u32  未知（实测恒 32）
+i32  pos / normal / color / secondColor 各自的 draco 属性 uid（-1 = 无）
+u32  自定义属性个数（实测 3）+ i32[] 各自的 uid
+u32  vertexAttrCount   // 实测恒 0
+u32  dracoSize; byte[dracoSize]   // 标准 draco 比特流，开头 5 字节 "DRACO"
+String descript        // {"PointCloudClassCode":2,"PointCloudIntensity":1,"VertexWeight":0}
+```
+
+`descript` 的值是「该属性在自定义 uid 数组里的**下标**」，不是分量数。OBB 不在这段里读，由 `parseSkeletonEntries` 统一按条目末尾 96 字节取。
+
+官方 SDK 的 `parseDracoSkeleton` 在这个分支上**解析不了同一个服务**：字段顺序里多了一个 `materialCount`，而且 `version === 3` 的判定对 v3.01 瓦片不成立。所以这里不能照官方实现抄。
+
+读偏的兜底是四重自校验（`payloadSize` 覆盖范围 / `dracoSize` / `"DRACO"` 魔数 / 骨架自带的 `skeletonStreamSize`）加单骨架 64M 点数上限。实测两个瓦片 5 个骨架逐字节一致；**这条路径尚未纳入 `tests/`**，改动 `core/Draco.ts` 前请拿真实瓦片复验。
+
 ### `S3MTileset`
 
 单个数据集的瓦片树。不依赖 three，可以用注入的 `buildTile` 在 Node 里跑通完整链路（URL 解析 → 解析 → LOD 调度），适合做数据体检。
@@ -695,6 +757,26 @@ await ts.init();
 ts.update([0, 0, 500], 0.64, 900); // 相机在局部 ENU 的位置
 ```
 
+`configUrl` 必须指向**某个数据源的 config**，不是 `datas` 目录：
+
+```
+https://host/iserver/services/3D-xxx/rest/realspace/datas/<数据源名>/config
+```
+
+数据源名可以是中文（如 `寿宁阁`），`new URL()` 会自动百分号编码；后缀只能写 `config`，写 `config.xml` 会 406。只给到 `…/realspace/datas` 时拿到的是一个资源清单数组，`JSON.parse` 不报错但没有 `position` / `rootTiles`，表现为「视角跳到 (0,0) + 一句缺少 root tile」——先用 `…/datas.json` 列出数据源，再逐个拼 `/config`。
+
+配套导出的三个纯函数，方便自建数据集列表与做体检：
+
+```ts
+parseConfigText(text)      // JSON 与 SuperMapCache XML 两种配置统一成同一种形状（含 fileType）
+usableGeoBounds(bounds)    // 判断 geoBounds 是否真的可用；不可用返回 null（见「锚点」）
+fixPathEncoding(url)       // 补路径里没编码但服务端会改写的字符：+ → %2B、空格 → %20
+```
+
+`fixPathEncoding` 这条是硬需求：OSGB 转出来的瓦片名就是 `Tile_+002_+001`，而 iServer 按 `URLDecoder` 解路径，未编码的 `+` 会变成空格 → 404「瓦片数据不存在」。`new URL()` 认为 `+` 在 path 里合法，不会替我们编码，所以拼完 URL 必须补这一刀（query 里的 `+` 不动，那本来就是空格约定）。
+
+失败处理分两类：**网络类**错误退避重试（`maxRetries`，默认 2 次）；**格式类**错误（`e.permanent === true`，例如 S3M 1.x 容器）直接判失败不重试，并且整棵瓦片树里同类错误只回调一次 `onError`，避免几十块瓦片刷同样的日志。
+
 ### 单体属性工具
 
 ```ts
@@ -743,12 +825,31 @@ viewer.flushOverrides();
 
 ## 已知限制
 
-- **Draco 压缩几何**能识别、不能解码，遇到会抛明确错误。接法与 MeshOpt 相同（内联 wasm、按需 `import`、解码后走同一套 attribute 组装），但必须先拿 Draco 瓦片标定容器结构。MeshOpt 已支持，且是逐字节对过 60 个真实瓦片才做对的。
+- **Draco 压缩几何**已支持（v3.01 点云分支）：内联 wasm 按需 `import`，解码后与标准骨架同路输出 attribute，点云按 `primitiveType = 1` 走 `THREE.Points`，分类码 / 强度 / 权重三种自定义属性一并解出。两点要留意：一是**容器与规范描述对不上**，字段顺序是从真实瓦片逐字节标定的（`payloadSize` / `dracoSize` / `"DRACO"` 魔数 / `skeletonStreamSize` 四重自校验兜读偏，另有单骨架 64M 点数上限），官方 SDK 的 `parseDracoSkeleton` 字段顺序多一个 `materialCount` 且 `version === 3` 的判定对 v3.01 不成立，解析不了同一个服务，不能照抄；二是这条路径**还没有回归测试钉住**（目前只有排查探针脚本），改 `core/Draco.ts` 的字段顺序必须拿真实瓦片复验。
 - **实例化单体**（`pickInfo` 里给的是 `instanceIds` 而不是 `batchId`，白模常见）只做了渲染，没做按单体控制：`setFeatureStyle` / `filterByField` / `elevateByField` / GPU 拾取走的都是 `aBatchId`，这条路径对实例化几何不生效。要支持得把每个实例单独上色，得改 InstancedMesh 的 instanceColor + 拾取编码。
-- **CRN 纹理**已支持，且已在真实服务上验证：内联的 crunch wasm 转回 DXT 后走现成解码，DXT 具体格式看 CRN 头，wasm 约 76KB、只有真遇到 CRN 时才动态加载。**判定看 `compressType` 而不是 `pixelFormat`**——实测 v3.00 是 `ct=26 / pf=13`、行标是 `ct=50000 / pf=32856`，按 `pixelFormat` 26 / 27 判断会把真实 CRN 整包丢掉（模型变灰模）。判定收敛在 `packages/s3m-three/src/core/TextureFormat.ts`（`resolveTextureKind` / `TextureCompress` / `dxtPixelFormatOf`，已从包入口导出）。用 `npm run probe:crn -- --crn <数据集 config 地址>` 可以对任意服务跑「尺寸吻合 / 色数 / 粗糙度 / ASCII 预览」的实测。
-- **纹理分包（`s3m:TextureSharing`）未支持**：这类数据集的 `tiles` 全是 `.s3mblock`，不是 `.s3mb`，加载会失败（例：SuperMap Online `3D-CBD/Xiaopin@CBD`）。
-- **多块 MeshOpt 骨架**（`blockCount > 1`）暂未对齐：例 `3D-WorkSpace_pbr1/pbrmodel`，第二块头部按现有布局读会错位，会给出「流尺寸异常」的可定位报错而不是底层 RangeError。
+- **CRN 纹理**已支持，且已在真实服务上验证：内联的 crunch wasm 转回 DXT 后走现成解码，DXT 具体格式看 CRN 头，wasm 约 76KB、只有真遇到 CRN 时才动态加载。**判定看 `compressType` 而不是 `pixelFormat`**——实测 v3.00 是 `ct=26 / pf=13`、行标是 `ct=50000 / pf=32856`，按 `pixelFormat` 26 / 27 判断会把真实 CRN 整包丢掉（模型变灰模）。判定收敛在 `packages/s3m-three/src/core/TextureFormat.ts`（`resolveTextureKind` / `TextureCompress` / `dxtPixelFormatOf`，已从包入口导出）。用 `bun run probe:crn -- --crn <数据集 config 地址>` 可以对任意服务跑「尺寸吻合 / 色数 / 粗糙度 / ASCII 预览」的实测。
+- **纹理分包（`s3m:TextureSharing` / S3MBLOCK）已完整支持**：
+  - **容器结构**：`.s3mblock` 单文件容器 = 若干 RO 组，每组包含一段 pageLOD 元信息 + zlib 压缩的 v2 瓦片体（段目录：groupNode / 骨架 / secondColor / 图集 / 材质 / 单体化）；纹理是图集（`isSaveData`），材质按图集 id（`-N.texblock`）引用，几何顶点区间绑定到图集子区域；
+  - **解析与 UV 重映射**：解析端把顶点 UV 用 `fract` 平铺语义重映射进图集空间，多图集自动走货架式装箱合并（`AtlasPack`），下游材质直接绑定整张图集；
+  - **细级 LOD（leaf）外部图集加载**：细级瓦片的图集未内嵌原始像素（`data = null`），由 `_fillExternalAtlases` 解析子请求名（`_subRequestNames`）：
+    - 支持展开 `Tex_x.texblock#<三位数字串>` 多精灵容器索引；
+    - 对齐官方 `Uci` 规范的 pack 请求：URL 拼装 `extratiles=<names>` 批量合并拉取，避免高并发零碎请求；
+    - 响应体通过 `parseTexblockSegments` 解码 `kMi` 分段记录，并通过 `leafRequestCache` 与 `_leafPending` 实现跨瓦片并发请求自动去重缓存；
+    - **组合画布与装配**：对 leaf 模式，解出子精灵 RGBA 缓冲，按 `subTexInfos[i]` 的偏移量（`offsetX`、`offsetY`）以标准自上而下行序拷贝进高分辨率组合画布；
+    - **安全判定与重拼**：外部图集接入前通过 `evaluateAtlasUpgrade` 进行长宽比与下采样色差校验，判定通过后由 `rebuildBlockTextureState` 重新生成拼图与重算归一化 `texRect`；
+  - 实现位于 `core/S3MBlockParser.ts`、`core/AtlasPack.ts` 与 `tileset/S3MTileset.ts`，并通过 `tests/unit/s3mblock.test.ts`、`tests/unit/leaf-atlas.test.ts` 和 `tests/unit/leaf-uv-render.test.ts` 交叉验证钉住。
+- **多块 MeshOpt 骨架**（`blockCount > 1`）已支持。这类骨架里**每块后面紧跟自己的索引包**（不是所有块之后再统一放一份），索引是块内局部编号；解析时按块顺序合并顶点流，再把每块索引加上顶点基数偏移，对外仍是一份顶点缓冲 + 多组索引包。实测 `3D-WorkSpace_pbr1/pbrmodel` 的 `blockCount=2` / `3` 瓦片可正常加载。
 - **切线顶点流**只跳过不解码（渲染没有法线贴图通道），带 TANGENT 的数据不会被判失败。
+- **S3M 1.x（`.s3m`，SuperMapCache）已支持**。这类服务的 `config` 返回 `SuperMapCache` XML（`sml:FileType = OSGBFile`），位置与范围按米制盒反算（见「锚点」）；瓦片是 `73 33 6D 00` 魔数 + zlib 的老容器，`parseS3MB` 认出魔数后交给 `core/S3M1Parser.ts`，输出同形状的 `ParsedTile`，下游渲染 / LOD / 拾取零改动。
+  **注意：它的下一级 LOD 并不是 `.osgb`** —— XML 里 `RangeDataList` 写的 `..._L16_0.osgb` 只是切片时的原始文件名，服务实际发布的是同名换 `.s3m` 后缀，走 `datas/<数据源>/data/path/<瓦片目录>/<名>.s3m`（实测 L16/L17/L18 全部 200，`?sceneName=` 不参与寻址）。所以整棵 LOD 树都是同一种容器，**不需要 OSG Binary 解码器**；早先「因为子瓦是 .osgb 所以做不了」的结论是没验证就下的，已作废。
+  已标定：`73 33 6D 00` 魔数 + zlib；解压后 `uint32 xmlSize + XML + 补齐 4 字节对齐（实测 2~3 个 0x30，不是固定标记）+ (uint32 size + data) × 3`，三段长度链在四块样本上全部精确闭合；几何流 = `uint32 meshCount` + 每块网格 `{ geoName, 7, 772, V, 0 }` + `V × 16B` 顶点 `(x, y, z, z)` + 数组区 + `uint32 1` + `uint32 materialId`（与 XML 材质号一致）；纹理流 = `uint32 count` + 每条 `{ id, width, height, format, size, flag }` + `size` 字节（实测 `format=14`、0.5 B/px = DXT1，`28 + size` 精确等于段长）；索引确认为 u16（值域最大恰为 `V-1`）；几何里**没有法线数组**，接解码时要 `computeVertexNormals()`。
+  接这种格式时有三个坑，都是实测出来的，别凭直觉：
+  1. **几何里没有法线数组**（全段扫 `|v|≈1` 的最长游程只有 4~10 个），建完要 `computeVertexNormals()`；
+  2. **头里的 `format` 不是 `S3MPixelFormat` 枚举** —— 实测四块瓦片都是 `14`，而这枚举里 14 = BGRA（4 B/px），照搬就会把 0.5 B/px 的 DXT1 当 4 字节读，满屏彩噪。必须按 `size / (width*height)` 反推（`pixelFormatOfBpp`）；
+  3. **UV 是「v = 0 对应文件首行」**，与 DXT 解码器内部那次 GL 方向的 Y 翻转相反。不抵消的话几何的 v（实测 0.483~0.983）会正好采到图集空的那半张 —— 区域均值亮度 5.6 对比 76.1，模型上就是一片黑块。所以 v1 纹理要置 `S3MTexture.flipY = true`。
+
+  子瓦地址规则见 `s3m1ChildUrl`：XML 的 `RangeDataList` 给的是切片时残留的 `.osgb` 名，实际发布是同名换 `.s3m` 并插在 `datas/<数据源>/data/path/<瓦片目录>/` 下；父瓦自己已经在 `data/path` 下时只能换文件名，再插一层就成了 `data/path/data/path/...` 全部 404（有回归测试钉住）。
+- **高斯泼溅（`3DGaussianSplatting`）只按点渲染**。加载、细化、出图整条链路是通的（这类瓦片没有索引包，顶点即点，`GeometryBuilder` 会补一个「顶点即点」的伪包走 `THREE.Points`；不补的话整块瓦片落到「无可用几何」被丢掉，这是之前"加载不出来"的第二个原因）。但画出来的是带顶色的点集，不是真正的泼溅：`gsScale` / `gsRotation` 两条自定义流的量化格式还没标定，而且颜色是 RGBA（A 通道是泼溅不透明度），现在的顶点色路径会丢掉 alpha。要上 EWA splatting 得先按深度层级取样把这两条流对准，再补协方差 + 深度排序的 alpha 混合。
 - **KTX2** 不在 S3M 的 `pixelFormat` 枚举里，iServer 也不会发；要支持需自行引入 `basis_transcoder.wasm` 并解析容器，属于「换数据源才需要考虑」的项。
 - **骨骼动画**解析了但未驱动。
 - 跨城市量级的数据集叠加会有 float32 精度问题。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3m-three",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "SuperMap S3M 三维模型格式的 three.js 渲染内核：浏览器内直接解析 .s3mb 瓦片，无需转 3D Tiles，支持 LOD 调度、白膜/按高度/按单体/动态扫描着色、单体级 GPU 拾取。宿主无关，可单独用于任意 three 场景。",
   "type": "module",
   "repository": {

package/src/core/AtlasAlpha.ts

@@ -0,0 +1,82 @@
+import DXTTextureDecode from './DXTTextureDecode.js';
+
+/**
+ * 解出图集的 alpha 掩码（1 B/像素）。只对 DXT 图集做，其它格式返回 null。
+ *
+ * 用途：图集里的每个精灵是「建筑立面 + 上方天空」的一整块照片，天空是 alpha=0。
+ * 官方材质 alphaMode 全是 opaque，说明它拿到的精灵本来就没有天空 —— 也就是
+ * **rect 只框立面本体**。我们手里的 rect 是"照片块"，所以用掩码把它收缩到
+ * 不透明包围盒，等价于官方那份裁好的 rect。
+ */
+export function atlasAlphaMask(tex: {
+  width: number;
+  height: number;
+  pixelFormat: number;
+  compressType: number;
+  data: Uint8Array | null;
+}): Uint8Array | null {
+  if (!tex.data || !tex.width || !tex.height) return null;
+  const ct = tex.compressType;
+  const isDxt = ct === 14 || ct === 13 || ct === 12 || ct === 17 || ct === 19 || ct === 20 || ct === 21 || tex.pixelFormat >= 17;
+  if (!isDxt) return null;
+  // compressType 14 → DXT5（pixelFormat 13），见 TextureFormat.ts 的说明
+  const pf = ct === 14 ? 21 : tex.pixelFormat;
+  if (pf !== 19 && pf !== 20 && pf !== 21) return null; // 只有带 alpha 的格式值得做
+  const w = tex.width;
+  const h = tex.height;
+  const rgba = new Uint8Array(w * h * 4);
+  try {
+    DXTTextureDecode.decode(rgba, w, h, tex.data, pf);
+  } catch {
+    return null;
+  }
+  const mask = new Uint8Array(w * h);
+  for (let i = 0; i < w * h; i++) mask[i] = rgba[i * 4 + 3]!;
+  return mask;
+}
+
+/**
+ * 把 rect（uv 空间、y 向上的归一化矩形）收缩到掩码里的不透明包围盒。
+ * 找不到不透明像素时原样返回，避免把合法 rect 弄成退化矩形。
+ */
+export function shrinkRectToOpaque(
+  rect: { x: number; y: number; w: number; h: number },
+  mask: Uint8Array | null,
+  W: number,
+  H: number
+): { x: number; y: number; w: number; h: number } {
+  if (!mask) return rect;
+  const px0 = Math.max(0, Math.floor(rect.x * W));
+  const px1 = Math.min(W, Math.ceil((rect.x + rect.w) * W));
+  // rect.y 是 uv 空间（0 在底部），掩码是图像空间（0 在顶部）
+  const py0 = Math.max(0, Math.floor(rect.y * H));
+  const py1 = Math.min(H, Math.ceil((rect.y + rect.h) * H));
+  if (px1 <= px0 || py1 <= py0) return rect;
+
+  let bx0 = Infinity, bx1 = -Infinity, by0 = Infinity, by1 = -Infinity;
+  for (let py = py0; py < py1; py++) {
+    const iy = H - 1 - py;
+    if (iy < 0) continue;
+    for (let px = px0; px < px1; px++) {
+      if (mask[iy * W + px]! <= 8) continue;
+      if (px < bx0) bx0 = px;
+      if (px > bx1) bx1 = px;
+      if (py < by0) by0 = py;
+      if (py > by1) by1 = py;
+    }
+  }
+  if (!(bx1 >= bx0) || !(by1 >= by0)) return rect;
+
+  // 内缩半像素，避开边缘的混色 alpha
+  const x0 = bx0;
+  const x1 = bx1 + 1;
+  const y0 = by0;
+  const y1 = by1 + 1;
+  const eps = 0.5;
+  return {
+    x: (x0 + eps) / W,
+    w: Math.max(1 / W, (x1 - x0 - 2 * eps) / W),
+    y: (y0 + eps) / H,
+    h: Math.max(1 / H, (y1 - y0 - 2 * eps) / H),
+  };
+}

package/src/core/AtlasPack.ts

@@ -0,0 +1,127 @@
+import DXTTextureDecode from './DXTTextureDecode.js';
+
+/**
+ * 把「一个块里的多张图集」合并成一张。
+ *
+ * 为什么必须合并：S3MBLOCK 的一个 geo（= 一个网格）里，不同顶点区间可以绑定到**不同的图集**
+ * （实测 41_00.s3mblock 里 6 张图集，尺寸 120x144 / 192x128 / 216x288 …，各自的 subTexInfo
+ * 绑定不同的 vertexOffset 区间）。而我们的材质只有一个 `map`，只能喂一张图 ——
+ * 其它图集那部分顶点就会拿着「自己图集里的归一化坐标」去采另一张图集，采到的是完全无关的
+ * 内容（表现就是墙上贴着别处的立面照）。
+ *
+ * 官方用的是纹理数组（着色器里 `atlas_batchTable_xywh(batchId, batchTextureAtlas, …)` +
+ * `uTexAtlasDim` 复数形式），每个 batch 自己带图集序号。这里用等价但更省事的做法：
+ * 解析阶段把所有图集按「货架」拼进一张大图，rect 全部换算到这张大图的坐标系，
+ * 于是单张 map 就够用了。
+ *
+ * 坐标系约定：拼图按**自上而下**的行序存放，并让纹理 `flipY = false`，
+ * 也就是 UV 的 v=0 对应图片顶行 —— 这样 rect 的 y 直接用 `offsetY / height` 即可。
+ */
+
+interface AtlasLike {
+  id?: string;
+  width: number;
+  height: number;
+  pixelFormat: number;
+  compressType: number;
+  data?: Uint8Array | null;
+}
+
+export interface PackedAtlases {
+  width: number;
+  height: number;
+  data: Uint8Array;
+  /** 图集 id → 它在拼图里的左上角像素坐标 */
+  offsets: Map<string, { x: number; y: number }>;
+}
+
+/** 解码出的图集图像 + 行序约定 */
+export interface DecodedAtlasImage {
+  rgba: Uint8Array;
+  /**
+   * `true` = 缓冲已是自上而下（v=0 顶行），直接拷；
+   * `false` = 底朝上（DXT 解码输出即是：源第 sy 行写到 height-1-sy），贴进画布要逐行倒序。
+   */
+  topDown: boolean;
+}
+
+/**
+ * 解出图集图像。非 DXT 且非「已经是解好的 RGBA」时返回 null。
+ *
+ * - `compressType=0 + pixelFormat=28`（leaf 组合画布 / 拼图产物）：本来就是自上而下 RGBA，原样返回；
+ * - DXT 族：走 `DXTTextureDecode`，输出按仓库约定是**底朝上**的（见 packAtlases 的行序注释）。
+ */
+export function decodeAtlasImage(tex: AtlasLike): DecodedAtlasImage | null {
+  if (!tex.data || !tex.width || !tex.height) return null;
+  const ct = tex.compressType;
+  if ((ct === 0 || ct === undefined) && tex.pixelFormat === 28 && tex.data.length === tex.width * tex.height * 4) {
+    return { rgba: tex.data, topDown: true };
+  }
+  const isDxt =
+    ct === 12 || ct === 13 || ct === 14 || ct === 17 || ct === 19 || ct === 20 || ct === 21 || tex.pixelFormat >= 17;
+  if (!isDxt) return null;
+  const out = new Uint8Array(tex.width * tex.height * 4);
+  try {
+    DXTTextureDecode.decode(out, tex.width, tex.height, tex.data, tex.pixelFormat);
+  } catch {
+    return null;
+  }
+  return { rgba: out, topDown: false };
+}
+
+/**
+ * 合并一个块里的全部图集。只有一张图集时返回 null（没必要合并，也避免多一次解码）。
+ */
+export function packAtlases(tp: Record<string, AtlasLike>): PackedAtlases | null {
+  const entries = Object.entries(tp).filter(([, t]) => t.data && t.width > 0 && t.height > 0);
+  if (entries.length < 2) return null;
+
+  const images = new Map<string, { w: number; h: number; rgba: Uint8Array; topDown: boolean }>();
+  for (const [key, tex] of entries) {
+    const img = decodeAtlasImage(tex);
+    if (!img) return null; // 有一张解不出来就整体放弃，保持原样比拼错强
+    images.set(key, { w: tex.width, h: tex.height, rgba: img.rgba, topDown: img.topDown });
+  }
+
+  // 货架式装箱：按宽度累加，超宽换行。图集都是小块，这样做足够紧凑。
+  const MAX_W = 1024;
+  let x = 0;
+  let y = 0;
+  let rowH = 0;
+  let usedW = 0;
+  const offsets = new Map<string, { x: number; y: number }>();
+  for (const [id, img] of images) {
+    if (x > 0 && x + img.w > MAX_W) {
+      x = 0;
+      y += rowH;
+      rowH = 0;
+    }
+    offsets.set(id, { x, y });
+    x += img.w;
+    rowH = Math.max(rowH, img.h);
+    usedW = Math.max(usedW, x);
+  }
+  const W = Math.max(1, usedW);
+  const H = Math.max(1, y + rowH);
+  const data = new Uint8Array(W * H * 4);
+
+  for (const [id, img] of images) {
+    const off = offsets.get(id)!;
+    // ★ DXT 解码缓冲必须逐行**倒序**拷贝（topDown=false 时）。
+    //
+    // DXTTextureDecode 输出的是「源图上下颠倒」的缓冲（源第 sy 行写到 height-1-sy），
+    // 而 rect 的 y 是按源图**自上而下**的 offsetY 算的。原样拷贝会让拼图的行序和
+    // rect 的约定相反；更糟的是同一块里各图集高度不同（192 / 184 / 64 / 128），
+    // 颠倒量随图集而异，于是「哪些精灵对、哪些精灵错」取决于它属于哪张图集 ——
+    // 表现为同一面墙一半正常一半贴到别处。
+    // 倒序拷进来之后，拼图行 0 就对应源图顶行，rect.y = (off.y + offsetY) / H 对全部图集统一成立。
+    // 已经是自上而下的缓冲（leaf 组合画布，topDown=true）则原样拷贝，不能再翻一次。
+    for (let row = 0; row < img.h; row++) {
+      const srcRow = img.topDown ? row : img.h - 1 - row;
+      const src = srcRow * img.w * 4;
+      data.set(img.rgba.subarray(src, src + img.w * 4), ((off.y + row) * W + off.x) * 4);
+    }
+  }
+
+  return { width: W, height: H, data, offsets };
+}

package/src/core/AtlasUpgrade.ts

@@ -0,0 +1,182 @@
+/**
+ * 外部图集文件（`requestNames` 指向的 `.texblock`）能不能顶替块里自带的那份？
+ * —— **先验证，再替换**。
+ *
+ * 官方 `createTexture` 的判定（SuperMap3D.js，`lM.prototype.createTexture`）：
+ *
+ * ```js
+ * if (!n || !E) {                       // 非根瓦片，或没开 textureLod
+ *   this._subRequestNames = [];
+ *   for (...) this._subRequestNames.push(yke(h.requestNames[D]));  // 只取 requestNames
+ * }
+ * return this.isLeaf = (!n || !E) && !(h.requestNames.length === 1 && h.requestNames[0] === a);
+ * ```
+ *
+ * 关键两点：
+ * 1. **只认 `requestNames`**。`childTexNames` 是**下一级 LOD 的图集指针**（官方 `_ancestorTexture`
+ *    只用它继承 batchTable 的 rect），同一个精灵在父级叫 `1460_3` 96×64、子级叫 `1460_2` 192×128，
+ *    排布完全不同。拿父级的 rect 去套子级像素必然整张错位 —— 这是曾经踩过的坑。
+ * 2. `requestNames.length === 1 && requestNames[0] === 自身 id` → `isLeaf = false` → **整张替换**；
+ *    否则是 leaf → 逐精灵贴进图集（那条路要解析多精灵容器，见 HANDOFF）。
+ *
+ * 本模块只负责「整张替换」这一支的判据：替换前后必须是**同一套排布**，否则 rect 全错。
+ *
+ * | 缩略图 | 外部文件 | 长宽比偏差 | 下采样后色差 | 结论 |
+ * |---|---|---|---|---|
+ * | 96×64 | 192×128 | 0.0% | **8.5** | 同一张图，换对了 |
+ * | 108×192 | 204×384 | −5.6% | 43.3 | 不是同一张 |
+ * | 96×192 | 192×128 | +200% | 63.4 | 根本不是这张 |
+ *
+ * 判据（三条全过才允许换）：
+ *   1. 长宽比偏差 ≤ 2%
+ *   2. 两轴必须是**同一个整数倍**（`subTexInfos` 的像素 offset 要能精确换算，见 rectScale）
+ *   3. 面积平均缩到缩略图尺寸后，不透明区域 RGB 平均绝对误差 ≤ 24/255
+ * 纯色/全透明图集无法判定，一律不换（宁可不换，不能换错）。
+ */
+
+import DXTTextureDecode from './DXTTextureDecode.js';
+import { dxtPixelFormatOf, resolveTextureKind } from './TextureFormat.js';
+
+export interface AtlasPixels {
+  width: number;
+  height: number;
+  data: Uint8Array;
+  /** 文件里声明的格式；DXT 族的真实块格式以 compressType 为准（pf 常是 13/ABGR 的错标签） */
+  compressType: number;
+  pixelFormat: number;
+}
+
+export interface UpgradeVerdict {
+  ok: boolean;
+  reason: 'ok' | 'aspect' | 'scale' | 'content' | 'undecodable' | 'empty';
+  /** |hi.aspect / lo.aspect - 1|，0 表示完全等比 */
+  aspectDelta: number;
+  /** 等比倍数（hi / lo）。只有 ok 时才保证是**整数**且两轴相同 */
+  scale: number;
+  /** 不透明区域 RGB 的平均绝对误差（0..255）；无法比较时为 NaN */
+  meanAbsError: number;
+}
+
+export const DEFAULT_MAX_ASPECT_DELTA = 0.02;
+export const DEFAULT_MAX_MEAN_ERROR = 24;
+
+/**
+ * 解成 RGBA。**不翻行**：比较双方都用同一套方向，翻不翻不影响结论。
+ * 非 DXT / 解不出来返回 null。
+ */
+function decodeRgba(tex: AtlasPixels): Uint8Array | null {
+  if (!tex.data?.length || !tex.width || !tex.height) return null;
+  // 已经是 RGBA（AtlasPack 拼图、或某些服务端直接给 RGBA 的 .texblock）
+  const need = tex.width * tex.height * 4;
+  if (tex.compressType === 0 && tex.pixelFormat === 28 && tex.data.length >= need) {
+    return tex.data.subarray(0, need);
+  }
+  const kind = resolveTextureKind(tex.compressType, tex.pixelFormat);
+  if (!kind.startsWith('dxt')) return null;
+  const out = new Uint8Array(tex.width * tex.height * 4);
+  try {
+    DXTTextureDecode.decode(out, tex.width, tex.height, tex.data, dxtPixelFormatOf(kind as 'dxt1'));
+  } catch {
+    return null;
+  }
+  return out;
+}
+
+/** 面积平均缩小到 dw×dh（最近邻会在比较时引入大量假误差，必须用面积平均） */
+export function boxDownsample(
+  src: Uint8Array,
+  sw: number,
+  sh: number,
+  dw: number,
+  dh: number
+): Uint8Array {
+  const out = new Uint8Array(dw * dh * 4);
+  for (let ty = 0; ty < dh; ty++) {
+    const y0 = (ty * sh) / dh;
+    const y1 = ((ty + 1) * sh) / dh;
+    for (let tx = 0; tx < dw; tx++) {
+      const x0 = (tx * sw) / dw;
+      const x1 = ((tx + 1) * sw) / dw;
+      let r = 0, g = 0, b = 0, a = 0, n = 0;
+      for (let y = Math.floor(y0); y < Math.ceil(y1); y++) {
+        for (let x = Math.floor(x0); x < Math.ceil(x1); x++) {
+          const cx = Math.min(sw - 1, x);
+          const cy = Math.min(sh - 1, y);
+          const o = (cy * sw + cx) * 4;
+          r += src[o]!;
+          g += src[o + 1]!;
+          b += src[o + 2]!;
+          a += src[o + 3]!;
+          n++;
+        }
+      }
+      const o = (ty * dw + tx) * 4;
+      out[o] = r / n;
+      out[o + 1] = g / n;
+      out[o + 2] = b / n;
+      out[o + 3] = a / n;
+    }
+  }
+  return out;
+}
+
+/**
+ * 判断 `hi` 是否可以顶替 `lo`。
+ *
+ * @param lo 块内嵌的缩略图（`subTexInfos` 的坐标就是按它算的）
+ * @param hi `.texblock` 里解析出来的高清图
+ */
+export function evaluateAtlasUpgrade(
+  lo: AtlasPixels,
+  hi: AtlasPixels,
+  opts: { maxAspectDelta?: number; maxMeanError?: number } = {}
+): UpgradeVerdict {
+  const maxAspect = opts.maxAspectDelta ?? DEFAULT_MAX_ASPECT_DELTA;
+  const maxErr = opts.maxMeanError ?? DEFAULT_MAX_MEAN_ERROR;
+
+  const loAspect = lo.width / lo.height;
+  const hiAspect = hi.width / hi.height;
+  const aspectDelta = Math.abs(hiAspect / loAspect - 1);
+  const scale = hi.width / lo.width;
+  const scaleY = hi.height / lo.height;
+  const fail = (reason: UpgradeVerdict['reason']): UpgradeVerdict => ({
+    ok: false,
+    reason,
+    aspectDelta,
+    scale,
+    meanAbsError: NaN,
+  });
+
+  if (!Number.isFinite(aspectDelta)) return fail('aspect');
+  if (aspectDelta > maxAspect) return fail('aspect');
+  // 高清版必须真的更大，否则换了没意义
+  if (hi.width * hi.height <= lo.width * lo.height) return fail('content');
+  // ★ 必须**整数等比**：subTexInfos 的 offset/width 是缩略图像素坐标，换图后要按倍数
+  //   精确换算（见 S3MBlockTexture.rectScale）。非整数倍会让 rect 落到半个纹素上，
+  //   平铺时逐格漂移 —— 宁可不换。
+  if (scale !== scaleY || !Number.isInteger(scale)) return fail('scale');
+
+  const loPx = decodeRgba(lo);
+  const hiPx = decodeRgba(hi);
+  if (!loPx || !hiPx) return fail('undecodable');
+
+  const down = boxDownsample(hiPx, hi.width, hi.height, lo.width, lo.height);
+  let err = 0;
+  let n = 0;
+  for (let i = 0; i < lo.width * lo.height; i++) {
+    // 只比不透明区域：透明填充的色值没有意义
+    if (loPx[i * 4 + 3]! < 8) continue;
+    for (let c = 0; c < 3; c++) err += Math.abs(loPx[i * 4 + c]! - down[i * 4 + c]!);
+    n += 3;
+  }
+  if (n === 0) return fail('empty');
+
+  const meanAbsError = err / n;
+  return {
+    ok: meanAbsError <= maxErr,
+    reason: meanAbsError <= maxErr ? 'ok' : 'content',
+    aspectDelta,
+    scale,
+    meanAbsError,
+  };
+}

package/src/core/DXTTextureDecode.ts

@@ -218,8 +218,10 @@ function DecompressImage(rgba: Uint8Array, width: number, height: number, blocks
           const sx = x + px;
           const sy = y + py;
           if (sx < width && sy < height) {
-            // flip Y
-            let nBegin = 4 * (width * (height - sy) + sx);
+            // flip Y：squish 的原式是 height - 1 - sy。写成 height - sy 会让 sy = 0
+            // 落到 row = height 越界（TypedArray 越界写是静默丢弃），于是缓冲区第 0 行
+            // 永远是全 0（透明黑），其余行整体错位一行。
+            let nBegin = 4 * (width * (height - 1 - sy) + sx);
 
             for (let i = 0; i < 4; ++i) rgba[nBegin++] = targetRgba[nOffsetTarget++];
           } else {
@@ -245,11 +247,31 @@ const DXTTextureDecode = {
   decode(out: Uint8Array, width: number, height: number, block: Uint8Array, format: number): void {
     if (out == null || block == null || height === 0 || width === 0) return;
 
-    // 有 alpha 通道 → RGBA，否则走 rgb565
-    // S3MPixelFormat.BGR -> 11 / LUMINANCE_ALPHA -> 5
-    const flags = format > 11 || format === 5 ? kDxt5 : kDxt1 | krgb565;
+    // 块大小与 alpha 编码只由压缩格式决定：DXT1 = 8 B/块，DXT3/4/5 = 16 B/块。
+    //
+    // 不能再靠「format > 11」判有没有 alpha：S3MPixelFormat 里 DXT1 = 17 也 > 11，
+    // 那样会把 DXT1 当 16 字节块读——512×512 的 DXT1 实际只有 131072 B（0.5 B/px），
+    // 按 16 字节块要 262144 B，正好差一倍，越界部分解成全 0。
+    // 官方 JS 那个判断是在「无 alpha 时纹理标成 RGB(10)/BGR(11)」的前提下才成立。
+    let flags: number;
+    switch (format) {
+      case 17: // DXT1
+        flags = kDxt1;
+        break;
+      case 18:
+      case 19: // DXT3
+        flags = kDxt3;
+        break;
+      case 20: // DXT4
+      case 21: // DXT5
+        flags = kDxt5;
+        break;
+      default:
+        // 老数据只在 RGB / BGR / LUMINANCE_ALPHA 里出现：无 alpha 时走 DXT1 + rgb565 快路径
+        flags = format > 11 || format === 5 ? kDxt5 : kDxt1 | krgb565;
+    }
 
-    if (flags & kDxt1 && flags & krgb565) {
+    if ((flags & kDxt1) !== 0 && (flags & krgb565) !== 0) {
       DecompressImage565(asU16(out), width, height, asU16(block));
     } else {
       DecompressImage(out, width, height, block, flags);