@bitmagic/cli 0.1.66-dev.6 → 0.1.66-dev.7

package/assets/metahuman/src/work/metahuman/MetaHumanLabHooks.ts

@@ -0,0 +1,122 @@
+/**
+ * `window.__lab` — the debug handle the shipped MetaHuman rigs drive (tools/metahuman/e2e: shot.mjs,
+ * eval.mjs, walk-probe.mjs and the probes under probes/). Install it once the actor has adopted the
+ * engine's player; add your own entries on top:
+ *
+ *     window.__lab = { ...installMetaHumanLabHooks({ engine, actor, playerLoader, player }), mine: () => … };
+ *
+ * Nothing here is needed by the game itself — it is how a headless browser measures the character:
+ * pin the render camera (`freeCam`), freeze the procedural life (`setLife`), read the head position
+ * and facing for deterministic framing, tune the helper-joint policy, and dump the engine's retarget
+ * state (`retargetInfo`, `boneMap`) to see which rig bones are posed and corrected.
+ */
+import * as THREE from 'three';
+import type { EngineLike } from 'types/game.js';
+import type { HelperGroup, MetaHumanActor } from './MetaHumanActor.js';
+
+/** The engine's ThirdPersonCamera, structurally (only what `orbitTo` touches). */
+interface OrbitCamera {
+    setAutoFollow(on: boolean): void;
+    spherical: { theta: number; phi: number; radius: number };
+    targetSpherical: { theta: number; phi: number; radius: number };
+    distance: number;
+}
+
+export interface MetaHumanLabDeps {
+    engine: EngineLike;
+    actor: MetaHumanActor;
+    /** The engine's PlayerLoader: its private retarget maps are what `retargetInfo()` / `boneMap()` read. */
+    playerLoader: unknown;
+    /** The player object (capsule root) for `playerPosition()`. */
+    player?: THREE.Object3D | null;
+    /** The third-person camera, for `orbitTo` (optional). */
+    cameraController?: OrbitCamera | null;
+    /** The player controller, for `setPlayerYaw` (optional; needs `setFacingLock`). */
+    playerController?: { setFacingLock?: (rad: number | null) => void } | null;
+}
+
+export interface Vec3Like { x: number; y: number; z: number }
+
+export interface MetaHumanLabHooks {
+    actor: MetaHumanActor;
+    engine: () => EngineLike;
+    playerLoader: () => unknown;
+    camera: () => OrbitCamera | null;
+    playerPosition: () => Vec3Like | null;
+    headPosition: () => Vec3Like;
+    facing: () => Vec3Like;
+    setLife: (on: boolean) => void;
+    /** Snap the orbit camera: theta 0 = in front of the character (+Z), phi = polar angle from +Y. */
+    orbitTo: (theta: number, phi: number, distance?: number) => void;
+    /** Pin the render camera (applied right before render, after the camera controller). */
+    freeCam: (pos: Vec3Like, look: Vec3Like, fovDeg?: number) => void;
+    freeCamOff: () => void;
+    /** Turn the player to a yaw (null releases the lock). */
+    setPlayerYaw: (rad: number | null) => void;
+    /** Tune how much the corrective helper roots follow their parents (0 pinned … 1 rigid). */
+    setHelperFollow: (f: Partial<Record<HelperGroup, number>>) => Record<HelperGroup, number>;
+    /** The engine's memoised rig-bone → clip-bone name resolution (fills as frames run). */
+    boneMap: () => string[] | null;
+    /** Which rig bones the engine poses each frame, and which get a bind-difference correction. */
+    retargetInfo: () => { posed: string[] | null; deltas: string[] | null; bindCount: number | null };
+}
+
+export function installMetaHumanLabHooks(deps: MetaHumanLabDeps): MetaHumanLabHooks {
+    let freeCamOff: (() => void) | null = null;
+    const hooks: MetaHumanLabHooks = {
+        actor: deps.actor,
+        engine: () => deps.engine,
+        playerLoader: () => deps.playerLoader,
+        camera: () => deps.cameraController ?? null,
+        playerPosition: () => { const p = deps.player?.position; return p ? { x: p.x, y: p.y, z: p.z } : null; },
+        headPosition: () => { const v = new THREE.Vector3(); deps.actor.getHeadWorldPosition(v); return { x: v.x, y: v.y, z: v.z }; },
+        facing: () => { const f = deps.actor.getFacing(); return { x: f.x, y: f.y, z: f.z }; },
+        setLife: (on) => deps.actor.setLifeEnabled(on),
+        orbitTo: (theta, phi, distance) => {
+            const tpc = deps.cameraController;
+            if (!tpc) return;
+            tpc.setAutoFollow(false);
+            tpc.spherical.theta = theta; tpc.targetSpherical.theta = theta;
+            tpc.spherical.phi = phi; tpc.targetSpherical.phi = phi;
+            if (distance !== undefined) { tpc.distance = distance; tpc.spherical.radius = distance; tpc.targetSpherical.radius = distance; }
+        },
+        freeCam: (pos, look, fovDeg) => {
+            freeCamOff?.();
+            const cam = deps.engine.getDefaultCamera();
+            const savedFov = cam.fov;
+            if (fovDeg !== undefined) { cam.fov = fovDeg; cam.updateProjectionMatrix(); }
+            const unregister = deps.engine.registerBeforeRender?.(() => {
+                cam.position.set(pos.x, pos.y, pos.z);
+                cam.lookAt(look.x, look.y, look.z);
+                cam.updateMatrixWorld(true);
+            });
+            freeCamOff = () => {
+                unregister?.();
+                cam.fov = savedFov; cam.updateProjectionMatrix();
+                freeCamOff = null;
+            };
+        },
+        freeCamOff: () => freeCamOff?.(),
+        setPlayerYaw: (rad) => deps.playerController?.setFacingLock?.(rad),
+        setHelperFollow: (f) => { Object.assign(deps.actor.helperFollow, f); return deps.actor.helperFollow; },
+        boneMap: () => {
+            const pl = deps.playerLoader as { mixamoNameMemo?: Map<string, string> };
+            return pl.mixamoNameMemo ? [...pl.mixamoNameMemo.entries()].map(([rig, clip]) => `${rig} → ${clip}`) : null;
+        },
+        retargetInfo: () => {
+            const pl = deps.playerLoader as {
+                skinnedRetargetDeltas?: Map<string, THREE.Quaternion> | null;
+                blendedPoseForBlock?: Map<string, unknown> | null;
+                skinnedBind?: { rotations: Map<string, THREE.Quaternion> } | null;
+            };
+            const deg = (q: THREE.Quaternion) => +(2 * Math.acos(Math.min(1, Math.abs(q.w))) * 180 / Math.PI).toFixed(1);
+            return {
+                posed: pl.blendedPoseForBlock ? [...pl.blendedPoseForBlock.keys()] : null,
+                deltas: pl.skinnedRetargetDeltas ? [...pl.skinnedRetargetDeltas.entries()].map(([k, q]) => `${k}:${deg(q)}°`) : null,
+                bindCount: pl.skinnedBind?.rotations.size ?? null,
+            };
+        },
+    };
+    (window as unknown as { __lab?: unknown }).__lab = hooks;
+    return hooks;
+}

package/assets/metahuman/src/work/metahuman/MetaHumanMaterials.ts

@@ -0,0 +1,500 @@
+/**
+ * MetaHuman material upgrades — renders an Epic MetaHuman GLB export (UE 5.7 →
+ * Blender → glTF, see assets/LICENSES.md) as faithfully as three.js allows,
+ * without touching the original geometry.
+ *
+ * WebGPU (the engine default) gets TSL node materials:
+ *   - skin: roughness floor + a wrap-lighting subsurface term in a custom
+ *     PhysicalLightingModel (light bleeding through ears / nose / lips)
+ *   - hair & brow cards: the 4K MetaHuman card atlas (R = coverage, G = root→tip,
+ *     B = per-strand seed) drives alpha-to-coverage, root darkening, per-strand
+ *     tint & roughness variance and a normal-based self-occlusion
+ *   - lashes: the 2K coverage mask, alpha-blended
+ *   - eyes: wet cornea (near-mirror roughness + clearcoat)
+ * WebGL falls back to the plain glTF PBR materials with the same scalar tweaks.
+ */
+import * as THREE from 'three';
+import { MeshPhysicalNodeMaterial, PhysicalLightingModel } from 'three/webgpu';
+import type { NodeBuilder, LightingModelDirectInput, Node } from 'three/webgpu';
+
+// @types/three 0.185 types TSL nodes by their GLSL-ish type parameter; the engine's
+// lighting-model inputs are declared as bare `Node`, so we cast them to typed nodes.
+type Vec3Node = Node<'vec3'>;
+type FloatNode = Node<'float'>;
+type Vec2Node = Node<'vec2'>;
+import {
+    texture, uv, float, mix, smoothstep, abs, dot, uniform,
+    normalView, positionViewDirection, materialRoughness,
+} from 'three/tsl';
+import { isWebGpuActive } from 'engine/RendererType.js';
+
+/** Which MetaHuman part a material belongs to, decided from its glTF name. */
+export type MetaHumanPart =
+    | 'skin' | 'body' | 'hair' | 'brows' | 'lashes' | 'eye' | 'eyeshell' | 'teeth' | 'cloth' | 'hidden' | 'other';
+
+export function classifyMaterial(name: string): MetaHumanPart {
+    const n = name.toLowerCase();
+    if (n.includes('eyeshell')) return 'eyeshell';
+    if (n === 'm_hide' || n.includes('lacrimal') || n.includes('eyeedge') || n.includes('saliva')) return 'hidden';
+    if (n.includes('face_skin') || n.includes('_face_') && n.includes('skin')) return 'skin';
+    if (n.includes('body_baked') || n.includes('mi_body')) return 'body';
+    if (n.includes('lashmat') || n.includes('eyelash')) return 'lashes';
+    if (n.includes('eyebrow') || n.includes('beard') || n.includes('mustache') || n.includes('goatee')) return 'brows';
+    if (n.includes('cardmat') || n.includes('hair_')) return 'hair';
+    if (n.includes('eyel_') || n.includes('eyer_') || n.includes('_eye_') || n.includes('mi_eye')) return 'eye';
+    if (n.includes('teeth')) return 'teeth';
+    if (n.includes('shirt') || n.includes('short') || n.includes('pants') || n.includes('hoodie') || n.includes('slacks') || n.includes('shoe') || n.includes('bodyshape')) return 'cloth';
+    return 'other';
+}
+
+export interface HairParams {
+    /** Hair colour (sRGB hex) — the atlas carries no albedo, only coverage/data. */
+    color: string;
+    roughness: number;
+    /** Gain applied to atlas coverage before alpha-to-coverage (MH atlases are authored for blending). */
+    density: number;
+    /** 0 = flat tone, 1 = fully black roots. */
+    rootDarkening: number;
+    /** Per-strand brightness variance amplitude. */
+    seedVariation: number;
+    roughnessFloor: number;
+    roughnessSeedAmp: number;
+    /** Extra alpha-blended fringe pass drawn over the A2C pass (0 = none). */
+    blendOpacity: number;
+    /** 'a2c' (needs MSAA), 'blend' (single sorted-ish pass), 'both'. */
+    mode: 'a2c' | 'blend' | 'both';
+    anisotropy: number;
+    anisotropyRotation: number;
+}
+
+export interface MetaHumanMaterialOptions {
+    hairAtlasUrl: string | null;
+    browAtlasUrl: string | null;
+    lashCoverageUrl: string | null;
+    hair: HairParams;
+    brows: HairParams;
+    /** Subsurface tint & strength for skin. */
+    sss: { color: string; strength: number; distortion: number; power: number; ambient: number };
+    skinRoughnessFloor: number;
+    skinSpecularIntensity: number;
+    /** 0 hides the MetaHuman eye shell (its UVs are not eye-centred in this export); >0 draws a dark socket ring. */
+    eyeShellOcclusion: number;
+    /** Whether the renderer really has MSAA (alpha-to-coverage is a no-op without it). */
+    msaa: boolean;
+}
+
+export const DEFAULT_HAIR: HairParams = {
+    color: '#090603', roughness: 0.55, density: 5.5, rootDarkening: 0.0, seedVariation: 0.36,
+    roughnessFloor: 0.56, roughnessSeedAmp: 0.08, blendOpacity: 0.22, mode: 'both',
+    anisotropy: 0.2, anisotropyRotation: Math.PI / 2,
+};
+export const DEFAULT_BROWS: HairParams = { ...DEFAULT_HAIR, mode: 'blend', blendOpacity: 0, anisotropy: 0 };
+
+export const DEFAULT_METAHUMAN_MATERIAL_OPTIONS: MetaHumanMaterialOptions = {
+    hairAtlasUrl: null, browAtlasUrl: null, lashCoverageUrl: null,
+    hair: DEFAULT_HAIR, brows: DEFAULT_BROWS,
+    sss: { color: '#ff5a3c', strength: 0.22, distortion: 0.25, power: 2.5, ambient: 0.0 },
+    skinRoughnessFloor: 0.42,
+    skinSpecularIntensity: 0.8,
+    eyeShellOcclusion: 0,
+    msaa: true,
+};
+
+// ---------------------------------------------------------------------------
+// Skin: physical material + wrap-lighting subsurface term (WebGPU / TSL)
+// ---------------------------------------------------------------------------
+
+interface SssNodes {
+    color: Vec3Node;
+    strength: FloatNode;
+    distortion: FloatNode;
+    power: FloatNode;
+    ambient: FloatNode;
+}
+
+/**
+ * PhysicalLightingModel with an extra back-scattering diffuse term (the classic
+ * "fast subsurface" from the three.js SSS example): light arriving from behind
+ * the surface, bent by the normal, bleeds toward the viewer tinted by `color`.
+ */
+class SkinLightingModel extends PhysicalLightingModel {
+    constructor(
+        private readonly sss: SssNodes,
+        clearcoat: boolean, sheen: boolean, iridescence: boolean,
+        anisotropy: boolean, transmission: boolean, dispersion: boolean,
+    ) {
+        super(clearcoat, sheen, iridescence, anisotropy, transmission, dispersion);
+    }
+
+    override direct(input: LightingModelDirectInput, builder: NodeBuilder): void {
+        const lightDirection = input.lightDirection as Vec3Node;
+        const lightColor = input.lightColor as Vec3Node;
+        const half = lightDirection.add(normalView.mul(this.sss.distortion)).normalize();
+        const vDotH = positionViewDirection.dot(half.negate()).saturate();
+        const scatter = vDotH.pow(this.sss.power).add(this.sss.ambient).mul(this.sss.color).mul(this.sss.strength);
+        (input.reflectedLight.directDiffuse as Vec3Node).addAssign(scatter.mul(lightColor));
+        super.direct(input, builder);
+    }
+}
+
+class MeshSkinNodeMaterial extends MeshPhysicalNodeMaterial {
+    sss: SssNodes | null = null;
+
+    override setupLightingModel(): PhysicalLightingModel {
+        if (!this.sss) return super.setupLightingModel();
+        return new SkinLightingModel(
+            this.sss, this.useClearcoat, this.useSheen, this.useIridescence,
+            this.useAnisotropy, this.useTransmission, this.useDispersion,
+        );
+    }
+}
+
+/** Standard/physical scalar + map properties worth carrying from a glTF material into a node material. */
+const PBR_PROPS = [
+    'name', 'color', 'map', 'normalMap', 'normalScale', 'roughness', 'roughnessMap', 'metalness', 'metalnessMap',
+    'aoMap', 'aoMapIntensity', 'emissive', 'emissiveMap', 'emissiveIntensity', 'alphaMap',
+    'specularIntensity', 'specularIntensityMap', 'specularColor', 'specularColorMap', 'ior',
+    'side', 'transparent', 'opacity', 'alphaTest', 'depthWrite', 'envMapIntensity', 'clearcoat', 'clearcoatRoughness',
+] as const;
+
+function copyPbrProps(dst: THREE.Material, src: THREE.Material): void {
+    const d = dst as unknown as Record<string, unknown>;
+    const s = src as unknown as Record<string, unknown>;
+    for (const k of PBR_PROPS) {
+        if (!(k in s) || s[k] === undefined || !(k in d)) continue;
+        const v = s[k];
+        if (v && typeof v === 'object' && 'isColor' in (v as object)) (d[k] as THREE.Color).copy(v as THREE.Color);
+        else if (v && typeof v === 'object' && 'isVector2' in (v as object)) (d[k] as THREE.Vector2).copy(v as THREE.Vector2);
+        else d[k] = v;
+    }
+}
+
+function makeSkinMaterial(src: THREE.Material, opts: MetaHumanMaterialOptions, strengthScale: number): THREE.Material {
+    src.vertexColors = false; // MetaHuman COLOR_0/1 are rig masks, never albedo
+    if (!isWebGpuActive()) {
+        const m = src as THREE.MeshPhysicalMaterial;
+        if ('metalness' in m) m.metalness = 0;
+        if ('specularIntensity' in m) m.specularIntensity = opts.skinSpecularIntensity;
+        m.needsUpdate = true;
+        return m;
+    }
+    const mat = new MeshSkinNodeMaterial();
+    copyPbrProps(mat, src);
+    mat.vertexColors = false;
+    mat.metalness = 0;
+    mat.specularIntensity = opts.skinSpecularIntensity;
+    // Baked MH roughness has oily hotspots on forehead/nose; clamp up to a matte floor.
+    mat.roughnessNode = materialRoughness.max(float(opts.skinRoughnessFloor));
+    mat.sss = {
+        color: uniform(new THREE.Color(opts.sss.color)) as unknown as Vec3Node,
+        strength: uniform(opts.sss.strength * strengthScale) as unknown as FloatNode,
+        distortion: uniform(opts.sss.distortion) as unknown as FloatNode,
+        power: uniform(opts.sss.power) as unknown as FloatNode,
+        ambient: uniform(opts.sss.ambient) as unknown as FloatNode,
+    };
+    return mat;
+}
+
+// ---------------------------------------------------------------------------
+// Hair cards / brows / lashes
+// ---------------------------------------------------------------------------
+
+const textureCache = new Map<string, THREE.Texture>();
+function loadDataTexture(url: string, like: THREE.Texture | null): THREE.Texture {
+    let tex = textureCache.get(url);
+    if (!tex) {
+        tex = new THREE.TextureLoader().load(url);
+        tex.colorSpace = THREE.NoColorSpace;
+        tex.flipY = false;            // glTF UV convention
+        tex.wrapS = tex.wrapT = THREE.RepeatWrapping;
+        tex.anisotropy = 8;
+        textureCache.set(url, tex);
+    }
+    if (like) {
+        // Mirror any KHR_texture_transform the glTF applied to the baked map.
+        tex.channel = like.channel;
+        tex.offset.copy(like.offset); tex.repeat.copy(like.repeat);
+        tex.rotation = like.rotation; tex.center.copy(like.center);
+        tex.matrixAutoUpdate = like.matrixAutoUpdate;
+        if (!like.matrixAutoUpdate) tex.matrix.copy(like.matrix);
+    }
+    return tex;
+}
+
+function hairMatrixUv(atlas: THREE.Texture): Vec2Node {
+    return uv(atlas.channel) as unknown as Vec2Node;
+}
+
+interface HairBuild { primary: THREE.Material; blend: THREE.Material | null }
+
+function makeHairMaterials(src: THREE.Material, atlasUrl: string | null, p: HairParams, msaa: boolean): HairBuild {
+    const base = new THREE.Color(p.color);
+    const srcMap = (src as THREE.MeshStandardMaterial).map ?? null;
+    const atlas = atlasUrl ? loadDataTexture(atlasUrl, srcMap) : null;
+    const useA2C = msaa && (p.mode === 'a2c' || p.mode === 'both');
+
+    if (!isWebGpuActive()) {
+        // WebGL fallback: alpha-tested + alpha-blended pair on the glTF material.
+        const m = src as THREE.MeshStandardMaterial;
+        m.vertexColors = false;
+        m.color.copy(base);
+        m.map = null;
+        m.roughness = p.roughness;
+        m.metalness = 0;
+        m.side = THREE.DoubleSide;
+        if (atlas) { m.alphaMap = atlas; }
+        m.transparent = true; m.alphaTest = 0.0; m.depthWrite = false;
+        m.polygonOffset = true; m.polygonOffsetFactor = -0.5; m.polygonOffsetUnits = -1;
+        const inner = m.clone();
+        inner.transparent = false; inner.alphaTest = 0.5; inner.depthWrite = true;
+        m.needsUpdate = true;
+        return { primary: inner, blend: m };
+    }
+
+    const build = (blendPass: boolean): THREE.Material => {
+        const mat = new MeshPhysicalNodeMaterial();
+        mat.name = (src.name || 'hair') + (blendPass ? '__blend' : '');
+        mat.side = THREE.DoubleSide;
+        mat.metalness = 0;
+        mat.roughness = p.roughness;
+        mat.specularIntensity = 0.45;
+        // A whisper of depth bias so cards flush with the scalp don't z-fight; anything bigger
+        // lets cards on the FAR side of the head win the depth test and show through the skin.
+        mat.polygonOffset = true; mat.polygonOffsetFactor = -0.5; mat.polygonOffsetUnits = -1;
+        if (p.anisotropy > 0) { mat.anisotropy = p.anisotropy; mat.anisotropyRotation = p.anisotropyRotation; }
+
+        const colorU = uniform(base);
+        const ndv = abs(dot(normalView, positionViewDirection));
+        const hairAO = mix(float(0.3), float(1.0), smoothstep(float(0.05), float(0.55), ndv));
+
+        if (atlas) {
+            const a = texture(atlas, hairMatrixUv(atlas));
+            const coverage = a.r.mul(float(p.density)).clamp(0.0, 1.0);
+            const rootT = a.g;
+            const seed = a.b;
+            const toneMul = mix(float(p.rootDarkening), float(1.0), rootT);
+            const strandMul = seed.sub(0.5).mul(2.0 * p.seedVariation).add(1.0);
+            mat.colorNode = colorU.mul(toneMul).mul(strandMul).mul(hairAO);
+            const rough = float(p.roughness)
+                .add(seed.sub(0.5).mul(2.0 * p.roughnessSeedAmp))
+                .add(rootT.oneMinus().mul(0.06))
+                .max(float(p.roughnessFloor)).clamp(0.0, 1.0);
+            mat.roughnessNode = rough;
+            mat.opacityNode = blendPass ? coverage.mul(float(p.blendOpacity)) : coverage;
+        } else {
+            mat.colorNode = colorU.mul(hairAO);
+            mat.alphaTest = 0.5;
+        }
+
+        if (blendPass || !useA2C) {
+            mat.transparent = true; mat.depthWrite = false; mat.alphaTest = 0.0; mat.alphaToCoverage = false;
+        } else {
+            mat.transparent = false; mat.depthWrite = true; mat.alphaTest = 0.0; mat.alphaToCoverage = true;
+        }
+        return mat;
+    };
+
+    if (useA2C) {
+        return { primary: build(false), blend: p.mode === 'both' && p.blendOpacity > 0 ? build(true) : null };
+    }
+    // No MSAA: opaque alpha-clipped core + blended fringe (the classic two-pass hair).
+    const core = build(false);
+    core.transparent = false; core.depthWrite = true; core.alphaTest = 0.5;
+    const fringe = build(true);
+    (fringe as MeshPhysicalNodeMaterial).opacityNode = atlas
+        ? texture(atlas, hairMatrixUv(atlas)).r.mul(float(p.density)).clamp(0.0, 1.0)
+        : null;
+    return { primary: core, blend: fringe };
+}
+
+function makeLashMaterial(src: THREE.Material, coverageUrl: string | null, color: string): THREE.Material {
+    const srcMap = (src as THREE.MeshStandardMaterial).map ?? null;
+    const cov = coverageUrl ? loadDataTexture(coverageUrl, srcMap) : null;
+    if (!isWebGpuActive()) {
+        const m = src as THREE.MeshStandardMaterial;
+        m.vertexColors = false; m.color.set(color); m.map = null; m.roughness = 0.55; m.metalness = 0;
+        m.side = THREE.DoubleSide; m.transparent = true; m.depthWrite = false; m.alphaTest = 0.0;
+        if (cov) m.alphaMap = cov;
+        m.needsUpdate = true;
+        return m;
+    }
+    const mat = new MeshPhysicalNodeMaterial();
+    mat.name = src.name || 'lashes';
+    mat.color.set(color); mat.roughness = 0.55; mat.metalness = 0; mat.side = THREE.DoubleSide;
+    mat.transparent = true; mat.depthWrite = false; mat.alphaTest = 0.0;
+    if (cov) mat.opacityNode = texture(cov, uv(cov.channel)).r;
+    return mat;
+}
+
+/**
+ * MetaHuman's eye shell is shader-procedural in UE (a soft dark ring under the lids that
+ * sells socket depth); the export ships it fully transparent. Rebuild it as a radial
+ * gradient — clear over the iris, darkening toward the rim — drawn over the eyeball.
+ */
+let eyeOcclusionTex: THREE.Texture | null = null;
+function eyeOcclusionTexture(): THREE.Texture {
+    if (eyeOcclusionTex) return eyeOcclusionTex;
+    const size = 256;
+    const canvas = document.createElement('canvas');
+    canvas.width = size; canvas.height = size;
+    const ctx = canvas.getContext('2d')!;
+    ctx.fillStyle = '#000'; ctx.fillRect(0, 0, size, size);
+    const grad = ctx.createRadialGradient(size / 2, size / 2, size * 0.10, size / 2, size / 2, size * 0.55);
+    grad.addColorStop(0.0, '#000'); grad.addColorStop(0.55, '#555'); grad.addColorStop(1.0, '#fff');
+    ctx.fillStyle = grad; ctx.fillRect(0, 0, size, size);
+    const tex = new THREE.CanvasTexture(canvas);
+    tex.wrapS = tex.wrapT = THREE.ClampToEdgeWrapping;
+    tex.flipY = false;
+    tex.colorSpace = THREE.NoColorSpace;
+    eyeOcclusionTex = tex;
+    return tex;
+}
+
+function makeEyeShellMaterial(src: THREE.Material, strength: number): THREE.Material {
+    const tex = eyeOcclusionTexture();
+    if (!isWebGpuActive()) {
+        const m = new THREE.MeshStandardMaterial({ color: 0x050302, roughness: 0.85, metalness: 0, transparent: true, depthWrite: false, alphaMap: tex });
+        m.name = src.name; m.vertexColors = false;
+        return m;
+    }
+    const mat = new MeshPhysicalNodeMaterial();
+    mat.name = src.name;
+    mat.color.set(0x050302); mat.roughness = 0.85; mat.metalness = 0;
+    mat.transparent = true; mat.depthWrite = false; mat.alphaTest = 0;
+    mat.opacityNode = texture(tex, uv(0) as unknown as Vec2Node).r.mul(float(strength));
+    return mat;
+}
+
+/**
+ * Clothing: same glTF PBR inputs, but as an explicit node material under WebGPU. The renderer's
+ * internal conversion of the loader's classic MeshPhysicalMaterial mis-skinned the outfit once the
+ * engine animated the rig (shards at the shoulders and hem), while node materials deform correctly.
+ */
+function makeClothMaterial(src: THREE.Material): THREE.Material {
+    src.vertexColors = false;
+    if (!isWebGpuActive()) {
+        src.needsUpdate = true;
+        return src;
+    }
+    const mat = new MeshPhysicalNodeMaterial();
+    copyPbrProps(mat, src);
+    mat.vertexColors = false;
+    mat.metalness = 0;
+    mat.sheen = 0.25; // a little fabric sheen on cotton
+    mat.sheenRoughness = 0.8;
+    mat.sheenColor.set(0xffffff);
+    return mat;
+}
+
+function makeEyeMaterial(src: THREE.Material): THREE.Material {
+    const m = src as THREE.MeshPhysicalMaterial;
+    m.vertexColors = false;
+    m.roughness = 0.05;
+    m.metalness = 0;
+    if ('clearcoat' in m) { m.clearcoat = 1.0; m.clearcoatRoughness = 0.03; }
+    if ('ior' in m) m.ior = 1.376;
+    if ('specularIntensity' in m) m.specularIntensity = 1.0;
+    m.needsUpdate = true;
+    return m;
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+export interface UpgradeReport {
+    byPart: Record<string, number>;
+    hiddenMeshes: string[];
+    blendClones: THREE.Mesh[];
+}
+
+/**
+ * Walk a loaded MetaHuman glTF scene and swap in the upgraded materials.
+ * Returns the extra alpha-blend hair meshes it added (share geometry, no extra VRAM).
+ */
+export function upgradeMetaHumanMaterials(root: THREE.Object3D, options: Partial<MetaHumanMaterialOptions> = {}): UpgradeReport {
+    const opts: MetaHumanMaterialOptions = { ...DEFAULT_METAHUMAN_MATERIAL_OPTIONS, ...options };
+    const report: UpgradeReport = { byPart: {}, hiddenMeshes: [], blendClones: [] };
+    const blendJobs: Array<{ mesh: THREE.Mesh; material: THREE.Material }> = [];
+
+    root.traverse((obj) => {
+        const mesh = obj as THREE.Mesh;
+        if (!mesh.isMesh) return;
+        const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        materials.forEach((mat, i) => {
+            if (!mat) return;
+            const part = classifyMaterial(mat.name || '');
+            report.byPart[part] = (report.byPart[part] ?? 0) + 1;
+            let replacement: THREE.Material | null = null;
+            switch (part) {
+                case 'hidden':
+                    mesh.visible = false;
+                    report.hiddenMeshes.push(`${mesh.name}/${mat.name}`);
+                    return;
+                case 'skin':
+                    replacement = makeSkinMaterial(mat, opts, 1.0);
+                    break;
+                case 'body':
+                    replacement = makeSkinMaterial(mat, opts, 0.6);
+                    break;
+                case 'hair': {
+                    const built = makeHairMaterials(mat, opts.hairAtlasUrl, opts.hair, opts.msaa);
+                    replacement = built.primary;
+                    if (built.blend) blendJobs.push({ mesh, material: built.blend });
+                    break;
+                }
+                case 'brows': {
+                    const built = makeHairMaterials(mat, opts.browAtlasUrl, opts.brows, opts.msaa);
+                    replacement = built.primary;
+                    if (built.blend) blendJobs.push({ mesh, material: built.blend });
+                    break;
+                }
+                case 'lashes':
+                    replacement = makeLashMaterial(mat, opts.lashCoverageUrl, opts.hair.color);
+                    break;
+                case 'eye':
+                    replacement = makeEyeMaterial(mat);
+                    break;
+                case 'eyeshell':
+                    if (opts.eyeShellOcclusion <= 0) {
+                        mesh.visible = false;
+                        report.hiddenMeshes.push(`${mesh.name}/${mat.name}`);
+                        return;
+                    }
+                    replacement = makeEyeShellMaterial(mat, opts.eyeShellOcclusion);
+                    mesh.renderOrder = 2; // after the eyeballs, before lashes
+                    break;
+                case 'cloth':
+                    replacement = makeClothMaterial(mat);
+                    break;
+                case 'teeth':
+                case 'other':
+                default:
+                    mat.vertexColors = false;
+                    mat.needsUpdate = true;
+                    replacement = mat;
+                    break;
+            }
+            if (replacement && replacement !== mat) {
+                if (Array.isArray(mesh.material)) mesh.material[i] = replacement;
+                else mesh.material = replacement;
+            }
+        });
+        mesh.castShadow = true;
+        mesh.receiveShadow = true;
+        mesh.frustumCulled = false; // skinned + morphed meshes: bounds are stale, never cull
+    });
+
+    // Second pass: add the alpha-blend fringe clones (never mutate the graph while traversing).
+    for (const { mesh, material } of blendJobs) {
+        const clone = mesh.clone() as THREE.Mesh;
+        clone.material = material;
+        clone.name = mesh.name + '__blend';
+        clone.castShadow = false;
+        clone.receiveShadow = true;
+        clone.renderOrder = mesh.renderOrder + 1;
+        mesh.parent?.add(clone);
+        report.blendClones.push(clone);
+    }
+    return report;
+}