s3m-three 0.4.25 → 0.4.26

package/docs/API.md

@@ -177,6 +177,7 @@ new S3MViewer(options?: S3MViewerOptions)
 | `maxImageCache` | `number` | `128` | 纹理缓存条数上限。一条 = 一张已解码的瓦片纹理，1024² RGBA 约 4MB，128 条即约 512MB 显存；低端设备 32~48。LRU，降下来下次淘汰时释放 |
 | `materialQuality` | `'pbr' \| 'lambert'` | `'pbr'` | 光照模型。`lambert` 用 `MeshLambertMaterial` 替换 PBR，去掉 GGX 与环境球谐，片元约省一半；白模 / 纯色 / 按高度着色几乎无差。**图层级**：同页多个图层各用各的，互不覆盖；不传则跟随模块级默认（`setMaterialQuality`）。只影响之后创建的材质 |
 | `colorPipeline` | `'linear' \| 'direct'` | `'linear'` | 颜色管线。`direct` = 官方 iClient3D 的 sRGB 直乘（同时关掉纹理解码），`lightingPreset: 'supermap'` 会选它。**图层级**：同页多图层各用各的；已加载瓦片可运行时 `setColorPipeline(q, { duration })` 走 fade-through 平滑切过去（重建材质 + 重传纹理，不重下瓦片） |
+| `motionBlur` | `{ mode?: 'afterimage' \| 'velocity'; damp?: number \| 'auto'; maxOffset?: number }` | 不传 = 关闭 | 可选的运动模糊后处理（**默认关闭**，不传时渲染路径与旧版逐字一致）。低端 / 移动设备低帧率下，用帧间残影在感知层面填补卡顿与边缘闪烁。`afterimage`（缺省）= 当前帧 + 上一帧全屏混合，几乎零边际 GPU 成本；`velocity` = 按上一帧 ↔ 当前帧相机矩阵逐像素反推屏幕速度、沿速度方向 8 tap 采样（方向感知，只覆盖相机运动）。`damp` 为拖尾长度（仅 afterimage），`'auto'`（缺省）按实时 FPS 收敛（`0.55^(fps/60)` 封顶 0.92），数值钳 [0, 0.98]；`maxOffset` 为拖影上限（仅 velocity），速度向量的最大屏幕偏移按绘图缓冲宽度的百分比计，缺省 `0.05`，数值钳 [0, 1]。运行时 `setMotionBlur(null)` 关闭并释放 RT。仅 WebGL2（WebGL1 静默回退直渲）；已知限制：拖影只在当前帧几何覆盖范围内（合成 quad 依赖本帧深度保住遮挡正确性）；RT 用 HalfFloatType 存线性值（高光不被 clamp，代价是三张全屏纹理显存 ×2） |
 | `buildTile` | `BuildTileFn \| null` | — | 自定义瓦片构建器（测试 / 服务端渲染时注入） |
 | `attributes` | `AttributeQueryOptions` | — | 可选的 iServer 数据服务配置，配了才能用 `colorByField()` 等便利方法；不配就自己取数 + `setFeaturesStyle()`，见[业务字段](#业务字段锚点在库内对应关系在外部) |
 | `onRequestRepaint` | `() => void` | — | 宿主请求重画的信号：纯 three 宿主接自己的渲染循环 |
@@ -526,6 +527,8 @@ readonly anisotropyCap: number
 setMaxTextureSize(n: number): void            // Infinity = 不限制（默认）
 readonly maxTextureSize: number
 readonly maxImageCache: number
+setMotionBlur(cfg: MotionBlurOptions | null): void  // 运行时开关运动模糊；null = 关闭并释放 RT 显存
+readonly motionBlur: MotionBlurOptions | null       // 当前配置（归一化后的副本）
 readonly stats: Stats
 readonly fps: number
 getBounds(): [[number, number], [number, number]] | null  // 合并经纬度范围
@@ -1366,9 +1369,9 @@ bun run test:meshopt
 
 **这两条 GS 流的量化格式还没标定**（4 字节 / 点，既不像 3 个 float，也不像明显四元数），所以渲染层目前只是把它们带到顶点属性上备用，没有接进真正的 splat 着色器。
 
-### Draco 点云几何
+### Draco 几何（点云与三角网格）
 
-v3.01 的点云数据还有一条 Draco 压缩分支（骨架 tag = `DRACO`）。接法与 MeshOpt 相同：内联 wasm 解码器（约 266KB）只在真的遇到时动态 `import`，解码后并入同一套 attribute 组装，点云按 `primitiveType = 1` 交给 `THREE.Points`，分类码 / 强度 / 权重三种自定义属性一并解出来。
+v3.01 支持 Draco 压缩分支（骨架 tag = `DRACO`），涵盖点云与三角网格（`TRIANGULAR_MESH`）。接法与 MeshOpt 相同：内联 wasm 解码器（约 266KB）只在遇到时动态 `import`，解码后并入同一套 attribute 组装：点云按 `primitiveType = 1` 交给 `THREE.Points`（分类码/强度/权重一并解出）；三角网格按面解出顶点索引与法线，按 `primitiveType = 4` 交给 `THREE.Mesh`。遇到未知几何类型自动 warn 降级并跳过，避免整层崩溃。
 
 **这个分支的字段顺序与规范描述对不上，是从真实瓦片逐字节标定的**（偏移以骨架 tag 字段之后为 0）：
 
@@ -1404,16 +1407,25 @@ ts.update([0, 0, 500], 0.64, 900); // 相机在局部 ENU 的位置
 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`。
+数据源名可以是中文（如 `寿宁阁`），`new URL()` 会自动百分号编码；后缀只能写 `config`，写 `config.xml` 会 406。只给到 `…/realspace/datas` 时拿到的是一个资源清单数组，`JSON.parse` 不报错但没有 `position` / `rootTiles`，表现为「视角跳到 (0,0) + 一句缺少 root tile」——先用 `…/datas.json` 列出数据源，再逐个拼 `/config`。这类报错会带上 config 的类型标记（`FileExtentName` / `Type` / `fileType` / `dataType`），便于区分「清单当配置」和「桌面导出漏瓦片清单」两种病因。
 
-配套导出的三个纯函数，方便自建数据集列表与做体检：
+混合服务（模型 + 地形 + 影像共存）里还有第三种触发面：地形/影像数据集的 config 也是 XML，但**没有瓦片清单**。`init` 会按类型标记提前拒绝并说明病因（见 [FORMAT-NOTES 第二章](./FORMAT-NOTES.md#二先判断是哪一种数据)），不再落到「缺少 root tile」：
+
+```
+Error: 数据集 beijingdem 是地形缓存（FileExtentName=Terrainz），本层仅支持模型类 S3M 数据集
+```
+
+配套导出的五个纯函数，方便自建数据集列表与做体检：
 
 ```ts
-parseConfigText(text)      // JSON 与 SuperMapCache XML 两种配置统一成同一种形状（含 fileType）
+parseConfigText(text)      // JSON 与 SuperMapCache XML 两种配置统一成同一种形状（含 fileType / fileExtentName / cacheType）
+classifyDatasetKind(config) // → 'model' | 'terrain' | 'imagery'；只有认出确凿的非模型标记才判 terrain / imagery
 usableGeoBounds(bounds)    // 判断 geoBounds 是否真的可用；不可用返回 null（见「锚点」）
 fixPathEncoding(url)       // 补路径里没编码但服务端会改写的字符：+ → %2B、空格 → %20
 ```
 
+`classifyDatasetKind` 的判别字段来自实测：地形 = `FileExtentName=Terrainz`；影像 = `Type=Image`（影像的 `FileExtentName` 是 `jpg_png` 这类扩展名样式，不可靠）。认不出标记的一律返回 `'model'`，保证行为与旧版一致；`init` 对非模型数据集抛出的错误上带 `datasetKind` 属性，数据集列表 UI 可以据此标注或跳过。
+
 `fixPathEncoding` 这条是硬需求：OSGB 转出来的瓦片名就是 `Tile_+002_+001`，而 iServer 按 `URLDecoder` 解路径，未编码的 `+` 会变成空格 → 404「瓦片数据不存在」。`new URL()` 认为 `+` 在 path 里合法，不会替我们编码，所以拼完 URL 必须补这一刀（query 里的 `+` 不动，那本来就是空格约定）。
 
 失败处理分两类：**网络类**错误退避重试（`maxRetries`，默认 2 次）；**格式类**错误（`e.permanent === true`，例如 S3M 1.x 容器）直接判失败不重试，并且整棵瓦片树里同类错误只回调一次 `onError`，避免几十块瓦片刷同样的日志。
@@ -1441,6 +1453,7 @@ buildAttributes({ smid, box, triangles, floorHeight })  // → S3MFeatureAttribu
 | `maxTextureSize` | 纹理长边像素上限，默认不限制。手机上 1024 即可，显存降到 1/4 |
 | `maxImageCache` | 纹理缓存条数，默认 128。低端机 32~48，和 `maxTextureSize` 一起管显存 |
 | `materialQuality: 'lambert'` | 换成 Lambert 光照，片元约省一半。白模 / 按高度配色看不出差别，贴图模式会略平。图层级设置，同页其它图层不受影响 |
+| `motionBlur: { mode: 'afterimage' }` | 运动模糊后处理（默认关闭）。低端机低帧率下用帧间残影填卡顿：`afterimage` 每帧只多两次全屏混合，`damp: 'auto'` 按实时 FPS 自适应拖尾长度。建议与上面的预算开关搭配用。注意 RT 为 HalfFloat（半精度浮点，显存 / 带宽 ×2），显存极度吃紧时权衡是否开启 |
 | `maxImageCache` | 原始图集与 leaf 段图像记录的 LRU 缓存容量上限（默认 128），超限自动淘汰旧缓存，防止漫游时内存不断累积 |
 | 纹理引用计数 | 瓦片淘汰时按引用计数释放未被其他瓦片复用的 `Texture` 并调用 `dispose()`，真正归还 GPU 显存 |
 | 几何/材质深度释放 | 瓦片注销时深度遍历对象树，彻底释放 `Mesh`、`Points`（点云/高斯泼溅）以及 `LineSegments`（棱线包）的 `BufferGeometry` 与材质 |

package/docs/FORMAT-NOTES.md

@@ -33,6 +33,16 @@ C 级的处置原则：**只在新样本进来时提高级别，不靠推理提
 | SuperMapCache / S3M 1.x | **XML**（`<SuperMapCache>`，`sml:FileType = OSGBFile`） | `.s3m`（整棵 LOD 树同一种容器） | `S3M1Parser` |
 | 高斯泼溅 | JSON，`dataType = "3DGaussianSplatting"` | `.s3mb` v3.01 + MeshOpt，**无索引包** | `S3MBParser` + `MeshOpt` |
 
+还有第四种撞法（issue #7）：**容器形态识别对了（XML），但内容不是模型**。混合服务（模型 + 地形 + 影像共存，iServer / supermapol 上很常见）里地形/影像数据集的 config 也是 SuperMapCache XML，只是按 `Level0Width/Level0Height + Levels` 的金字塔寻址、**没有瓦片清单**。实测判别字段（3D-OlympicGreen_Plan，2026-10-30）：
+
+| 数据集 | config 根节点 | 判别字段 |
+|:---|:---|:---|
+| `beijingdem`（地形） | `<SuperMapCache>` | `sml:FileExtentName = Terrainz` |
+| `beijingimg`（影像） | `<SuperMapCache_Unicode>` | `sml:Type = Image`（它的 FileExtentName 是 `jpg_png` 这种扩展名样式，**不可靠**） |
+| `Building` 等（模型） | `<SuperMapCache>` | `sml:FileType = OSGBFile / OSGBCacheFile`，无 FileExtentName / Type |
+
+`classifyDatasetKind(config)` 按上表识别，认出地形/影像时 `S3MTileset.init` 会在解析锚点之前明确报错（错误带 `datasetKind` 属性），不再落到误导性的「配置中缺少 root tile」。
+
 **S3M 1.x 必须靠魔数分流，不能靠配置。** 头 4 字节 `73 33 6D 00`（`"s3m\0"`）紧接 `78 da` 的 zlib。不分流的话，头 4 字节会被 float32 读成 1e-38 的「版本号」，再把 zlib 头当长度，报出来的是 `RangeError: Invalid typed array length` —— 一个彻底误导人的错。
 
 ---

package/package.json

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

package/src/core/CustomAttributes.ts

@@ -0,0 +1,53 @@
+import type { VertexAttribute, VertexPackage } from './types.js';
+
+/**
+ * 根据 descript（来自瓦片内嵌或 config.json 的 vertexAttributeDescript）
+ * 将 custom 扩展属性槽（如 custom0, custom1...）重命名为实际的语义名（如 VertexWeight, TextureCoordMatrix）。
+ */
+export function applyCustomAttributeSemantics(
+  vp: VertexPackage,
+  extAttrs?: VertexAttribute[],
+  configDescript?: unknown
+): void {
+  const attrsToRemap = extAttrs ?? vp.vertexAttributes.filter((a) => a.semantic.startsWith('custom'));
+  if (attrsToRemap.length === 0) return;
+
+  const descript = vp.customVertexAttribute ?? configDescript;
+
+  for (let i = 0; i < attrsToRemap.length; i++) {
+    const attr = attrsToRemap[i]!;
+    if (!attr.semantic.startsWith('custom')) continue;
+    const slotMatch = attr.semantic.match(/^custom(\d+)$/);
+    const slot = slotMatch ? parseInt(slotMatch[1]!, 10) : i;
+
+    let category: string | undefined;
+
+    const resolveCategory = (source: unknown): string | undefined => {
+      if (!source || typeof source !== 'object') return undefined;
+      if (Array.isArray(source)) {
+        const item = source[slot];
+        if (typeof item === 'string') return item;
+        if (item && typeof item === 'object' && typeof item.category === 'string') return item.category;
+        return undefined;
+      }
+      for (const [k, v] of Object.entries(source as Record<string, unknown>)) {
+        if (v === slot) return k;
+      }
+      return undefined;
+    };
+
+    category = resolveCategory(descript);
+    if (!category && configDescript && configDescript !== descript) {
+      category = resolveCategory(configDescript);
+    }
+
+    if (category) {
+      delete vp.attrLocation[attr.semantic];
+      delete vp.attrLocation[`a${attr.semantic}`];
+      attr.semantic = category;
+      const idx = vp.vertexAttributes.indexOf(attr);
+      vp.attrLocation[category] = idx;
+      vp.attrLocation[`a${category}`] = idx;
+    }
+  }
+}

package/src/core/Draco.ts

@@ -1,4 +1,4 @@
-/**
+/**
  * S3M v3 Draco 几何压缩（Skeleton 的 Draco 分支）
  *
  * 与 MeshOpt 一样，这里的布局不是照规范写的 —— 规范里的 Draco 分支描述和实际数据
@@ -33,7 +33,7 @@
  */
 import type { BinaryReader } from './BinaryReader.js';
 import type { AttrDType, IndexPackage, VertexPackage } from './types.js';
-import type { DracoModule, DracoPointAttribute, DracoPointCloud } from '../vendor/draco_decoder.module.js';
+import type { DracoMesh, DracoModule, DracoPointAttribute, DracoPointCloud } from '../vendor/draco_decoder.module.js';
 
 /* ------------------------------------------------------------ draco 枚举（本地副本） */
 
@@ -57,6 +57,9 @@ const DRACO_MAGIC = 'DRACO';
 /** primitiveType = 1：点云包（渲染层据此走 THREE.Points） */
 const POINT_PRIMITIVE = 1;
 
+/** primitiveType = 4：三角网格包（渲染层据此走 THREE.Mesh，对应 gl.TRIANGLES） */
+const TRIANGLE_PRIMITIVE = 4;
+
 /** 单个 skeleton 的点数上限，防头读错时开出天文数字的缓冲 */
 const MAX_POINTS = 64 * 1024 * 1024;
 
@@ -243,13 +246,27 @@ export async function parseDracoGeometry(r: BinaryReader, vp: VertexPackage): Pr
   /* ---- 2. 解码 ---- */
 
   const decoder = new draco.Decoder();
+  const geomType = decoder.GetEncodedGeometryType(data);
+
+  if (geomType === GEOM_TRIANGULAR_MESH) {
+    // 三角网格分支：draco mesh 内部自带面索引，不需要容器里的 IndexPackage
+    // 官方 S3ModelParser 对 Draco 分支的索引包解析阶段是空操作（see Issue #5）
+    const mesh = new draco.Mesh();
+    try {
+      return decodeDracoMesh(draco, decoder, mesh, data, vp, posUniqueId, normalUniqueId, colorUniqueId);
+    } finally {
+      try { draco.destroy(decoder); draco.destroy(mesh); } catch { /* ignore */ }
+    }
+  }
+
+  // 点云分支（GEOM_POINT_CLOUD）或其他未知类型
   const geometry = new draco.PointCloud();
   try {
-    const geomType = decoder.GetEncodedGeometryType(data);
     if (geomType !== GEOM_POINT_CLOUD) {
-      throw new Error(
-        `[s3m] Draco ${geomType === GEOM_TRIANGULAR_MESH ? '三角网格' : '未知'} 几何暂未实现（仅支持点云）`
-      );
+      // 未知几何类型：warn 并降级为空包，避免整层崩溃
+      console.warn(`[s3m] Draco 未知几何类型 ${geomType}，跳过该骨架`);
+      vp.verticesCount = 0;
+      return [pointPack()];
     }
 
     const status = decoder.DecodeArrayToPointCloud(data, data.length, geometry);
@@ -373,6 +390,151 @@ function pointPack(): IndexPackage {
   };
 }
 
+/**
+ * 解码 Draco TRIANGULAR_MESH 几何体，填充 VertexPackage 并返回带索引的 IndexPackage。
+ *
+ * 按官方 S3MDracoDecode.js 逻辑（Issue #5 调研）：
+ *   - DecodeArrayToMesh → num_faces → 逐面 GetFaceFromMesh → 填入索引缓冲
+ *   - primitiveType = TRIANGLE_PRIMITIVE（4），让渲染层走 THREE.Mesh
+ *   - 容器头（posUniqueId/normalUniqueId/colorUniqueId）与点云共用，直接复用属性装配代码
+ *
+ * 调用方负责 destroy(decoder) 和 destroy(mesh)。
+ */
+function decodeDracoMesh(
+  draco: DracoModule,
+  decoder: InstanceType<DracoModule['Decoder']>,
+  mesh: DracoMesh,
+  data: Uint8Array,
+  vp: VertexPackage,
+  posUniqueId: number,
+  normalUniqueId: number,
+  colorUniqueId: number,
+): IndexPackage[] {
+  const status = decoder.DecodeArrayToMesh(data, data.length, mesh);
+  if (!status.ok()) throw new Error(`[s3m] Draco mesh 解码失败：${status.error_msg()}`);
+
+  const numPoints = mesh.num_points();
+  if (!Number.isInteger(numPoints) || numPoints < 0 || numPoints > MAX_POINTS) {
+    throw new Error(`[s3m] Draco mesh 顶点数异常：${numPoints}`);
+  }
+  const numFaces = mesh.num_faces();
+
+  if (numPoints === 0 || numFaces === 0) {
+    vp.verticesCount = 0;
+    return [meshPack(new Uint8Array(0), 0, 0)];
+  }
+
+  /* ---- 属性装配（与点云分支共用逻辑，但三角网格有法线） ---- */
+
+  for (let i = 0; i < mesh.num_attributes(); i++) {
+    const attr = decoder.GetAttribute(mesh, i);
+    const uid = attr.unique_id();
+    const comps = Math.max(1, attr.num_components());
+
+    if (uid === posUniqueId || attr.attribute_type() === ATTR_POSITION) {
+      if (attr.data_type() !== DT_FLOAT32) {
+        throw new Error(`[s3m] Draco mesh 位置属性不是 float32（dt=${attr.data_type()}）`);
+      }
+      const raw = readAttribute(draco, decoder, mesh, attr) as Float32Array | null;
+      if (!raw) throw new Error('[s3m] Draco mesh 位置属性读取失败');
+      const out = new Float32Array(numPoints * 3);
+      for (let p = 0; p < numPoints; p++) {
+        out[p * 3] = raw[p * comps] ?? 0;
+        out[p * 3 + 1] = raw[p * comps + 1] ?? 0;
+        out[p * 3 + 2] = raw[p * comps + 2] ?? 0;
+      }
+      pushAttr(vp, 'position', new Uint8Array(out.buffer), 3, 12, 0, undefined, 'f32');
+      continue;
+    }
+
+    if (uid === normalUniqueId || attr.attribute_type() === ATTR_NORMAL) {
+      if (attr.data_type() === DT_FLOAT32) {
+        const raw = readAttribute(draco, decoder, mesh, attr) as Float32Array | null;
+        if (raw) {
+          // 法线量化由 draco 解码时自动还原为 float32
+          const out = new Float32Array(numPoints * 3);
+          for (let p = 0; p < numPoints; p++) {
+            out[p * 3] = raw[p * comps] ?? 0;
+            out[p * 3 + 1] = raw[p * comps + 1] ?? 0;
+            out[p * 3 + 2] = raw[p * comps + 2] ?? 0;
+          }
+          pushAttr(vp, 'normal', new Uint8Array(out.buffer), 3, 12, 0, undefined, 'f32');
+        }
+      }
+      continue;
+    }
+
+    if (uid === colorUniqueId || attr.attribute_type() === ATTR_COLOR) {
+      const raw = readAttribute(draco, decoder, mesh, attr);
+      if (raw) {
+        const out = new Uint8Array(numPoints * 4);
+        const isFloat = raw instanceof Float32Array;
+        for (let p = 0; p < numPoints; p++) {
+          const o = p * comps;
+          if (isFloat) {
+            out[p * 4] = clamp255(raw[o] ?? 1);
+            out[p * 4 + 1] = clamp255(raw[o + 1] ?? 1);
+            out[p * 4 + 2] = clamp255(raw[o + 2] ?? 1);
+          } else {
+            out[p * 4] = raw[o] ?? 255;
+            out[p * 4 + 1] = raw[o + 1] ?? 255;
+            out[p * 4 + 2] = raw[o + 2] ?? 255;
+          }
+          out[p * 4 + 3] = comps >= 4 && !isFloat ? (raw[o + 3] ?? 255) : 255;
+        }
+        pushAttr(vp, 'color', out, 4, 4, 0, undefined, 'u8');
+      }
+      continue;
+    }
+    // 其余属性（texCoord 等）：暂不处理，等真实瓦片来后按需补齐
+  }
+
+  if (vp.attrLocation.position === undefined) {
+    throw new Error('[s3m] Draco mesh 缺少 position 属性');
+  }
+
+  vp.verticesCount = numPoints;
+
+  /* ---- 三角面索引构建（按官方逻辑：numPoints <= 65535 用 U16，否则 U32） ---- */
+  const useU16 = numPoints <= 65535;
+  const indices = useU16
+    ? new Uint16Array(numFaces * 3)
+    : new Uint32Array(numFaces * 3);
+
+  const face = new draco.DracoInt32Array();
+  try {
+    let n = 0;
+    for (let f = 0; f < numFaces; f++) {
+      decoder.GetFaceFromMesh(mesh, f, face);
+      indices[n++] = face.GetValue(0);
+      indices[n++] = face.GetValue(1);
+      indices[n++] = face.GetValue(2);
+    }
+  } finally {
+    draco.destroy(face);
+  }
+
+  return [meshPack(new Uint8Array(indices.buffer), numFaces * 3, useU16 ? 0 : 1)];
+}
+
+/**
+ * 三角网格索引包。
+ *
+ * @param indicesBytes - Uint16Array 或 Uint32Array 的字节视图
+ * @param indexCount   - 索引总数（numFaces × 3）
+ * @param indexType    - 0 = Uint16, 1 = Uint32（与 IndexPackage.indexType 约定一致）
+ */
+function meshPack(indicesBytes: Uint8Array, indexCount: number, indexType: number): IndexPackage {
+  return {
+    indexCount,
+    indexType,
+    useIndex: 1,
+    primitiveType: TRIANGLE_PRIMITIVE,
+    indices: indexCount > 0 ? indicesBytes : null,
+    passNames: [],
+  };
+}
+
 function pushAttr(
   vp: VertexPackage,
   semantic: string,

package/src/core/MeshOpt.ts

@@ -18,6 +18,7 @@
 import type { BinaryReader } from './BinaryReader.js';
 import type { IndexPackage, VertexAttribute, VertexPackage } from './types.js';
 import type { MeshoptDecoder } from '../vendor/meshopt_decoder.module.js';
+import { applyCustomAttributeSemantics } from './CustomAttributes.js';
 
 /** 顶点语义是位标记，不是枚举序号 */
 export const MeshOptSemantic = {
@@ -451,6 +452,7 @@ export async function parseMeshOptGeometry(
   for (let i = 0; i < vp.vertexAttributes.length; i++) {
     vp.attrLocation[`a${vp.vertexAttributes[i].semantic}`] = i;
   }
+  applyCustomAttributeSemantics(vp);
 
   return { info, indexPackages };
 }

package/src/core/S3M1Parser.ts

@@ -225,14 +225,45 @@ interface MeshRecord {
   position: Float32Array;
   uv: Float32Array;
   indexCount: number;
-  indices: Uint16Array;
+  indices: Uint16Array | Uint32Array;
+  primitiveType: number;
   materialId: string;
   /** 实例矩阵（每实例 16 float：3×4 行主序 + RGBA），没有实例化时为 undefined */
   instances?: Float32Array;
 }
 
-/** 索引头的第 3 个 dword，全版本固定 */
-const INDEX_HEADER_MARK = 0x00040100;
+/**
+ * 校验 p 偏移处是否为合法的 S3M 1.x 索引头：
+ *   dword[0] = 1 (idxKind)
+ *   dword[1] = indexCount
+ *   dword[2] = mark，按字节小端存储：
+ *     byte 0: indexType (0=u16, 1/3=u32)
+ *     byte 1: useIndex (恒 1)
+ *     byte 2: primitiveType (1=POINTS, 2=LINES, 3=LINE_STRIP, 4=TRIANGLES, 5/6=STRIP/FAN, 13=EDGES)
+ *     byte 3: reserved (恒 0)
+ * 校验紧随其后的索引数据（4 字节对齐）之后，记录尾标记恒为 1。
+ */
+function isValidIndexHeader(view: DataView, p: number): boolean {
+  if (view.getUint32(p, true) !== 1) return false;
+  const count = view.getUint32(p + 4, true);
+  if (count === 0 || count > 10_000_000) return false;
+  const mark = view.getUint32(p + 8, true);
+  const indexType = mark & 0xff;
+  const useIndex = (mark >> 8) & 0xff;
+  const primitiveType = (mark >> 16) & 0xff;
+  const reserved = (mark >> 24) & 0xff;
+  if (useIndex !== 1 || reserved !== 0) return false;
+  if (indexType !== 0 && indexType !== 1 && indexType !== 3) return false;
+  if (![1, 2, 3, 4, 5, 6, 13].includes(primitiveType)) return false;
+  if (primitiveType === 4 && count % 3 !== 0) return false;
+  if (primitiveType === 2 && count % 2 !== 0) return false;
+
+  const wide = indexType === 1 || indexType === 3;
+  const indexBytes = count * (wide ? 4 : 2);
+  const tailOffset = (p + 12 + indexBytes + 3) & ~3;
+  if (tailOffset + 8 > view.byteLength) return false;
+  return view.getUint32(tailOffset, true) === 1;
+}
 
 /**
  * v1 里每个实例记录固定 20 个 float（80 字节）：
@@ -321,11 +352,7 @@ function readInstances(
 function findIndexHeader(view: DataView, from: number): number {
   const limit = view.byteLength - 12;
   for (let p = from; p <= limit; p += 4) {
-    if (view.getUint32(p, true) !== 1) continue;
-    const count = view.getUint32(p + 4, true);
-    if (count === 0 || count % 3 !== 0) continue;
-    if (view.getUint32(p + 8, true) !== INDEX_HEADER_MARK) continue;
-    return p;
+    if (isValidIndexHeader(view, p)) return p;
   }
   return -1;
 }
@@ -389,6 +416,39 @@ function applyQuantBox(position: Float32Array, box: Float32Array): boolean {
   return true;
 }
 
+/**
+ * 从版本 1 属性块中尝试提取 UV 坐标：
+ * 倾斜摄影（OSGB）等数据中，UV 块通常紧贴在索引头前：
+ *   头: [count: u32, dim: u32 = 2]
+ *   数据: V * 8 字节 float32 (u, v)
+ */
+function findV1UV(view: DataView, from: number, to: number, V: number): Float32Array | null {
+  const head = to - V * 8 - 8;
+  if (head >= from && view.getUint32(head, true) === V && view.getUint32(head + 4, true) === 2) {
+    let uv = new Float32Array(V * 2);
+    for (let i = 0; i < V * 2; i++) {
+      uv[i] = view.getFloat32(head + 8 + i * 4, true);
+    }
+    return uv;
+  }
+  for (let p = to - V * 8 - 8; p >= from; p -= 4) {
+    if (view.getUint32(p, true) === V && view.getUint32(p + 4, true) === 2) {
+      let uv = new Float32Array(V * 2);
+      let ok = true;
+      for (let i = 0; i < V * 2; i++) {
+        const val = view.getFloat32(p + 8 + i * 4, true);
+        if (!Number.isFinite(val) || Math.abs(val) > 1e4) {
+          ok = false;
+          break;
+        }
+        uv[i] = val;
+      }
+      if (ok) return uv;
+    }
+  }
+  return null;
+}
+
 function readGeometry(
   br: BinaryReader,
   geoSize: number
@@ -433,7 +493,7 @@ function readGeometry(
       position[i * 3 + 2] = z;
     }
 
-    const uv = new Float32Array(V * 2);
+    let uv = new Float32Array(V * 2);
     let instances: Float32Array | undefined;
     if (v0UvAt16) {
       // 版本 0：UV 数组头 [0,0,0,kind=1,count=V,flag=2]
@@ -456,7 +516,12 @@ function readGeometry(
         throw new Error(`[s3m] S3M 1.x 属性段无法定位索引头：网格 ${geoName}（偏移 ${br.offset}/${geoSize}）`);
       }
       if (at !== br.offset) {
-        skippedAttrs++;
+        const foundUv = findV1UV(br.view, br.offset, at, V);
+        if (foundUv) {
+          uv = foundUv;
+        } else {
+          skippedAttrs++;
+        }
         // 优先认实例化：柱状图是真·实例化的（一份模板 + N 个变换矩阵），
         // 顶点本来就该保持单位盒，靠矩阵摆位/缩放/上色。
         const inst = readInstances(br.view, br.offset, at);
@@ -471,15 +536,29 @@ function readGeometry(
       }
     }
 
-    // 索引头 [1, indexCount, 0x00040100]
+    // 索引头 [1, indexCount, mark]
     const idxKind = br.u32();
     const indexCount = br.u32();
-    br.u32(); // 常量标记
-    if (idxKind !== 1 || indexCount === 0 || indexCount % 3 !== 0) {
-      throw new Error(`[s3m] S3M 1.x 索引头不符：网格 ${geoName} kind=${idxKind} count=${indexCount}`);
+    const mark = br.u32();
+    const indexType = mark & 0xff;
+    const useIndex = (mark >> 8) & 0xff;
+    const primitiveType = (mark >> 16) & 0xff;
+    if (idxKind !== 1 || indexCount === 0 || useIndex !== 1) {
+      throw new Error(`[s3m] S3M 1.x 索引头不符：网格 ${geoName} kind=${idxKind} count=${indexCount} mark=0x${mark.toString(16)}`);
+    }
+    if (primitiveType === 4 && indexCount % 3 !== 0) {
+      throw new Error(`[s3m] S3M 1.x 索引头不符：网格 ${geoName} 三角形索引数 ${indexCount} 非 3 的倍数`);
+    }
+    if (primitiveType === 2 && indexCount % 2 !== 0) {
+      throw new Error(`[s3m] S3M 1.x 索引头不符：网格 ${geoName} 线段索引数 ${indexCount} 非 2 的倍数`);
+    }
+    const wide = indexType === 1 || indexType === 3;
+    const indices = wide ? new Uint32Array(indexCount) : new Uint16Array(indexCount);
+    if (wide) {
+      for (let i = 0; i < indexCount; i++) indices[i] = br.u32();
+    } else {
+      for (let i = 0; i < indexCount; i++) indices[i] = br.u16();
     }
-    const indices = new Uint16Array(indexCount);
-    for (let i = 0; i < indexCount; i++) indices[i] = br.u16();
     if (br.offset > geoSize) throw new Error(`[s3m] S3M 1.x 索引越界：网格 ${geoName}`);
     br.align4();
 
@@ -495,6 +574,7 @@ function readGeometry(
       uv,
       indexCount,
       indices,
+      primitiveType,
       materialId,
       ...(instances ? { instances } : {}),
     });
@@ -511,10 +591,10 @@ function readGeometry(
  */
 export function pixelFormatOfBpp(bpp: number, rawFormat: number): number {
   if (!Number.isFinite(bpp) || bpp <= 0) return rawFormat;
-  if (Math.abs(bpp - 0.5) < 0.02) return 17; // DXT1
-  if (Math.abs(bpp - 1) < 0.02) return 21; // DXT5
-  if (Math.abs(bpp - 4) < 0.02) return 14; // BGRA
-  if (Math.abs(bpp - 3) < 0.02) return 10; // RGB
+  if (Math.abs(bpp - 0.5) < 0.05 || (bpp >= 0.6 && bpp <= 0.75)) return 17; // DXT1（含全 mip 链 ~0.667 B/px）
+  if (Math.abs(bpp - 1) < 0.05 || (bpp >= 1.25 && bpp <= 1.5)) return 21; // DXT5（含全 mip 链 ~1.333~1.44 B/px）
+  if (Math.abs(bpp - 4) < 0.05) return 14; // BGRA
+  if (Math.abs(bpp - 3) < 0.05) return 10; // RGB
   console.warn(`[s3m] S3M 1.x 纹理密度 ${bpp.toFixed(3)} B/px 不在已知档位，按原 format=${rawFormat} 交给上层判定`);
   return rawFormat;
 }
@@ -668,9 +748,9 @@ export async function parseS3M1(arrayBuffer: ArrayBuffer, options: ParseS3M1Opti
     }
     const pack: IndexPackage = {
       indexCount: mesh.indexCount,
-      indexType: 0, // 0 = UNSIGNED_SHORT
+      indexType: mesh.indices instanceof Uint32Array ? 1 : 0,
       useIndex: 1,
-      primitiveType: 4, // TRIANGLES
+      primitiveType: mesh.primitiveType ?? 4,
       indices: new Uint8Array(mesh.indices.buffer, mesh.indices.byteOffset, mesh.indices.byteLength),
       passNames: [mesh.materialId],
     };