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

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

@@ -0,0 +1,580 @@
+/**
+ * A MetaHuman standing in the world: loads the original skinned GLB (no
+ * voxelization), upgrades its materials, shadows the player's capsule so the
+ * default block character can be hidden, and adds a little procedural life —
+ * blinks, eye saccades, breathing and a head that turns toward the camera —
+ * driven through the export's 51 ARKit blendshapes and the merged skeleton.
+ */
+import * as THREE from 'three';
+import type { EngineLike } from 'types/game.js';
+import { upgradeMetaHumanMaterials, type MetaHumanMaterialOptions, type UpgradeReport } from './MetaHumanMaterials.js';
+
+export interface MetaHumanActorOptions {
+    url: string;
+    /** Yaw added to the player's yaw so the model faces gameplay +Z. */
+    yawOffset: number;
+    materials: Partial<MetaHumanMaterialOptions>;
+    life: {
+        blink: boolean;
+        saccades: boolean;
+        breathing: boolean;
+        lookAtCamera: boolean;
+        /** Max head turn toward the camera, radians. */
+        maxHeadTurn: number;
+    };
+}
+
+interface LoadedGltf { scene: THREE.Group; animations: THREE.AnimationClip[] }
+
+export /** The engine CharacterLoader internals the arm rest-pose fix reads and patches (private fields). */
+interface EngineRetargetInternals {
+    skinnedRetargetDeltas?: Map<string, THREE.Quaternion> | null;
+    skinnedBind?: { rotations: Map<string, THREE.Quaternion> } | null;
+}
+
+export type HelperGroup =
+    | 'shoulder' | 'thigh' | 'elbow' | 'knee' | 'twistCor' | 'muscle' | 'clavicle' | 'lat' | 'wrist' | 'ankle' | 'finger';
+interface HelperJoint {
+    bone: THREE.Bone;
+    parent: THREE.Object3D;
+    group: HelperGroup;
+    /** Bind orientation of the helper and of its parent, in the model's frame. */
+    bindModelQ: THREE.Quaternion;
+    parentBindModelQ: THREE.Quaternion;
+}
+/** MetaHuman pose-driven helper joints by family. Children of a matched joint inherit its policy. */
+const HELPER_GROUPS: Array<[HelperGroup, RegExp]> = [
+    ['shoulder', /^upperarm_correctiveRoot_[lr]$/],
+    ['thigh', /^thigh_correctiveRoot_[lr]$/],
+    ['elbow', /^lowerarm_correctiveRoot_[lr]$/],
+    ['knee', /^calf_correctiveRoot_[lr]$/],
+    ['twistCor', /^(upperarm|lowerarm|thigh|calf)_twistCor_0[12]_[lr]$/],
+    ['muscle', /^upperarm_(bicep|tricep)_[lr]$/],
+    ['clavicle', /^clavicle_(scap|out|pec)_[lr]$/],
+    ['lat', /^spine_04_latissimus_[lr]$/],
+    ['wrist', /^wrist_(inner|outer)_[lr]$/],
+    ['ankle', /^ankle_(fwd|bck)_[lr]$/],
+    ['finger', /^(thumb|index|middle|ring|pinky)_\d\d_(bulge|half|in|side_out|side_inn|pip|dip|mcp|palm|palmMid)_[lr]$|^(index|middle|ring|pinky)_metacarpal_slide_[lr]$/],
+];
+
+const _v1 = new THREE.Vector3();
+const _v2 = new THREE.Vector3();
+const _q1 = new THREE.Quaternion();
+const _q2 = new THREE.Quaternion();
+const _q3 = new THREE.Quaternion();
+const IDENTITY_Q = new THREE.Quaternion();
+
+/** Rest-pose frame of a bone so we can rotate it about world axes without knowing its local axes. */
+interface BoneRest {
+    bone: THREE.Bone;
+    restQuat: THREE.Quaternion;
+    /** Inverse of the bone's rest WORLD rotation (model-space, root at identity). */
+    restWorldInv: THREE.Quaternion;
+}
+
+export class MetaHumanActor {
+    /** Standalone: our own group. Adopted: the engine-loaded glTF root (moved by the engine). */
+    root: THREE.Object3D = new THREE.Group();
+    private adopted = false;
+    private model: THREE.Object3D | null = null;
+    private morphMeshes: THREE.Mesh[] = [];
+    private bones = new Map<string, THREE.Bone>();
+    private head: BoneRest | null = null;
+    private spine: BoneRest[] = [];
+    private report: UpgradeReport | null = null;
+    private nativeHeight = 0;
+
+    // follow
+    private player: THREE.Object3D | null = null;
+    private feetOffsetY = 0;
+
+    // life state
+    private time = 0;
+    private blinkTimer = 2.5;
+    private blinkPhase = -1;       // <0 idle; else seconds into the blink
+    private blinkDouble = false;
+    private saccadeTimer = 1.0;
+    private gazeTarget = new THREE.Vector2();
+    private gaze = new THREE.Vector2();
+    private headCurrent = new THREE.Quaternion();
+    /** Smoothed head-look delta, applied on top of whatever pose the frame already gave the head bone. */
+    private headDelta = new THREE.Quaternion();
+
+    constructor(private readonly engine: EngineLike, private readonly options: MetaHumanActorOptions) {
+        this.root.name = 'MetaHumanActor';
+    }
+
+    getReport(): UpgradeReport | null { return this.report; }
+    isAdopted(): boolean { return this.adopted; }
+
+    /** Bind-pose world matrices (model space) per bone, from every skin's inverse bind matrices. */
+    private bindWorld = new Map<string, THREE.Matrix4>();
+    private buildBindWorldMap(model: THREE.Object3D): void {
+        this.bindWorld.clear();
+        model.traverse((o) => {
+            const m = o as THREE.SkinnedMesh;
+            if (!m.isSkinnedMesh || !m.skeleton) return;
+            m.skeleton.bones.forEach((b, i) => {
+                if (!this.bindWorld.has(b.name) && m.skeleton.boneInverses[i]) this.bindWorld.set(b.name, m.skeleton.boneInverses[i]!.clone().invert());
+            });
+        });
+    }
+    /** Bind-pose rotation of a bone in model space; falls back to the bone's current world rotation. */
+    private bindModelQuat(bone: THREE.Object3D, modelQInv: THREE.Quaternion): THREE.Quaternion {
+        const bw = this.bindWorld.get(bone.name);
+        if (bw) return new THREE.Quaternion().setFromRotationMatrix(bw);
+        return modelQInv.clone().multiply(bone.getWorldQuaternion(new THREE.Quaternion()));
+    }
+
+    /** Model-space forward direction of the character (the mesh faces +Z in its own space). */
+    getFacing(out = new THREE.Vector3()): THREE.Vector3 {
+        return out.set(0, 0, 1).applyQuaternion(this.root.getWorldQuaternion(new THREE.Quaternion())).setY(0).normalize();
+    }
+
+    /**
+     * Use a model the ENGINE already loaded (the high-res player path, driven by the engine's
+     * Mixamo locomotion): upgrade materials, wire morph meshes, take the bones from the real
+     * skeleton root (the player group also holds invisible skeleton clones with the same bone
+     * names), and parent the hair cards to the head. Must run while the rig is still at rest.
+     */
+    adopt(model: THREE.Object3D, skeletonRoot: THREE.Object3D, engineLoader: unknown = null): void {
+        this.adopted = true;
+        this.model = model;
+        this.root = model;
+        this.engineLoader = engineLoader as EngineRetargetInternals | null;
+        this.report = upgradeMetaHumanMaterials(model, this.options.materials);
+        skeletonRoot.traverse((o) => {
+            const bone = o as THREE.Bone;
+            if (bone.isBone && !this.bones.has(bone.name)) this.bones.set(bone.name, bone);
+        });
+        model.traverse((o) => {
+            const mesh = o as THREE.Mesh;
+            if (mesh.isMesh && mesh.morphTargetInfluences && mesh.morphTargetDictionary) this.morphMeshes.push(mesh);
+        });
+        model.updateMatrixWorld(true);
+        const box = new THREE.Box3().setFromObject(model);
+        this.nativeHeight = box.max.y - box.min.y;
+        // Everything "rest pose" below comes from the skins' inverse bind matrices, so it is
+        // correct even when the engine has already started animating the rig before we got here.
+        this.buildBindWorldMap(model);
+        this.captureRest();
+        this.captureHelperJoints();
+        this.attachCardsToHead(model);
+        console.log(
+            `[MetaHumanActor] adopted the engine's player model: height ${this.nativeHeight.toFixed(3)} m, ` +
+            `${this.morphMeshes.length} morph meshes, ${this.bones.size} bones, materials`, this.report.byPart,
+        );
+    }
+    getModel(): THREE.Object3D | null { return this.model; }
+    getBone(name: string): THREE.Bone | null { return this.bones.get(name) ?? null; }
+    getNativeHeight(): number { return this.nativeHeight; }
+
+    private lifeEnabled = true;
+    private speechEnergy = 0;
+    private readonly _qNod = new THREE.Quaternion();
+
+    /**
+     * MetaHuman corrective helper joints (`*_correctiveRoot_*` and their fwd/bck/in/out children)
+     * are positioned by Unreal's pose drivers, never by plain FK. Their skin weights straddle
+     * joint boundaries (a neck vertex carries 0.3 of a shoulder corrective), so letting them
+     * inherit the full animated rotation of their parent tears the mesh. Each group follows only
+     * a fraction of its parent's rotation delta from bind: 0 = pinned to the bind orientation
+     * (translates with the parent), 1 = rigid FK.
+     */
+    private engineLoader: EngineRetargetInternals | null = null;
+    private armRestPatched = false;
+    /** Rotate the arm chain's bind orientation up to a horizontal T-pose before the engine's per-bone
+     *  correction is built (MetaHumans bind in an A-pose; the engine's clips rest in a T-pose). */
+    armRestFix = true;
+
+    helperFollow: Record<HelperGroup, number> = {
+        // Coordinate-descent result (tools/metahuman/e2e/probes/helper-follow-descent.js) with the arm rest-pose
+        // fix in place and the weight-smoothed outfit (shorts 6 / shirt 12 Laplacian iterations):
+        // torn shirt/shorts/body edges at the Mixamo idle 600 (rigid FK) → ~270.
+        shoulder: 0.5, thigh: 0.5, elbow: 0.5, knee: 0.5, twistCor: 0, muscle: 1, clavicle: 0.5, lat: 1, wrist: 1, ankle: 1, finger: 1,
+    };
+    private helperJoints: HelperJoint[] = [];
+    private readonly _hq = [0, 1, 2, 3, 4, 5, 6].map(() => new THREE.Quaternion());
+
+    /** 0..1 loudness from the speech system: lifts the brows and nods the head on stressed syllables. */
+    setSpeechEnergy(e: number): void { this.speechEnergy = THREE.MathUtils.clamp(e, 0, 1); }
+    /** Freeze blinks / gaze / breathing / head-look (deterministic screenshots). */
+    setLifeEnabled(on: boolean): void {
+        this.lifeEnabled = on;
+        if (!on) {
+            this.setMorph('eyeBlinkLeft', 0); this.setMorph('eyeBlinkRight', 0);
+            for (const n of ['eyeLookOutLeft', 'eyeLookInLeft', 'eyeLookInRight', 'eyeLookOutRight', 'eyeLookUpLeft', 'eyeLookUpRight', 'eyeLookDownLeft', 'eyeLookDownRight']) this.setMorph(n, 0);
+        }
+    }
+
+    async load(): Promise<void> {
+        const gltf = (await this.engine.loader.loadAsync(this.options.url)) as LoadedGltf;
+        const model = gltf.scene;
+        this.model = model;
+
+        this.report = upgradeMetaHumanMaterials(model, this.options.materials);
+
+        model.traverse((o) => {
+            const mesh = o as THREE.Mesh;
+            if (mesh.isMesh && mesh.morphTargetInfluences && mesh.morphTargetDictionary) this.morphMeshes.push(mesh);
+            const bone = o as THREE.Bone;
+            if (bone.isBone && !this.bones.has(bone.name)) this.bones.set(bone.name, bone);
+        });
+
+        this.root.add(model);
+        this.engine.scene?.add(this.root);
+        this.root.updateMatrixWorld(true);
+
+        const box = new THREE.Box3().setFromObject(model);
+        this.nativeHeight = box.max.y - box.min.y;
+        // Feet on the actor origin, whatever the export's tiny offset was.
+        model.position.y -= box.min.y;
+
+        this.captureRest();
+        this.attachCardsToHead(model);
+        console.log(
+            `[MetaHumanActor] loaded ${this.options.url}: height ${this.nativeHeight.toFixed(3)} m, ` +
+            `${this.morphMeshes.length} morph meshes, ${this.bones.size} bones, materials`, this.report.byPart,
+            'hidden:', this.report.hiddenMeshes,
+        );
+    }
+
+    /**
+     * Hair, eyebrow and beard cards are exported as UNSKINNED meshes sitting in the head's
+     * rest pose (no JOINTS/WEIGHTS), so a head turn or a breathing spine leaves them behind.
+     * Re-parent every non-skinned mesh onto the head bone, keeping its world transform, so
+     * the cards ride the skeleton exactly like the skinned face does. Must run while the
+     * skeleton is still in its rest pose (before any animation touches the bones).
+     */
+    private attachCardsToHead(model: THREE.Object3D): void {
+        const head = this.bones.get('head');
+        if (!head) {
+            console.warn('[MetaHumanActor] no "head" bone — hair cards stay static');
+            return;
+        }
+        this.root.updateMatrixWorld(true);
+        const cards: THREE.Object3D[] = [];
+        model.traverse((o) => {
+            const mesh = o as THREE.Mesh;
+            if (mesh.isMesh && !(mesh as THREE.SkinnedMesh).isSkinnedMesh) cards.push(mesh);
+        });
+        const headBind = this.bindWorld.get('head');
+        const modelInv = new THREE.Matrix4().copy(model.matrixWorld).invert();
+        for (const mesh of cards) {
+            if (headBind) {
+                // Cards are authored in the head's REST pose: local = inv(headBind) · cardModelMatrix.
+                const cardModel = new THREE.Matrix4().copy(modelInv).multiply(mesh.matrixWorld);
+                const local = new THREE.Matrix4().copy(headBind).invert().multiply(cardModel);
+                mesh.removeFromParent();
+                head.add(mesh);
+                local.decompose(mesh.position, mesh.quaternion, mesh.scale);
+                mesh.updateMatrix();
+            } else {
+                head.attach(mesh);
+            }
+        }
+        console.log(`[MetaHumanActor] attached ${cards.length} card meshes to the head bone (${headBind ? 'from bind pose' : 'from current pose'}):`, cards.map((c) => c.name));
+    }
+
+    /** Find the corrective-root joints while the rig is at rest and remember their bind orientations. */
+    private captureHelperJoints(): void {
+        this.helperJoints = [];
+        const modelQInv = this.root.getWorldQuaternion(new THREE.Quaternion()).invert();
+        for (const [name, bone] of this.bones) {
+            const hit = HELPER_GROUPS.find(([, re]) => re.test(name));
+            if (!hit || !bone.parent) continue;
+            const group = hit[0];
+            const bindModelQ = this.bindModelQuat(bone, modelQInv);
+            const parentBindModelQ = this.bindModelQuat(bone.parent, modelQInv);
+            this.helperJoints.push({ bone, parent: bone.parent, group, bindModelQ, parentBindModelQ });
+        }
+        const counts: Record<string, number> = {};
+        for (const h of this.helperJoints) counts[h.group] = (counts[h.group] ?? 0) + 1;
+        console.log('[MetaHumanActor] pose-driven helper joints under policy:', counts);
+    }
+
+    /**
+     * The engine retargets a clip by mapping "clip rotation relative to the clip skeleton's rest"
+     * onto "rig rotation relative to the rig's bind". Its correction per bone is
+     * inv(B_src)·B_rig, which assumes both rests are the same anatomical pose. MetaHumans bind in an
+     * A-pose (upper arms 45° down) while the Mixamo clips rest in a T-pose, so every arm pose lands
+     * 45° too low and the arms cross into the torso. Fix: rebuild the arm chain's corrections with a
+     * virtual T-pose bind, R·B_rig, where R (model space) turns the bind upper-arm direction to
+     * horizontal-sideways. Runs once, as soon as the engine has built its map.
+     */
+    private patchArmRetarget(): void {
+        if (this.armRestPatched || !this.armRestFix || !this.engineLoader) return;
+        const deltas = this.engineLoader.skinnedRetargetDeltas;
+        const bind = this.engineLoader.skinnedBind?.rotations;
+        if (!deltas || deltas.size === 0 || !bind) return;
+        // Bind positions in model space, from the body skin's inverse bind matrices.
+        let skin: THREE.SkinnedMesh | null = null;
+        this.model?.traverse((o) => {
+            const m = o as THREE.SkinnedMesh;
+            if (!skin && m.isSkinnedMesh && m.skeleton.bones.some((b) => b.name === 'lowerarm_l')) skin = m;
+        });
+        if (!skin) return;
+        const sk = (skin as THREE.SkinnedMesh).skeleton;
+        const bindPos = (name: string): THREE.Vector3 | null => {
+            const i = sk.bones.findIndex((b) => b.name === name);
+            if (i < 0) return null;
+            return new THREE.Vector3().setFromMatrixPosition(sk.boneInverses[i]!.clone().invert());
+        };
+        let patched = 0;
+        const project = (v: THREE.Vector3, axis: THREE.Vector3) => v.clone().sub(axis.clone().multiplyScalar(v.dot(axis))).normalize();
+        for (const side of ['l', 'r'] as const) {
+            const shoulder = bindPos(`upperarm_${side}`), elbow = bindPos(`lowerarm_${side}`), wrist = bindPos(`hand_${side}`);
+            const knuckle = bindPos(`middle_01_${side}`), thumb = bindPos(`thumb_02_${side}`);
+            if (!shoulder || !elbow || !wrist || !knuckle || !thumb) continue;
+            // T-pose target: every segment straight out sideways, thumbs forward.
+            const dT = new THREE.Vector3(Math.sign(shoulder.x) || 1, 0, 0);
+            const rUp = new THREE.Quaternion().setFromUnitVectors(elbow.clone().sub(shoulder).normalize(), dT);
+            const dFore = wrist.clone().sub(elbow).normalize().applyQuaternion(rUp);
+            const rFore = new THREE.Quaternion().setFromUnitVectors(dFore, dT).multiply(rUp);
+            const dHand = knuckle.clone().sub(wrist).normalize().applyQuaternion(rFore);
+            const rHandDir = new THREE.Quaternion().setFromUnitVectors(dHand, dT).multiply(rFore);
+            // Roll the whole (now straight) arm about its axis so the thumb points forward (+Z).
+            const thumbDir = project(thumb.clone().sub(wrist).applyQuaternion(rHandDir), dT);
+            const rRoll = new THREE.Quaternion().setFromUnitVectors(thumbDir, new THREE.Vector3(0, 0, 1));
+            const R: Array<[RegExp, THREE.Quaternion]> = [
+                [new RegExp(`^upperarm_${side}$`), rRoll.clone().multiply(rUp)],
+                [new RegExp(`^lowerarm_${side}$`), rRoll.clone().multiply(rFore)],
+                [new RegExp(`^(hand|thumb|index|middle|ring|pinky)_(.*_)?${side}$`), rRoll.clone().multiply(rHandDir)],
+            ];
+            for (const [name, delta] of deltas) {
+                const hit = R.find(([re]) => re.test(name));
+                const bRig = hit && bind.get(name);
+                if (!hit || !bRig) continue;
+                const bSrc = bRig.clone().multiply(delta.clone().invert());   // B_rig = B_src · delta
+                delta.copy(bSrc.invert().multiply(hit[1]).multiply(bRig));   // inv(B_src) · R · B_rig
+                patched++;
+            }
+            const deg = (q: THREE.Quaternion) => THREE.MathUtils.radToDeg(2 * Math.acos(Math.min(1, Math.abs(q.w)))).toFixed(0);
+            console.log(`[MetaHumanActor] arm ${side}: virtual T-pose — upper ${deg(rUp)}°, forearm ${deg(rFore)}°, hand ${deg(rHandDir)}°, roll ${deg(rRoll)}°`);
+        }
+        this.armRestPatched = true;
+        console.log(`[MetaHumanActor] arm rest-pose fix applied to ${patched} retarget corrections`);
+    }
+
+    /** Runs after the engine has posed the rig this frame: partial-follow the corrective roots. */
+    private applyHelperJointPolicy(): void {
+        if (this.helperJoints.length === 0) return;
+        const [modelQ, modelQInv, parentW, parentModel, delta, partial, tmp] = this._hq as [THREE.Quaternion, THREE.Quaternion, THREE.Quaternion, THREE.Quaternion, THREE.Quaternion, THREE.Quaternion, THREE.Quaternion];
+        this.root.getWorldQuaternion(modelQ);
+        modelQInv.copy(modelQ).invert();
+        for (const h of this.helperJoints) {
+            const follow = THREE.MathUtils.clamp(this.helperFollow[h.group], 0, 1);
+            h.parent.updateWorldMatrix(true, false);
+            h.parent.getWorldQuaternion(parentW);
+            parentModel.copy(modelQInv).multiply(parentW);
+            // The parent's animated rotation relative to its bind, in model space.
+            delta.copy(parentModel).multiply(tmp.copy(h.parentBindModelQ).invert());
+            partial.identity().slerp(delta, follow);
+            // Helper world rotation = partial parent delta applied to the helper's bind orientation.
+            const targetWorld = tmp.copy(modelQ).multiply(partial.multiply(h.bindModelQ));
+            h.bone.quaternion.copy(parentW.invert().multiply(targetWorld));
+            h.bone.updateMatrix();
+        }
+    }
+
+    private captureRest(): void {
+        const rootQInv = this.root.getWorldQuaternion(new THREE.Quaternion()).invert();
+        const rest = (name: string): BoneRest | null => {
+            const bone = this.bones.get(name);
+            if (!bone) return null;
+            bone.updateMatrixWorld(true);
+            const bw = this.bindWorld.get(name);
+            let restQuat: THREE.Quaternion;
+            let wq: THREE.Quaternion;
+            if (bw && bone.parent) {
+                // Bind world rotation (model space) and the bind LOCAL rotation from the parent's bind.
+                wq = new THREE.Quaternion().setFromRotationMatrix(bw);
+                const pw = this.bindWorld.get(bone.parent.name);
+                restQuat = pw ? new THREE.Quaternion().setFromRotationMatrix(pw).invert().multiply(wq) : bone.quaternion.clone();
+            } else {
+                wq = bone.getWorldQuaternion(new THREE.Quaternion()).premultiply(rootQInv);
+                restQuat = bone.quaternion.clone();
+            }
+            return { bone, restQuat, restWorldInv: wq.invert() };
+        };
+        this.head = rest('head');
+        if (this.head) this.headCurrent.copy(this.head.restQuat);
+        this.spine = ['spine_03', 'spine_04', 'spine_05'].map(rest).filter((r): r is BoneRest => r !== null);
+    }
+
+    /** Follow the player's capsule: feet at the capsule bottom, same yaw. */
+    attachToPlayer(player: THREE.Object3D, feetOffsetY: number): void {
+        this.player = player;
+        this.feetOffsetY = feetOffsetY;
+        this.syncToPlayer();
+    }
+
+    private syncToPlayer(): void {
+        if (!this.player) return;
+        this.root.position.set(this.player.position.x, this.player.position.y + this.feetOffsetY, this.player.position.z);
+        this.root.rotation.y = this.player.rotation.y + this.options.yawOffset;
+    }
+
+    setPose(position: THREE.Vector3, yaw: number): void {
+        this.player = null;
+        this.root.position.copy(position);
+        this.root.rotation.y = yaw;
+    }
+
+    /** World position of the head bone (falls back to 1.6 m above the feet). */
+    getHeadWorldPosition(out: THREE.Vector3): THREE.Vector3 {
+        if (this.head) return this.head.bone.getWorldPosition(out);
+        return out.copy(this.root.position).add(_v1.set(0, 1.6, 0));
+    }
+
+    setMorph(name: string, value: number): void {
+        for (const mesh of this.morphMeshes) {
+            const idx = mesh.morphTargetDictionary![name];
+            if (idx !== undefined) mesh.morphTargetInfluences![idx] = value;
+        }
+    }
+
+    getMorphNames(): string[] {
+        const first = this.morphMeshes[0];
+        return first ? Object.keys(first.morphTargetDictionary!) : [];
+    }
+
+    update(deltaTime: number, cameraPosition: THREE.Vector3 | null): void {
+        if (!this.model) return;
+        const dt = Math.min(deltaTime, 0.1);
+        this.time += dt;
+        if (!this.adopted) this.syncToPlayer();
+        if (this.adopted) {
+            this.patchArmRetarget();
+            this.applyHelperJointPolicy();
+        }
+        this.updateSpeechAccents();
+        if (!this.lifeEnabled) return;
+        const life = this.options.life;
+        if (life.blink) this.updateBlink(dt);
+        if (life.saccades) this.updateSaccades(dt);
+        // The engine's idle clip already breathes when it drives the rig.
+        if (life.breathing && !this.adopted) this.updateBreathing();
+        if (life.lookAtCamera) this.updateHeadLook(dt, cameraPosition);
+    }
+
+    // --- blinking ----------------------------------------------------------
+    private updateBlink(dt: number): void {
+        const CLOSE = 0.07, HOLD = 0.03, OPEN = 0.13;
+        if (this.blinkPhase < 0) {
+            this.blinkTimer -= dt;
+            if (this.blinkTimer <= 0) {
+                this.blinkPhase = 0;
+                this.blinkDouble = Math.random() < 0.15;
+            }
+            return;
+        }
+        this.blinkPhase += dt;
+        let v: number;
+        if (this.blinkPhase < CLOSE) v = this.blinkPhase / CLOSE;
+        else if (this.blinkPhase < CLOSE + HOLD) v = 1;
+        else if (this.blinkPhase < CLOSE + HOLD + OPEN) v = 1 - (this.blinkPhase - CLOSE - HOLD) / OPEN;
+        else {
+            v = 0;
+            this.blinkPhase = -1;
+            this.blinkTimer = this.blinkDouble ? 0.18 : 1.8 + Math.random() * 4.0;
+            this.blinkDouble = false;
+        }
+        const eased = v * v * (3 - 2 * v);
+        this.setMorph('eyeBlinkLeft', eased);
+        this.setMorph('eyeBlinkRight', eased);
+    }
+
+    // --- eye saccades (ARKit look shapes) ------------------------------------
+    private updateSaccades(dt: number): void {
+        this.saccadeTimer -= dt;
+        if (this.saccadeTimer <= 0) {
+            this.saccadeTimer = 0.5 + Math.random() * 2.5;
+            // Mostly small drifts, sometimes a larger glance; pitch stays gentle.
+            const big = Math.random() < 0.25;
+            this.gazeTarget.set(
+                (Math.random() * 2 - 1) * (big ? 0.7 : 0.25),
+                (Math.random() * 2 - 1) * (big ? 0.35 : 0.15),
+            );
+        }
+        // Saccades are fast: snap most of the way each frame.
+        this.gaze.lerp(this.gazeTarget, 1 - Math.exp(-dt * 25));
+        const yaw = this.gaze.x, pitch = this.gaze.y;
+        // +yaw = character's left. Left eye looks OUT, right eye looks IN (and vice versa).
+        this.setMorph('eyeLookOutLeft', Math.max(0, yaw));
+        this.setMorph('eyeLookInLeft', Math.max(0, -yaw));
+        this.setMorph('eyeLookInRight', Math.max(0, yaw));
+        this.setMorph('eyeLookOutRight', Math.max(0, -yaw));
+        this.setMorph('eyeLookUpLeft', Math.max(0, pitch));
+        this.setMorph('eyeLookUpRight', Math.max(0, pitch));
+        this.setMorph('eyeLookDownLeft', Math.max(0, -pitch));
+        this.setMorph('eyeLookDownRight', Math.max(0, -pitch));
+    }
+
+    // --- breathing (tiny chest pitch) ----------------------------------------
+    private updateBreathing(): void {
+        const breath = Math.sin(this.time * (Math.PI * 2) / 4.2); // ~14 breaths / min
+        const angle = breath * 0.012;
+        for (const s of this.spine) this.rotateAboutWorldAxis(s, _v1.set(1, 0, 0), angle, 1);
+    }
+
+    /** bone = rest * (world-axis rotation expressed in the bone's rest-local frame), blended by `weight`. */
+    private rotateAboutWorldAxis(r: BoneRest, worldAxis: THREE.Vector3, angle: number, weight: number): void {
+        const localAxis = _v2.copy(worldAxis).applyQuaternion(r.restWorldInv).normalize();
+        _q1.setFromAxisAngle(localAxis, angle);
+        _q2.copy(r.restQuat).multiply(_q1);
+        if (weight >= 1) r.bone.quaternion.copy(_q2);
+        else r.bone.quaternion.slerp(_q2, weight);
+    }
+
+    // --- speech accents: brows + a nod on loud syllables -------------------------
+    private updateSpeechAccents(): void {
+        const e = this.speechEnergy;
+        this.setMorph('browInnerUp', e * 0.3);
+        this.setMorph('browOuterUpLeft', e * 0.18);
+        this.setMorph('browOuterUpRight', e * 0.18);
+    }
+
+    // --- head turns toward the camera ------------------------------------------
+    private updateHeadLook(dt: number, cameraPosition: THREE.Vector3 | null): void {
+        const h = this.head;
+        if (!h) return;
+        // Base = whatever this frame already gave the head (the engine's animation pose when
+        // adopted, the rest pose otherwise). We only ever ADD a smoothed look delta on top.
+        const base = h.bone.quaternion;
+        const delta = _q2.identity();
+        if (cameraPosition) {
+            const headPos = h.bone.getWorldPosition(_v1);
+            const toCam = _v2.subVectors(cameraPosition, headPos).normalize();
+            // Only when the camera is roughly in front of the character.
+            const forward = new THREE.Vector3(0, 0, 1).applyQuaternion(this.root.getWorldQuaternion(_q1));
+            const facing = toCam.dot(forward);
+            if (facing > 0.15) {
+                // Direction to camera in the head's rest-local frame (good enough for the small
+                // turns we allow, even while the body animates).
+                const rootInv = _q1.invert();
+                const toCamLocal = toCam.applyQuaternion(rootInv).applyQuaternion(h.restWorldInv).normalize();
+                const fwdLocal = new THREE.Vector3(0, 0, 1).applyQuaternion(h.restWorldInv).normalize();
+                delta.setFromUnitVectors(fwdLocal, toCamLocal);
+                let angle = 2 * Math.acos(THREE.MathUtils.clamp(delta.w, -1, 1));
+                if (angle > Math.PI) angle = 2 * Math.PI - angle;
+                const max = this.options.life.maxHeadTurn;
+                if (angle > max) delta.slerp(IDENTITY_Q, 1 - max / angle);
+            }
+        }
+        if (this.speechEnergy > 0.02) {
+            // Talking heads move: a small pitch nod that follows the loudness envelope.
+            const nod = this.speechEnergy * 0.045 * Math.sin(this.time * 9.0);
+            const localX = _v2.set(1, 0, 0).applyQuaternion(h.restWorldInv).normalize();
+            delta.multiply(this._qNod.setFromAxisAngle(localX, nod));
+        }
+        this.headDelta.slerp(delta, 1 - Math.exp(-dt * 4));
+        h.bone.quaternion.copy(base).multiply(this.headDelta);
+        this.headCurrent.copy(h.bone.quaternion);
+    }
+
+    dispose(): void {
+        if (!this.adopted) this.engine.scene?.remove(this.root);
+        this.model = null;
+    }
+}