@threenative/raw-unreal 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,102 @@
+# @threenative/raw-unreal
+
+Loads **raw Unreal editor `.uasset` static meshes** directly into three.js geometry — no glTF/GLB/FBX/OBJ conversion step at any point.
+
+```
+raw .uasset → package summary → payload scan → decode → typed arrays → THREE.Mesh
+```
+
+Three serialized source-model layouts are decoded, from four payload stores:
+
+| Layout | Engine generation | Where the data lives |
+|---|---|---|
+| `mesh-description` | UE5.x (`FMeshDescription`, named element containers) | Inline, or inside a UE5 `FCompressedBuffer` package-trailer payload |
+| `mesh-description-ue4` | UE4.2x (`FMeshDescription`, fixed-order containers) | `FByteBulkData`, usually zlib-compressed at the end of the package |
+| `raw-mesh` | UE4.6–UE4.2x (`FRawMesh` source models) | Inline uncompressed, or `FByteBulkData` |
+
+`FByteBulkData` payloads are read wherever the flags put them: inline after the header, at the end
+of the `.uasset` against the summary's `BulkDataStartOffset`, or in a sibling `.ubulk`/`.uptnl`
+file whose bytes the caller supplies through `bulkDataFiles`.
+
+Every path is self-validating: a candidate offset is trusted only after a full parse consumes it
+exactly with every count agreeing, and the summary walk that anchors bulk data is accepted only
+when it ends on the package's own name table. Unsupported layouts throw a typed `UAssetError`
+with a code and details; nothing invents fallback geometry.
+
+## Use
+
+```ts
+import { UAssetLoader } from "@threenative/raw-unreal";
+
+const loader = new UAssetLoader(manager, { parse: { oodle } });
+const mesh = await new Promise((resolve, reject) =>
+  loader.load("/assets/SM_pine01.uasset", resolve, undefined, reject),
+);
+scene.add(mesh); // materials via mesh.userData.unreal.sections / geometry groups
+```
+
+The format layer is independent of three.js until the final adapter:
+
+```ts
+import { parseUAssetStaticMesh } from "@threenative/raw-unreal";
+
+const decoded = parseUAssetStaticMesh(bytes, { oodle });
+// decoded.positions / normals / uvs / indices / sections / bounds / metadata / unreal
+```
+
+## Codec injection and licensing
+
+This package is MIT and **bundles no compression codecs**. UE5 `FCompressedBuffer` payloads are
+commonly Oodle-compressed, and every Oodle decompressor that is known to work in JavaScript is
+GPL-licensed (`ooz-wasm`). To keep the GPL out of this package while keeping the capability
+reachable, the loader takes codecs as call arguments:
+
+```ts
+import { decompress as oodle } from "ooz-wasm"; // GPL-3.0-or-later — the game's choice to make
+
+parseUAssetStaticMesh(bytes, { oodle });
+```
+
+Adding `ooz-wasm` to a game applies that game's GPL obligations to that game's distribution;
+it never touches this package. Uncompressed payloads need no codec, and LZ4 payloads take an
+`lz4(compressed, rawSize)` function the same way. A payload whose codec was not supplied throws
+`MISSING_CODEC` rather than guessing.
+
+UE4 editor bulk data is stored zlib-compressed, which takes a `zlib(compressed, rawSize)` function
+on the same terms — `node:zlib`'s `inflateSync` in Node, any of the small MIT inflate libraries in
+the browser:
+
+```ts
+import { inflateSync } from "node:zlib";
+
+parseUAssetStaticMesh(bytes, { zlib: (data) => new Uint8Array(inflateSync(data)) });
+```
+
+The test suite uses `ooz-wasm` as a **devDependency only** — it decodes the committed fixture and
+ships in no published artifact.
+
+## Fixture provenance
+
+`fixtures/SM_cube.uasset` is a real Unreal Engine 5.7 editor package from the MIT-licensed
+[uassets](https://github.com/1danielcoelho/uassets) sample set, pinned by SHA-256 in the specs —
+see `fixtures/PROVENANCE.md`. The FRawMesh specs run against synthetic packages built in
+`__tests__/fixture-builder.ts`; the real-pack conformance spec runs only when the licensed
+Landscape Pro pack is present on disk and commits nothing from it.
+
+## Current compatibility
+
+**Decoded:** legacy-tag uncooked editor packages (`.uasset`/`.umap`), the package summary prefix
+and the full summary walk (`TotalHeaderSize`, `BulkDataStartOffset`, `FEditorObjectVersion`) for
+`LegacyFileVersion` −3 through −8, UE5 `FCompressedBuffer` payloads (uncompressed/Oodle/LZ4
+methods), UE5 and UE4.2x `FMeshDescription` serializations, UE4-era `FRawMesh` source models,
+`FByteBulkData` payloads stored inline, at the end of the package, or in a supplied sibling file,
+`FArchive::SerializeCompressed` zlib containers, per-wedge positions/normals/UVs, polygon-group
+sections with their `ImportedMaterialSlotName`s from a MeshDescription, Unreal→three.js coordinate
+conversion (`(x, z, −y)`) and winding repair.
+
+**Not decoded (throws, honestly):** IoStore containers (`.utoc`/`.ucas`), PAK archives, cooked
+render buffers, Nanite clusters, skeletal meshes and skin weights, textures and material graphs,
+`LegacyFileVersion` −9 and below (UE 5.5+ replaced the package GUID with a saved hash; the summary
+walk declines rather than guessing, so bulk data in those packages is not reached), material-slot
+*names* from FRawMesh packages (the section indices are real; the names need the package name map),
+and full `.umap` actor reconstruction.

package/dist/index.d.ts

@@ -0,0 +1,428 @@
+import * as three from 'three';
+import { Material, BufferGeometry, Object3D, Loader, LoadingManager } from 'three';
+
+/** Signature of an Oodle decompressor, matching the `decompress(compressed, rawSize)` shape the
+ * common WebAssembly Oodle builds expose. The package never bundles one; see README licensing. */
+type OodleCodec = (compressed: Uint8Array, rawSize: number) => Uint8Array;
+/** Signature of an LZ4 block decompressor. The package never bundles one. */
+type Lz4Codec = (compressed: Uint8Array, rawSize: number) => Uint8Array;
+/** Signature of a zlib (RFC 1950) decompressor, the form editor bulk data is stored in when the
+ * `BULKDATA_SerializeCompressedZLIB` flag is set. The package never bundles one; `node:zlib`'s
+ * `inflateSync` and any of the small browser inflate libraries fit this shape. */
+type ZlibCodec = (compressed: Uint8Array, rawSize: number) => Uint8Array;
+/** Bytes of the package's sibling payload files, for the bulk-data flag that says the payload
+ * was written beside the `.uasset` rather than inside it. The parser stays a pure format layer:
+ * it never opens a file, so a caller that has these bytes hands them over. */
+interface IUAssetBulkDataFiles {
+    uexp?: ArrayBuffer | ArrayBufferView;
+    ubulk?: ArrayBuffer | ArrayBufferView;
+    uptnl?: ArrayBuffer | ArrayBufferView;
+}
+interface IUAssetParseOptions {
+    /** Required for UE5 `FCompressedBuffer` payloads compressed with Oodle (method 3). */
+    oodle?: OodleCodec;
+    /** Required for `FCompressedBuffer` payloads compressed with LZ4 (method 4). */
+    lz4?: Lz4Codec;
+    /** Required for editor bulk data stored with `BULKDATA_SerializeCompressedZLIB`. */
+    zlib?: ZlibCodec;
+    /** Sibling `.uexp`/`.ubulk`/`.uptnl` bytes, when a bulk payload lives outside the package. */
+    bulkDataFiles?: IUAssetBulkDataFiles;
+    /** Convert Unreal's Z-up left-handed coordinates to three.js Y-up. Default true. */
+    convertCoordinates?: boolean;
+    /** Swap each triangle's second and third indices after conversion. Default true. */
+    flipWinding?: boolean;
+    /** Flip texture V so three.js sampling matches Unreal's UV convention. Default false. */
+    flipV?: boolean;
+}
+/** One material draw range, already in output index order. */
+interface IUAssetSection {
+    materialIndex: number;
+    /** The section (polygon-group / face-material) index the package itself records. */
+    sectionIndex: number;
+    /** The package's material-slot name when the layout carries one; otherwise the section index
+     * as a string. Slot-name extraction from FRawMesh packages needs the name map and tagged
+     * properties, which this loader does not walk. */
+    materialName: string;
+    start: number;
+    count: number;
+}
+interface IUAssetBounds {
+    min: readonly [number, number, number];
+    max: readonly [number, number, number];
+}
+interface IUAssetSourceStats {
+    vertices: number;
+    vertexInstances: number;
+    triangles: number;
+}
+/** Which serialized source-model layout the geometry came from. `mesh-description` is the UE5
+ * form, whose element containers carry their own names; `mesh-description-ue4` is the UE4.2x
+ * form, whose containers are a fixed sequence and whose triangles trail the attribute sets. */
+type UAssetMeshLayout = "mesh-description" | "mesh-description-ue4" | "raw-mesh";
+/** Where an `FByteBulkData` payload was stored, per its flags. */
+type UAssetBulkDataStorage = "inline" | "end-of-file" | "separate-file";
+/** Which file the payload bytes were read from. */
+type UAssetBulkDataFile = "uasset" | "uexp" | "ubulk" | "uptnl";
+interface IUAssetBulkDataInfo {
+    /** Byte offset of the `FByteBulkData` header inside the `.uasset`. */
+    headerOffset: number;
+    /** `EBulkDataFlags` exactly as serialized. */
+    flags: number;
+    storage: UAssetBulkDataStorage;
+    file: UAssetBulkDataFile;
+    compression: "none" | "zlib";
+    elementCount: number;
+    /** Bytes the payload occupies on disk, compressed size included. */
+    sizeOnDisk: number;
+    /** The header's own offset field, before the `BulkDataStartOffset` fix-up. */
+    offsetInFile: number;
+    /** Where the payload actually begins in the file it lives in. */
+    payloadOffset: number;
+}
+interface IUAssetMetadata {
+    assetClass: "StaticMesh";
+    engineVersion: string;
+    objectPath: string;
+    packageByteLength: number;
+}
+interface IUAssetCompressedBufferInfo {
+    offset: number;
+    method: number;
+    compressor: number;
+    compressionLevel: number;
+    rawSize: number;
+    compressedSize: number;
+    blockCount: number;
+}
+interface IUAssetUnrealInfo {
+    /** Unreal's legacy package tag, `0x9e2a83c1`. */
+    packageTag: number;
+    /** `FPackageFileSummary.LegacyFileVersion`, negative (−7 for UE4-era, −8 and below for UE5). */
+    legacyFileVersion: number;
+    fileVersionUE4?: number;
+    fileVersionUE5?: number;
+    licenseeVersion?: number;
+    /** `FEditorObjectVersion` from the summary's custom-version list, when present. */
+    editorObjectVersion?: number;
+    layout: UAssetMeshLayout;
+    /** Where the decoded source-model payload was found. `frame` names the coordinate system the
+     * offset is relative to: the package file itself, the buffer left after decompression, or the
+     * resolved bulk-data payload — whose own location is in `bulkData`. */
+    payload: {
+        frame: "package" | "decompressed" | "bulk-data";
+        offset: number;
+        byteLength: number;
+    };
+    compressedBuffer?: IUAssetCompressedBufferInfo;
+    bulkData?: IUAssetBulkDataInfo;
+}
+interface IDecodedUAssetStaticMesh {
+    /** Per-vertex-instance positions, already converted per the parse options. */
+    positions: Float32Array;
+    /** Per-vertex-instance normals, present when the package carries them. */
+    normals: Float32Array | undefined;
+    /** Per-vertex-instance UV set 0. */
+    uvs: Float32Array;
+    indices: Uint16Array | Uint32Array;
+    sections: readonly IUAssetSection[];
+    bounds: IUAssetBounds;
+    metadata: IUAssetMetadata;
+    unreal: IUAssetUnrealInfo;
+    sourceStats: IUAssetSourceStats;
+}
+
+/** Parses a raw Unreal editor `.uasset` into validated, plain static-mesh data — no interchange
+ * conversion, no Three.js objects, no fallback geometry invented for unsupported layouts. */
+declare function parseUAssetStaticMesh(input: ArrayBuffer | ArrayBufferView, options?: IUAssetParseOptions): IDecodedUAssetStaticMesh;
+
+/** Unreal's legacy package tag: every editor `.uasset`/`.umap` starts with it, little-endian. */
+declare const PACKAGE_FILE_TAG = 2653586369;
+interface IPackageSummary {
+    packageTag: number;
+    legacyFileVersion: number;
+    legacyUE3Version: number;
+    fileVersionUE4?: number;
+    fileVersionUE5?: number;
+    licenseeVersion?: number;
+    editorObjectVersion?: number;
+}
+/** Reads the fixed prefix of `FPackageFileSummary` — the legacy tag and the engine version
+ * fields — and locates the `FEditorObjectVersion` custom-version entry. The rest of the summary
+ * (name map, export map, dependency graph) belongs to a full package index; this package's
+ * payload readers locate data by self-validating signature scans instead. */
+declare function readPackageSummary(bytes: Uint8Array): IPackageSummary;
+/**
+ * The parts of `FPackageFileSummary` a bulk-data reader needs: how long the header is, where the
+ * export data that carries `FByteBulkData` headers begins, and where the bulk payload region
+ * starts. `readPackageSummary` deliberately reads only the fixed prefix; this walk reads the
+ * whole summary, which is the only way to learn `BulkDataStartOffset`.
+ */
+interface IPackageLayout extends IPackageSummary {
+    /** End of the package header — the first byte of export data. */
+    totalHeaderSize: number;
+    /** First byte of the bulk-data region, the anchor every end-of-file payload offset is fixed
+     * up against. */
+    bulkDataStartOffset: number;
+    nameCount: number;
+    nameOffset: number;
+    exportCount: number;
+    exportOffset: number;
+}
+/**
+ * Walks the whole `FPackageFileSummary` for the offsets bulk data is addressed against, and
+ * returns `undefined` when the walk cannot be trusted — an unmodelled legacy version, or a
+ * summary that does not end on its own name table. Declining is the point: an offset guessed
+ * from a mis-walked summary would send the bulk reader somewhere plausible and wrong.
+ */
+declare function readPackageLayout(bytes: Uint8Array): IPackageLayout | undefined;
+
+/**
+ * Unreal's `EBulkDataFlags`. Only the bits this reader acts on are named; the rest are carried
+ * through untouched on `IUAssetBulkDataInfo.flags`.
+ */
+declare const BULK_DATA_FLAG: Readonly<{
+    PAYLOAD_AT_END_OF_FILE: 1;
+    SERIALIZE_COMPRESSED_ZLIB: 2;
+    FORCE_INLINE_PAYLOAD: 64;
+    PAYLOAD_IN_SEPARATE_FILE: 256;
+    OPTIONAL_PAYLOAD: 2048;
+    MEMORY_MAPPED_PAYLOAD: 4096;
+    SIZE_64_BIT: 8192;
+    NO_OFFSET_FIX_UP: 65536;
+}>;
+interface IBulkDataHeader extends IUAssetBulkDataInfo {
+    /** First byte after the header — the payload itself for an inline payload. */
+    headerEnd: number;
+}
+/**
+ * Parses one `FByteBulkData` header at `offset`: the flags, the element count and size on disk
+ * (widened to 64 bits when `BULKDATA_Size64Bit` is set), and the offset the payload sits at.
+ * Throws `UAssetError` "INVALID_BULK_DATA" when the fields cannot describe a payload.
+ */
+declare function parseBulkDataHeader(bytes: Uint8Array, offset: number, layout: IPackageLayout): IBulkDataHeader;
+/**
+ * Scans the package's export-data region for `FByteBulkData` headers. Export data is where
+ * Unreal serializes them, so the scan is bounded by the summary's own offsets rather than
+ * sweeping the whole file. Every candidate is decided by `parseBulkDataHeader` plus a range
+ * check against the file the payload claims to live in; anything else is dropped silently,
+ * because a rejected candidate is a byte pattern, not a defect.
+ */
+declare function findBulkDataHeaders(bytes: Uint8Array, layout: IPackageLayout, files?: IUAssetBulkDataFiles): IBulkDataHeader[];
+/**
+ * Inverts `FArchive::SerializeCompressed`: the package tag and the loading chunk size, the
+ * compressed and raw totals, one `FCompressedChunkInfo` per chunk, then the chunk data. The
+ * zlib codec is the caller's; a payload whose codec was not supplied throws `MISSING_CODEC`
+ * rather than returning a partial buffer.
+ */
+declare function decompressBulkData(container: Uint8Array, codecs: {
+    zlib?: ZlibCodec;
+}): Uint8Array;
+/**
+ * Resolves one header's payload bytes: reads them out of the `.uasset`, the sibling file the
+ * flags name, or the compressed container, and hands back plain bytes. Throws
+ * `MISSING_BULK_DATA_FILE` when the payload lives beside the package and the caller did not
+ * supply that file, and `MISSING_CODEC` when it is compressed with a codec that was not.
+ */
+declare function resolveBulkDataPayload(bytes: Uint8Array, header: IBulkDataHeader, options?: {
+    files?: IUAssetBulkDataFiles;
+    zlib?: ZlibCodec;
+}): Uint8Array;
+
+interface IUe4AttributeEntry {
+    name: string;
+    type: string;
+    components: number;
+    numElements: number;
+    values: Float32Array | Int32Array | Uint8Array | string[];
+}
+type Ue4AttributeSet = Map<string, IUe4AttributeEntry>;
+
+interface IUe4MeshDescription {
+    byteLength: number;
+    /** Allocated vertices; `vertexSlots` is how many ids the container spans. */
+    vertexCount: number;
+    vertexSlots: number;
+    validVertexIds: readonly number[];
+    /** Vertex-instance ids the file allocated, ascending. */
+    validVertexInstanceIds: readonly number[];
+    /** Vertex index of each vertex-instance **slot**; unallocated slots hold −1. */
+    vertexInstanceVertices: Int32Array;
+    /** Polygon-group index of each polygon **slot**; unallocated slots hold −1. */
+    polygonGroups: Int32Array;
+    polygonGroupCount: number;
+    /** Triangle ids the file allocated, ascending. */
+    validTriangleIds: readonly number[];
+    /** Three vertex-instance indices per triangle **slot**. */
+    triangleVertexInstances: Int32Array;
+    /** Polygon index of each triangle **slot**. */
+    trianglePolygons: Int32Array;
+    vertexAttributes: Ue4AttributeSet;
+    vertexInstanceAttributes: Ue4AttributeSet;
+    polygonGroupAttributes: Ue4AttributeSet;
+}
+/**
+ * Parses one UE4.2x `FMeshDescription` payload, validating that the walk consumes it exactly and
+ * that every index lands inside the container it references. Throws `UAssetError`
+ * "INVALID_MESH_DESCRIPTION" when anything disagrees; nothing is inferred.
+ */
+declare function parseMeshDescriptionUe4(input: Uint8Array, offset?: number): IUe4MeshDescription;
+/** The serialized signature of a UE4 MeshDescription payload: a vertex allocation bit array
+ * followed by a second one whose own bit count starts exactly where the first one ends. Strong
+ * enough to gate a full parse attempt, not strong enough to trust alone — the parse decides. */
+declare function looksLikeMeshDescriptionUe4(bytes: Uint8Array, offset?: number): boolean;
+
+/** `FCompressedBuffer`'s big-endian magic. */
+declare const COMPRESSED_BUFFER_MAGIC = 3077923682;
+declare const COMPRESSION_METHOD: Readonly<{
+    readonly NONE: 0;
+    readonly OODLE: 3;
+    readonly LZ4: 4;
+}>;
+interface ICompressedBuffer {
+    offset: number;
+    crc32: number;
+    method: number;
+    compressor: number;
+    compressionLevel: number;
+    blockSizeExponent: number;
+    blockCount: number;
+    totalRawSize: number;
+    totalCompressedSize: number;
+    /** BLAKE3 hash the writer recorded; validated by the caller, not here. */
+    rawHash: Uint8Array;
+    blockSizes: readonly number[];
+    payloadBytes: Uint8Array;
+}
+interface IUAssetCodecs {
+    oodle?: OodleCodec;
+    lz4?: Lz4Codec;
+}
+/** Scans for candidate `FCompressedBuffer` magics. Candidates are speculative — the four magic
+ * bytes can appear in a payload — so every candidate goes through the full validating parse. */
+declare function findCompressedBufferOffsets(bytes: Uint8Array): number[];
+declare function parseCompressedBuffer(bytes: Uint8Array, offset?: number): ICompressedBuffer;
+/** Decompresses a parsed `FCompressedBuffer` block-by-block. Uncompressed payloads are copied
+ * natively; Oodle and LZ4 payloads require the caller's codec. */
+declare function decompressCompressedBuffer(buffer: ICompressedBuffer, codecs: IUAssetCodecs): Uint8Array;
+
+interface IBitArray {
+    numBits: number;
+    validIds: number[];
+}
+interface IAttributeChannel {
+    extent: number;
+    values: Float32Array | Int32Array | Uint8Array | string[];
+    serializedCount: number;
+}
+interface IAttributeEntry {
+    name: string;
+    type: string;
+    components: number;
+    extent: number;
+    numElements: number;
+    channels: readonly IAttributeChannel[];
+}
+interface IElementContainer {
+    allocation: IBitArray;
+    attributeSet: {
+        numElements: number;
+        attributes: Map<string, IAttributeEntry>;
+    };
+}
+interface IMeshDescription {
+    byteLength: number;
+    trailingBytes: number;
+    elements: Map<string, {
+        name: string;
+        channels: readonly IElementContainer[];
+    }>;
+}
+/** Parses a serialized `FMeshDescription` — element containers, allocation bit arrays, and
+ * attribute sets — into typed arrays, validating every count against its neighbors. */
+declare function parseMeshDescription(input: Uint8Array, offset?: number): IMeshDescription;
+/** The serialized MeshDescription signature: an element-type count followed by the FString
+ * "Vertices". Strong enough to gate a full parse attempt, not strong enough to trust alone. */
+declare function looksLikeMeshDescription(bytes: Uint8Array, offset?: number): boolean;
+declare function findMeshDescriptionOffsets(bytes: Uint8Array): number[];
+
+interface IRawMesh {
+    version: number;
+    /** Per-face material (section) index. */
+    faceMaterialIndices: Int32Array;
+    /** Per-vertex positions, three floats each, in Unreal coordinates. */
+    vertexPositions: Float32Array;
+    vertexCount: number;
+    /** Per-wedge vertex index — the instance-to-vertex table. */
+    wedgeIndices: Uint32Array;
+    wedgeNormals: Float32Array | undefined;
+    /** One UV set per non-empty channel, each with `wedgeCount` uv pairs. */
+    wedgeUvs: Float32Array[];
+}
+interface IRawMeshBlob {
+    offset: number;
+    byteLength: number;
+    mesh: IRawMesh;
+}
+/** Parses an FRawMesh blob at `offset`, per `operator<<(FArchive&, FRawMesh&)`: a version pair
+ * then eighteen plain TArrays in a fixed order. A correct parse consumes the blob to its last
+ * byte and every count must agree with the wedge/face totals, which is what makes a candidate
+ * offset trustworthy rather than a lucky match. Throws `UAssetError` "INVALID_RAW_MESH" when
+ * anything disagrees. */
+declare function parseRawMesh(bytes: Uint8Array, offset?: number): IRawMeshBlob;
+/** Scans for FRawMesh blob candidates. Each candidate is decided by the full validating parse,
+ * which must consume the blob exactly and pass every cross-count check, so false positives cost
+ * only a rejected attempt. Offsets come back in file order — the first is LOD0. */
+declare function findRawMeshBlobs(bytes: Uint8Array): IRawMeshBlob[];
+
+interface IThreeAdapterOptions {
+    /** Override the fallback material. Every material is the game's decision; the fallback is one
+     * plain `MeshStandardMaterial` per section (or a single one for single-section meshes). */
+    materialFactory?: (decoded: IDecodedUAssetStaticMesh) => Material | Material[];
+}
+/** Converts one decoded `.uasset` static mesh into a `THREE.BufferGeometry` — positions, UVs,
+ * normals, an index buffer sized to the vertex count, and one draw group per material section.
+ * Coordinate conversion and winding repair already happened at parse time per the parse
+ * options; this builder makes no further geometry decisions. */
+declare function createThreeGeometry(decoded: IDecodedUAssetStaticMesh): BufferGeometry;
+/** Converts a decoded `.uasset` static mesh into a renderable `THREE.Mesh` with provenance in
+ * `userData.unreal`. Materials come from `materialFactory`; without one, a plain fallback is
+ * used so nothing renders invisible by accident. */
+declare function createThreeObject(decoded: IDecodedUAssetStaticMesh, options?: IThreeAdapterOptions): Object3D;
+
+interface IUAssetLoaderOptions {
+    parse?: IUAssetParseOptions;
+    three?: IThreeAdapterOptions;
+}
+/** Loads a raw Unreal editor `.uasset` static mesh under the standard three.js loader protocol:
+ * `load(url)` for the browser, `parse(data)` for bytes you already hold. Parse and adapter
+ * options pass straight through; the parse options carry the injected codecs. */
+declare class UAssetLoader extends Loader {
+    readonly options: IUAssetLoaderOptions;
+    constructor(manager?: LoadingManager, options?: IUAssetLoaderOptions);
+    parse(data: ArrayBuffer | ArrayBufferView): three.Object3D<three.Object3DEventMap>;
+    load(url: string, onLoad: (object: ReturnType<UAssetLoader["parse"]>) => void, onProgress?: (event: ProgressEvent) => void, onError?: (error: unknown) => void): this;
+}
+
+/**
+ * The stable error codes a `UAssetError` can carry.
+ * @situation switch on a raw .uasset failure without parsing error strings
+ * @constraint codes are part of the public surface; new failure modes add codes rather than reusing them
+ * @example if (error.code === "MISSING_CODEC") hintAtOodleSetup();
+ */
+type UAssetErrorCode = "INVALID_PACKAGE_TAG" | "TRUNCATED_PACKAGE" | "INVALID_PACKAGE_SUMMARY" | "INVALID_COMPRESSED_BUFFER" | "UNSUPPORTED_COMPRESSION_METHOD" | "MISSING_CODEC" | "CODEC_SIZE_MISMATCH" | "INCOMPLETE_DECOMPRESSION" | "INVALID_MESH_DESCRIPTION" | "INVALID_BULK_DATA" | "MISSING_BULK_DATA_FILE" | "INVALID_RAW_MESH" | "MISSING_MESH_ATTRIBUTE" | "INVALID_MESH_REFERENCE" | "UNSUPPORTED_STATIC_MESH_LAYOUT" | "INVALID_GEOMETRY_OPTIONS";
+/**
+ * The error thrown for every malformed, truncated, or unsupported `.uasset` input, carrying a
+ * stable `code` and structured details instead of invented fallback geometry.
+ * @situation tell why a raw .uasset failed to load, by code, before any geometry is shown
+ * @situation branch on an unsupported Unreal layout instead of shipping broken geometry
+ * @constraint every parse, decompression, and geometry failure surfaces as this error; the loader never invents fallback geometry
+ * @requires npm i @threenative/raw-unreal
+ * @example catch (error) { if (error instanceof UAssetError) log(error.code, error.details); }
+ */
+declare class UAssetError extends Error {
+    readonly code: UAssetErrorCode;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: UAssetErrorCode, message: string, details?: Readonly<Record<string, unknown>>);
+}
+
+export { BULK_DATA_FLAG, COMPRESSED_BUFFER_MAGIC, COMPRESSION_METHOD, type IBulkDataHeader, type IDecodedUAssetStaticMesh, type IPackageLayout, type IUAssetBounds, type IUAssetBulkDataFiles, type IUAssetBulkDataInfo, type IUAssetCompressedBufferInfo, type IUAssetLoaderOptions, type IUAssetMetadata, type IUAssetParseOptions, type IUAssetSection, type IUAssetSourceStats, type IUAssetUnrealInfo, type IUe4MeshDescription, type Lz4Codec, type OodleCodec, PACKAGE_FILE_TAG, type UAssetBulkDataFile, type UAssetBulkDataStorage, UAssetError, type UAssetErrorCode, UAssetLoader, type UAssetMeshLayout, type ZlibCodec, createThreeGeometry, createThreeObject, decompressBulkData, decompressCompressedBuffer, findBulkDataHeaders, findCompressedBufferOffsets, findMeshDescriptionOffsets, findRawMeshBlobs, looksLikeMeshDescription, looksLikeMeshDescriptionUe4, parseBulkDataHeader, parseCompressedBuffer, parseMeshDescription, parseMeshDescriptionUe4, parseRawMesh, parseUAssetStaticMesh, readPackageLayout, readPackageSummary, resolveBulkDataPayload };