ThreeNative

@threenative/raw-unreal API

Every public function and class in @threenative/raw-unreal. Loads raw Unreal editor .uasset static meshes directly into Three.js geometry — UE5 FMeshDescription and UE4.18 FRawMesh layouts, with no interchange conversion.

On this page

Generated from the engine's capability manifest: 19 functions and 2 classes. Each entry is the exported signature, what it is for, and a working example. Start with the package overview.

createThreeGeometry

function · import { createThreeGeometry } from "@threenative/raw-unreal"

Converts a decoded .uasset static mesh into a THREE.BufferGeometry, with one draw group per material section.

ts
function createThreeGeometry(decoded: IDecodedUAssetStaticMesh): BufferGeometry

Needs

  • npm i @threenative/raw-unreal

Use it to

  • build custom scene objects from Unreal mesh data instead of a whole mesh
  • hand a decoded Unreal mesh to a framework pipeline that owns materials itself

Example

ts
const geometry = createThreeGeometry(parseUAssetStaticMesh(buffer));

Good to know

  • materials are never chosen here; the geometry carries groups, the game carries materials

createThreeObject

function · import { createThreeObject } from "@threenative/raw-unreal"

Converts a decoded .uasset static mesh into a renderable THREE.Mesh with provenance in userData.unreal and material selection left to the game's materialFactory.

ts
function createThreeObject( decoded: IDecodedUAssetStaticMesh, options: IThreeAdapterOptions =

Needs

  • npm i @threenative/raw-unreal

Use it to

  • put a raw .uasset mesh on screen without converting it to glTF first
  • key materials to a package's own sections by name or section index

Example

ts
const mesh = createThreeObject(decoded, { materialFactory: (d) => d.sections.map(() => barkMaterial) });

Good to know

  • the fallback is three.js's own plain MeshStandardMaterial; every real material comes from the game

decompressBulkData

function · import { decompressBulkData } from "@threenative/raw-unreal"

Reads the FByteBulkData headers an editor package serializes into its export data, and resolves each payload — inline, at the end of the package, or in a sibling .ubulk/.uptnl file whose bytes the caller supplies — decompressing FArchive::SerializeCompressed blocks.

ts
function decompressBulkData( container: Uint8Array, codecs:

Needs

  • npm i @threenative/raw-unreal

Use it to

  • read a UE4 editor static mesh whose source model lives in bulk data rather than inline
  • decompress the zlib-chunked bulk payload a UE4.2x package stores its MeshDescription in

Example

ts
const payload = resolveBulkDataPayload(bytes, header, { zlib });

Good to know

  • zlib payloads require an injected zlib codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing
  • a payload written to a sibling file throws MISSING_BULK_DATA_FILE naming that file, rather than inventing geometry

decompressCompressedBuffer

function · import { decompressCompressedBuffer } from "@threenative/raw-unreal"

Parses one UE5 FCompressedBuffer and decompresses it block-by-block with the codecs the caller injected — uncompressed payloads are handled natively.

ts
function decompressCompressedBuffer( buffer: ICompressedBuffer, codecs: IUAssetCodecs, ): Uint8Array

Needs

  • npm i @threenative/raw-unreal

Use it to

  • decompress the package-trailer payload that carries a UE5 MeshDescription

Example

ts
const payload = decompressCompressedBuffer(parseCompressedBuffer(bytes, offset), { oodle });

Good to know

  • Oodle and LZ4 payloads require an injected codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing

findBulkDataHeaders

function · import { findBulkDataHeaders } from "@threenative/raw-unreal"

Reads the FByteBulkData headers an editor package serializes into its export data, and resolves each payload — inline, at the end of the package, or in a sibling .ubulk/.uptnl file whose bytes the caller supplies — decompressing FArchive::SerializeCompressed blocks.

ts
function findBulkDataHeaders( bytes: Uint8Array, layout: IPackageLayout, files: IUAssetBulkDataFiles =

Needs

  • npm i @threenative/raw-unreal

Use it to

  • read a UE4 editor static mesh whose source model lives in bulk data rather than inline
  • decompress the zlib-chunked bulk payload a UE4.2x package stores its MeshDescription in

Example

ts
const payload = resolveBulkDataPayload(bytes, header, { zlib });

Good to know

  • zlib payloads require an injected zlib codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing
  • a payload written to a sibling file throws MISSING_BULK_DATA_FILE naming that file, rather than inventing geometry

findCompressedBufferOffsets

function · import { findCompressedBufferOffsets } from "@threenative/raw-unreal"

Parses one UE5 FCompressedBuffer and decompresses it block-by-block with the codecs the caller injected — uncompressed payloads are handled natively.

ts
function findCompressedBufferOffsets(bytes: Uint8Array): number[]

Needs

  • npm i @threenative/raw-unreal

Use it to

  • decompress the package-trailer payload that carries a UE5 MeshDescription

Example

ts
const payload = decompressCompressedBuffer(parseCompressedBuffer(bytes, offset), { oodle });

Good to know

  • Oodle and LZ4 payloads require an injected codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing

findMeshDescriptionOffsets

function · import { findMeshDescriptionOffsets } from "@threenative/raw-unreal"

Parses a serialized FMeshDescription — element containers, allocation bit arrays, and attribute sets — into validated typed arrays, exactly consuming its byte range.

ts
function findMeshDescriptionOffsets(bytes: Uint8Array): number[]

Needs

  • npm i @threenative/raw-unreal

Use it to

  • inspect the vertex, triangle, and polygon-group structure of a UE5 MeshDescription

Example

ts
const description = parseMeshDescription(payload, offset);

Good to know

  • every count is validated against its neighbors before any geometry is built

findRawMeshBlobs

function · import { findRawMeshBlobs } from "@threenative/raw-unreal"

Parses one FRawMesh blob — the UE4.18-era source-model layout — validating that the fixed eighteen-array walk consumes the blob exactly and every count agrees with the wedge totals.

ts
function findRawMeshBlobs(bytes: Uint8Array): IRawMeshBlob[]

Needs

  • npm i @threenative/raw-unreal

Use it to

  • read the source geometry of a Fab pack saved by UE 4.18 straight from its .uasset

Example

ts
const blob = parseRawMesh(bytes, offset);

Good to know

  • only inline uncompressed blobs are found; compressed or external bulk data throws rather than guessing

looksLikeMeshDescription

function · import { looksLikeMeshDescription } from "@threenative/raw-unreal"

Parses a serialized FMeshDescription — element containers, allocation bit arrays, and attribute sets — into validated typed arrays, exactly consuming its byte range.

ts
function looksLikeMeshDescription(bytes: Uint8Array, offset = 0): boolean

Needs

  • npm i @threenative/raw-unreal

Use it to

  • inspect the vertex, triangle, and polygon-group structure of a UE5 MeshDescription

Example

ts
const description = parseMeshDescription(payload, offset);

Good to know

  • every count is validated against its neighbors before any geometry is built

looksLikeMeshDescriptionUe4

function · import { looksLikeMeshDescriptionUe4 } from "@threenative/raw-unreal"

Parses the UE4.2x serialization of FMeshDescription — fixed-order element containers, and a triangle container that trails the attribute sets rather than sitting with its siblings.

ts
function looksLikeMeshDescriptionUe4(bytes: Uint8Array, offset = 0): boolean

Needs

  • npm i @threenative/raw-unreal

Use it to

  • decode the MeshDescription a UE 4.23-4.27 editor package keeps in bulk data

Example

ts
const description = parseMeshDescriptionUe4(payload);

Good to know

  • the walk must consume the payload exactly; a short walk throws rather than returning the geometry it managed to read

parseBulkDataHeader

function · import { parseBulkDataHeader } from "@threenative/raw-unreal"

Reads the FByteBulkData headers an editor package serializes into its export data, and resolves each payload — inline, at the end of the package, or in a sibling .ubulk/.uptnl file whose bytes the caller supplies — decompressing FArchive::SerializeCompressed blocks.

ts
function parseBulkDataHeader( bytes: Uint8Array, offset: number, layout: IPackageLayout, ): IBulkDataHeader

Needs

  • npm i @threenative/raw-unreal

Use it to

  • read a UE4 editor static mesh whose source model lives in bulk data rather than inline
  • decompress the zlib-chunked bulk payload a UE4.2x package stores its MeshDescription in

Example

ts
const payload = resolveBulkDataPayload(bytes, header, { zlib });

Good to know

  • zlib payloads require an injected zlib codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing
  • a payload written to a sibling file throws MISSING_BULK_DATA_FILE naming that file, rather than inventing geometry

parseCompressedBuffer

function · import { parseCompressedBuffer } from "@threenative/raw-unreal"

Parses one UE5 FCompressedBuffer and decompresses it block-by-block with the codecs the caller injected — uncompressed payloads are handled natively.

ts
function parseCompressedBuffer(bytes: Uint8Array, offset = 0): ICompressedBuffer

Needs

  • npm i @threenative/raw-unreal

Use it to

  • decompress the package-trailer payload that carries a UE5 MeshDescription

Example

ts
const payload = decompressCompressedBuffer(parseCompressedBuffer(bytes, offset), { oodle });

Good to know

  • Oodle and LZ4 payloads require an injected codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing

parseMeshDescription

function · import { parseMeshDescription } from "@threenative/raw-unreal"

Parses a serialized FMeshDescription — element containers, allocation bit arrays, and attribute sets — into validated typed arrays, exactly consuming its byte range.

ts
function parseMeshDescription(input: Uint8Array, offset = 0): IMeshDescription

Needs

  • npm i @threenative/raw-unreal

Use it to

  • inspect the vertex, triangle, and polygon-group structure of a UE5 MeshDescription

Example

ts
const description = parseMeshDescription(payload, offset);

Good to know

  • every count is validated against its neighbors before any geometry is built

parseMeshDescriptionUe4

function · import { parseMeshDescriptionUe4 } from "@threenative/raw-unreal"

Parses the UE4.2x serialization of FMeshDescription — fixed-order element containers, and a triangle container that trails the attribute sets rather than sitting with its siblings.

ts
function parseMeshDescriptionUe4(input: Uint8Array, offset = 0): IUe4MeshDescription

Needs

  • npm i @threenative/raw-unreal

Use it to

  • decode the MeshDescription a UE 4.23-4.27 editor package keeps in bulk data

Example

ts
const description = parseMeshDescriptionUe4(payload);

Good to know

  • the walk must consume the payload exactly; a short walk throws rather than returning the geometry it managed to read

parseRawMesh

function · import { parseRawMesh } from "@threenative/raw-unreal"

Parses one FRawMesh blob — the UE4.18-era source-model layout — validating that the fixed eighteen-array walk consumes the blob exactly and every count agrees with the wedge totals.

ts
function parseRawMesh(bytes: Uint8Array, offset = 0): IRawMeshBlob

Needs

  • npm i @threenative/raw-unreal

Use it to

  • read the source geometry of a Fab pack saved by UE 4.18 straight from its .uasset

Example

ts
const blob = parseRawMesh(bytes, offset);

Good to know

  • only inline uncompressed blobs are found; compressed or external bulk data throws rather than guessing

parseUAssetStaticMesh

function · import { parseUAssetStaticMesh } from "@threenative/raw-unreal"

Parses a raw Unreal editor .uasset static mesh into validated, plain typed arrays — UE5 FMeshDescription payloads (including the Oodle-compressed package-trailer form) and the UE4.18-era FRawMesh source-model layout, with no interchange conversion at any step.

ts
function parseUAssetStaticMesh( input: ArrayBuffer | ArrayBufferView, options: IUAssetParseOptions =

Needs

  • npm i @threenative/raw-unreal

Use it to

  • load a raw Unreal editor .uasset mesh in the browser without conversion
  • decode a Fab pack's UE4.18 static meshes straight from their .uasset files

Example

ts
const decoded = parseUAssetStaticMesh(await file.arrayBuffer(), { oodle });

Good to know

  • only legacy-tag uncooked editor packages are read; IoStore (.utoc/.ucas), PAK archives, cooked render buffers, Nanite, and skeletal data throw UAssetError
  • the format layer never invents fallback geometry; every malformed or unsupported layout surfaces as UAssetError with its byte offset or counts

readPackageLayout

function · import { readPackageLayout } from "@threenative/raw-unreal"

Walks the whole FPackageFileSummary for the offsets bulk data is addressed against — TotalHeaderSize and BulkDataStartOffset — and returns undefined when the walk cannot be trusted.

ts
function readPackageLayout(bytes: Uint8Array): IPackageLayout | undefined

Needs

  • npm i @threenative/raw-unreal

Use it to

  • find where a .uasset's export data and bulk-data region begin

Example

ts
const layout = readPackageLayout(bytes); if (layout) readBulk(layout.bulkDataStartOffset);

Good to know

  • returns undefined rather than guessing when the summary does not end on its own name table, or when the package uses a LegacyFileVersion this walk does not model

readPackageSummary

function · import { readPackageSummary } from "@threenative/raw-unreal"

Reads the fixed prefix of FPackageFileSummary — the legacy tag, engine versions, and the custom-version list — without walking the name map, export map, or dependency graph.

ts
function readPackageSummary(bytes: Uint8Array): IPackageSummary

Needs

  • npm i @threenative/raw-unreal

Use it to

  • report which engine generation a .uasset was written by before decoding it
  • reject a non-Unreal file with the stable INVALID_PACKAGE_TAG error

Example

ts
const summary = readPackageSummary(bytes);

Good to know

  • only the summary prefix is read; locating payload data is the payload readers' self-validating signature scans

resolveBulkDataPayload

function · import { resolveBulkDataPayload } from "@threenative/raw-unreal"

Reads the FByteBulkData headers an editor package serializes into its export data, and resolves each payload — inline, at the end of the package, or in a sibling .ubulk/.uptnl file whose bytes the caller supplies — decompressing FArchive::SerializeCompressed blocks.

ts
function resolveBulkDataPayload( bytes: Uint8Array, header: IBulkDataHeader, options:

Needs

  • npm i @threenative/raw-unreal

Use it to

  • read a UE4 editor static mesh whose source model lives in bulk data rather than inline
  • decompress the zlib-chunked bulk payload a UE4.2x package stores its MeshDescription in

Example

ts
const payload = resolveBulkDataPayload(bytes, header, { zlib });

Good to know

  • zlib payloads require an injected zlib codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing
  • a payload written to a sibling file throws MISSING_BULK_DATA_FILE naming that file, rather than inventing geometry

UAssetError

class · import { UAssetError } from "@threenative/raw-unreal"

The error thrown for every malformed, truncated, or unsupported .uasset input, carrying a stable code and structured details instead of invented fallback geometry.

ts
class UAssetError extends Error

Needs

  • npm i @threenative/raw-unreal

Use it to

  • tell why a raw .uasset failed to load, by code, before any geometry is shown
  • branch on an unsupported Unreal layout instead of shipping broken geometry

Example

ts
catch (error) { if (error instanceof UAssetError) log(error.code, error.details); }

Good to know

  • every parse, decompression, and geometry failure surfaces as this error; the loader never invents fallback geometry

UAssetLoader

class · import { UAssetLoader } from "@threenative/raw-unreal"

Loads a raw Unreal .uasset static mesh as a three.js loader — load(url) for the browser, parse(data) for bytes you already hold — with parse and adapter options passed through.

ts
class UAssetLoader extends Loader

Needs

  • npm i @threenative/raw-unreal

Use it to

  • load a .uasset asset in the browser with the standard three.js loader protocol
  • hand raw Fab-pack meshes to the framework's asset loading without a conversion step

Example

ts
const mesh = new UAssetLoader(manager, { parse: { oodle } }).parse(data);

Good to know

  • UE5 Oodle payloads require an oodle codec in the parse options; see README licensing
View source on GitHub ↗