@threenative/ueformat 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ThreeNative contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @threenative/ueformat
+
+A strict UEFormat v10 `.uemodel` parser and Three.js loader for assets exported from Unreal
+packages by CUE4Parse/FModel.
+
+```text
+.uasset / .uexp / .ubulk / .pak / .utoc
+                  ↓ CUE4Parse
+              .uemodel
+                  ↓ this package
+     BufferGeometry / Mesh / LOD / Group
+```
+
+This package does **not** pretend that an isolated `.uasset` is a self-contained mesh. It handles
+the stable interchange boundary: CUE4Parse extracts UE4/UE5 packages, then this loader validates
+and constructs renderable Three.js objects.
+
+## Supported
+
+- UEFormat v10 `UEMODEL` headers and named attribute sets
+- uncompressed, GZIP, and injected-decoder ZSTD bodies
+- static and skeletal mesh LOD records
+- positions, normals, tangents, indices, multiple UV/color channels
+- material sections as `BufferGeometry.groups`
+- sparse morph targets
+- skin indices/weights and skeleton metadata parsing
+- sockets, virtual bones, and convex collision geometry
+- Unreal centimeters/Z-up/left-handed coordinates to Three.js meters/Y-up/right-handed coordinates
+- automatic winding and tangent-sign repair
+- browser `Loader.load`, synchronous `parse`, and `ueformat-inspect` CLI validation
+
+## Not implemented
+
+- **Automatic texture/material extraction** — `.uemodel` carries material *slots* (name, path,
+  index range), not texture payloads. Resolve textures through your own pipeline (the asset MCP
+  does this) and supply materials through `materialFactory`.
+- **Skeletal binding** — parsed bones, sockets and skin weights are exposed on `userData` and as
+  `skinIndex`/`skinWeight` attributes, but the package never constructs a `THREE.SkinnedMesh` or
+  binds a skeleton. That is deliberately left to the game; nothing here invents it.
+- ZSTD bodies require an injected `zstdDecoder` — the package never bundles a ZSTD implementation.
+
+## The look is the game's
+
+Every material comes from the game through `materialFactory`. The fallback matches three.js's own
+`GLTFLoader`: a plain `MeshStandardMaterial` named after the slot. No colour, roughness, or
+metalness is decided here.
+
+## Provenance
+
+Absorbed from the standalone `three-ueformat-loader` package (MIT, ThreeNative contributors, 2026)
+into the engine. The parser is pure TypeScript with no browser or Node globals — the same code runs
+in the browser, in Node, and on the native arm.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,567 @@
+#!/usr/bin/env node
+import { readFile } from 'fs/promises';
+import { gunzipSync } from 'fflate';
+
+// src/errors.ts
+var UEFormatError = class extends Error {
+  code;
+  offset;
+  constructor(code, message, offset = -1, cause) {
+    super(message, cause === void 0 ? void 0 : { cause });
+    this.name = "UEFormatError";
+    this.code = code;
+    this.offset = offset;
+  }
+};
+
+// src/binary.ts
+var BinaryReader = class _BinaryReader {
+  bytes;
+  limits;
+  baseOffset;
+  view;
+  offset = 0;
+  constructor(bytes, limits, baseOffset = 0) {
+    this.bytes = bytes;
+    this.limits = limits;
+    this.baseOffset = baseOffset;
+    this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  }
+  get remaining() {
+    return this.bytes.length - this.offset;
+  }
+  get absoluteOffset() {
+    return this.baseOffset + this.offset;
+  }
+  ensure(size) {
+    if (!Number.isSafeInteger(size) || size < 0 || size > this.remaining) {
+      throw new UEFormatError(
+        "TRUNCATED_FILE",
+        `Need ${size} byte(s), but only ${this.remaining} remain`,
+        this.absoluteOffset
+      );
+    }
+  }
+  uint8() {
+    this.ensure(1);
+    return this.view.getUint8(this.offset++);
+  }
+  bool() {
+    const value = this.uint8();
+    if (value > 1) {
+      throw new UEFormatError(
+        "INVALID_LENGTH",
+        `Invalid boolean value ${value}`,
+        this.absoluteOffset - 1
+      );
+    }
+    return value === 1;
+  }
+  uint16() {
+    this.ensure(2);
+    const value = this.view.getUint16(this.offset, true);
+    this.offset += 2;
+    return value;
+  }
+  int32() {
+    this.ensure(4);
+    const value = this.view.getInt32(this.offset, true);
+    this.offset += 4;
+    return value;
+  }
+  uint32() {
+    this.ensure(4);
+    const value = this.view.getUint32(this.offset, true);
+    this.offset += 4;
+    return value;
+  }
+  float32() {
+    this.ensure(4);
+    const value = this.view.getFloat32(this.offset, true);
+    this.offset += 4;
+    return value;
+  }
+  raw(size) {
+    this.ensure(size);
+    const result = this.bytes.subarray(this.offset, this.offset + size);
+    this.offset += size;
+    return result;
+  }
+  fixedString(size) {
+    return new TextDecoder("utf-8", { fatal: true }).decode(this.raw(size)).replace(/\0+$/, "");
+  }
+  string() {
+    const start = this.absoluteOffset;
+    const size = this.int32();
+    if (size < 0 || size > this.limits.maxStringBytes) {
+      throw new UEFormatError("INVALID_LENGTH", `Invalid string byte length ${size}`, start);
+    }
+    try {
+      return new TextDecoder("utf-8", { fatal: true }).decode(this.raw(size)).replace(/\0+$/, "");
+    } catch (error) {
+      if (error instanceof UEFormatError) throw error;
+      throw new UEFormatError("INVALID_LENGTH", "String is not valid UTF-8", start, error);
+    }
+  }
+  count(label) {
+    const start = this.absoluteOffset;
+    const count = this.int32();
+    if (count < 0 || count > this.limits.maxArrayElements) {
+      throw new UEFormatError("INVALID_COUNT", `Invalid ${label} count ${count}`, start);
+    }
+    return count;
+  }
+  vector2() {
+    return { u: this.float32(), v: this.float32() };
+  }
+  vector3() {
+    return { x: this.float32(), y: this.float32(), z: this.float32() };
+  }
+  quaternion() {
+    return { ...this.vector3(), w: this.float32() };
+  }
+  array(label, read) {
+    const count = this.count(label);
+    const values = new Array(count);
+    for (let index = 0; index < count; index++) values[index] = read(this, index);
+    return values;
+  }
+  chunk(size) {
+    const start = this.absoluteOffset;
+    return new _BinaryReader(this.raw(size), this.limits, start);
+  }
+};
+function toUint8Array(input) {
+  return input instanceof ArrayBuffer ? new Uint8Array(input) : new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+}
+function crc32(bytes) {
+  let crc = 4294967295;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit++) {
+      crc = crc >>> 1 ^ 3988292384 & -(crc & 1);
+    }
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+function validateGzipTrailer(compressed, decoded) {
+  if (compressed.length < 18)
+    throw new TypeError("GZIP payload is shorter than its minimum header and trailer");
+  const trailer = new DataView(
+    compressed.buffer,
+    compressed.byteOffset + compressed.byteLength - 8,
+    8
+  );
+  const expectedCrc = trailer.getUint32(0, true);
+  const expectedSize = trailer.getUint32(4, true);
+  if (crc32(decoded) !== expectedCrc || decoded.length >>> 0 !== expectedSize) {
+    throw new TypeError("GZIP CRC32 or ISIZE trailer check failed");
+  }
+}
+function decompressBody(format, compressed, uncompressedSize, zstdDecoder) {
+  let result;
+  try {
+    if (format === "GZIP") {
+      result = gunzipSync(compressed);
+      validateGzipTrailer(compressed, result);
+    } else if (format === "ZSTD") {
+      if (!zstdDecoder) {
+        throw new UEFormatError(
+          "INVALID_COMPRESSION",
+          "ZSTD body requires ParseUEModelOptions.zstdDecoder"
+        );
+      }
+      result = zstdDecoder(compressed, uncompressedSize);
+      if (!(result instanceof Uint8Array)) {
+        throw new TypeError("ZSTD decoder must return Uint8Array");
+      }
+    } else {
+      throw new UEFormatError(
+        "INVALID_COMPRESSION",
+        `Unsupported compression format ${JSON.stringify(format)}`
+      );
+    }
+  } catch (error) {
+    if (error instanceof UEFormatError) throw error;
+    throw new UEFormatError(
+      "DECOMPRESSION_FAILED",
+      `Failed to decompress ${format} body`,
+      -1,
+      error
+    );
+  }
+  if (result.length !== uncompressedSize) {
+    throw new UEFormatError(
+      "SIZE_MISMATCH",
+      `Decoded body has ${result.length} byte(s); header declares ${uncompressedSize}`
+    );
+  }
+  return result;
+}
+
+// src/parser.ts
+var DEFAULT_LIMITS = {
+  maxStringBytes: 16 * 1024 * 1024,
+  maxArrayElements: 5e7,
+  maxAttributes: 1e5
+};
+function readAttributes(reader, handlers, unknown) {
+  const count = reader.int32();
+  if (count < 0 || count > reader.limits.maxAttributes) {
+    throw new UEFormatError(
+      "INVALID_COUNT",
+      `Invalid attribute count ${count}`,
+      reader.absoluteOffset - 4
+    );
+  }
+  for (let index = 0; index < count; index++) {
+    const name = reader.string();
+    const byteSizeOffset = reader.absoluteOffset;
+    const byteSize = reader.int32();
+    if (byteSize < 0) {
+      throw new UEFormatError(
+        "INVALID_LENGTH",
+        `Invalid byte size ${byteSize} for attribute ${name}`,
+        byteSizeOffset
+      );
+    }
+    const payload = reader.chunk(byteSize);
+    const handler = handlers[name];
+    if (!handler) {
+      unknown.push(name);
+      continue;
+    }
+    handler(payload);
+    if (payload.remaining !== 0) {
+      throw new UEFormatError(
+        "ATTRIBUTE_SIZE_MISMATCH",
+        `Attribute ${name} has ${payload.remaining} unread byte(s)`,
+        payload.absoluteOffset
+      );
+    }
+  }
+}
+function readVectorArray(reader, label) {
+  return reader.array(label, (item) => item.vector3());
+}
+function readLod(reader) {
+  const lod = {
+    name: reader.string(),
+    vertices: [],
+    normals: [],
+    tangents: [],
+    texCoords: [],
+    indices: [],
+    vertexColors: [],
+    materials: [],
+    weights: [],
+    morphTargets: [],
+    unknownAttributes: []
+  };
+  readAttributes(
+    reader,
+    {
+      VERTICES(payload) {
+        lod.vertices = readVectorArray(payload, "vertex");
+      },
+      INDICES(payload) {
+        lod.indices = payload.array("index", (item) => item.uint32());
+      },
+      NORMALS(payload) {
+        lod.normals = payload.array("normal", (item) => ({
+          binormalSign: item.float32(),
+          ...item.vector3()
+        }));
+      },
+      TANGENTS(payload) {
+        lod.tangents = readVectorArray(payload, "tangent");
+      },
+      TEXCOORDS(payload) {
+        lod.texCoords = payload.array("texture-coordinate channel", (item) => ({
+          name: item.string(),
+          uvs: item.array("texture coordinate", (uvReader) => uvReader.vector2())
+        }));
+      },
+      VERTEXCOLORS(payload) {
+        lod.vertexColors = payload.array("vertex-color channel", (item) => ({
+          name: item.string(),
+          colors: item.array("vertex color", (colorReader) => ({
+            r: colorReader.uint8(),
+            g: colorReader.uint8(),
+            b: colorReader.uint8(),
+            a: colorReader.uint8()
+          }))
+        }));
+      },
+      MATERIALS(payload) {
+        lod.materials = payload.array("material", (item) => ({
+          materialName: item.string(),
+          materialPath: item.string(),
+          firstIndex: item.int32(),
+          numFaces: item.int32()
+        }));
+      },
+      WEIGHTS(payload) {
+        lod.weights = payload.array("weight", (item) => ({
+          boneIndex: item.uint16(),
+          vertexIndex: item.int32(),
+          weight: item.float32()
+        }));
+      },
+      MORPHTARGETS(payload) {
+        lod.morphTargets = payload.array("morph target", (item) => ({
+          name: item.string(),
+          deltas: item.array("morph delta", (deltaReader) => ({
+            positionDelta: deltaReader.vector3(),
+            tangentZDelta: deltaReader.vector3(),
+            vertexIndex: deltaReader.uint32()
+          }))
+        }));
+      }
+    },
+    lod.unknownAttributes
+  );
+  return lod;
+}
+function readBone(reader) {
+  return {
+    name: reader.string(),
+    parentIndex: reader.int32(),
+    position: reader.vector3(),
+    orientation: reader.quaternion(),
+    scale: reader.vector3()
+  };
+}
+function readSkeleton(reader) {
+  const skeleton = {
+    metadata: "",
+    bones: [],
+    sockets: [],
+    virtualBones: [],
+    unknownAttributes: []
+  };
+  readAttributes(
+    reader,
+    {
+      METADATA(payload) {
+        skeleton.metadata = payload.string();
+      },
+      BONES(payload) {
+        skeleton.bones = payload.array("bone", (item) => readBone(item));
+      },
+      SOCKETS(payload) {
+        skeleton.sockets = payload.array("socket", (item) => ({
+          name: item.string(),
+          boneName: item.string(),
+          relativeLocation: item.vector3(),
+          relativeRotation: item.quaternion(),
+          relativeScale: item.vector3()
+        }));
+      },
+      VIRTUALBONES(payload) {
+        skeleton.virtualBones = payload.array("virtual bone", (item) => ({
+          sourceBoneName: item.string(),
+          targetBoneName: item.string(),
+          virtualBoneName: item.string()
+        }));
+      }
+    },
+    skeleton.unknownAttributes
+  );
+  return skeleton;
+}
+function readCollision(reader) {
+  return {
+    name: reader.string(),
+    vertices: readVectorArray(reader, "collision vertex"),
+    indices: reader.array("collision index", (item) => item.uint32())
+  };
+}
+function parseUEModel(input, options = {}) {
+  const limits = {
+    maxStringBytes: options.maxStringBytes ?? DEFAULT_LIMITS.maxStringBytes,
+    maxArrayElements: options.maxArrayElements ?? DEFAULT_LIMITS.maxArrayElements,
+    maxAttributes: options.maxAttributes ?? DEFAULT_LIMITS.maxAttributes
+  };
+  const reader = new BinaryReader(toUint8Array(input), limits);
+  const magic = reader.fixedString(8);
+  if (magic !== "UEFORMAT") {
+    throw new UEFormatError(
+      "INVALID_MAGIC",
+      `Expected UEFORMAT, received ${JSON.stringify(magic)}`,
+      0
+    );
+  }
+  const identifier = reader.string();
+  if (identifier !== "UEMODEL") {
+    throw new UEFormatError(
+      "INVALID_IDENTIFIER",
+      `Expected UEMODEL, received ${JSON.stringify(identifier)}`,
+      8
+    );
+  }
+  const fileVersion = reader.uint8();
+  if (fileVersion !== 10) {
+    throw new UEFormatError(
+      "UNSUPPORTED_VERSION",
+      `Only UEFormat v10 is supported; received v${fileVersion}`,
+      reader.absoluteOffset - 1
+    );
+  }
+  const objectName = reader.string();
+  const objectPath = reader.string();
+  const compressed = reader.bool();
+  let bodyReader = reader;
+  let compression = null;
+  if (compressed) {
+    const format = reader.string();
+    const uncompressedSize = reader.int32();
+    const compressedSize = reader.int32();
+    if (uncompressedSize < 0 || compressedSize < 0) {
+      throw new UEFormatError(
+        "INVALID_LENGTH",
+        "Compression sizes must be non-negative",
+        reader.absoluteOffset - 8
+      );
+    }
+    if (compressedSize !== reader.remaining) {
+      throw new UEFormatError(
+        "SIZE_MISMATCH",
+        `Compressed body has ${reader.remaining} byte(s); header declares ${compressedSize}`,
+        reader.absoluteOffset
+      );
+    }
+    if (format !== "GZIP" && format !== "ZSTD") {
+      throw new UEFormatError(
+        "INVALID_COMPRESSION",
+        `Unsupported compression format ${JSON.stringify(format)}`,
+        reader.absoluteOffset
+      );
+    }
+    const decoded = decompressBody(
+      format,
+      reader.raw(compressedSize),
+      uncompressedSize,
+      options.zstdDecoder
+    );
+    bodyReader = new BinaryReader(decoded, limits);
+    compression = { format, uncompressedSize, compressedSize };
+  }
+  const header = {
+    magic: "UEFORMAT",
+    identifier: "UEMODEL",
+    fileVersion: 10,
+    objectName,
+    objectPath,
+    compression
+  };
+  const model = {
+    header,
+    lods: [],
+    skeleton: null,
+    collision: [],
+    unknownAttributes: []
+  };
+  readAttributes(
+    bodyReader,
+    {
+      LODS(payload) {
+        model.lods = payload.array("LOD", (item) => readLod(item));
+      },
+      SKELETON(payload) {
+        model.skeleton = readSkeleton(payload);
+      },
+      COLLISION(payload) {
+        model.collision = payload.array("collision mesh", (item) => readCollision(item));
+      }
+    },
+    model.unknownAttributes
+  );
+  if (bodyReader.remaining !== 0) {
+    throw new UEFormatError(
+      "ATTRIBUTE_SIZE_MISMATCH",
+      `Model has ${bodyReader.remaining} trailing byte(s)`,
+      bodyReader.absoluteOffset
+    );
+  }
+  return model;
+}
+
+// src/summary.ts
+function summarizeUEModel(model) {
+  return {
+    objectName: model.header.objectName,
+    objectPath: model.header.objectPath,
+    formatVersion: model.header.fileVersion,
+    compression: model.header.compression?.format ?? null,
+    lods: model.lods.map((lod) => ({
+      name: lod.name,
+      vertices: lod.vertices.length,
+      triangles: lod.indices.length / 3,
+      materials: lod.materials.map((material) => material.materialName),
+      uvChannels: lod.texCoords.map((channel) => channel.name),
+      vertexColorChannels: lod.vertexColors.map((channel) => channel.name),
+      weights: lod.weights.length,
+      morphTargets: lod.morphTargets.map((target) => target.name)
+    })),
+    skeleton: model.skeleton === null ? null : {
+      bones: model.skeleton.bones.length,
+      sockets: model.skeleton.sockets.length,
+      virtualBones: model.skeleton.virtualBones.length
+    },
+    collisionMeshes: model.collision.map((collision) => ({
+      name: collision.name,
+      vertices: collision.vertices.length,
+      triangles: collision.indices.length / 3
+    })),
+    unknownAttributes: [
+      ...model.unknownAttributes,
+      ...model.lods.flatMap((lod) => lod.unknownAttributes.map((name) => `${lod.name}:${name}`)),
+      ...model.skeleton?.unknownAttributes.map((name) => `SKELETON:${name}`) ?? []
+    ]
+  };
+}
+
+// src/cli.ts
+function usage() {
+  return [
+    "Usage: ueformat-inspect [--json] <file.uemodel>",
+    "",
+    "Validates a UEFormat v10 model and prints a compact summary.",
+    "ZSTD files require using the JavaScript API with an injected decoder."
+  ].join("\n");
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(`${usage()}
+`);
+    return;
+  }
+  const json = args.includes("--json");
+  const path = args.find((argument) => !argument.startsWith("-"));
+  if (!path) {
+    process.stderr.write(`${usage()}
+`);
+    process.exitCode = 2;
+    return;
+  }
+  try {
+    const bytes = await readFile(path);
+    const summary = summarizeUEModel(parseUEModel(bytes));
+    process.stdout.write(`${JSON.stringify(summary, null, json ? 0 : 2)}
+`);
+  } catch (error) {
+    if (error instanceof UEFormatError) {
+      process.stderr.write(
+        `${error.code}: ${error.message}${error.offset >= 0 ? ` (offset ${error.offset})` : ""}
+`
+      );
+    } else {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+    }
+    process.exitCode = 1;
+  }
+}
+await main();