modelstage 0.0.0-stage → 0.5.28

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

@@ -0,0 +1,189 @@
+// ============================================================================
+// plugins/unity-live2d-bundle/lib/bytes.js —— 二进制读取原语
+//
+// 职责：在 ArrayBuffer/Uint8Array 上做**小端**定长读取、变长字符串、对齐、hex/sha256。
+//   Unity 的资源文件一律小端（本插件暂不支持大端序列化文件，遇到就抛可读错误）。
+//
+// 设计要点：
+//   · 只用 DataView + Uint8Array（浏览器与 Node 都有），零依赖。
+//   · 位置（pos）显式可读写：容器格式里有大量「先跳到某处再读」的写法。
+//   · 64 位整数统一用 Number 返回 —— 本插件只处理「文件内偏移/长度」这类远小于 2^53 的值；
+//    读到的值超出安全整数范围时抛可读错误，避免静默精度丢失。
+//   · sha256 分两种实现：有 WebCrypto 用 crypto.subtle（浏览器/https），否则用宿主注入的实现
+//     （Node 侧自检脚本会注入 node:crypto）。二者都不可用时返回 null，由调用方决定是否算校验失败。
+//
+// 挂载：globalThis.__ULB__ = { bytes: {...} }（浏览器与 Node 自检脚本都走同一入口）
+// ============================================================================
+
+'use strict';
+
+{
+  const root = globalThis;   // 原 IIFE 的 root 引用（脚本级裸块内保持同名）
+  const NS = (root.__ULB__ = root.__ULB__ || {});
+
+  const HEX = '0123456789abcdef';
+
+  // CRC32（多项式 0xEDB88320，初值/末值取反）——与 zlib.crc32 一致。
+  // 用途：Unity 的动画绑定把「属性路径」存成 32 位哈希，本插件用 CRC32 反查名字
+  //   （实测 crc32('Value') = 3702945584，正是本样本所有绑定的 attribute 值）。
+  const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+      let c = n;
+      for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+      t[n] = c >>> 0;
+    }
+    return t;
+  })();
+
+  /** 字符串（UTF-8）的 CRC32，返回无符号 32 位整数 */
+  function crc32(str) {
+    const u8 = new TextEncoder().encode(str);
+    let c = 0xffffffff;
+    for (let i = 0; i < u8.length; i++) c = CRC_TABLE[(c ^ u8[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+  }
+
+  /** 字节数组 → 十六进制小写串 */
+  function toHex(u8) {
+    let s = '';
+    for (let i = 0; i < u8.length; i++) s += HEX[u8[i] >> 4] + HEX[u8[i] & 15];
+    return s;
+  }
+
+  function concatBytes(list) {
+    let total = 0;
+    for (const b of list) total += b.length;
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const b of list) { out.set(b, off); off += b.length; }
+    return out;
+  }
+
+  /** 用 latin1 解码一段字节（用于比较 ASCII 魔数，不受 UTF-8 影响） */
+  function latin1(u8, from, to) {
+    let s = '';
+    const end = to === undefined ? u8.length : Math.min(to, u8.length);
+    for (let i = from; i < end; i++) s += String.fromCharCode(u8[i]);
+    return s;
+  }
+
+  /**
+   * 字节读取器。
+   * @param {ArrayBuffer|Uint8Array} buf 数据
+   * @param {object} [opts]
+   *   pos        起始位置（相对 buf）
+   *   baseOffset 把「相对 buf 的偏移」换算成「相对整个文件的偏移」（缓冲区是切片时用）
+   *   endian     '>' 大端 / '<' 小端（默认 '<'）。
+   *              注意：**同一个文件里可能两种字节序都有** —— UnityFS 容器头与 blocksInfo 表是
+   *              大端，而容器里内嵌的 SerializedFile 的字节序由它自己的头字节决定（通常小端）。
+   *              所以字节序是「读取器实例」的属性，不写成全局常量。
+   */
+  class Reader {
+    constructor(buf, opts) {
+      const o = opts || {};
+      this.raw = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+      this.view = new DataView(this.raw.buffer, this.raw.byteOffset, this.raw.byteLength);
+      this.pos = o.pos || 0;
+      this.baseOffset = o.baseOffset || 0;
+      this.le = o.endian !== '>';
+      this.length = this.raw.byteLength;
+    }
+
+    /** 相对整个文件的绝对偏移 */
+    get absOffset() { return this.baseOffset + this.pos; }
+    get remaining() { return this.length - this.pos; }
+    eof() { return this.pos >= this.length; }
+
+    need(n, what) {
+      if (this.pos + n > this.length) {
+        throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `读取越界：需要 ${n} 字节（${what || '未命名字段'}），剩余 ${this.remaining}`);
+      }
+    }
+
+    seek(pos) { this.pos = pos; return this; }
+    skip(n) { this.pos += n; return this; }
+    align(n) { const r = this.pos % n; if (r !== 0) this.pos += n - r; return this; }
+
+    u8() { this.need(1, 'u8'); return this.view.getUint8(this.pos++); }
+    i8() { this.need(1, 'i8'); return this.view.getInt8(this.pos++); }
+    bool() { return this.u8() !== 0; }
+    u16() { this.need(2, 'u16'); const v = this.view.getUint16(this.pos, this.le); this.pos += 2; return v; }
+    i16() { this.need(2, 'i16'); const v = this.view.getInt16(this.pos, this.le); this.pos += 2; return v; }
+    u32() { this.need(4, 'u32'); const v = this.view.getUint32(this.pos, this.le); this.pos += 4; return v; }
+    i32() { this.need(4, 'i32'); const v = this.view.getInt32(this.pos, this.le); this.pos += 4; return v; }
+    f32() { this.need(4, 'f32'); const v = this.view.getFloat32(this.pos, this.le); this.pos += 4; return v; }
+    f64() { this.need(8, 'f64'); const v = this.view.getFloat64(this.pos, this.le); this.pos += 8; return v; }
+
+    /** 64 位整数（返回 Number；超出安全整数范围抛错，避免静默丢精度） */
+    i64(what) {
+      this.need(8, 'i64');
+      const v = this.view.getBigInt64(this.pos, this.le);
+      this.pos += 8;
+      const n = Number(v);
+      if (Math.abs(n) > Number.MAX_SAFE_INTEGER) {
+        throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `64 位整数超出安全范围（${what || ''}）：${v.toString()}，本插件按 Number 处理会丢精度`);
+      }
+      return n;
+    }
+
+    /** 64 位整数（返回 BIGINT，不做范围检查；适合 pathID 这类会超过 2^53 的标识） */
+    i64b(what) {
+      this.need(8, 'i64');
+      const v = this.view.getBigInt64(this.pos, this.le);
+      this.pos += 8;
+      void what;
+      return v;
+    }
+
+    u64(what) { return this.i64(what); }
+
+    bytes(n, what) {
+      this.need(n, what || 'bytes');
+      const out = this.raw.subarray(this.pos, this.pos + n);
+      this.pos += n;
+      return out;
+    }
+
+    /** 以 NUL 结尾的字符串（Unity 的 string-to-null，UTF-8 解码） */
+    cstring(what) {
+      const start = this.pos;
+      while (this.pos < this.length && this.raw[this.pos] !== 0) this.pos++;
+      if (this.pos >= this.length) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `字符串缺少结尾 NUL（${what || ''}）`);
+      const raw = this.raw.subarray(start, this.pos);
+      this.pos++;   // 跳过 NUL
+      return new TextDecoder('utf-8').decode(raw);
+    }
+
+    /** Unity 的长度前缀字符串：i32 长度 + UTF-8 字节 + 4 字节对齐 */
+    string(what) {
+      const len = this.i32();
+      if (len === 0) { this.align(4); return ''; }
+      if (len < 0 || len > this.remaining) throw NS.errors.fail('ULB_ERR_CONTAINER_PARSE', `字符串长度非法（${what || ''}）：${len}`);
+      const raw = this.bytes(len, what);
+      this.align(4);
+      return new TextDecoder('utf-8').decode(raw);
+    }
+  }
+
+  /**
+   * 可注入的 sha256 实现：Node 自检脚本启动时调用 setSha256() 注入 node:crypto 版本；
+   * 浏览器里若存在 crypto.subtle 则用内置实现；都没有时返回 null。
+   */
+  let sha256Impl = null;
+  function setSha256(fn) { sha256Impl = fn; }
+
+  async function sha256Hex(u8) {
+    if (sha256Impl) return sha256Impl(u8);
+    const subtle = root.crypto && root.crypto.subtle;
+    if (subtle && subtle.digest) {
+      const buf = u8.byteOffset === 0 && u8.byteLength === u8.buffer.byteLength
+        ? u8.buffer : u8.slice().buffer;
+      const d = await subtle.digest('SHA-256', buf);
+      return toHex(new Uint8Array(d));
+    }
+    return null;
+  }
+
+  NS.bytes = { Reader, toHex, concatBytes, latin1, sha256Hex, setSha256, crc32 };
+}

package/plugins/unity-live2d-bundle/lib/common-strings.js

@@ -0,0 +1,46 @@
+// ============================================================================
+// plugins/unity-live2d-bundle/lib/common-strings.js —— Unity 类型树"公共字符串表"
+//
+// 用途：类型树节点里的字段名/类型名有两种存法 ——
+//   ① 最高位为 0：偏移 → 指向该类型树自带的字符串池；
+//   ② 最高位为 1：下标 → 指向 Unity 内置的这张公共表（跨文件共享的常用名字，省字节）。
+// 没有这张表就解不出 ② 的名字（本样本的 Texture2D/MonoBehaviour 类型树就用到了它）。
+//
+// 数据来源：Unity 的 CommonString 表（随类型树 TPK 数据分发），
+//   本文件是它的**离线快照**，键=下标、值=字符串；仅用于解析 ②，不参与任何游戏特有逻辑。
+// ============================================================================
+
+'use strict';
+
+(function (root) {
+  const NS = (root.__ULB__ = root.__ULB__ || {});
+  NS.commonStrings = {
+    0: 'AABB', 5: 'AnimationClip', 19: 'AnimationCurve', 34: 'AnimationState', 49: 'Array',
+    55: 'Base', 60: 'BitField', 69: 'bitset', 76: 'bool', 81: 'char', 86: 'ColorRGBA',
+    96: 'Component', 106: 'data', 111: 'deque', 117: 'double', 124: 'dynamic_array',
+    138: 'FastPropertyName', 155: 'first', 161: 'float', 167: 'Font', 172: 'GameObject',
+    183: 'Generic Mono', 196: 'GradientNEW', 208: 'GUID', 213: 'GUIStyle', 222: 'int',
+    226: 'list', 231: 'long long', 241: 'map', 245: 'Matrix4x4f', 256: 'MdFour',
+    263: 'MonoBehaviour', 277: 'MonoScript', 288: 'm_ByteSize', 299: 'm_Curve',
+    307: 'm_EditorClassIdentifier', 331: 'm_EditorHideFlags', 349: 'm_Enabled',
+    359: 'm_ExtensionPtr', 374: 'm_GameObject', 387: 'm_Index', 395: 'm_IsArray',
+    405: 'm_IsStatic', 416: 'm_MetaFlag', 427: 'm_Name', 434: 'm_ObjectHideFlags',
+    452: 'm_PrefabInternal', 469: 'm_PrefabParentObject', 490: 'm_Script',
+    499: 'm_StaticEditorFlags', 519: 'm_Type', 526: 'm_Version', 536: 'Object', 543: 'pair',
+    548: 'PPtr<Component>', 564: 'PPtr<GameObject>', 581: 'PPtr<Material>',
+    596: 'PPtr<MonoBehaviour>', 616: 'PPtr<MonoScript>', 633: 'PPtr<Object>',
+    646: 'PPtr<Prefab>', 659: 'PPtr<Sprite>', 672: 'PPtr<TextAsset>', 688: 'PPtr<Texture>',
+    702: 'PPtr<Texture2D>', 718: 'PPtr<Transform>', 734: 'Prefab', 741: 'Quaternionf',
+    753: 'Rectf', 759: 'RectInt', 767: 'RectOffset', 778: 'second', 785: 'set', 789: 'short',
+    795: 'size', 800: 'SInt16', 807: 'SInt32', 814: 'SInt64', 821: 'SInt8', 827: 'staticvector',
+    840: 'string', 847: 'TextAsset', 857: 'TextMesh', 866: 'Texture', 874: 'Texture2D',
+    884: 'Transform', 894: 'TypelessData', 907: 'UInt16', 914: 'UInt32', 921: 'UInt64',
+    928: 'UInt8', 934: 'unsigned int', 947: 'unsigned long long', 966: 'unsigned short',
+    981: 'vector', 988: 'Vector2f', 997: 'Vector3f', 1006: 'Vector4f',
+    1015: 'm_ScriptingClassIdentifier', 1042: 'Gradient', 1051: 'Type*', 1057: 'int2_storage',
+    1070: 'int3_storage', 1083: 'BoundsInt', 1093: 'm_CorrespondingSourceObject',
+    1121: 'm_PrefabInstance', 1138: 'm_PrefabAsset', 1152: 'FileSize', 1161: 'Hash128',
+    1169: 'RenderingLayerMask', 1188: 'fixed_array', 1200: 'EntityId',
+    1209: 'LoadableObjectId', 1226: 'LoadableSceneId',
+  };
+})(typeof globalThis !== 'undefined' ? globalThis : this);

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

@@ -0,0 +1,197 @@
+// ============================================================================
+// lib/dxt.js —— BC/DXT 家族纹理解码（BC1/DXT1、BC3/DXT5、BC4、BC5）
+//
+// 为什么需要：Unity 的 PC/主机资源包常用 BC 系列（Unity TextureFormat 10=DXT1、12=DXT5、
+//   26=BC4、27=BC5），而移动端资源包用 ETC2。两类资源包都可能出现在同一批素材里，
+//   缺哪一种都会让"整个模型不可用"（纹理解不出来 → 舞台拿不到贴图）。
+//
+// 挂载：globalThis.__ULB__.dxt = { decodeBc1, decodeBc3, decodeBc4, decodeBc5 }
+//
+// 实现要点（都是块式压缩，逐 4×4 块解）：
+//   · BC1：每块 8 字节 = 两个 RGB565 端点 + 32 位 2bit 索引；c0>c1 为 4 色模式，
+//     否则 3 色 + 透明（用于 1bit alpha）。
+//   · BC3：每块 16 字节 = 8 字节 alpha 块（a0/a1 + 48 位 3bit 索引）+ 8 字节颜色块（同 BC1 的 4 色模式）。
+//   · BC4：单通道，就是 BC3 的 alpha 块（8 字节）。
+//   · BC5：双通道，两个 BC4 alpha 块（16 字节）→ R/G，B 置 0、A 置 255。
+//   · 所有解码都按行优先输出 RGBA，边缘块不足 4×4 时只写落在图内的像素。
+// ============================================================================
+
+'use strict';
+
+{
+  /** 5:6:5 → 8:8:8（按位扩展，与 GPU 的端点插值一致：复制高位） */
+  function r5g6b5(v) {
+    const r = (v >> 11) & 0x1f;
+    const g = (v >> 5) & 0x3f;
+    const b = v & 0x1f;
+    return [(r << 3) | (r >> 2), (g << 2) | (g >> 4), (b << 3) | (b >> 2)];
+  }
+
+  function u16(d, o) { return d[o] | (d[o + 1] << 8); }
+
+  /**
+   * 解一个 BC1 颜色块（8 字节）到 4×4 的 RGBA 输出。
+   * @param {Uint8Array} d 压缩数据
+   * @param {number} o 块起始偏移
+   * @param {boolean} fourColorOnly true 时强制 4 色模式（BC3 的颜色块用）
+   * @returns {{colors:number[][], idx:number[]}} colors 为 4 个 [r,g,b,a]
+   */
+  function readColorBlock(d, o, fourColorOnly) {
+    const c0 = u16(d, o);
+    const c1 = u16(d, o + 2);
+    const p0 = r5g6b5(c0);
+    const p1 = r5g6b5(c1);
+    let colors;
+    if (fourColorOnly || c0 > c1) {
+      // 4 色模式：p2 = (2*p0 + p1)/3，p3 = (p0 + 2*p1)/3
+      colors = [
+        [p0[0], p0[1], p0[2], 255],
+        [p1[0], p1[1], p1[2], 255],
+        [(2 * p0[0] + p1[0]) / 3 | 0, (2 * p0[1] + p1[1]) / 3 | 0, (2 * p0[2] + p1[2]) / 3 | 0, 255],
+        [(p0[0] + 2 * p1[0]) / 3 | 0, (p0[1] + 2 * p1[1]) / 3 | 0, (p0[2] + 2 * p1[2]) / 3 | 0, 255],
+      ];
+    } else {
+      // 3 色 + 透明模式：p2 = (p0+p1)/2，p3 = 全透明
+      colors = [
+        [p0[0], p0[1], p0[2], 255],
+        [p1[0], p1[1], p1[2], 255],
+        [(p0[0] + p1[0]) / 2 | 0, (p0[1] + p1[1]) / 2 | 0, (p0[2] + p1[2]) / 2 | 0, 255],
+        [0, 0, 0, 0],
+      ];
+    }
+    const bits = d[o + 4] | (d[o + 5] << 8) | (d[o + 6] << 16) | (d[o + 7] << 24);
+    const idx = new Array(16);
+    for (let i = 0; i < 16; i++) idx[i] = (bits >>> (i * 2)) & 0x3;
+    return { colors, idx };
+  }
+
+  /**
+   * 解一个 alpha 块（8 字节）到 16 个 0~255 的 alpha 值（BC3/BC4 共用）。
+   *   a0 > a1：8 档线性插值；a0 <= a1：6 档插值 + 0 与 255 两个极值。
+   */
+  function readAlphaBlock(d, o) {
+    const a0 = d[o];
+    const a1 = d[o + 1];
+    const table = new Array(8);
+    table[0] = a0;
+    table[1] = a1;
+    if (a0 > a1) {
+      for (let i = 1; i <= 6; i++) table[i + 1] = ((7 - i) * a0 + i * a1) / 7 | 0;
+    } else {
+      for (let i = 1; i <= 4; i++) table[i + 1] = ((5 - i) * a0 + i * a1) / 5 | 0;
+      table[6] = 0;
+      table[7] = 255;
+    }
+    // 48 位、每像素 3bit 的索引（跨 6 字节）
+    const out = new Array(16);
+    let acc = 0;
+    let bits = 0;
+    let p = o + 2;
+    for (let i = 0; i < 16; i++) {
+      while (bits < 3) { acc |= d[p++] << bits; bits += 8; }
+      out[i] = table[acc & 7];
+      acc >>>= 3;
+      bits -= 3;
+    }
+    return out;
+  }
+
+  /** 把 4×4 块的像素写进 RGBA 输出（自动裁剪到图内） */
+  function writeBlock(out, width, height, bx, by, pixels) {
+    for (let y = 0; y < 4; y++) {
+      const py = by * 4 + y;
+      if (py >= height) break;
+      for (let x = 0; x < 4; x++) {
+        const px = bx * 4 + x;
+        if (px >= width) break;
+        const p = pixels[y * 4 + x];
+        const o = (py * width + px) * 4;
+        out[o] = p[0];
+        out[o + 1] = p[1];
+        out[o + 2] = p[2];
+        out[o + 3] = p[3];
+      }
+    }
+  }
+
+  /** 解 DXT1/BC1（每块 8 字节） */
+  function decodeBc1(data, width, height) {
+    const bw = Math.ceil(width / 4);
+    const bh = Math.ceil(height / 4);
+    const need = bw * bh * 8;
+    if (data.length < need) throw NS.errors.fail('ULB_ERR_TEX_DATA_SHORT', `DXT1 数据不足：需要 ${need} 字节，实际 ${data.length}`);
+    const out = new Uint8Array(width * height * 4);
+    for (let by = 0; by < bh; by++) {
+      for (let bx = 0; bx < bw; bx++) {
+        const { colors, idx } = readColorBlock(data, (by * bw + bx) * 8, false);
+        const pixels = new Array(16);
+        for (let i = 0; i < 16; i++) pixels[i] = colors[idx[i]];
+        writeBlock(out, width, height, bx, by, pixels);
+      }
+    }
+    return out;
+  }
+
+  /** 解 DXT5/BC3（每块 16 字节 = alpha 块 + 颜色块） */
+  function decodeBc3(data, width, height) {
+    const bw = Math.ceil(width / 4);
+    const bh = Math.ceil(height / 4);
+    const need = bw * bh * 16;
+    if (data.length < need) throw NS.errors.fail('ULB_ERR_TEX_DATA_SHORT', `DXT5 数据不足：需要 ${need} 字节，实际 ${data.length}`);
+    const out = new Uint8Array(width * height * 4);
+    for (let by = 0; by < bh; by++) {
+      for (let bx = 0; bx < bw; bx++) {
+        const o = (by * bw + bx) * 16;
+        const alphas = readAlphaBlock(data, o);
+        const { colors, idx } = readColorBlock(data, o + 8, true);
+        const pixels = new Array(16);
+        for (let i = 0; i < 16; i++) {
+          const c = colors[idx[i]];
+          pixels[i] = [c[0], c[1], c[2], alphas[i]];
+        }
+        writeBlock(out, width, height, bx, by, pixels);
+      }
+    }
+    return out;
+  }
+
+  /** 解 BC4（单通道，每块 8 字节）：R=通道值，G/B=0，A=255 */
+  function decodeBc4(data, width, height) {
+    const bw = Math.ceil(width / 4);
+    const bh = Math.ceil(height / 4);
+    const need = bw * bh * 8;
+    if (data.length < need) throw NS.errors.fail('ULB_ERR_TEX_DATA_SHORT', `BC4 数据不足：需要 ${need} 字节，实际 ${data.length}`);
+    const out = new Uint8Array(width * height * 4);
+    for (let by = 0; by < bh; by++) {
+      for (let bx = 0; bx < bw; bx++) {
+        const vals = readAlphaBlock(data, (by * bw + bx) * 8);
+        const pixels = vals.map((v) => [v, 0, 0, 255]);
+        writeBlock(out, width, height, bx, by, pixels);
+      }
+    }
+    return out;
+  }
+
+  /** 解 BC5（双通道，每块 16 字节 = 两个 BC4 块）：R/G=两通道，B=0，A=255 */
+  function decodeBc5(data, width, height) {
+    const bw = Math.ceil(width / 4);
+    const bh = Math.ceil(height / 4);
+    const need = bw * bh * 16;
+    if (data.length < need) throw NS.errors.fail('ULB_ERR_TEX_DATA_SHORT', `BC5 数据不足：需要 ${need} 字节，实际 ${data.length}`);
+    const out = new Uint8Array(width * height * 4);
+    for (let by = 0; by < bh; by++) {
+      for (let bx = 0; bx < bw; bx++) {
+        const o = (by * bw + bx) * 16;
+        const r = readAlphaBlock(data, o);
+        const g = readAlphaBlock(data, o + 8);
+        const pixels = new Array(16);
+        for (let i = 0; i < 16; i++) pixels[i] = [r[i], g[i], 0, 255];
+        writeBlock(out, width, height, bx, by, pixels);
+      }
+    }
+    return out;
+  }
+
+  const NS = (globalThis.__ULB__ = globalThis.__ULB__ || {});
+  NS.dxt = { decodeBc1, decodeBc3, decodeBc4, decodeBc5 };
+}

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

@@ -0,0 +1,71 @@
+// ============================================================================
+// lib/errors.js —— 插件错误码表 + 带码的失败构造器
+//
+// 为什么需要：只给中文 message 时，调用方（新前端/其它程序）无法**程序化区分**失败类型——
+//   做重试、降级、提示都只能靠字符串匹配（脆、且随文案变化而失效）。
+//   这里给每类失败一个**稳定错误码**（大写蛇形 + ULB_ERR_ 前缀），message 仍保留中文可读说明。
+//
+// 稳定性约定：
+//   · 码按「失败类别」定义，**不按行号/临时条件生成**；同一失败原因永远同一码。
+//   · 已发布的码不删不改（需要区分新情况时**新增**码）。
+//   · 错误对象上：err.code（稳定码）+ err.message（中文可读）+ err.ulb = true（便于跨层识别）。
+//
+// 挂载：globalThis.__ULB__.errors = { CODES, fail, isUlbError, codeOf }
+// ============================================================================
+
+'use strict';
+
+{
+  /** 稳定错误码表（值即码本身；键用于文档与自检遍历） */
+  const CODES = {
+    BAD_ARGS: 'ULB_ERR_BAD_ARGS',                       // 调用参数缺失/非法（缺 rootId/rel 等）
+    IO: 'ULB_ERR_IO',                                   // 读取资源失败（宿主取文件失败、HTTP 非 2xx、超时）
+    NO_FILE: 'ULB_ERR_NO_FILE',                         // 目标文件不存在/为空（路径对但文件没有）
+    NOT_UNITYFS: 'ULB_ERR_NOT_UNITYFS',                 // 文件不是 UnityFS 容器
+    NO_CAB: 'ULB_ERR_NO_CAB',                           // 容器里没有 CAB-* 节点（不是资产包）
+    CONTAINER_PARSE: 'ULB_ERR_CONTAINER_PARSE',         // 容器/序列化/类型树解析失败（数据布局不符该版本）
+    LZMA_FAIL: 'ULB_ERR_LZMA_FAIL',                     // LZMA 解压失败（数据损坏 / 解出长度与声明不符）
+    LZMA_UNAVAILABLE: 'ULB_ERR_LZMA_UNAVAILABLE',       // LZMA 解码器未加载（lib/lzma-d-min.js 未按序声明）
+    EXTRACT: 'ULB_ERR_EXTRACT',                         // 从对象表抽取资产失败（缺 .resS、越界等）
+    TEXTURE_FORMAT_UNSUPPORTED: 'ULB_ERR_TEX_FORMAT_UNSUPPORTED',   // 纹理格式未实现
+    TEXTURE_DATA_SHORT: 'ULB_ERR_TEX_DATA_SHORT',       // 纹理压缩数据不足（截断/尺寸不符）
+    TEXTURE_DECODE: 'ULB_ERR_TEX_DECODE',               // 纹理解码失败（其余原因）
+    CURVE_BINDING_MISMATCH: 'ULB_ERR_CURVE_BINDING_MISMATCH',       // 曲线数与绑定数不一致
+    STREAMED_CLIP_INVALID: 'ULB_ERR_STREAMED_CLIP_INVALID',         // StreamedClip 结构异常
+    MODEL_BUILD: 'ULB_ERR_MODEL_BUILD',                 // 拼装可渲染模型失败（缺 moc3/贴图等）
+    NO_HOST: 'ULB_ERR_NO_HOST',                         // 宿主能力面缺失（§3.6：fetchFile 不可用且 file.bytes 缺失，可退化）
+    EXPORT_NO_SPACE: 'ULB_ERR_EXPORT_NO_SPACE',           // 导出：磁盘剩余不足（预估 ×1.5 仍不够）
+    EXPORT_INTERRUPTED: 'ULB_ERR_EXPORT_INTERRUPTED',     // 导出：被 SIGINT/SIGTERM 中断（临时目录已清理）
+  };
+
+  /**
+   * 构造一个带稳定错误码的 Error。
+   * @param {string} code CODES 里的码
+   * @param {string} message 中文可读说明
+   * @param {object} [extra] 附加字段（会挂到 err 上，便于调用方取上下文，如 { texture: 'texture_00' }）
+   */
+  function fail(code, message, extra) {
+    const err = new Error(message);
+    err.code = code;
+    err.ulb = true;
+    if (extra && typeof extra === 'object') {
+      for (const k of Object.keys(extra)) {
+        if (k !== 'code' && k !== 'message' && k !== 'ulb') err[k] = extra[k];
+      }
+    }
+    return err;
+  }
+
+  /** 是否本插件产出的带码错误 */
+  function isUlbError(e) {
+    return Boolean(e && e.ulb === true && typeof e.code === 'string');
+  }
+
+  /** 取错误码（非本插件的错误返回 null，便于调用方区分） */
+  function codeOf(e) {
+    return isUlbError(e) ? e.code : null;
+  }
+
+  const NS = (globalThis.__ULB__ = globalThis.__ULB__ || {});
+  NS.errors = { CODES, fail, isUlbError, codeOf };
+}