@convai/embody 1.0.1-beta.0 → 1.1.0-beta.0

package/dist/inspect/report.js

@@ -0,0 +1,193 @@
+import { detectRig } from '../clips/retarget.js';
+import { REQUIRED_BONES } from '../rig/resolve.js';
+import { CHANNELS } from './morphMap.js';
+/** The mouth motions speech needs, each by the channels that carry it. */
+const MOUTH_GROUPS = {
+    'jaw open': /^jawOpen$/,
+    'lip rounding (oo, w)': /^(mouthFunnel|mouthLipsPurse)/,
+    'lip closure (m, b, p)': /^(mouthLipsTogether|mouthPress|mouthLipsPress)/,
+    'lip spread (ee, smile)': /^(mouthCornerPull|mouthStretch)/,
+    'upper and lower lip (f, v, open vowels)': /^(mouthUpperLipRaise|mouthLowerLipDepress)/,
+};
+const PREFIX = 'CTRL_expressions_';
+const list = (xs, n = 6) => (xs.length > n ? `${xs.slice(0, n).join(', ')} and ${xs.length - n} more` : xs.join(', '));
+const configSnippet = (map) => `morphMap: {\n${Object.entries(map).map(([k, v]) => `  ${k}: ${JSON.stringify(v)},`).join('\n')}\n}`;
+export function inspectCharacter(input) {
+    const { root, rig, match } = input;
+    const issues = [];
+    // ── face ──────────────────────────────────────────────────────────────────
+    const answered = new Set();
+    let morphTargets = 0;
+    const seen = new Set();
+    root.traverse((o) => {
+        const dict = o.morphTargetDictionary;
+        if (!dict)
+            return;
+        for (const k of Object.keys(dict)) {
+            if (k.startsWith(PREFIX))
+                answered.add(k.slice(PREFIX.length));
+            if (!seen.has(k) && !(k.startsWith(PREFIX) && input.morphMap.map[k.slice(PREFIX.length)]))
+                seen.add(k);
+        }
+    });
+    morphTargets = seen.size;
+    const bound = CHANNELS.filter((c) => answered.has(c));
+    const mouth = Object.fromEntries(Object.entries(MOUTH_GROUPS).map(([g, re]) => [g, bound.some((c) => re.test(c))]));
+    const blink = rig.morphs.has('blinkL') || rig.morphs.has('blinkR');
+    const eyeLook = rig.morphs.has('eyeLookUpL') || rig.morphs.has('eyeLookInL');
+    if (match.naming === 'none') {
+        issues.push({
+            level: 'error', area: 'face',
+            message: 'The model has no morph targets (blendshapes), so its face cannot move: no lipsync, no blinking, no eye movement. Head and body motion still work.',
+            fix: 'Export the face with blendshapes: MetaHuman expressions (CTRL_expressions_*) for the best lipsync, or the ARKit 52. In Blender, keep shape keys on export; in Maya or Unreal, export morph targets.',
+        });
+    }
+    else {
+        if (!mouth['jaw open']) {
+            issues.push({
+                level: 'error', area: 'face',
+                message: `None of the model's ${morphTargets} morph targets opens the jaw under a name embody recognises, so the mouth will not move with speech.` +
+                    (match.naming === 'visemes' ? ` It has viseme shapes (${list(match.visemes, 4)}); the stream drives expression channels, not visemes.` : ''),
+                fix: 'Map the jaw-open shape and the other mouth shapes with `morphMap` (MetaHuman channel name → your morph name), e.g. morphMap: { jawOpen: "MouthOpen" }, or export the ARKit 52 or MetaHuman expressions.',
+            });
+        }
+        else {
+            const lacking = Object.entries(mouth).filter(([, ok]) => !ok).map(([g]) => g);
+            if (lacking.length) {
+                issues.push({
+                    level: 'warning', area: 'face',
+                    message: `The mouth opens with speech but cannot make ${list(lacking)}: speech will look like a jaw flapping.`,
+                    fix: 'Add those shapes to the model, or map existing ones with `morphMap`.',
+                });
+            }
+        }
+        if (!blink)
+            issues.push({ level: 'warning', area: 'face', message: 'No blink shapes found: the eyes will never blink.', fix: 'Map them with `morphMap: { eyeBlinkL: "…", eyeBlinkR: "…" }`.' });
+        if (!eyeLook)
+            issues.push({ level: 'warning', area: 'face', message: 'No eye-look shapes found: the eyes will not follow the camera.', fix: 'Map eyeLookUpL/DownL/LeftL/RightL and the R side with `morphMap`.' });
+        if (match.naming === 'arkit') {
+            issues.push({
+                level: 'info', area: 'face',
+                message: 'ARKit face: MetaHuman channels were mapped onto ARKit shapes by meaning. Lipsync works; the finer MetaHuman lip detail (sticky lips, lip roll-in per corner) has no ARKit shape.',
+            });
+        }
+    }
+    const mapped = Object.keys(input.morphMap.map).length;
+    if (input.morphMap.source === 'auto' && mapped) {
+        issues.push({
+            level: 'info', area: 'face',
+            message: `${mapped} MetaHuman channel${mapped === 1 ? '' : 's'} mapped onto the model's own shapes by name. Pass the map yourself to pin it or correct an entry.`,
+            fix: configSnippet(input.morphMap.map),
+        });
+    }
+    if (input.morphMap.unknown.length) {
+        issues.push({
+            level: 'error', area: 'face',
+            message: `morphMap names shapes the model does not have: ${list(input.morphMap.unknown)}.`,
+            fix: Object.keys(match.map).length ? `Shapes embody found by name:\n${configSnippet(match.map)}` : 'Check the names against the model in a glTF viewer.',
+        });
+    }
+    // ── skeleton ──────────────────────────────────────────────────────────────
+    const bones = [];
+    root.traverse((o) => { if (o.isBone)
+        bones.push(o); });
+    const missing = rig.missing.map((r) => rig.profile.bones[r]?.[0] ?? r);
+    const detected = detectRig(root);
+    const kind = bones.length === 0 ? 'none'
+        : missing.length === 0 ? 'convai-mha-1'
+            : root.getObjectByName('CC_Base_Head') ? 'character-creator'
+                : detected?.kind ?? 'unknown';
+    if (kind === 'none') {
+        issues.push({
+            level: 'warning', area: 'skeleton',
+            message: 'The model has no skeleton: it cannot play animations, turn its head or breathe.',
+            fix: 'Rig and skin the model (Mixamo auto-rigging works) and export the armature with it.',
+        });
+    }
+    else if (missing.length) {
+        const what = missing.length === REQUIRED_BONES.length ? 'Gaze and breathing are off' : 'Parts of gaze and breathing are off';
+        issues.push({
+            level: 'warning', area: 'skeleton',
+            message: `${what}: the ${kind === 'unknown' ? '' : `${kind} `}skeleton has no ${list(missing)} (MetaHuman bone names). The head will not turn toward the camera.` +
+                (kind === 'mixamo' || kind === 'unreal' || kind === 'rigify' ? ` Animations from Mixamo, Unreal and Rigify skeletons still play: they are retargeted.` : ''),
+            fix: 'Rename the head, neck and spine bones to head, neck_01, neck_02, spine_04 and spine_02, or retarget the model to the MetaHuman skeleton.',
+        });
+    }
+    // ── animations ────────────────────────────────────────────────────────────
+    const registered = new Map(input.registered.map((r) => [r.name, r]));
+    const clips = input.clipNotes.map((n) => {
+        const r = registered.get(n.name);
+        return r ? { ...n, tracks: r.kept, dropped: r.dropped } : n;
+    });
+    for (const c of clips) {
+        if (c.status === 'not-in-file') {
+            issues.push({
+                level: 'error', area: 'animation',
+                message: `Clip "${c.name}" is not in ${c.url}${c.available?.length ? `, which has: ${list(c.available, 8)}` : ', which has no animations'}.`,
+                fix: c.available?.length ? `Use one of those names as the clip's key, e.g. { ${JSON.stringify(c.available[0])}: ${JSON.stringify(c.url)} }.` : undefined,
+            });
+        }
+        else if (c.status === 'not-loaded') {
+            issues.push({ level: 'error', area: 'animation', message: `Clip "${c.name}": ${c.url} did not load${c.detail ? ` (${c.detail})` : ''}.`, fix: 'Check the URL, that the host sends CORS headers for this page, and that the file is GLB, glTF or FBX.' });
+        }
+        else if (c.status === 'failed') {
+            issues.push({ level: 'error', area: 'animation', message: `Clip "${c.name}" could not be retargeted from its ${c.from} skeleton: ${c.detail}` });
+        }
+        else if ('tracks' in c && c.tracks === 0) {
+            issues.push({
+                level: 'error', area: 'animation',
+                message: `Clip "${c.name}" moves nothing on this model: none of its ${c.dropped} tracks names a bone the model has.`,
+                fix: 'Export the clip on the model\'s own skeleton, or on Mixamo, the Unreal mannequin or Rigify, which embody retargets.',
+            });
+        }
+        else if (c.status === 'foreign') {
+            issues.push({
+                level: 'warning', area: 'animation',
+                message: `Clip "${c.name}" is on a different skeleton (${c.from ?? 'unrecognised'}) and ${c.detail}; it plays only where bone names happen to match.`,
+                fix: 'Export the clip on the model\'s own skeleton, or on Mixamo, the Unreal mannequin or Rigify, which embody retargets.',
+            });
+        }
+        else if (c.status === 'retargeted') {
+            issues.push({ level: 'info', area: 'animation', message: `Clip "${c.name}" was retargeted from a ${c.from} skeleton.` });
+        }
+    }
+    if (input.embedded) {
+        issues.push({ level: 'info', area: 'animation', message: `No clips were declared; the ${input.embedded} animation${input.embedded === 1 ? '' : 's'} inside the model file ${input.embedded === 1 ? 'is' : 'are'} used.` });
+    }
+    if (input.idleRequested && input.idle !== input.idleRequested) {
+        issues.push({
+            level: 'error', area: 'animation',
+            message: `idleClip "${input.idleRequested}" is not one of the character's clips${input.registered.length ? ` (${list(input.registered.map((r) => r.name), 8)})` : ''}.`,
+        });
+    }
+    else if (!input.idle && kind !== 'none' && input.idleRequested === undefined) {
+        issues.push({
+            level: 'warning', area: 'animation',
+            message: 'No animation plays at rest, so the body holds its bind pose (often arms out).',
+            fix: 'Add an idle clip: animations: { Idle: "https://…/idle.fbx" } (Mixamo FBX, GLB and glTF work).',
+        });
+    }
+    return {
+        ok: !issues.some((i) => i.level === 'error'),
+        face: { morphTargets, naming: match.naming, channels: { bound: bound.length, of: CHANNELS.length }, mouth, blink, eyeLook, morphMap: input.morphMap.map },
+        skeleton: { kind, bones: bones.length, missing },
+        animations: { clips, idle: input.idle },
+        issues,
+    };
+}
+/** The report as console text: a summary line, then each issue with its fix. */
+export function formatReport(report, label = 'character') {
+    const f = report.face;
+    const lines = [
+        `[embody] ${label}: ${report.ok ? 'ready' : 'needs attention'} — face ${f.naming} (${f.channels.bound}/${f.channels.of} channels), skeleton ${report.skeleton.kind}, ${report.animations.clips.length || 'no'} clip${report.animations.clips.length === 1 ? '' : 's'}${report.animations.idle ? `, idle "${report.animations.idle}"` : ''}`,
+    ];
+    const order = ['error', 'warning', 'info'];
+    for (const level of order) {
+        for (const i of report.issues.filter((x) => x.level === level)) {
+            lines.push(`  ${level.toUpperCase()} (${i.area}) ${i.message}`);
+            if (i.fix)
+                lines.push(...i.fix.split('\n').map((l, k) => `    ${k === 0 ? 'fix: ' : '     '}${l}`));
+        }
+    }
+    return lines.join('\n');
+}

package/dist/motion/eyeAim.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Eyes that look at a point, each on its own, measured from the body itself.
+ *
+ * convai-mha-1 turns the eyes with blend shapes, not bones, and a blend shape
+ * moves a vertex in a straight line rather than round the eyeball, so weight
+ * is not angle — and how far a shape turns the eye is a property of each
+ * body's sculpt. The fixed `residual × 0.65` mapping this replaces moved the
+ * eyes about a third of the way to the camera on the published bodies (the
+ * shapes turn them ~50° sideways, 33° up and 44° down at full weight): they
+ * never met the lens.
+ *
+ * So at load, from the eye mesh's own geometry:
+ *  · each eye's vertices are the ones its own (`…L` / `…R`) look shapes move;
+ *  · the pupil is the vertex at the centre of the iris texture (uv 0.5, 0.5),
+ *    the eyeball centre one eyeball radius (12 mm) behind it;
+ *  · "left" and "up" are the directions the look-left and look-up shapes move
+ *    the pupil — no assumption about the export's axes or units;
+ *  · each shape's weight → angle curve is tabulated from the pupil's path.
+ *
+ * Each frame both eyes aim at the target separately (so they converge on a
+ * near one), the weights come from inverting the curves, and the pupil's real
+ * direction — with every other active shape applied (relax, lids, blink) — is
+ * fed back as a correction the next frame.
+ */
+import * as THREE from 'three';
+import type { ResolvedRig } from '../rig/resolve.js';
+type Curve = number[];
+export interface EyeAimLimits {
+    left: number;
+    right: number;
+    up: number;
+    down: number;
+}
+/** The weight at which a curve reaches `deg` (0 at or below 0, 1 past its reach). */
+export declare function weightFor(curve: Curve, deg: number): number;
+export declare class EyeAim {
+    private readonly rig;
+    private readonly eyes;
+    private readonly mesh;
+    private readonly head;
+    private readonly toHead;
+    private readonly m;
+    private readonly v;
+    private readonly w;
+    private readonly t;
+    readonly limits: EyeAimLimits;
+    /**
+     * Measure the body. Returns null when it cannot be measured — no skinned eye
+     * mesh carrying both eyes' look shapes, or one not bound to the head bone —
+     * and the caller keeps its fallback.
+     */
+    static calibrate(rig: ResolvedRig): EyeAim | null;
+    private constructor();
+    /**
+     * Where `target` (world) lies from between the eyes, in the eyes' neutral
+     * frame: yaw (+ toward the character's left) and pitch (+ up), degrees.
+     */
+    angleTo(target: THREE.Vector3): {
+        yaw: number;
+        pitch: number;
+    };
+    /**
+     * Turn the eyes toward `target` (world), offset by `offset` degrees.
+     * `rate` is the exponential approach rate, 1/s. Writes only the eight
+     * look shapes.
+     */
+    update(dt: number, target: THREE.Vector3 | null, rate: number, offset?: {
+        yaw: number;
+        pitch: number;
+    }): void;
+    /** Current aim of each eye, degrees, for tests and debugging. */
+    get aim(): {
+        yaw: number;
+        pitch: number;
+    }[];
+    /**
+     * The closed-loop correction each eye currently carries, degrees. Near zero
+     * when the measured curves are right and no other shape moves the pupil.
+     */
+    get correction(): {
+        yaw: number;
+        pitch: number;
+    }[];
+    /** The pupil, every active shape applied, measured as the eye sees it: degrees. */
+    measured(): {
+        yaw: number;
+        pitch: number;
+    }[];
+    private local;
+    private angles;
+    private pupilNow;
+    private write;
+}
+export {};

package/dist/motion/eyeAim.js

@@ -0,0 +1,276 @@
+/**
+ * Eyes that look at a point, each on its own, measured from the body itself.
+ *
+ * convai-mha-1 turns the eyes with blend shapes, not bones, and a blend shape
+ * moves a vertex in a straight line rather than round the eyeball, so weight
+ * is not angle — and how far a shape turns the eye is a property of each
+ * body's sculpt. The fixed `residual × 0.65` mapping this replaces moved the
+ * eyes about a third of the way to the camera on the published bodies (the
+ * shapes turn them ~50° sideways, 33° up and 44° down at full weight): they
+ * never met the lens.
+ *
+ * So at load, from the eye mesh's own geometry:
+ *  · each eye's vertices are the ones its own (`…L` / `…R`) look shapes move;
+ *  · the pupil is the vertex at the centre of the iris texture (uv 0.5, 0.5),
+ *    the eyeball centre one eyeball radius (12 mm) behind it;
+ *  · "left" and "up" are the directions the look-left and look-up shapes move
+ *    the pupil — no assumption about the export's axes or units;
+ *  · each shape's weight → angle curve is tabulated from the pupil's path.
+ *
+ * Each frame both eyes aim at the target separately (so they converge on a
+ * near one), the weights come from inverting the curves, and the pupil's real
+ * direction — with every other active shape applied (relax, lids, blink) — is
+ * fed back as a correction the next frame.
+ */
+import * as THREE from 'three';
+/** Weight steps per tabulated curve. */
+const STEPS = 50;
+/** Human eyeball radius, metres. */
+const EYEBALL_RADIUS = 0.012;
+/** The weight at which a curve reaches `deg` (0 at or below 0, 1 past its reach). */
+export function weightFor(curve, deg) {
+    if (deg <= 0)
+        return 0;
+    for (let j = 1; j < curve.length; j++)
+        if (curve[j] >= deg) {
+            const a = curve[j - 1];
+            return (j - 1 + (deg - a) / Math.max(1e-6, curve[j] - a)) / (curve.length - 1);
+        }
+    return 1;
+}
+const SIDES = {
+    // The profile names in/out in the rig basis' frame; see CONVAI_MHA_1. For
+    // the left eye "in" is toward the character's left, for the right eye "out".
+    L: { left: 'eyeLookInL', right: 'eyeLookOutL', up: 'eyeLookUpL', down: 'eyeLookDownL' },
+    R: { left: 'eyeLookOutR', right: 'eyeLookInR', up: 'eyeLookUpR', down: 'eyeLookDownR' },
+};
+function morphIndex(rig, role, mesh) {
+    return rig.morphs.get(role)?.find((b) => b.mesh === mesh)?.index;
+}
+export class EyeAim {
+    /**
+     * Measure the body. Returns null when it cannot be measured — no skinned eye
+     * mesh carrying both eyes' look shapes, or one not bound to the head bone —
+     * and the caller keeps its fallback.
+     */
+    static calibrate(rig) {
+        const head = rig.bones.head;
+        if (!head)
+            return null;
+        const candidates = rig.morphs.get('eyeLookUpL')?.map((b) => b.mesh) ?? [];
+        const mesh = candidates.find((m) => {
+            const mat = (Array.isArray(m.material) ? m.material[0] : m.material);
+            return m.isSkinnedMesh && /^eyes?(?!occlusion)/i.test(mat?.name ?? '');
+        });
+        if (!mesh?.geometry.morphAttributes.position)
+            return null;
+        const bone = mesh.skeleton.bones.indexOf(head);
+        if (bone < 0)
+            return null;
+        try {
+            return new EyeAim(rig, mesh, head, bone);
+        }
+        catch {
+            return null;
+        }
+    }
+    constructor(rig, mesh, head, bone) {
+        this.rig = rig;
+        this.eyes = [];
+        this.toHead = new THREE.Matrix4();
+        this.m = new THREE.Matrix4();
+        this.v = new THREE.Vector3();
+        this.w = new THREE.Vector3();
+        this.t = new THREE.Vector3();
+        this.mesh = mesh;
+        this.head = head;
+        // Mesh space → head-bone space, from the bind pose alone.
+        this.toHead.copy(mesh.skeleton.boneInverses[bone]).multiply(mesh.bindMatrix);
+        const g = mesh.geometry;
+        const pos = g.attributes.position;
+        const uv = g.attributes.uv;
+        const shapes = g.morphAttributes.position;
+        // Mesh units per metre, from how the body is placed in the world now
+        // (scaled to metres by the unit normaliser, still in its bind pose).
+        mesh.updateWorldMatrix(true, false);
+        const unitsPerMetre = 1 / mesh.matrixWorld.getMaxScaleOnAxis();
+        const radius = EYEBALL_RADIUS * unitsPerMetre;
+        const delta = (shape, i) => new THREE.Vector3().fromBufferAttribute(shapes[shape], i);
+        const curves = {};
+        for (const side of ['L', 'R']) {
+            const roles = SIDES[side];
+            const idx = {
+                left: morphIndex(rig, roles.left, mesh),
+                right: morphIndex(rig, roles.right, mesh),
+                up: morphIndex(rig, roles.up, mesh),
+                down: morphIndex(rig, roles.down, mesh),
+            };
+            if (idx.left === undefined || idx.up === undefined || idx.right === undefined || idx.down === undefined)
+                throw new Error('look shapes missing');
+            // This eye: the vertices its own look-up shape moves.
+            const own = [];
+            for (let i = 0; i < pos.count; i++)
+                if (delta(idx.up, i).lengthSq() > 1e-12)
+                    own.push(i);
+            if (own.length < 3)
+                throw new Error('eye not found');
+            let pupil = own[0];
+            if (uv) {
+                let best = Infinity;
+                for (const i of own) {
+                    const d = Math.hypot(uv.getX(i) - 0.5, uv.getY(i) - 0.5);
+                    if (d < best) {
+                        best = d;
+                        pupil = i;
+                    }
+                }
+            }
+            else {
+                let most = -1;
+                for (const i of own) {
+                    const d = delta(idx.up, i).lengthSq();
+                    if (d > most) {
+                        most = d;
+                        pupil = i;
+                    }
+                }
+            }
+            const apex = new THREE.Vector3().fromBufferAttribute(pos, pupil);
+            const centroid = new THREE.Vector3();
+            for (const i of own)
+                centroid.add(this.v.fromBufferAttribute(pos, i));
+            centroid.divideScalar(own.length);
+            // The eye mesh is a front cap: its centroid sits behind the pupil.
+            const fwd = apex.clone().sub(centroid).normalize();
+            const centre = apex.clone().addScaledVector(fwd, -radius);
+            const orth = (d, ...axes) => {
+                for (const a of axes)
+                    d.addScaledVector(a, -d.dot(a));
+                return d.normalize();
+            };
+            const left = orth(delta(idx.left, pupil), fwd);
+            const up = orth(delta(idx.up, pupil), fwd, left);
+            if (!Number.isFinite(left.x) || !Number.isFinite(up.x))
+                throw new Error('degenerate shapes');
+            const angle = (shape, axis, sign) => {
+                const d = delta(shape, pupil);
+                const out = [];
+                for (let j = 0; j <= STEPS; j++) {
+                    const p = apex.clone().addScaledVector(d, j / STEPS).sub(centre);
+                    const a = p.dot(axis);
+                    out.push(sign * THREE.MathUtils.radToDeg(Math.atan2(a, p.dot(fwd))));
+                }
+                // Monotone, as the inversion assumes.
+                for (let j = 1; j < out.length; j++)
+                    out[j] = Math.max(out[j], out[j - 1]);
+                return out;
+            };
+            curves[side] = {
+                roles,
+                curves: {
+                    left: angle(idx.left, left, 1),
+                    right: angle(idx.right, left, -1),
+                    up: angle(idx.up, up, 1),
+                    down: angle(idx.down, up, -1),
+                },
+                vertex: pupil,
+                pupil: apex.clone().applyMatrix4(this.toHead),
+                centre: centre.clone().applyMatrix4(this.toHead),
+                fwd: fwd.clone().transformDirection(this.toHead),
+                left: left.clone().transformDirection(this.toHead),
+                up: up.clone().transformDirection(this.toHead),
+                yaw: 0, pitch: 0, fixYaw: 0, fixPitch: 0,
+            };
+        }
+        this.eyes.push(curves.L, curves.R);
+        const reach = (k) => Math.min(...this.eyes.map((e) => e.curves[k][STEPS]));
+        this.limits = { left: reach('left'), right: reach('right'), up: reach('up'), down: reach('down') };
+    }
+    /**
+     * Where `target` (world) lies from between the eyes, in the eyes' neutral
+     * frame: yaw (+ toward the character's left) and pitch (+ up), degrees.
+     */
+    angleTo(target) {
+        const local = this.local(target);
+        const mid = this.w.copy(this.eyes[0].centre).add(this.eyes[1].centre).multiplyScalar(0.5);
+        return this.angles(this.eyes[0], local.sub(mid));
+    }
+    /**
+     * Turn the eyes toward `target` (world), offset by `offset` degrees.
+     * `rate` is the exponential approach rate, 1/s. Writes only the eight
+     * look shapes.
+     */
+    update(dt, target, rate, offset = { yaw: 0, pitch: 0 }) {
+        const k = 1 - Math.exp(-rate * Math.max(0, dt));
+        const local = target ? this.local(target) : null;
+        for (const e of this.eyes) {
+            let yaw = 0, pitch = 0;
+            if (local) {
+                const want = this.angles(e, this.w.copy(local).sub(e.centre));
+                yaw = THREE.MathUtils.clamp(want.yaw + offset.yaw, -this.limits.right, this.limits.left);
+                pitch = THREE.MathUtils.clamp(want.pitch + offset.pitch, -this.limits.down, this.limits.up);
+            }
+            e.yaw += (yaw - e.yaw) * k;
+            e.pitch += (pitch - e.pitch) * k;
+            const y = e.yaw + e.fixYaw;
+            const p = e.pitch + e.fixPitch;
+            this.write(e.roles.left, weightFor(e.curves.left, y));
+            this.write(e.roles.right, weightFor(e.curves.right, -y));
+            this.write(e.roles.up, weightFor(e.curves.up, p));
+            this.write(e.roles.down, weightFor(e.curves.down, -p));
+            // Closed loop: other shapes move the pupil too, and two look shapes at
+            // once do not add exactly. Correct by half the error each frame.
+            const got = this.angles(e, this.pupilNow(e).sub(e.centre));
+            e.fixYaw = THREE.MathUtils.clamp(e.fixYaw + (e.yaw - got.yaw) * 0.5, -15, 15);
+            e.fixPitch = THREE.MathUtils.clamp(e.fixPitch + (e.pitch - got.pitch) * 0.5, -15, 15);
+        }
+    }
+    /** Current aim of each eye, degrees, for tests and debugging. */
+    get aim() {
+        return this.eyes.map((e) => ({ yaw: e.yaw, pitch: e.pitch }));
+    }
+    /**
+     * The closed-loop correction each eye currently carries, degrees. Near zero
+     * when the measured curves are right and no other shape moves the pupil.
+     */
+    get correction() {
+        return this.eyes.map((e) => ({ yaw: e.fixYaw, pitch: e.fixPitch }));
+    }
+    /** The pupil, every active shape applied, measured as the eye sees it: degrees. */
+    measured() {
+        return this.eyes.map((e) => this.angles(e, this.pupilNow(e).sub(e.centre)));
+    }
+    local(target) {
+        this.head.updateWorldMatrix(true, false);
+        return this.t.copy(target).applyMatrix4(this.m.copy(this.head.matrixWorld).invert());
+    }
+    angles(e, v) {
+        const x = v.dot(e.left);
+        const y = v.dot(e.up);
+        const z = v.dot(e.fwd);
+        return { yaw: THREE.MathUtils.radToDeg(Math.atan2(x, z)), pitch: THREE.MathUtils.radToDeg(Math.atan2(y, Math.hypot(x, z))) };
+    }
+    pupilNow(e) {
+        const g = this.mesh.geometry;
+        const v = this.v.fromBufferAttribute(g.attributes.position, e.vertex);
+        const inf = this.mesh.morphTargetInfluences ?? [];
+        const shapes = g.morphAttributes.position;
+        for (let i = 0; i < inf.length; i++) {
+            const wgt = inf[i];
+            if (wgt)
+                v.add(this.w.fromBufferAttribute(shapes[i], e.vertex).multiplyScalar(wgt));
+        }
+        return v.applyMatrix4(this.toHead);
+    }
+    write(role, value) {
+        const bindings = this.rig.morphs.get(role);
+        if (!bindings)
+            return;
+        const v = THREE.MathUtils.clamp(value, 0, 1);
+        for (const b of bindings) {
+            const infl = b.mesh.morphTargetInfluences;
+            if (infl)
+                infl[b.index] = v;
+        }
+    }
+}

package/dist/motion/eyeGaze.d.ts

@@ -1,6 +1,13 @@
 import type { FrameContext, System } from '../character/pipeline.js';
 import type { GazeSource } from './types.js';
+import { EyeAim } from './eyeAim.js';
 export interface EyeGazeConfig {
+    /**
+     * Micro-saccades while holding eye contact: a tiny jump every 0.5–1.6 s, so
+     * the stare is alive but never leaves the viewer. Default `true`; off under
+     * reduced motion regardless.
+     */
+    saccades?: boolean;
     /**
      * Per-frame ease rate toward the gaze target. Verbatim from
      * `useEyeTracking.ts`'s `DEFAULT_CONFIG.lerpSpeed` (useEyeTracking.ts:108)
@@ -60,6 +67,16 @@ export declare class EyeGazeSystem implements System {
     readonly stage: 6;
     private h;
     private v;
+    /** undefined until the first frame measures the body; null if it cannot be. */
+    private aim;
+    private readonly target;
+    private offset;
+    private nextSaccade;
+    private saccadeLeft;
     constructor(gaze: GazeSource, cfg?: EyeGazeConfig);
+    /** The calibrated aim, once measured (null when the body cannot be). */
+    get calibrated(): EyeAim | null;
     update(dt: number, ctx: FrameContext): void;
+    private aimAt;
+    private legacy;
 }

package/dist/motion/eyeGaze.js

@@ -1,5 +1,6 @@
 import * as THREE from 'three';
 import { writeMorph } from '../rig/resolve.js';
+import { EyeAim } from './eyeAim.js';
 /**
  * Eye gaze on convai-mha-1 is MORPH-ONLY — the mandated rig has no eye bones
  * (character spec 2.2). This system ports only the morph-output half of
@@ -31,8 +32,49 @@ export class EyeGazeSystem {
         this.stage = 6;
         this.h = 0;
         this.v = 0;
+        this.target = new THREE.Vector3();
+        this.offset = { yaw: 0, pitch: 0 };
+        this.nextSaccade = 0.3;
+        this.saccadeLeft = 0;
+    }
+    /** The calibrated aim, once measured (null when the body cannot be). */
+    get calibrated() {
+        return this.aim ?? null;
     }
     update(dt, ctx) {
+        // Measured on the first frame rather than at construction: by then the
+        // unit normaliser has put the body in metres, which sets the eyeball's
+        // size in mesh units.
+        if (this.aim === undefined)
+            this.aim = EyeAim.calibrate(ctx.rig);
+        if (this.aim)
+            return this.aimAt(dt, ctx, this.aim);
+        this.legacy(dt, ctx);
+    }
+    aimAt(dt, ctx, aim) {
+        const attending = !!ctx.camera && this.gaze.attending !== false;
+        if (!attending || ctx.reducedMotion) {
+            this.offset.yaw = this.offset.pitch = 0;
+            this.saccadeLeft = 0;
+        }
+        else if (this.cfg.saccades !== false) {
+            this.nextSaccade -= dt;
+            if (this.nextSaccade <= 0) {
+                // A micro-saccade: about half a degree, held 0.5–1.6 s.
+                this.offset = { yaw: (Math.random() * 2 - 1) * 0.6, pitch: (Math.random() * 2 - 1) * 0.5 };
+                this.nextSaccade = 0.5 + Math.random() * 1.1;
+                this.saccadeLeft = 0.06;
+            }
+        }
+        // A saccade is a ~40 ms jump; between them the eyes settle, and they ease
+        // home slowly when the character stops attending.
+        const rate = !attending ? 6 : this.saccadeLeft > 0 ? 28 : ctx.reducedMotion ? 8 : 14;
+        this.saccadeLeft = Math.max(0, this.saccadeLeft - dt);
+        const focus = this.gaze.focus;
+        const target = !attending ? null : focus ? this.target.set(focus.x, focus.y, focus.z) : ctx.camera.getWorldPosition(this.target);
+        aim.update(dt, target, rate, this.offset);
+    }
+    legacy(dt, ctx) {
         const lerpSpeed = this.cfg.lerpSpeed ?? 0.2;
         const verticalOffset = this.cfg.verticalOffset ?? -0.15;
         const gain = this.cfg.morphGain ?? 0.65;