s3m-three 0.3.4 → 0.3.6

package/src/core/TextureDecode.ts

@@ -0,0 +1,158 @@
+/**
+ * S3M 纹理解码（three 无关，主线程 / Worker 共用同一份实现）
+ *
+ * 职责到「解出像素数据」为止：DXT 族解块成 RGBA8、CRN 先用 crunch wasm 转码回 DXT
+ * 再解块、WEBP 交给 createImageBitmap、RGB 系逐像素重排。产出是纯数据
+ * （DecodedTextureData），包成 three 对象由渲染层的 TextureFactory 负责——
+ * 这样整份文件可以原样搬进 Worker 跑。
+ *
+ * 该走哪条解码路径由 compressType 判定（见 core/TextureFormat.ts）：
+ * v3.00 的 CRN 纹理 pixelFormat 是 13（ABGR）、行标的 CRN 是 32856（GL_RGBA8），
+ * 都不是 26 / 27，所以判定只能看 compressType，不能看 pixelFormat。
+ */
+import DXTTextureDecode from './DXTTextureDecode.js';
+import { transcodeCRN } from './CRNDecode.js';
+import { dxtPixelFormatOf, resolveTextureKind, PixelFormat } from './TextureFormat.js';
+import type { S3MTexture } from './types.js';
+
+/** 解码产物：rgba 与 bitmap 二选一，都为 null = 解码失败 / 格式不支持 */
+export interface DecodedTextureData {
+  /** 实际走的解码路径（'crn->dxt5' / 'dxt1' / 'raw' / 'webp' / 'crn(failed)' / 'unsupported(...)'） */
+  kind: string;
+  width: number;
+  height: number;
+  /** RGBA8 像素（已按需翻行） */
+  rgba: Uint8Array | null;
+  /** WEBP 路径的解码结果（ImageBitmap 可 transfer，主线程直接 new THREE.Texture 包） */
+  bitmap: ImageBitmap | null;
+  hasAlpha: boolean;
+  /** CRN 转码失败时的原始错误（渲染层负责打 warn） */
+  error?: string;
+}
+
+/** 行序翻转（原地）。S3MBLOCK 图集按 GL 方向存储（v=0 在最后一行），解码后要翻一次行 */
+function flipRows(rgba: Uint8Array, width: number, height: number): void {
+  const row = width * 4;
+  const tmp = new Uint8Array(row);
+  for (let y = 0; y < height >> 1; y++) {
+    const a = y * row;
+    const b = (height - 1 - y) * row;
+    tmp.set(rgba.subarray(a, a + row));
+    rgba.copyWithin(a, b, b + row);
+    rgba.set(tmp, b);
+  }
+}
+
+/** 该像素格式自带 alpha 通道（DXT1 的 1bit alpha 不算，历史上没开过 alphaTest） */
+function hasAlphaChannel(pixelFormat: number): boolean {
+  return (
+    pixelFormat === PixelFormat.DXT3 ||
+    pixelFormat === PixelFormat.DXT4 ||
+    pixelFormat === PixelFormat.DXT5 ||
+    pixelFormat === PixelFormat.ARGB ||
+    pixelFormat === PixelFormat.ABGR ||
+    pixelFormat === PixelFormat.BGRA ||
+    pixelFormat === PixelFormat.RGBA
+  );
+}
+
+/** 解 DXT 到 RGBA8。DXT5 是 1 字节/像素，DXT1 是 0.5 字节/像素。 */
+/** DXT 解码只需要尺寸 / 格式 / 字节，CRN 转码出来的结果也走这条路 */
+function decodeDXT(tex: Pick<S3MTexture, 'width' | 'height' | 'pixelFormat' | 'data' | 'flipY'>): {
+  rgba: Uint8Array;
+  hasAlpha: boolean;
+} {
+  const { width, height, pixelFormat, data } = tex;
+  const out = new Uint8Array(width * height * 4);
+  DXTTextureDecode.decode(out, width, height, data, pixelFormat);
+  if (tex.flipY) flipRows(out, width, height);
+  return { rgba: out, hasAlpha: hasAlphaChannel(pixelFormat) };
+}
+
+function rawRGBA(tex: S3MTexture): { rgba: Uint8Array; hasAlpha: boolean } {
+  const { width, height, pixelFormat, data } = tex;
+  const out = new Uint8Array(width * height * 4);
+  // RGBA / BGRA / ARGB / ABGR 都是 4 字节，前两个是「尾字节是 alpha」，后两个是「首字节是 alpha」
+  const hasAlpha =
+    pixelFormat === PixelFormat.RGBA ||
+    pixelFormat === PixelFormat.BGRA ||
+    pixelFormat === PixelFormat.ARGB ||
+    pixelFormat === PixelFormat.ABGR;
+  const swapRB = pixelFormat === PixelFormat.BGR || pixelFormat === PixelFormat.BGRA;
+  const alphaFirst = pixelFormat === PixelFormat.ARGB || pixelFormat === PixelFormat.ABGR;
+  const src = hasAlpha ? 4 : 3;
+  for (let i = 0, s = 0, d = 0; i < width * height; i++, s += src, d += 4) {
+    const p = alphaFirst ? s + 1 : s;
+    out[d] = swapRB ? data[p + 2] : data[p];
+    out[d + 1] = data[p + 1];
+    out[d + 2] = swapRB ? data[p] : data[p + 2];
+    out[d + 3] = hasAlpha ? data[alphaFirst ? s : s + 3] : 255;
+  }
+  if (tex.flipY) flipRows(out, width, height);
+  return { rgba: out, hasAlpha: hasAlphaChannel(pixelFormat) };
+}
+
+/** 主线程 / Worker 共用的解码入口。不抛错：失败与不支持都体现在返回值里 */
+export async function decodeTextureData(tex: S3MTexture): Promise<DecodedTextureData> {
+  const empty: DecodedTextureData = {
+    kind: 'unsupported(0/0)',
+    width: 0,
+    height: 0,
+    rgba: null,
+    bitmap: null,
+    hasAlpha: false,
+  };
+  if (!tex || !tex.width || !tex.height) return empty;
+
+  const kind = resolveTextureKind(tex.compressType ?? 0, tex.pixelFormat);
+
+  if (kind === 'crn') {
+    try {
+      const crn = await transcodeCRN(tex.data);
+      const decoded = decodeDXT({
+        width: crn.width,
+        height: crn.height,
+        pixelFormat: crn.dxtFormat === 1 ? PixelFormat.DXT1 : PixelFormat.DXT5,
+        data: crn.data,
+      });
+      return {
+        kind: `crn->dxt${crn.dxtFormat}`,
+        width: crn.width,
+        height: crn.height,
+        rgba: decoded.rgba,
+        bitmap: null,
+        hasAlpha: decoded.hasAlpha,
+      };
+    } catch (e) {
+      // 一张纹理坏了不该带崩整个瓦片，如实上报并降级成无贴图
+      return {
+        kind: 'crn(failed)',
+        width: tex.width,
+        height: tex.height,
+        rgba: null,
+        bitmap: null,
+        hasAlpha: false,
+        error: String((e as Error | null)?.message ?? e),
+      };
+    }
+  }
+
+  if (kind === 'dxt1' || kind === 'dxt3' || kind === 'dxt4' || kind === 'dxt5') {
+    const decoded = decodeDXT({ ...tex, pixelFormat: dxtPixelFormatOf(kind) });
+    return { kind, width: tex.width, height: tex.height, rgba: decoded.rgba, bitmap: null, hasAlpha: decoded.hasAlpha };
+  }
+
+  if (kind === 'webp') {
+    const blob = new Blob([tex.data as BlobPart], { type: 'image/webp' });
+    const bitmap = await createImageBitmap(blob);
+    return { kind, width: bitmap.width, height: bitmap.height, rgba: null, bitmap, hasAlpha: true };
+  }
+
+  if (kind === 'raw') {
+    const decoded = rawRGBA(tex);
+    return { kind, width: tex.width, height: tex.height, rgba: decoded.rgba, bitmap: null, hasAlpha: decoded.hasAlpha };
+  }
+
+  // KTX2 / ETC 需要额外解码器，先如实上报而不是静默出错
+  return { ...empty, kind: `unsupported(${tex.compressType}/${tex.pixelFormat})` };
+}

package/src/core/TextureFormat.ts

@@ -18,8 +18,29 @@
  * 真实服务里的 CRN 纹理会被当成未知格式整包丢掉（模型变成无贴图的灰模）。
  */
 
-/** S3M 3.01（行标）compressType 取值 */
-export const TextureCompress = {
+/**
+ * S3M 像素 / 块格式枚举（iClient3D S3MPixelFormat）。
+ *
+ * 原本住在 render/TextureFactory，纹理解码下沉到 core（Worker 复用）后搬到这里；
+ * TextureFactory 保留同名 re-export，对外 API 不变。
+ */
+export const PixelFormat = {
+  RGB: 10,
+  BGR: 11,
+  ARGB: 12,
+  ABGR: 13,
+  BGRA: 14,
+  RGBA: 28,
+  WEBP: 25,
+  DXT1: 17,
+  DXT3: 19,
+  DXT4: 20,
+  DXT5: 21,
+  CRN_DXT5: 26,
+  STANDARD_CRN: 27,
+} as const;
+
+/** S3M 3.01（行标）compressType 取值 */export const TextureCompress = {
   NONE: 0,
   DXT1_RGB: 33776,
   DXT1_RGBA: 33777,

package/src/render/DatasetManager.ts

@@ -31,6 +31,8 @@ export interface S3MDatasetOptions {
   align?: DatasetAlignment;
   /** 垂直高度偏移（米），在 align 对齐基准上的额外偏移，正数抬升，负数下降，默认 0 */
   heightOffset?: number;
+  /** 是否用 Web Worker 解析经典 .s3mb 瓦片（默认开，崩溃自动降级主线程），见 S3MTilesetOptions.useWorker */
+  useWorker?: boolean;
   /**
    * 是否对该数据集生成几何棱线（CPU 端 EdgesGeometry）。
    * - 不填：跟随全局 `style.edges`
@@ -194,6 +196,7 @@ export class DatasetManager {
       maxConcurrent: maxConcurrent,
       lodRangeScale: ds.lodRangeScale ?? defaultLodRangeScale,
       buildTile: buildTile ?? null,
+      useWorker: ds.useWorker,
       uniforms: uniforms,
       onTile: (node) => {
         callbacks.onTile(node, entry);

package/src/render/FeatureStyleManager.ts

@@ -6,7 +6,9 @@
  * 2. 专题图分析（按业务字段分段着色、连续插值着色、字段过滤、高度拉伸）
  * 3. 2 行状态纹理（uBatchTex）的烘焙与 GPU 上传：
  *    - Row 0: [R, G, B, elevation / hidden]
- *    - Row 1: [translationX, translationY, translationZ, reserved]
+ *    - Row 1: [translationX, translationY, translationZ, opacity]
+ *      约定：alpha 0 = 无单体透明覆盖（shader 不乘），(0,1) 开区间为实际透明度，
+ *      opacity <= 0 等价 hidden（走 Row 0 的 -1 隐藏位）
  * 4. 批次冲突审计（auditBatches）
  */
 import * as THREE from 'three';
@@ -26,7 +28,7 @@ export interface FeatureStyle {
   elevation?: number;
   /** 自定义单体三维平移偏移量 [dx, dy, dz]（米） */
   translation?: [number, number, number];
-  /** 自定义单体透明度（0~1） */
+  /** 自定义单体透明度（0~1，batch 粒度；<= 0 等价 hidden，1 / 不传 = 不覆盖） */
   opacity?: number;
   /** 是否隐藏该单体 */
   hidden?: boolean;
@@ -562,6 +564,8 @@ export class FeatureStyleManager {
       if (mat.userData.uBatchTexActive) {
         mat.userData.uBatchTexActive.value = 0;
       }
+      // 单体淡化清除后，把材质 transparent 还原成全局透明度语义
+      if (mat.transparent && mat.opacity >= 0.999) mat.transparent = false;
       return;
     }
 
@@ -569,6 +573,7 @@ export class FeatureStyleManager {
       if (mat.userData.uBatchTexActive) {
         mat.userData.uBatchTexActive.value = 0;
       }
+      if (mat.transparent && mat.opacity >= 0.999) mat.transparent = false;
       return;
     }
 
@@ -611,6 +616,7 @@ export class FeatureStyleManager {
     const colorOfBatch = new Map<number, string>();
     const elevOfBatch = new Map<number, number>();
     const translationOfBatch = new Map<number, [number, number, number]>();
+    const opacityOfBatch = new Map<number, number>();
     const ownersOfBatch = new Map<number, number>();
 
     for (const [smidStr, entry] of Object.entries(pickInfo)) {
@@ -661,6 +667,16 @@ export class FeatureStyleManager {
         continue;
       }
 
+      // 单体独立透明度：<= 0 等价 hidden；(0,1) 写入状态纹理第 2 行 alpha；>= 1 不覆盖
+      const fade = st?.opacity;
+      if (fade != null) {
+        if (fade <= 0) {
+          hiddenBatches.add(bId);
+          continue;
+        }
+        if (fade < 1 && !opacityOfBatch.has(bId)) opacityOfBatch.set(bId, fade);
+      }
+
       const col = st?.color ?? this.thematicColors.get(smid);
       if (col && !colorOfBatch.has(bId)) colorOfBatch.set(bId, col);
 
@@ -704,6 +720,19 @@ export class FeatureStyleManager {
       hasActive = true;
     }
 
+    // 单体独立透明度写在第 2 行 alpha：shader 里 0 = 无覆盖，不会误伤未设置的单体
+    let hasFade = false;
+    for (const [bId, fade] of opacityOfBatch) {
+      if (hiddenBatches.has(bId)) continue;
+      data[(w + bId) * 4 + 3] = fade;
+      hasActive = true;
+      hasFade = true;
+    }
+
+    // 有淡化单体时整块材质要开混合才有透明效果；清除后还原为全局透明度语义
+    if (hasFade && !mat.transparent) mat.transparent = true;
+    else if (!hasFade && mat.transparent && mat.opacity >= 0.999) mat.transparent = false;
+
     let conflicts = 0;
     for (const [bId, owners] of ownersOfBatch) {
       if (owners < 2) continue;

package/src/render/MergeVertices.ts

@@ -0,0 +1,56 @@
+/**
+ * 轻量版顶点焊合（只按位置）
+ *
+ * 为什么不用 three/examples/jsm/utils/BufferGeometryUtils.js 的 mergeVertices：
+ * 1. jsm 子路径导入会在宿主打包器里给 three 制造第二个依赖入口，
+ *    典型症状就是控制台「WARNING: Multiple instances of Three.js being imported.」
+ *    ——同一页面出现两份 three，instanceof 全部失灵。库端唯一治本的办法是
+ *    不引入 jsm 子路径，把 import 面收敛到 `three` 一个入口。
+ * 2. 对「提棱线」这个用途，位置焊合反而是更对的行为：完整版 mergeVertices
+ *    要求所有属性都在容差内匹配，而 S3M 几何常是「每面独立顶点 + 各自 UV」，
+ *    重合顶点会因 UV 不同而焊不上，EdgesGeometry 照样把每条三角形边当边界。
+ *
+ * 输出只保留 position（EdgesGeometry 只消费位置），并把原索引重映射到焊后顶点。
+ */
+import * as THREE from 'three';
+
+export function mergeVerticesByPosition(
+  geometry: THREE.BufferGeometry,
+  tolerance: number
+): THREE.BufferGeometry {
+  const pos = geometry.getAttribute('position') as THREE.BufferAttribute | undefined;
+  if (!pos || pos.count === 0) return geometry;
+
+  const inv = 1 / Math.max(tolerance, 1e-9);
+  /** 网格哈希：坐标量化到 tolerance 网格，同格即视为重合 */
+  const map = new Map<string, number>();
+  const out: number[] = [];
+  const remap = new Int32Array(pos.count);
+
+  for (let i = 0; i < pos.count; i++) {
+    const x = pos.getX(i);
+    const y = pos.getY(i);
+    const z = pos.getZ(i);
+    const key = `${Math.round(x * inv)},${Math.round(y * inv)},${Math.round(z * inv)}`;
+    let id = map.get(key);
+    if (id === undefined) {
+      id = out.length / 3;
+      out.push(x, y, z);
+      map.set(key, id);
+    }
+    remap[i] = id;
+  }
+
+  // 原几何可能带索引：按原三角形拓扑重映射，不能按顶点顺序重造三角形
+  const srcIndex = geometry.getIndex();
+  const triCount = srcIndex ? srcIndex.count : pos.count;
+  const outIndex = new Uint32Array(triCount);
+  for (let i = 0; i < triCount; i++) {
+    outIndex[i] = remap[srcIndex ? srcIndex.getX(i) : i]!;
+  }
+
+  const welded = new THREE.BufferGeometry();
+  welded.setAttribute('position', new THREE.Float32BufferAttribute(out, 3));
+  welded.setIndex(new THREE.BufferAttribute(outIndex, 1));
+  return welded;
+}

package/src/render/S3MViewer.ts

@@ -21,10 +21,10 @@
  * MapLibre / Mapbox 的胶水层在 s3m-maplibre 包的 S3MLayer.ts。
  */
 import * as THREE from 'three';
-import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js';
 import { S3MTileset, usableGeoBounds } from '../tileset/S3MTileset.js';
 import type { BuildTileFn, TileNode } from '../tileset/S3MTileset.js';
-import { setMaxAnisotropy } from './TextureFactory.js';
+import { setMaxAnisotropy, setTextureOffThreadDecode } from './TextureFactory.js';
+import { decodeTextureWithWorker } from '../worker/S3MWorkerClient.js';
 import {
   STYLE,
   STYLE_LABELS,
@@ -43,6 +43,7 @@ import {
   createThickLineMaterial,
 } from './EdgeLines.js';
 import type { LineSharedUniforms, ThickLineMaterial } from './EdgeLines.js';
+import { mergeVerticesByPosition } from './MergeVertices.js';
 import {
   resolveFeature,
   measureSegments,
@@ -193,6 +194,8 @@ export interface S3MViewerOptions {
   maxTiles?: number;
   /** 每个数据集并发请求数 */
   maxConcurrent?: number;
+  /** 是否用 Web Worker 解析经典 .s3mb 瓦片（默认开，崩溃自动降级主线程），见 S3MTilesetOptions.useWorker */
+  useWorker?: boolean;
   /** LOD 切换范围缩放系数（默认 1.0），> 1 更倾向保留粗模，< 1 提前换细模 */
   lodRangeScale?: number;
   /** 自定义瓦片构建器（测试 / 服务端渲染时注入） */
@@ -401,6 +404,8 @@ export class S3MViewer {
     );
 
     this.uniforms = createSharedUniforms();
+    // 纹理解码优先派给共享解析 Worker（崩溃自动回主线程，见 decodeTextureWithWorker）
+    setTextureOffThreadDecode(decodeTextureWithWorker);
     this.style = { ...DEFAULT_STYLE, ...(options.style ?? {}) };
     this.outlineMaterial = createOutlineMaterial(this.uniforms);
 
@@ -604,7 +609,8 @@ export class S3MViewer {
 
   private _normalizeDatasets(options: S3MViewerOptions): S3MDatasetOptions[] {
     if (Array.isArray(options.datasets)) return options.datasets.filter((d) => !!d?.configUrl);
-    if (options.configUrl) return [{ id: 'default', name: '默认数据集', configUrl: options.configUrl }];
+    if (options.configUrl)
+      return [{ id: 'default', name: '默认数据集', configUrl: options.configUrl, useWorker: options.useWorker }];
     return [];
   }
 
@@ -1544,8 +1550,10 @@ export class S3MViewer {
 
     // 1. 先做顶点容差焊合，让相邻三角形正确共享边索引。
     //    S3M 几何常为「每面独立顶点」，不焊合的话 EdgesGeometry 会把每条三角形边都当成边界，棱线爆炸。
+    //    注意用本地实现而不是 three/examples/jsm —— jsm 子路径导入会在宿主里
+    //    制造第二份 three 实例（"Multiple instances of Three.js" 警告的元凶）。
     //    tolerance 取米级模型下的 5mm，足以合并重合顶点又不会误并真实相邻面。
-    const welded = BufferGeometryUtils.mergeVertices(mesh.geometry, 0.005);
+    const welded = mergeVerticesByPosition(mesh.geometry, 0.005);
     // 2. 调大临界角（默认 55°，可在 style.edgeThreshold 调），过滤浅坡与曲面细分，只保留真正的棱。
     const thresholdAngle = this.style.edgeThreshold ?? 55;
     const source = new THREE.EdgesGeometry(welded, thresholdAngle);

package/src/render/StyleMaterial.ts

@@ -499,6 +499,12 @@ const FRAG_COLOR = /* glsl */ `
       diffuseColor.rgb = bState.rgb;
       hasCustomColor = true;
     }
+    // 单体独立透明度（状态纹理第 2 行 alpha，0 = 无覆盖）。
+    // 与全局 uOpacity（diffuseColor.a 初值）和图集贴图自带 alpha 逐级叠乘
+    vec4 bOffset = texture2D( uBatchTex, vec2( ( s3mBid + 0.5 ) / uBatchTexWidth, 0.75 ) );
+    if ( bOffset.a > 0.0 ) {
+      diffuseColor.a *= bOffset.a;
+    }
   }
 
   // 3. 选中单体高亮 + 其余压暗

package/src/render/TextureFactory.ts

@@ -1,32 +1,18 @@
 /**
  * S3M 纹理 → three.js Texture
  *
- * S3M 的纹理是「裸块」：没有容器头，只有 width/height/compressType/dataSize/pixelFormat + 原始字节。
- * 该走哪条解码路径由 compressType 决定（见 core/TextureFormat.ts）：DXT 族直接解块，
- * CRN（26 / 27 / 38001 / 50000）先用 crunch wasm 转码回 DXT，WEBP 交给浏览器，
- * RGB 系逐像素拷贝。
+ * 解码本体已下沉到 core/TextureDecode.ts（three 无关，主线程 / Worker 共用），
+ * 本文件只负责两件事：
+ *   1. 优先把解码派给 Worker（setTextureOffThreadDecode 注入，S3MViewer 装配），
+ *      Worker 不可用时用同一份 decodeTextureData 在主线程兜底；
+ *   2. 把纯数据解码产物包成 three Texture 并按 atlas / 普通 分别配置采样参数。
  */
 import * as THREE from 'three';
-import DXTTextureDecode from '../core/DXTTextureDecode.js';
-import { transcodeCRN } from '../core/CRNDecode.js';
-import { dxtPixelFormatOf, resolveTextureKind } from '../core/TextureFormat.js';
 import type { S3MTexture } from '../core/types.js';
+import { decodeTextureData } from '../core/TextureDecode.js';
+import type { DecodedTextureData } from '../core/TextureDecode.js';
 
-export const PixelFormat = {
-  RGB: 10,
-  BGR: 11,
-  ARGB: 12,
-  ABGR: 13,
-  BGRA: 14,
-  RGBA: 28,
-  WEBP: 25,
-  DXT1: 17,
-  DXT3: 19,
-  DXT4: 20,
-  DXT5: 21,
-  CRN_DXT5: 26,
-  STANDARD_CRN: 27,
-} as const;
+export { PixelFormat } from '../core/TextureFormat.js';
 
 /** 由 S3MLayer 在拿到 GL 上下文后注入，用于斜视角下保持纹理清晰 */
 let maxAnisotropy = 1;
@@ -41,6 +27,26 @@ export interface DecodedTexture {
   decoded: string;
 }
 
+/**
+ * 注入「离线解码」实现（S3MViewer 装配：走共享解析 Worker）。
+ * 返回 null = Worker 不可用 / 崩溃，createTexture 自动退回主线程 decodeTextureData。
+ */
+let offThreadDecode: ((tex: S3MTexture) => Promise<DecodedTextureData | null>) | null = null;
+
+export function setTextureOffThreadDecode(
+  fn: ((tex: S3MTexture) => Promise<DecodedTextureData | null>) | null
+): void {
+  offThreadDecode = fn;
+}
+
+async function decodeTexture(tex: S3MTexture): Promise<DecodedTextureData> {
+  if (offThreadDecode) {
+    const viaWorker = await offThreadDecode(tex);
+    if (viaWorker) return viaWorker;
+  }
+  return decodeTextureData(tex);
+}
+
 function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
   tex.wrapS = THREE.RepeatWrapping;
   tex.wrapT = THREE.RepeatWrapping;
@@ -74,117 +80,32 @@ function configureAtlas<T extends THREE.Texture>(tex: T): T {
   return tex;
 }
 
-/** 行序翻转（原地）。S3MBLOCK 图集按 GL 方向存储（v=0 在最后一行），解码后要翻一次行 */
-function flipRows(rgba: Uint8Array, width: number, height: number): void {
-  const row = width * 4;
-  const tmp = new Uint8Array(row);
-  for (let y = 0; y < height >> 1; y++) {
-    const a = y * row;
-    const b = (height - 1 - y) * row;
-    tmp.set(rgba.subarray(a, a + row));
-    rgba.copyWithin(a, b, b + row);
-    rgba.set(tmp, b);
-  }
-}
-
-/** 该像素格式自带 alpha 通道（DXT1 的 1bit alpha 不算，历史上没开过 alphaTest） */
-function hasAlphaChannel(pixelFormat: number): boolean {
-  return (
-    pixelFormat === PixelFormat.DXT3 ||
-    pixelFormat === PixelFormat.DXT4 ||
-    pixelFormat === PixelFormat.DXT5 ||
-    pixelFormat === PixelFormat.ARGB ||
-    pixelFormat === PixelFormat.ABGR ||
-    pixelFormat === PixelFormat.BGRA ||
-    pixelFormat === PixelFormat.RGBA
-  );
-}
-
-/** 解 DXT 到 RGBA8。DXT5 是 1 字节/像素，DXT1 是 0.5 字节/像素。 */
-/** DXT 解码只需要尺寸 / 格式 / 字节，CRN 转码出来的结果也走这条路 */
-function decodeDXT(tex: Pick<S3MTexture, 'width' | 'height' | 'pixelFormat' | 'data' | 'flipY'>): THREE.DataTexture {
-  const { width, height, pixelFormat, data } = tex;
-  const out = new Uint8Array(width * height * 4);
-  DXTTextureDecode.decode(out, width, height, data, pixelFormat);
-  if (tex.flipY) flipRows(out, width, height);
-  const dt = new THREE.DataTexture(out, width, height, THREE.RGBAFormat, THREE.UnsignedByteType);
-  if (hasAlphaChannel(pixelFormat)) dt.userData.s3mHasAlpha = true;
-  return dt;
-}
-
-function fromRawRGB(tex: S3MTexture): THREE.DataTexture {
-  const { width, height, pixelFormat, data } = tex;
-  const out = new Uint8Array(width * height * 4);
-  // RGBA / BGRA / ARGB / ABGR 都是 4 字节，前两个是「尾字节是 alpha」，后两个是「首字节是 alpha」
-  const hasAlpha =
-    pixelFormat === PixelFormat.RGBA ||
-    pixelFormat === PixelFormat.BGRA ||
-    pixelFormat === PixelFormat.ARGB ||
-    pixelFormat === PixelFormat.ABGR;
-  const swapRB = pixelFormat === PixelFormat.BGR || pixelFormat === PixelFormat.BGRA;
-  const alphaFirst = pixelFormat === PixelFormat.ARGB || pixelFormat === PixelFormat.ABGR;
-  const src = hasAlpha ? 4 : 3;
-  for (let i = 0, s = 0, d = 0; i < width * height; i++, s += src, d += 4) {
-    const p = alphaFirst ? s + 1 : s;
-    out[d] = swapRB ? data[p + 2] : data[p];
-    out[d + 1] = data[p + 1];
-    out[d + 2] = swapRB ? data[p] : data[p + 2];
-    out[d + 3] = hasAlpha ? data[alphaFirst ? s : s + 3] : 255;
-  }
-  if (tex.flipY) flipRows(out, width, height);
-  const dt = new THREE.DataTexture(out, width, height, THREE.RGBAFormat, THREE.UnsignedByteType);
-  if (hasAlphaChannel(pixelFormat)) dt.userData.s3mHasAlpha = true;
-  return dt;
-}
-
 export async function createTexture(tex: S3MTexture | null | undefined): Promise<DecodedTexture> {
   if (!tex || !tex.width || !tex.height) return { texture: null, decoded: 'empty' };
 
   // 图集纹理（flipY 的原始 DXT 图集 / AtlasPack 拼出来的 RGBA 大图 / leaf 组合画布）都必须
   // 关 GPU mip，层级由 StyleMaterial.s3mAtlasUnit 的内联金字塔自己算。
   const isAtlas = tex.packed === true || tex.flipY === true || tex.composed === true;
-  const asAtlas = <T extends THREE.Texture>(t: T): T => (isAtlas ? configureAtlas(t) : configure(t));
 
-  // 判定只能看 compressType：v3.00 的 CRN 纹理 pixelFormat 是 13（ABGR）、
-  // 行标的 CRN 是 32856（GL_RGBA8），都不是 26 / 27（见 core/TextureFormat.ts）
-  const kind = resolveTextureKind(tex.compressType ?? 0, tex.pixelFormat);
+  const data = await decodeTexture(tex);
 
-  if (kind === 'crn') {
-    try {
-      const crn = await transcodeCRN(tex.data);
-      const decoded = decodeDXT({
-        width: crn.width,
-        height: crn.height,
-        pixelFormat: crn.dxtFormat === 1 ? 17 : 21,
-        data: crn.data,
-      });
-      return { texture: asAtlas(decoded), decoded: `crn->dxt${crn.dxtFormat}` };
-    } catch (e) {
+  if (!data.rgba && !data.bitmap) {
+    if (data.error) {
       // 一张纹理坏了不该带崩整个瓦片，如实上报并降级成无贴图
-      console.warn('[s3m] CRN 转码失败：', e);
-      return { texture: null, decoded: 'crn(failed)' };
+      console.warn('[s3m] CRN 转码失败：', data.error);
     }
+    return { texture: null, decoded: data.kind };
   }
 
-  if (kind === 'dxt1' || kind === 'dxt3' || kind === 'dxt4' || kind === 'dxt5') {
-    const decoded = decodeDXT({ ...tex, pixelFormat: dxtPixelFormatOf(kind) });
-    // flipY 为真即 S3MBLOCK 图集（见 core/types.ts），必须无 mip
-    return { texture: asAtlas(decoded), decoded: kind };
+  let texture: THREE.Texture;
+  if (data.bitmap) {
+    texture = new THREE.Texture(data.bitmap);
+  } else {
+    const dt = new THREE.DataTexture(data.rgba!, data.width, data.height, THREE.RGBAFormat, THREE.UnsignedByteType);
+    if (data.hasAlpha) dt.userData.s3mHasAlpha = true;
+    texture = dt;
   }
-
-  if (kind === 'webp') {
-    const blob = new Blob([tex.data as BlobPart], { type: 'image/webp' });
-    const bmp = await createImageBitmap(blob);
-    const t = new THREE.Texture(bmp);
-    t.needsUpdate = true;
-    return { texture: asAtlas(t), decoded: 'webp' };
-  }
-
-  if (kind === 'raw') {
-    const decoded = fromRawRGB(tex);
-    return { texture: asAtlas(decoded), decoded: 'raw' };
-  }
-
-  // KTX2 / ETC 需要额外解码器，先如实上报而不是静默出错
-  return { texture: null, decoded: `unsupported(${tex.compressType}/${tex.pixelFormat})` };
+  texture.needsUpdate = true;
+  // flipY 为真即 S3MBLOCK 图集（见 core/types.ts），必须无 mip
+  return { texture: isAtlas ? configureAtlas(texture) : configure(texture), decoded: data.kind };
 }