@threenative/metahuman API

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

assertAssetPath

function · import { assertAssetPath } from "@threenative/metahuman"

Keeps a caller-supplied asset path inside the asset directory.

function assertAssetPath(path: string): string

Needs

• npm i @threenative/metahuman

Use it to

• reject a MetaHuman asset path that would read outside the game's asset root

Example

assertAssetPath("metahuman/specimen.glb");

Good to know

• absolute paths, Windows drive letters, backslashes and any .. segment throw MetaHumanAssetError with TN_MH_PATH_ESCAPE before the path is joined onto a root

loadMetaHuman

function · import { loadMetaHuman } from "@threenative/metahuman"

Load a prepared MetaHuman head and drive its expression from the browser's WASM evaluator: declared faceboard controls in, joint deltas and morph weights out, applied to an ordinary Three.js object graph. two characters never write each other's face and nothing is disposed that ctx.assets still owns switch re-evaluates the current controls before the replacement mesh is shown dispose() throw, each with a stable code; nothing is clamped or coerced diagnostics().backend reads "native"; the game code does not change

loadMetaHuman = (options: ILoadMetaHumanOptions): Promise<IMetaHuman> => createMetaHuman(

Needs

• npm i @threenative/metahuman

Use it to

• put a MetaHuman head in a browser game without an Unreal import or a baked clip

Example

const human = await loadMetaHuman({ assets: ctx.assets, model: "metahuman/head.glb",
  dna: "metahuman/head.dna", bindings: "metahuman/bindings.json" });
  human.setControls({ jawOpen: 0.4 });
// in the scene update, after any body animation
  human.update();

Good to know

• the model is loaded through the game's own asset loader and cloned per instance, so
• the rig's own GUI-to-raw mapping runs; the adapter never re-derives it, and a LOD
• an undeclared control, an out-of-domain value, an undeclared LOD and any call after
• in a native host that installed the MetaHuman resident the C++ evaluator runs and

MetaHumanAssetError

class · import { MetaHumanAssetError } from "@threenative/metahuman"

The rejection every check in this package raises, carrying a stable machine-readable code.

class MetaHumanAssetError extends Error

Needs

• npm i @threenative/metahuman

Use it to

• branch on why a MetaHuman asset or evaluator call was refused

Example

if (error instanceof MetaHumanAssetError && error.code === "TN_MH_HASH_MISMATCH") refetch();

Good to know

• code is part of the public surface; renaming one is a breaking change

RigEvaluator

class · import { RigEvaluator } from "@threenative/metahuman"

One MetaHuman head rig over the checksum-verified browser WASM build of the shared OpenRigLogic ABI: faceboard GUI controls in, joint deltas, blend shape weights and animated map weights out. instantiated, and nothing is fetched from a CDN evaluator throws instead of reading freed memory create and the WASM is never fetched; RigEvaluator.backend() says which one runs

class RigEvaluator implements IRigEvaluator

Needs

• npm i @threenative/metahuman

Use it to

• drive a prepared MetaHuman head's expression from the browser without an Unreal import

Example

const rig = await RigEvaluator.create(dna); rig.setGuiControls(gui); rig.evaluate(true); rig.jointOutputs();

Good to know

• the binary's SHA-256 is checked against the shipped manifest before it is
• every returned array is a copy, so no view survives a memory growth; a disposed
• a native host that installed the MetaHuman resident gets its C++ evaluator from

validateMetaHumanAssets

function · import { validateMetaHumanAssets } from "@threenative/metahuman"

Checks one prepared specimen — bindings sidecar, DNA and GLB — against the rig it claims to drive, and returns the bindings only when every name, index, domain and hash holds up. channels, morph targets or LODs the loaded files do not contain disk and an index past the end of its array are rejections, each with a stable code cannot pass a hand-written sidecar the rig cannot drive

function validateMetaHumanAssets(input: IMetaHumanAssetInput): IMetaHumanBindings

Needs

• npm i @threenative/metahuman

Use it to

• refuse a MetaHuman specimen whose bindings point at joints, nodes, blend shape

Example

const bindings = validateMetaHumanAssets({ bindings: parsed, dnaSha256, glbSha256, rig, gltf });

Good to know

• fails closed: a missing key, a wrong type, a hash that differs from the bytes on
• reads the rig's real names and the GLB's real node, mesh and target counts, so it