modelstage 0.0.0-stage → 0.5.28

package/plugins/unity-live2d-bundle/lib/serialized.js

@@ -0,0 +1,233 @@
+// ============================================================================
+// plugins/unity-live2d-bundle/lib/serialized.js —— SerializedFile 解析（对象表）
+//
+// 职责：把 UnityFS 里的 CAB-<hash> 节点（一个 SerializedFile）解析成**对象表**：
+//   每个对象 = { pathID, classID, className, typeIndex, dataOffset, byteSize }，
+//   加上文件级信息（Unity 版本、目标平台、类型表、脚本类型、外部引用、容器清单）。
+//   派生能力：按类名统计（本样本 MonoBehaviour 2167 / AnimationClip 34 / Texture2D 2 …）、
+//             按类取对象切片（moc3 在 MonoBehaviour 里、physics3 在 TextAsset 里、纹理在 Texture2D 里）。
+//
+// 字节序（同一个文件里会变，必须逐段确认）：
+//   · 头部前 4 个 u32 与 v22 的追加字段（metadataSize/fileSize/dataOffset/unknown）
+//     跟在**容器**后面，用容器端的字节序（UnityFS 是大端）——这一点最容易踩：
+//     直接用文件自己的端序去读这 4 个 u32，版本号会变成一个天文数字。
+//   · 头部里的 endian 标志字节（0=小端/1=大端）之后的元数据段，才是文件自己的端序。
+//
+// 版本覆盖：本实现覆盖 v22（Unity 2020.3，本样本）用到的字段；更老/更新的版本按
+//   同样的分支条件处理，遇到没实现的字段（v23 的类型树 hash + 长度前缀等）抛可读错误。
+//
+// 挂载：globalThis.__ULB__.serialized
+// ============================================================================
+
+'use strict';
+
+{
+  const root = globalThis;   // 原 IIFE 的 root 引用（脚本级裸块内保持同名）
+  const NS = (root.__ULB__ = root.__ULB__ || {});
+  const B = NS.bytes;
+
+  // Unity 的类 ID → 可读类名（只列本插件会用到/会遇到的；其余用 "ClassID <n>" 表示）
+  const CLASS_NAMES = {
+    1: 'GameObject', 4: 'Transform', 21: 'Material', 23: 'MeshRenderer', 28: 'Texture2D',
+    33: 'MeshFilter', 43: 'Mesh', 48: 'Shader', 49: 'TextAsset', 65: 'BoxCollider',
+    74: 'AnimationClip', 82: 'AudioSource', 83: 'AudioClip', 91: 'AnimatorController',
+    95: 'Animator', 104: 'RenderSettings', 111: 'Animation', 114: 'MonoBehaviour',
+    115: 'MonoScript', 128: 'Font', 142: 'AssetBundle', 213: 'Sprite', 222: 'CanvasRenderer',
+    223: 'Canvas', 224: 'RectTransform', 225: 'CanvasGroup',
+  };
+  const CLASS_IDS = { MonoBehaviour: 114, Texture2D: 28, TextAsset: 49, AssetBundle: 142, AnimationClip: 74 };
+
+  const className = (id) => CLASS_NAMES[id] || `ClassID ${id}`;
+
+  /** 读一个 SerializedType（含类型树，类型树只记偏移/长度，不在此处展开字段） */
+  function readType(r, opts) {
+    const version = opts.version;
+    const isRefType = !!opts.isRefType;
+    const t = { classID: r.i32(), scriptTypeIndex: -1, scriptID: null, oldTypeHash: null, typeTree: null };
+    if (version >= 16) t.isStripped = r.bool();
+    if (version >= 17) t.scriptTypeIndex = r.i16();
+    if (version >= 13) {
+      if ((isRefType && t.scriptTypeIndex >= 0) || (version < 16 && t.classID < 0) || (version >= 16 && t.classID === 114)) {
+        t.scriptID = r.bytes(16, 'scriptID');
+      }
+      t.oldTypeHash = r.bytes(16, 'oldTypeHash');
+    }
+    if (opts.enableTypeTree) {
+      let treeSizeHint = null;
+      if (version >= 23) {
+        t.typeTreeContentHash = r.bytes(16, 'typeTreeContentHash');
+        treeSizeHint = r.i32();
+        t.typeTreeSerializedSize = treeSizeHint;
+      }
+      // v12+/v10 的类型树是**内联 blob**：i32 节点数 + i32 字符串池长度 + 节点数组 + 字符串池。
+      //   节点记录（v19+）32 字节：h(m_Version) B(m_Level) B(m_TypeFlags) I(m_TypeStrOffset)
+      //   I(m_NameStrOffset) i(m_ByteSize) i(m_Index) i(m_MetaFlag) Q(m_RefTypeHash)
+      //   —— 前面 8 个字段 24 字节，v19 起多 8 字节的 m_RefTypeHash，合计 32。
+      //   （这也是本文件的坑之一：把节点记录当 28 字节算，整段类型表就会错位。）
+      if (version >= 12 || version === 10) {
+        const start = r.pos;
+        const nodeCount = r.i32();
+        const stringBufferSize = r.i32();
+        if (nodeCount < 0 || stringBufferSize < 0) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `类型树长度非法：节点数=${nodeCount} 字符串池=${stringBufferSize}`);
+        const nodeStructSize = version >= 19 ? 32 : 24;
+        r.skip(nodeCount * nodeStructSize + stringBufferSize);
+        t.typeTree = { nodeCount, stringBufferSize, offset: start, size: r.pos - start };
+      } else {
+        throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `尚未支持 v${version} 的非内联类型树（v12 之前的旧格式）`);
+      }
+      if (version >= 21) {
+        if (isRefType) {
+          t.m_ClassName = r.cstring('m_ClassName');
+          t.m_NameSpace = r.cstring('m_NameSpace');
+          t.m_AssemblyName = r.cstring('m_AssemblyName');
+        } else {
+          const n = r.i32();
+          if (n < 0 || n > 128) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `type_dependencies 长度非法：${n}`);
+          const deps = [];
+          for (let i = 0; i < n; i++) deps.push(r.i32());
+          t.typeDependencies = deps;
+        }
+      }
+    }
+    t.className = className(t.classID);
+    return t;
+  }
+
+  /**
+   * 解析 SerializedFile。
+   * @param {Uint8Array} u8 CAB 节点字节
+   * @returns {object} { version, unityVersion, platform, enableTypeTree, types, objects, scripts, externals, dataOffset, container }
+   */
+  function parse(u8) {
+    // 头部前 4 个 u32 用**容器端**字节序（大端）——它们只是"预览"，真实值在 v22 段重读
+    const r = new B.Reader(u8, { endian: '>' });
+    const preview = { metadataSize: r.u32(), fileSize: r.u32(), version: r.u32(), dataOffset: r.u32() };
+    const fieldOrder = preview.version;
+    const endianFlag = r.u8();
+    r.skip(3); // reserved
+    let metadataSize = preview.metadataSize;
+    let fileSize = preview.fileSize;
+    let dataOffset = preview.dataOffset;
+    let unknown = 0;
+    if (fieldOrder >= 22) {
+      metadataSize = r.u32();
+      fileSize = r.i64('fileSize');
+      dataOffset = r.i64('dataOffset');
+      unknown = r.i64('unknown');
+    }
+    if (fieldOrder >= 9 && endianFlag > 1) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `字节序标志非法：${endianFlag}`);
+    // 之后的元数据段用文件自己的字节序
+    r.le = endianFlag === 0;
+
+    const version = fieldOrder;
+    let unityVersion = '';
+    let platform = 0;
+    let enableTypeTree = true;
+    if (version >= 7) unityVersion = r.cstring('unityVersion');
+    if (version >= 8) platform = r.i32();
+    if (version >= 13) enableTypeTree = r.bool();
+
+    const typeCount = r.i32();
+    if (typeCount < 0 || typeCount > 4096) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `类型数非法：${typeCount}`);
+    const opt = { version, enableTypeTree, isRefType: false };
+    const types = [];
+    for (let i = 0; i < typeCount; i++) types.push(readType(r, opt));
+
+    let bigIdEnabled = 0;
+    if (version >= 7 && version < 14) bigIdEnabled = r.i32();
+
+    const objectCount = r.i32();
+    if (objectCount < 0 || objectCount > 1e6) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `对象数非法：${objectCount}`);
+    const objects = [];
+    const byPathID = new Map();
+    for (let i = 0; i < objectCount; i++) {
+      // pathID 是 int64，**实测会超过 2^53**（本样本有 2.8e17 这样的值），
+      //   所以用 BigInt 读、以十进制字符串对外（JSON 化安全），同时保留 BigInt 供内部比较。
+      let pathIDBig;
+      if (bigIdEnabled) pathIDBig = r.i64b('pathID');
+      else if (version < 14) pathIDBig = BigInt(r.i32());
+      else { r.align(4); pathIDBig = r.i64b('pathID'); }
+      let byteStart = version >= 22 ? r.i64('byteStart') : r.u32();
+      const byteSize = r.u32();
+      const typeIndex = r.i32();
+      const type = types[typeIndex];
+      if (!type) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `对象 ${pathIDBig} 的 typeIndex 越界：${typeIndex}（类型数 ${types.length}）`);
+      byteStart += dataOffset;
+      if (byteStart + byteSize > u8.length) {
+        throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `对象 ${pathIDBig} 越界：offset=${byteStart} size=${byteSize} 文件=${u8.length}`);
+      }
+      const obj = {
+        pathID: pathIDBig.toString(), pathIDBig, typeIndex, classID: type.classID, className: type.className,
+        dataOffset: byteStart, byteSize,
+      };
+      objects.push(obj);
+      byPathID.set(obj.pathID, obj);
+    }
+
+    let scripts = [];
+    if (version >= 11) {
+      const scriptCount = r.i32();
+      if (scriptCount < 0 || scriptCount > 1e5) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `脚本类型数非法：${scriptCount}`);
+      for (let i = 0; i < scriptCount; i++) {
+        const localSerializedFileIndex = r.i32();
+        let localIdentifierInFile;
+        if (version < 14) localIdentifierInFile = String(r.i32());
+        else { r.align(4); localIdentifierInFile = r.i64b('localIdentifierInFile').toString(); }
+        scripts.push({ localSerializedFileIndex, localIdentifierInFile });
+      }
+    }
+
+    const externalCount = r.i32();
+    if (externalCount < 0 || externalCount > 1e5) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `外部引用数非法：${externalCount}`);
+    const externals = [];
+    for (let i = 0; i < externalCount; i++) {
+      const e = {};
+      if (version >= 6) e.tempEmpty = r.cstring('tempEmpty');
+      if (version >= 5) { e.guid = B.toHex(r.bytes(16, 'guid')); e.type = r.i32(); }
+      e.path = r.cstring('externalPath');
+      externals.push(e);
+    }
+
+    let refTypes = [];
+    if (version >= 20) {
+      const refCount = r.i32();
+      if (refCount < 0 || refCount > 1e5) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `引用类型数非法：${refCount}`);
+      const refOpt = { version, enableTypeTree, isRefType: true };
+      for (let i = 0; i < refCount; i++) refTypes.push(readType(r, refOpt));
+    }
+
+    let userInformation = '';
+    if (version >= 5) userInformation = r.cstring('userInformation');
+
+    // 强自检：元数据段必须落在数据区之前（偏移算错时这里会先炸，而不是等到取值阶段）
+    if (dataOffset && r.pos > dataOffset) {
+      throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `元数据段越过了数据区：读到的位置=${r.pos} 但 dataOffset=${dataOffset}（字段布局可能不匹配该版本）`);
+    }
+
+    return {
+      version, unityVersion, platform, enableTypeTree, metadataSize, fileSize, dataOffset, unknown,
+      bigIdEnabled, le: endianFlag === 0, types, objects, byPathID, scripts, externals, refTypes, userInformation,
+      metaEnd: r.pos,
+      bytes: u8,
+    };
+  }
+
+  /** 按类统计对象数（M4 的验收口径） */
+  function typeStats(sf) {
+    const stats = {};
+    for (const o of sf.objects) stats[o.className] = (stats[o.className] || 0) + 1;
+    return stats;
+  }
+
+  /** 取某个类 ID 的全部对象（按文件内出现顺序） */
+  function byClass(sf, classID) {
+    return sf.objects.filter((o) => o.classID === classID);
+  }
+
+  /** 取某个对象的字节切片 */
+  function objectBytes(sf, obj) {
+    return sf.bytes.subarray(obj.dataOffset, obj.dataOffset + obj.byteSize);
+  }
+
+  NS.serialized = { parse, typeStats, byClass, objectBytes, className, CLASS_NAMES, CLASS_IDS };
+}

package/plugins/unity-live2d-bundle/lib/texdecode.js

@@ -0,0 +1,190 @@
+// ============================================================================
+// plugins/unity-live2d-bundle/lib/texdecode.js —— 纹理格式分发
+//
+// 职责：读 Texture2D 的 m_TextureFormat，分发给对应解码器，返回 RGBA 字节。
+//   · 已实现：ETC2_RGBA8(47) / ETC2_RGB(45) / ETC1_RGB4(34) / 未压缩 RGBA32/RGB24/Alpha8 等直通格式
+//   · 未实现：ASTC / PVRTC / BCn 等 —— **抛可读错误**并把格式名与格式号带上，
+//     绝不返回空白图或猜出来的图（否则上层会把"解码失败"当成"资源损坏"）。
+//
+// 纹理尺寸与数据量的自检：按格式的块大小算出期望数据量，与给的字节数比对；
+//   不匹配直接报错——这类错通常意味着字段读取错位，早报比晚报好。
+//
+// 挂载：globalThis.__ULB__.texdecode
+// ============================================================================
+
+'use strict';
+
+{
+  const root = globalThis;   // 原 IIFE 的 root 引用（脚本级裸块内保持同名）
+  const NS = (root.__ULB__ = root.__ULB__ || {});
+
+  // Unity TextureFormat → 名称 + 每块字节数 + 块边长（4 或 0 表示未压缩的逐像素格式）
+  const FORMATS = {
+    1: { name: 'Alpha8', block: 1, size: 1 },
+    3: { name: 'RGB24', block: 3, size: 1 },
+    4: { name: 'RGBA32', block: 4, size: 1 },
+    5: { name: 'ARGB32', block: 4, size: 1 },
+    7: { name: 'RGB565', block: 2, size: 1 },
+    34: { name: 'ETC_RGB4', compress: 'etc1', block: 8, size: 4 },
+    45: { name: 'ETC2_RGB', compress: 'etc2', block: 8, size: 4 },
+    47: { name: 'ETC2_RGBA8', compress: 'etc2a8', block: 16, size: 4 },
+    48: { name: 'ETC2_RGBA1', compress: 'etc2a1', block: 16, size: 4 },
+    // BC/DXT 家族（PC/主机资源包常用；块式压缩，解码实现见 lib/dxt.js）
+    10: { name: 'DXT1', compress: 'bc1', block: 8, size: 4 },
+    12: { name: 'DXT5', compress: 'bc3', block: 16, size: 4 },
+    26: { name: 'BC4', compress: 'bc4', block: 8, size: 4 },
+    27: { name: 'BC5', compress: 'bc5', block: 16, size: 4 },
+  };
+
+  function formatName(fmt) {
+    const f = FORMATS[fmt];
+    return f ? f.name : `未知格式 ${fmt}`;
+  }
+
+  /** 按格式算期望的压缩/原始数据量 */
+  function expectedSize(fmt, width, height) {
+    const f = FORMATS[fmt];
+    if (!f) return null;
+    if (f.size === 1) return width * height * f.block;
+    const bw = Math.ceil(width / 4);
+    const bh = Math.ceil(height / 4);
+    return bw * bh * f.block;
+  }
+
+  /** unpack ARGB32 → RGBA */
+  function argbToRgba(data) {
+    const out = new Uint8Array(data.length);
+    for (let i = 0; i < data.length; i += 4) {
+      out[i] = data[i + 1];
+      out[i + 1] = data[i + 2];
+      out[i + 2] = data[i + 3];
+      out[i + 3] = data[i];
+    }
+    return out;
+  }
+
+  /** RGB24(3) → RGBA：每 3 字节一像素，alpha 补 255 */
+  function rgb24ToRgba(data, width, height, need) {
+    const out = new Uint8Array(width * height * 4);
+    for (let i = 0, p = 0; i < need; i += 3, p += 4) {
+      out[p] = data[i]; out[p + 1] = data[i + 1]; out[p + 2] = data[i + 2]; out[p + 3] = 255;
+    }
+    return out;
+  }
+
+  /** Alpha8(1) → RGBA：单通道进 alpha，RGB 填白 */
+  function alpha8ToRgba(data, width, height, need) {
+    const out = new Uint8Array(width * height * 4);
+    for (let i = 0, p = 0; i < need; i++, p += 4) {
+      out[p] = 255; out[p + 1] = 255; out[p + 2] = 255; out[p + 3] = data[i];
+    }
+    return out;
+  }
+
+  /** RGB565(7) → RGBA：5/6/5 位展开到 8 位（低位复制高位，保持满量程） */
+  function rgb565ToRgba(data, width, height, need) {
+    const out = new Uint8Array(width * height * 4);
+    for (let i = 0, p = 0; i < need; i += 2, p += 4) {
+      const v = data[i] | (data[i + 1] << 8);
+      const r = (v >> 11) & 0x1f, g = (v >> 5) & 0x3f, b = v & 0x1f;
+      out[p] = (r << 3) | (r >> 2);
+      out[p + 1] = (g << 2) | (g >> 4);
+      out[p + 2] = (b << 3) | (b >> 2);
+      out[p + 3] = 255;
+    }
+    return out;
+  }
+
+  /**
+   * 垂直翻转 RGBA。
+   *
+   * 为什么所有格式都要翻：Unity 的纹理数据按 **GL 习惯自下而上**存放（第 0 行是图像底部），
+   *   而页面/PNG 期望自上而下。实测证据：按存储顺序解码后与权威参考 PNG 比对，
+   *   不做翻转时 2048² 的采样差异 461,728/466,489，翻转后差异为 0。
+   * 所以解码的输出统一为"显示方向"，调用方拿到的就是能直接显示/编码的朝向。
+   */
+  function flipY(rgba, width, height) {
+    const out = new Uint8Array(rgba.length);
+    const stride = width * 4;
+    for (let y = 0; y < height; y++) {
+      out.set(rgba.subarray((height - 1 - y) * stride, (height - y) * stride), y * stride);
+    }
+    return out;
+  }
+
+  /**
+   * 格式号 → 解码器。
+   *
+   * **等价性前提**：原来是"先按 compress 字段判 7 个分支、再按 fmt 号判 5 个"，
+   *   这里改成按 fmt 号查表 —— 两者等价的唯一前提是"一个 fmt 只对应一条解码路径"。
+   *   实测成立：FORMATS 里每个 compress 值都只挂着一个 fmt
+   *   （bc1→10 / bc3→12 / bc4→26 / bc5→27 / etc1→34 / etc2→45 / etc2a8→47 / etc2a1→48）。
+   *   所以不存在"两个 fmt 共享 compress 却需要不同处理"的情况。
+   *
+   * 解码器签名统一 `(data, width, height, need) => Uint8Array`，返回**未翻转**的 RGBA；
+   *   翻转由 decode 末尾统一做（与原来的 finish() 等价）。
+   *
+   * **buffer 共享约定**：未压缩格式走 slice（拷贝一份），压缩格式直接透传原始 data。
+   *   调用方**不得依赖**返回的 rgba 与入参共享底层 buffer（有的格式共享、有的不共享，
+   *   原地修改它可能改到源数据、也可能改不到）。
+   */
+  const DECODERS = {
+    // 压缩格式：解码器自身产出 RGBA
+    34: (d, w, h) => NS.etc2.decodeEtc1Rgb(d, w, h),
+    45: (d, w, h) => NS.etc2.decodeEtc2Rgb(d, w, h),
+    47: (d, w, h) => NS.etc2.decodeEtc2Rgba8(d, w, h),
+    // 48 ETC2_RGBA1：ETC2 RGB 块（8 字节）+ 1bit alpha 平面（8 字节）。块布局与位序见
+    //   lib/etc2.js 的 decodeEtc2Rgba1 注释。此格式长期"格式表里有、解码器没登记"，
+    //   导致该格式的包整包报 ULB_ERR_TEX_DECODE（现场：蔚蓝档案部分 spinebackground 包）。
+    48: (d, w, h) => NS.etc2.decodeEtc2Rgba1(d, w, h),
+    10: (d, w, h) => NS.dxt.decodeBc1(d, w, h),
+    12: (d, w, h) => NS.dxt.decodeBc3(d, w, h),
+    26: (d, w, h) => NS.dxt.decodeBc4(d, w, h),
+    27: (d, w, h) => NS.dxt.decodeBc5(d, w, h),
+    // 未压缩格式：切片后按通道展开
+    4: (d, w, h, need) => d.slice(0, need),
+    5: (d, w, h, need) => argbToRgba(d.slice(0, need)),
+    3: (d, w, h, need) => rgb24ToRgba(d, w, h, need),
+    1: (d, w, h, need) => alpha8ToRgba(d, w, h, need),
+    7: (d, w, h, need) => rgb565ToRgba(d, w, h, need),
+  };
+
+  /**
+   * 解码一张纹理的压缩数据。
+   * @param {{format:number, width:number, height:number, name?:string}} meta
+   * @param {Uint8Array} data 压缩/原始数据（取自 .resS 或对象内联）
+   * @param {{flipY?:boolean}} [opts] flipY 默认 true（Unity 存储方向）；给 false 拿原始存储方向
+   * @returns {Uint8Array} RGBA（显示方向）
+   */
+  function decode(meta, data, opts) {
+    const fmt = meta.format;
+    const f = FORMATS[fmt];
+    if (!f) throw NS.errors.fail('ULB_ERR_TEX_FORMAT_UNSUPPORTED', `暂不支持纹理格式 ${fmt}（${meta.name || ''}）——已支持：ETC2_RGBA8(47)、ETC2_RGBA1(48)、ETC2_RGB(45)、ETC_RGB4(34)、DXT1(10)、DXT5(12)、BC4(26)、BC5(27)、RGBA32(4)、ARGB32(5)、RGB24(3)、Alpha8(1)、RGB565(7)；暂未实现：ASTC(50 系列)、PVRTC(30/31)、BC6H(24)、BC7(25)`);
+    const need = expectedSize(fmt, meta.width, meta.height);
+    if (data.length < need) throw NS.errors.fail('ULB_ERR_TEX_DATA_SHORT', `纹理 ${meta.name || ''}（${f.name} ${meta.width}x${meta.height}）数据不足：需要 ${need} 字节，实际 ${data.length}`);
+    // 表里有格式、但没有登记解码器（如 ASTC 50 系列）⇒ 继续走这条兜底
+    const decoder = DECODERS[fmt];
+    if (!decoder) throw NS.errors.fail('ULB_ERR_TEX_DECODE', `纹理格式 ${f.name} 的分发分支缺失`);
+    const rgba = decoder(data, meta.width, meta.height, need);
+    // 统一翻转：原实现用 finish() 包住每个 return，等价于在这里一次做完
+    return !opts || opts.flipY !== false ? flipY(rgba, meta.width, meta.height) : rgba;
+  }
+
+  /**
+   * 某个 Unity TextureFormat 能否**真正解码**。
+   *
+   * 为什么需要它：FORMATS 是"格式字典"（名称 / 尺寸 / block 布局），**不代表能解码** ——
+   *   例如 ASTC(50 系列) 在 FORMATS 里可能有条目、但 DECODERS 没登记，decode() 会抛
+   *   ULB_ERR_TEX_DECODE。若外部（预检 / 面板提示）拿 `!!FORMATS[fmt]` 当"支持"，
+   *   就会先报"支持"、真正解包时才炸 —— 同一件事两套判据。
+   * ⇒ 能力判定只认这张表：**这是"能不能解码"的唯一真相**。
+   *
+   * @param {number} fmt
+   * @returns {boolean}
+   */
+  function canDecode(fmt) {
+    return typeof DECODERS[fmt] === 'function';
+  }
+
+  NS.texdecode = { decode, canDecode, formatName, expectedSize, flipY, FORMATS };
+}

package/plugins/unity-live2d-bundle/lib/typetree.js

@@ -0,0 +1,215 @@
+// ============================================================================
+// plugins/unity-live2d-bundle/lib/typetree.js —— 类型树解析 + 按字段名取值
+//
+// 为什么需要它：SerializedFile 里的对象是"裸字节"，字段边界只存在于**类型树**里。
+//   有了类型树，才能按字段名取到 m_Width / m_TextureFormat / m_StreamData / m_Script / 曲线数组……
+//   没有它就只能靠魔数/长度前缀猜（本插件把它作为兜底，而不是主路径）。
+//
+// 类型树 blob（v12+/v10，内联在 SerializedType 里）：
+//   i32 节点数 | i32 字符串池长度 | 节点记录×N | 字符串池
+//   节点记录（v19+，32 字节）：
+//     u16 m_Version | u8 m_Level | u8 m_TypeFlags | u32 m_TypeStrOffset | u32 m_NameStrOffset
+//     i32 m_ByteSize | i32 m_Index | i32 m_MetaFlag | u64 m_RefTypeHash
+//   字符串引用：最高位为 0 → 指向字符串池的偏移（读到 NUL 结束）；
+//               最高位为 1 → Unity 内置公共字符串表的下标（本插件遇到时抛可读错误，
+//               不猜名字，避免把字段名张冠李戴）。
+//
+// 取值规则（与 Unity 的序列化规则一致，两处最容易错）：
+//   · 每个节点自己的 m_MetaFlag 带 0x4000（kAlignBytes）时，读完该节点要 4 字节对齐；
+//   · 变长数组是「i32 长度 + 元素」，且当**容器节点**或 Array 子节点带对齐标志时，读完数组也要对齐。
+//
+// 挂载：globalThis.__ULB__.typetree
+// ============================================================================
+
+'use strict';
+
+{
+  const root = globalThis;   // 原 IIFE 的 root 引用（脚本级裸块内保持同名）
+  const NS = (root.__ULB__ = root.__ULB__ || {});
+  const B = NS.bytes;
+
+  const ALIGN_BYTES = 0x4000;
+
+  const isAligned = (metaFlag) => ((metaFlag || 0) & ALIGN_BYTES) !== 0;
+
+  /** 解析类型树 blob → 根节点（含 children 树） */
+  function parseBlob(blob, version) {
+    const r = new B.Reader(blob);
+    if (version >= 23) {
+      const magic = B.latin1(r.bytes(4), 0, 4);
+      if (magic !== 'mhtt') throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `类型树 blob 魔数不是 mhtt：${magic}`);
+      const fmt = r.i32();
+      if (fmt !== version) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `类型树格式版本不一致：${fmt} vs ${version}`);
+    }
+    const nodeCount = r.i32();
+    const stringBufferSize = r.i32();
+    if (nodeCount <= 0 || stringBufferSize < 0) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `类型树长度非法：节点数=${nodeCount} 字符串池=${stringBufferSize}`);
+    const recordSize = version >= 19 ? 32 : 24;
+
+    const raw = [];
+    for (let i = 0; i < nodeCount; i++) {
+      const start = r.pos;
+      const rec = {
+        m_Version: r.u16(),
+        m_Level: r.u8(),
+        m_TypeFlags: r.u8(),
+        m_TypeStrOffset: r.u32(),
+        m_NameStrOffset: r.u32(),
+        m_ByteSize: r.i32(),
+        m_Index: r.i32(),
+        m_MetaFlag: r.i32(),
+      };
+      if (version >= 19) rec.m_RefTypeHash = r.i64('m_RefTypeHash');
+      if (r.pos - start !== recordSize) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', '类型树节点记录长度与预期不符');
+      raw.push(rec);
+    }
+    const stringBuffer = r.bytes(stringBufferSize, '类型树字符串池');
+
+    // 字符串池就是一个连续字节区，用 NUL 分隔；按偏移直接解出
+    const readPoolString = (offset) => {
+      let end = offset;
+      while (end < stringBuffer.length && stringBuffer[end] !== 0) end++;
+      return new TextDecoder('utf-8').decode(stringBuffer.subarray(offset, end));
+    };
+    const resolveString = (value, kind) => {
+      const isOffset = (value & 0x80000000) === 0;
+      if (isOffset) return readPoolString(value);
+      const idx = value & 0x7fffffff;
+      const hit = NS.commonStrings && NS.commonStrings[idx];
+      if (hit === undefined) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `公共字符串表里没有下标 ${idx}（${kind}），无法确定字段名`);
+      return hit;
+    };
+
+    // 用层级栈把平铺的节点还原成树（与 Unity 的类型树遍历顺序一致）
+    const fakeRoot = { name: '', type: '', level: -1, metaFlag: 0, byteSize: 0, children: [] };
+    const stack = [fakeRoot];
+    let parent = fakeRoot;
+    let prev = fakeRoot;
+    for (const rec of raw) {
+      const node = {
+        version: rec.m_Version,
+        level: rec.m_Level,
+        flags: rec.m_TypeFlags,
+        byteSize: rec.m_ByteSize,
+        index: rec.m_Index,
+        metaFlag: rec.m_MetaFlag,
+        type: resolveString(rec.m_TypeStrOffset, 'type'),
+        name: resolveString(rec.m_NameStrOffset, 'name'),
+        children: [],
+      };
+      if (node.level > prev.level) { stack.push(parent); parent = prev; }
+      else if (node.level < prev.level) { while (node.level <= parent.level) parent = stack.pop(); }
+      parent.children.push(node);
+      prev = node;
+    }
+    if (!fakeRoot.children.length) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', '类型树为空');
+    return fakeRoot.children[0];
+  }
+
+  // 64 位字段：能精确表示就返回 Number（好用好 JSON 化），超出安全范围才保留 BigInt。
+  // 为什么不直接抛错：对象里本来就有大整数（如 PPtr 的 pathID、哈希），抛错会让整棵树读不出来。
+  const readLong = (r) => {
+    const v = r.i64b('SInt64');
+    const n = Number(v);
+    return Math.abs(n) <= Number.MAX_SAFE_INTEGER ? n : v;
+  };
+
+  // 基本类型的读取函数（与 Unity 的类型名一一对应）
+  const PRIMITIVE = {
+    SInt8: (r) => r.i8(), UInt8: (r) => r.u8(), char: (r) => r.u8(),
+    short: (r) => r.i16(), SInt16: (r) => r.i16(), 'unsigned short': (r) => r.u16(), UInt16: (r) => r.u16(),
+    int: (r) => r.i32(), SInt32: (r) => r.i32(), 'unsigned int': (r) => r.u32(), UInt32: (r) => r.u32(),
+    'Type*': (r) => r.u32(),
+    'long long': readLong, SInt64: readLong,
+    'unsigned long long': readLong, UInt64: readLong, FileSize: readLong,
+    float: (r) => r.f32(), double: (r) => r.f64(), bool: (r) => r.bool(),
+    string: (r) => r.string('string'),
+    // TypelessData：i32 长度 + 原始字节（moc3 这类"字节数组"字段就是它）
+    TypelessData: (r) => { const n = r.i32(); return r.bytes(n, 'TypelessData'); },
+  };
+
+  /**
+   * string 的「原始字节」读取：返回 { text, bytes }，而不是只给 text。
+   *
+   * 为什么需要：Unity 的 `string` 在序列化层是「i32 长度 + 原始字节」，**Unity 自己不校验 UTF-8** ——
+   *   TextAsset 允许承载二进制（spine 的 `.skel` 就是二进制，实测 651994 字节）。
+   *   而 `bytes.string()` 一律 UTF-8 解码 ⇒ 非法序列被替换成 U+FFFD，**信息永久丢失且不可逆**
+   *   （实测某 .skel：641818 字符里 165995 个 U+FFFD，再编码回去长度都不对了）。
+   *   所以需要二进制字段时必须走这条，不能事后从 text 反推。
+   * 保留 text 是为了同一字段两种用途都能覆盖（`.atlas` 要文本、`.skel` 要字节）。
+   * @param {object} r Reader
+   */
+  function readRawString(r) {
+    const len = r.i32();
+    if (len === 0) { r.align(4); return { text: '', bytes: new Uint8Array(0) }; }
+    if (len < 0 || len > r.remaining) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `字符串长度非法（string.raw）：${len}`);
+    const raw = r.bytes(len, 'string.raw');
+    r.align(4);
+    // text 做成**惰性**：调用方常常只要 bytes（.skel 二进制，实测 651994 字节）或只要 text
+    //   （m_Name 几十字节）。不访问就不解码 —— 探测阶段逐字段全量解码会明显拖慢 canHandle。
+    // 行为不变：访问 .text 得到的字符串与立即解码完全相同。
+    let decoded = null;
+    return {
+      bytes: raw,
+      get text() {
+        if (decoded === null) decoded = new TextDecoder('utf-8').decode(raw);
+        return decoded;
+      },
+    };
+  }
+
+  /**
+   * 按类型树递归取值。
+   * @param {object} node 类型树节点
+   * @param {object} r Reader
+   * @param {boolean} rawStrings true 时 `string` 返回 `{text,bytes}` 而非 `text`（见 readRawString）
+   */
+  function readValue(node, r, rawStrings) {
+    let align = isAligned(node.metaFlag);
+    let value;
+    const primitive = (rawStrings && node.type === 'string') ? readRawString : PRIMITIVE[node.type];
+    if (primitive) {
+      value = primitive(r);
+    } else if (node.type === 'pair') {
+      value = [readValue(node.children[0], r, rawStrings), readValue(node.children[1], r, rawStrings)];
+    } else if (node.children.length && node.children[0].type === 'Array') {
+      // 变长数组/容器：先读 i32 长度，再读元素
+      const arrayNode = node.children[0];
+      if (isAligned(arrayNode.metaFlag)) align = true;
+      const size = r.i32();
+      if (size < 0 || size > 1e7) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `数组长度非法：${size}（字段 ${node.name}）`);
+      const subtype = arrayNode.children[1];
+      value = [];
+      for (let i = 0; i < size; i++) value.push(readValue(subtype, r, rawStrings));
+    } else if (node.children.length) {
+      // 结构体/类：按子节点顺序取值
+      value = {};
+      for (const child of node.children) {
+        if (child.type === 'ManagedReferencesRegistry') throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', '尚未支持 ManagedReferencesRegistry（Unity 2020.1+ 的引用注册表）');
+        value[child.name] = readValue(child, r, rawStrings);
+      }
+    } else {
+      throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `未知类型，无法取值：type=${node.type} name=${node.name}`);
+    }
+    if (align) r.align(4);
+    return value;
+  }
+
+  /**
+   * 按类型树读取一个对象的全部字段。
+   * @param {object} sf serialized.parse() 的结果
+   * @param {object} obj serialized 的对象条目
+   * @param {{rawStrings?: boolean}} [opts] rawStrings=true 时 `string` 字段返回 `{text,bytes}`（需要二进制时用）
+   * @returns {object} 字段名 → 值（结构体为嵌套对象，数组为数组）
+   */
+  function readObject(sf, obj, opts) {
+    const type = sf.types[obj.typeIndex];
+    if (!type || !type.typeTree) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `对象 ${obj.pathID} 的类型没有类型树`);
+    const blob = sf.bytes.subarray(type.typeTree.offset, type.typeTree.offset + type.typeTree.size);
+    const root = parseBlob(blob, sf.version);
+    const r = new B.Reader(sf.bytes, { pos: obj.dataOffset, endian: sf.le === false ? '>' : '<' });
+    return readValue(root, r, !!(opts && opts.rawStrings));
+  }
+
+  NS.typetree = { parseBlob, readValue, readObject, readRawString, isAligned, ALIGN_BYTES };
+}