@convai/embody 1.0.1 → 1.1.0-beta.0

package/dist/motion/hair.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Hair that rests on the shoulders.
+ *
+ * Avatar hair is skinned to the head bone alone, with no strand bones. So a
+ * 45° head turn swings long hair rigidly into the shoulders and chest, and
+ * every head movement carries the whole hairstyle like a helmet.
+ *
+ * `restHairOnShoulders` re-weights each hair vertex by its bind height — the
+ * head above the head bone, the upper chest at shoulder height, blended
+ * between — so the crown and face frame follow the head and the lengths stay
+ * on the body, bending in between. Skin weights only, every renderer.
+ *
+ * It is checked against the body before it is kept, because a hairstyle the
+ * default does not suit (a bun, a braid lying on the back, hair on a hood)
+ * can be pushed into the skin or clothing: tried in the head turns and nods
+ * gaze makes (±45° yaw, ±20° pitch), a mesh it pushes further into the body
+ * than its own weights did keeps its own weights.
+ *
+ * (Secondary motion — a spring swinging the ends — was tried and removed:
+ * hair moving on its own read worse than hair that rests.)
+ */
+import * as THREE from 'three';
+/**
+ * Re-skin hair so its lengths rest on the shoulders. Idempotent per geometry.
+ * Returns the number of meshes re-weighted.
+ */
+export declare function restHairOnShoulders(root: THREE.Object3D): number;

package/dist/motion/hair.js

@@ -0,0 +1,127 @@
+/**
+ * Hair that rests on the shoulders.
+ *
+ * Avatar hair is skinned to the head bone alone, with no strand bones. So a
+ * 45° head turn swings long hair rigidly into the shoulders and chest, and
+ * every head movement carries the whole hairstyle like a helmet.
+ *
+ * `restHairOnShoulders` re-weights each hair vertex by its bind height — the
+ * head above the head bone, the upper chest at shoulder height, blended
+ * between — so the crown and face frame follow the head and the lengths stay
+ * on the body, bending in between. Skin weights only, every renderer.
+ *
+ * It is checked against the body before it is kept, because a hairstyle the
+ * default does not suit (a bun, a braid lying on the back, hair on a hood)
+ * can be pushed into the skin or clothing: tried in the head turns and nods
+ * gaze makes (±45° yaw, ±20° pitch), a mesh it pushes further into the body
+ * than its own weights did keeps its own weights.
+ *
+ * (Secondary motion — a spring swinging the ends — was tried and removed:
+ * hair moving on its own read worse than hair that rests.)
+ */
+import * as THREE from 'three';
+import { BodySurface, posedPoints } from './hairClearance.js';
+/** Hair meshes: named as hair, drawn with alpha (cards), skinned. */
+const isHairMesh = (o) => {
+    const m = o;
+    if (!m.isSkinnedMesh || !/hair/i.test(m.name))
+        return false;
+    const mat = (Array.isArray(m.material) ? m.material[0] : m.material);
+    return mat.transparent || mat.alphaTest > 0 || mat.alphaToCoverage;
+};
+/** Bind-world position of a skeleton bone. */
+const bindPosition = (mesh, i) => new THREE.Vector3().setFromMatrixPosition(mesh.skeleton.boneInverses[i].clone().invert());
+/**
+ * Re-skin hair so its lengths rest on the shoulders. Idempotent per geometry.
+ * Returns the number of meshes re-weighted.
+ */
+export function restHairOnShoulders(root) {
+    let done = 0;
+    root.traverse((o) => {
+        if (!isHairMesh(o))
+            return;
+        const g = o.geometry;
+        if (g.userData.embodyHairOnShoulders)
+            return;
+        const bones = o.skeleton.bones;
+        const head = bones.findIndex((b) => b.name === 'head');
+        const chest = bones.findIndex((b) => b.name === 'spine_05' || b.name === 'spine_04');
+        const clavicle = bones.findIndex((b) => b.name === 'clavicle_l' || b.name === 'clavicle_r');
+        const index = g.attributes.skinIndex;
+        const weight = g.attributes.skinWeight;
+        if (head < 0 || chest < 0 || clavicle < 0 || !index || !weight)
+            return;
+        const top = bindPosition(o, head).y;
+        const shoulders = bindPosition(o, clavicle).y;
+        if (!(top > shoulders))
+            return;
+        const pos = g.attributes.position;
+        const ia = index.array;
+        const wa = weight.array;
+        const ownIndex = ia.slice();
+        const ownWeight = wa.slice();
+        const v = new THREE.Vector3();
+        for (let i = 0; i < pos.count; i++) {
+            v.fromBufferAttribute(pos, i).applyMatrix4(o.bindMatrix);
+            const onChest = 1 - THREE.MathUtils.smoothstep(v.y, shoulders, top);
+            index.setXYZW(i, head, chest, 0, 0);
+            weight.setXYZW(i, 1 - onChest, onChest, 0, 0);
+        }
+        const newIndex = ia.slice();
+        const newWeight = wa.slice();
+        const restWeights = () => { ia.set(ownIndex); wa.set(ownWeight); };
+        const useNew = () => { ia.set(newIndex); wa.set(newWeight); };
+        if (pushesIntoBody(root, o, bones[head], restWeights, useNew)) {
+            restWeights();
+            g.userData.embodyHairOnShoulders = 'kept own weights: resting on the shoulders pushed it into the body';
+            return;
+        }
+        index.needsUpdate = true;
+        weight.needsUpdate = true;
+        g.userData.embodyHairOnShoulders = true;
+        done++;
+    });
+    return done;
+}
+/** Turn `bone` by `angle` about a world axis through its own origin. */
+function turnBone(bone, axis, angle) {
+    const parent = bone.parent ? bone.parent.getWorldQuaternion(new THREE.Quaternion()) : new THREE.Quaternion();
+    const turn = new THREE.Quaternion().setFromAxisAngle(axis, angle);
+    bone.quaternion.premultiply(parent.clone().invert().multiply(turn).multiply(parent));
+}
+/** The head turns and nods gaze makes: ±45° yaw, ±20° pitch. */
+const GAZE_POSES = [
+    [new THREE.Vector3(0, 1, 0), THREE.MathUtils.degToRad(45)],
+    [new THREE.Vector3(0, 1, 0), THREE.MathUtils.degToRad(-45)],
+    [new THREE.Vector3(1, 0, 0), THREE.MathUtils.degToRad(20)],
+    [new THREE.Vector3(1, 0, 0), THREE.MathUtils.degToRad(-20)],
+];
+/**
+ * Whether the new weights push `hair` further into the body than its own,
+ * over the gaze poses. Leaves the new weights in place and the head as found.
+ */
+function pushesIntoBody(root, hair, head, own, next) {
+    root.updateMatrixWorld(true);
+    const box = new THREE.Box3().setFromPoints(posedPoints(hair, 7));
+    const body = new BodySurface(root, isHairMesh, box);
+    if (!body.size)
+        return false;
+    const rest = head.quaternion.clone();
+    let ownInside = 0;
+    let newInside = 0;
+    let points = 0;
+    for (const [axis, angle] of GAZE_POSES) {
+        turnBone(head, axis.clone().transformDirection(root.matrixWorld), angle);
+        root.updateMatrixWorld(true);
+        body.refresh();
+        own();
+        const a = posedPoints(hair);
+        ownInside += body.inside(a);
+        next();
+        newInside += body.inside(posedPoints(hair));
+        points += a.length;
+        head.quaternion.copy(rest);
+    }
+    root.updateMatrixWorld(true);
+    return newInside > ownInside + Math.max(3, points * 0.01);
+}

package/dist/motion/hairClearance.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Whether hair goes into the body: the check behind hair's two motions, so
+ * either is skipped on a model where it would push hair through the skin or
+ * clothing.
+ *
+ * The body is every skinned mesh that is neither hair nor see-through (skin
+ * and clothing), sampled near the hair, each sample with its outward normal
+ * in the CURRENT pose (three's own skinning, `applyBoneTransform`). A point
+ * is inside the body by how far it lies behind the nearest sample's surface,
+ * looked for within `reach`. Distances are world metres: call it after the
+ * body is scaled.
+ */
+import * as THREE from 'three';
+/** Behind the surface by more than this counts as inside, m (skinning and sampling slack). */
+export declare const INSIDE = 0.004;
+export declare class BodySurface {
+    private readonly reach;
+    private readonly samples;
+    private pos;
+    private nrm;
+    private readonly grid;
+    private readonly a;
+    private readonly b;
+    /**
+     * @param near only body points inside this box (world) are sampled
+     * @param reach how far from a point the surface is looked for, m
+     */
+    constructor(root: THREE.Object3D, isHair: (m: THREE.Mesh) => boolean, near: THREE.Box3, reach?: number);
+    get size(): number;
+    /** Re-read the samples in the body's current pose. World matrices must be current. */
+    refresh(): void;
+    /** How far `p` (world) lies inside the body, m; 0 outside or with no surface near. */
+    depth(p: THREE.Vector3): number;
+    /** How many of `points` lie more than `INSIDE` inside the body. */
+    inside(points: readonly THREE.Vector3[]): number;
+    private cell;
+}
+/** World positions of every `stride`-th vertex of a skinned mesh, in its current pose. */
+export declare function posedPoints(mesh: THREE.SkinnedMesh, stride?: number): THREE.Vector3[];

package/dist/motion/hairClearance.js

@@ -0,0 +1,125 @@
+/**
+ * Whether hair goes into the body: the check behind hair's two motions, so
+ * either is skipped on a model where it would push hair through the skin or
+ * clothing.
+ *
+ * The body is every skinned mesh that is neither hair nor see-through (skin
+ * and clothing), sampled near the hair, each sample with its outward normal
+ * in the CURRENT pose (three's own skinning, `applyBoneTransform`). A point
+ * is inside the body by how far it lies behind the nearest sample's surface,
+ * looked for within `reach`. Distances are world metres: call it after the
+ * body is scaled.
+ */
+import * as THREE from 'three';
+/** Behind the surface by more than this counts as inside, m (skinning and sampling slack). */
+export const INSIDE = 0.004;
+export class BodySurface {
+    /**
+     * @param near only body points inside this box (world) are sampled
+     * @param reach how far from a point the surface is looked for, m
+     */
+    constructor(root, isHair, near, reach = 0.03) {
+        this.reach = reach;
+        this.samples = [];
+        this.pos = new Float32Array(0);
+        this.nrm = new Float32Array(0);
+        this.grid = new Map();
+        this.a = new THREE.Vector3();
+        this.b = new THREE.Vector3();
+        root.updateMatrixWorld(true);
+        const box = near.clone().expandByScalar(reach);
+        const p = new THREE.Vector3();
+        root.traverse((o) => {
+            const m = o;
+            if (!m.isSkinnedMesh || !m.visible || isHair(m))
+                return;
+            const mats = Array.isArray(m.material) ? m.material : [m.material];
+            if (mats.every((x) => x.transparent))
+                return;
+            const g = m.geometry;
+            const position = g.attributes.position;
+            const normal = g.attributes.normal;
+            if (!position || !normal)
+                return;
+            for (let i = 0; i < position.count; i++) {
+                if (!box.containsPoint(m.getVertexPosition(i, p).applyMatrix4(m.matrixWorld)))
+                    continue;
+                const at = new THREE.Vector3().fromBufferAttribute(position, i);
+                const n = new THREE.Vector3().fromBufferAttribute(normal, i);
+                // Along the normal by a share of the mesh's own size: units vary.
+                const step = 0.002 / (m.getWorldScale(this.a).x || 1);
+                this.samples.push({ mesh: m, index: i, at, out: at.clone().addScaledVector(n, step) });
+            }
+        });
+        this.refresh();
+    }
+    get size() {
+        return this.samples.length;
+    }
+    /** Re-read the samples in the body's current pose. World matrices must be current. */
+    refresh() {
+        const n = this.samples.length;
+        if (this.pos.length !== n * 3) {
+            this.pos = new Float32Array(n * 3);
+            this.nrm = new Float32Array(n * 3);
+        }
+        this.grid.clear();
+        for (let k = 0; k < n; k++) {
+            const s = this.samples[k];
+            // applyBoneTransform applies the bind matrix and its inverse itself.
+            const p = s.mesh.applyBoneTransform(s.index, this.a.copy(s.at)).applyMatrix4(s.mesh.matrixWorld);
+            const q = s.mesh.applyBoneTransform(s.index, this.b.copy(s.out)).applyMatrix4(s.mesh.matrixWorld);
+            q.sub(p).normalize();
+            p.toArray(this.pos, k * 3);
+            q.toArray(this.nrm, k * 3);
+            const key = this.cell(p.x, p.y, p.z);
+            let c = this.grid.get(key);
+            if (!c)
+                this.grid.set(key, (c = []));
+            c.push(k);
+        }
+    }
+    /** How far `p` (world) lies inside the body, m; 0 outside or with no surface near. */
+    depth(p) {
+        let best = this.reach * this.reach;
+        let hit = -1;
+        for (let dx = -1; dx <= 1; dx++)
+            for (let dy = -1; dy <= 1; dy++)
+                for (let dz = -1; dz <= 1; dz++) {
+                    const c = this.grid.get(this.cell(p.x + dx * this.reach, p.y + dy * this.reach, p.z + dz * this.reach));
+                    if (!c)
+                        continue;
+                    for (const k of c) {
+                        const d = (this.pos[k * 3] - p.x) ** 2 + (this.pos[k * 3 + 1] - p.y) ** 2 + (this.pos[k * 3 + 2] - p.z) ** 2;
+                        if (d < best) {
+                            best = d;
+                            hit = k;
+                        }
+                    }
+                }
+        if (hit < 0)
+            return 0;
+        const s = (p.x - this.pos[hit * 3]) * this.nrm[hit * 3] + (p.y - this.pos[hit * 3 + 1]) * this.nrm[hit * 3 + 1] + (p.z - this.pos[hit * 3 + 2]) * this.nrm[hit * 3 + 2];
+        return s < 0 ? -s : 0;
+    }
+    /** How many of `points` lie more than `INSIDE` inside the body. */
+    inside(points) {
+        let n = 0;
+        for (const p of points)
+            if (this.depth(p) > INSIDE)
+                n++;
+        return n;
+    }
+    cell(x, y, z) {
+        const r = this.reach;
+        return ((Math.floor(x / r) + 4096) * 8192 + (Math.floor(y / r) + 4096)) * 8192 + (Math.floor(z / r) + 4096);
+    }
+}
+/** World positions of every `stride`-th vertex of a skinned mesh, in its current pose. */
+export function posedPoints(mesh, stride = 3) {
+    const out = [];
+    const n = mesh.geometry.attributes.position.count;
+    for (let i = 0; i < n; i += stride)
+        out.push(mesh.getVertexPosition(i, new THREE.Vector3()).applyMatrix4(mesh.matrixWorld));
+    return out;
+}

package/dist/motion/morphNormals.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Normals for morphed faces that ship none.
+ *
+ * The published heads carry blend-shape positions but no blend-shape
+ * normals, so three lights every morphed face with its bind-pose normals.
+ * On a closed eye the upper-lid margin, whose normals face down into the
+ * socket, is pulled onto the lower lid and shades black under a key from
+ * above: a dark band along the lid that read as the eye standing proud.
+ * Mouth shapes have the same defect, less visibly.
+ *
+ * Recomputing the whole head every frame costs ~9 ms (12k vertices, 242
+ * targets measured), so this is sparse: once, each target's touched
+ * vertices (a displacement above a small share of the mesh's size) and the
+ * faces around every vertex; each frame, only when a weight changed, the
+ * positions of the touched vertices are rebuilt from the base and the active
+ * targets, the normals of every vertex on a face around them are recomputed
+ * from those positions, and vertices that relaxed since last frame get their
+ * base normals back. Writes go through the attribute, so interleaved exports
+ * are safe. Normals are in object space, as the normal attribute is; skinning
+ * transforms them after, as it does the positions.
+ *
+ * Meshes that ship their own morph normals, or no normals, are left alone.
+ * Runs after every morph writer (stage 6: lipsync, eye gaze, blink).
+ */
+import * as THREE from 'three';
+import type { FrameContext, Stage, System } from '../character/pipeline.js';
+export declare class MorphNormals implements System {
+    readonly stage: Stage;
+    private readonly patches;
+    constructor(root: THREE.Object3D, minDelta?: number);
+    /** How many meshes this is correcting. */
+    get size(): number;
+    private build;
+    update(_dt: number, _ctx: FrameContext): void;
+    /** Recompute where weights changed. Returns how many vertices were rewritten. */
+    run(): number;
+    private runPatch;
+}

package/dist/motion/morphNormals.js

@@ -0,0 +1,237 @@
+/**
+ * Normals for morphed faces that ship none.
+ *
+ * The published heads carry blend-shape positions but no blend-shape
+ * normals, so three lights every morphed face with its bind-pose normals.
+ * On a closed eye the upper-lid margin, whose normals face down into the
+ * socket, is pulled onto the lower lid and shades black under a key from
+ * above: a dark band along the lid that read as the eye standing proud.
+ * Mouth shapes have the same defect, less visibly.
+ *
+ * Recomputing the whole head every frame costs ~9 ms (12k vertices, 242
+ * targets measured), so this is sparse: once, each target's touched
+ * vertices (a displacement above a small share of the mesh's size) and the
+ * faces around every vertex; each frame, only when a weight changed, the
+ * positions of the touched vertices are rebuilt from the base and the active
+ * targets, the normals of every vertex on a face around them are recomputed
+ * from those positions, and vertices that relaxed since last frame get their
+ * base normals back. Writes go through the attribute, so interleaved exports
+ * are safe. Normals are in object space, as the normal attribute is; skinning
+ * transforms them after, as it does the positions.
+ *
+ * Meshes that ship their own morph normals, or no normals, are left alone.
+ * Runs after every morph writer (stage 6: lipsync, eye gaze, blink).
+ */
+import * as THREE from 'three';
+/** Share of the mesh's size below which a target's move of a vertex is ignored. */
+const MIN_DELTA = 2e-4;
+export class MorphNormals {
+    constructor(root, minDelta = MIN_DELTA) {
+        this.stage = 6;
+        this.patches = [];
+        root.traverse((o) => {
+            const mesh = o;
+            if (!mesh.isMesh)
+                return;
+            const g = mesh.geometry;
+            const targets = g.morphAttributes.position;
+            if (!targets?.length || g.morphAttributes.normal || !g.attributes.normal || !mesh.morphTargetInfluences)
+                return;
+            this.patches.push(this.build(mesh, targets, minDelta));
+        });
+    }
+    /** How many meshes this is correcting. */
+    get size() {
+        return this.patches.length;
+    }
+    build(mesh, targets, minDelta) {
+        const g = mesh.geometry;
+        const position = g.attributes.position;
+        const normal = g.attributes.normal;
+        const n = position.count;
+        const base = new Float32Array(n * 3);
+        const baseNormal = new Float32Array(n * 3);
+        for (let i = 0; i < n; i++) {
+            base[i * 3] = position.getX(i);
+            base[i * 3 + 1] = position.getY(i);
+            base[i * 3 + 2] = position.getZ(i);
+            baseNormal[i * 3] = normal.getX(i);
+            baseNormal[i * 3 + 1] = normal.getY(i);
+            baseNormal[i * 3 + 2] = normal.getZ(i);
+        }
+        g.computeBoundingBox();
+        const size = g.boundingBox.getSize(new THREE.Vector3()).length() || 1;
+        const eps2 = (size * minDelta) ** 2;
+        const index = g.index ? g.index.array : null;
+        const faceCount = index ? index.length / 3 : n / 3;
+        const vert = (f, k) => (index ? index[f * 3 + k] : f * 3 + k);
+        const degree = new Uint32Array(n + 1);
+        for (let f = 0; f < faceCount; f++)
+            for (let k = 0; k < 3; k++)
+                degree[vert(f, k) + 1]++;
+        for (let i = 0; i < n; i++)
+            degree[i + 1] += degree[i];
+        const faceStart = degree;
+        const faces = new Uint32Array(faceStart[n]);
+        const fill = new Uint32Array(n);
+        for (let f = 0; f < faceCount; f++)
+            for (let k = 0; k < 3; k++) {
+                const v = vert(f, k);
+                faces[faceStart[v] + fill[v]++] = f;
+            }
+        const relative = g.morphTargetsRelative;
+        const targetVerts = [];
+        const targetDeltas = [];
+        for (const t of targets) {
+            const vs = [];
+            const ds = [];
+            for (let i = 0; i < n; i++) {
+                let dx = t.getX(i), dy = t.getY(i), dz = t.getZ(i);
+                if (!relative) {
+                    dx -= base[i * 3];
+                    dy -= base[i * 3 + 1];
+                    dz -= base[i * 3 + 2];
+                }
+                if (dx * dx + dy * dy + dz * dz < eps2)
+                    continue;
+                vs.push(i);
+                ds.push(dx, dy, dz);
+            }
+            targetVerts.push(Uint32Array.from(vs));
+            targetDeltas.push(Float32Array.from(ds));
+        }
+        return {
+            mesh, normal, n, base, baseNormal, pos: base.slice(), index, faceCount, faceStart, faces, targetVerts, targetDeltas,
+            last: new Float64Array(targets.length).fill(NaN), written: new Uint32Array(n), writtenCount: 0,
+            touched: new Uint8Array(n), faceFlag: new Uint32Array(faceCount), faceNormal: new Float32Array(faceCount * 3), stamp: 0,
+        };
+    }
+    update(_dt, _ctx) {
+        this.run();
+    }
+    /** Recompute where weights changed. Returns how many vertices were rewritten. */
+    run() {
+        let total = 0;
+        for (const p of this.patches)
+            total += this.runPatch(p);
+        return total;
+    }
+    runPatch(p) {
+        const w = p.mesh.morphTargetInfluences;
+        let changed = false;
+        for (let t = 0; t < w.length; t++)
+            if (w[t] !== p.last[t]) {
+                changed = true;
+                break;
+            }
+        if (!changed)
+            return 0;
+        p.last.set(w);
+        p.stamp++;
+        const { base, pos, touched, faceStart, faces, faceFlag, faceNormal, index } = p;
+        // Touched vertices: reset to base, then add every active target.
+        const touchedList = [];
+        for (let t = 0; t < w.length; t++) {
+            if (Math.abs(w[t]) < 1e-4)
+                continue;
+            const vs = p.targetVerts[t];
+            for (let k = 0; k < vs.length; k++) {
+                const v = vs[k];
+                if (!touched[v]) {
+                    touched[v] = 1;
+                    touchedList.push(v);
+                    pos[v * 3] = base[v * 3];
+                    pos[v * 3 + 1] = base[v * 3 + 1];
+                    pos[v * 3 + 2] = base[v * 3 + 2];
+                }
+            }
+        }
+        for (let t = 0; t < w.length; t++) {
+            const wt = w[t];
+            if (Math.abs(wt) < 1e-4)
+                continue;
+            const vs = p.targetVerts[t], ds = p.targetDeltas[t];
+            for (let k = 0; k < vs.length; k++) {
+                const v = vs[k];
+                pos[v * 3] += ds[k * 3] * wt;
+                pos[v * 3 + 1] += ds[k * 3 + 1] * wt;
+                pos[v * 3 + 2] += ds[k * 3 + 2] * wt;
+            }
+        }
+        // Vertices to rewrite: every vertex of every face around a touched vertex.
+        const rewrite = [];
+        const seen = p.stamp;
+        for (const v of touchedList) {
+            for (let j = faceStart[v]; j < faceStart[v + 1]; j++) {
+                const f = faces[j];
+                if (faceFlag[f] === seen)
+                    continue;
+                faceFlag[f] = seen;
+                for (let k = 0; k < 3; k++) {
+                    const u = index ? index[f * 3 + k] : f * 3 + k;
+                    if (!touched[u]) {
+                        touched[u] = 1;
+                        rewrite.push(u);
+                    }
+                }
+            }
+        }
+        for (const v of touchedList)
+            rewrite.push(v);
+        // Face normals (unnormalised: area-weighted) around the rewritten vertices.
+        const stampFace = (f) => {
+            const a = index ? index[f * 3] : f * 3, b = index ? index[f * 3 + 1] : f * 3 + 1, c = index ? index[f * 3 + 2] : f * 3 + 2;
+            const ax = pos[a * 3], ay = pos[a * 3 + 1], az = pos[a * 3 + 2];
+            const bx = pos[b * 3] - ax, by = pos[b * 3 + 1] - ay, bz = pos[b * 3 + 2] - az;
+            const cx = pos[c * 3] - ax, cy = pos[c * 3 + 1] - ay, cz = pos[c * 3 + 2] - az;
+            faceNormal[f * 3] = by * cz - bz * cy;
+            faceNormal[f * 3 + 1] = bz * cx - bx * cz;
+            faceNormal[f * 3 + 2] = bx * cy - by * cx;
+        };
+        // Untouched neighbours of the rewritten set keep base positions in `pos`
+        // already (pos starts as the base and only touched vertices change).
+        const done = new Set();
+        for (const v of rewrite) {
+            let nx = 0, ny = 0, nz = 0;
+            for (let j = faceStart[v]; j < faceStart[v + 1]; j++) {
+                const f = faces[j];
+                if (!done.has(f)) {
+                    stampFace(f);
+                    done.add(f);
+                }
+                nx += faceNormal[f * 3];
+                ny += faceNormal[f * 3 + 1];
+                nz += faceNormal[f * 3 + 2];
+            }
+            const l = Math.hypot(nx, ny, nz) || 1;
+            p.normal.setXYZ(v, nx / l, ny / l, nz / l);
+        }
+        // Vertices written last frame that relaxed: back to their base normals.
+        const nowWritten = new Uint8Array(p.n);
+        for (const v of rewrite)
+            nowWritten[v] = 1;
+        for (let i = 0; i < p.writtenCount; i++) {
+            const v = p.written[i];
+            if (!nowWritten[v])
+                p.normal.setXYZ(v, p.baseNormal[v * 3], p.baseNormal[v * 3 + 1], p.baseNormal[v * 3 + 2]);
+        }
+        for (let i = 0; i < rewrite.length; i++)
+            p.written[i] = rewrite[i];
+        p.writtenCount = rewrite.length;
+        // Positions of touched vertices that relaxed to zero weight must return
+        // to base for the next frame's neighbours: reset the touched flags and
+        // positions of everything we touched (they are rebuilt each change).
+        for (const v of touchedList) {
+            touched[v] = 0;
+        }
+        for (const v of rewrite)
+            touched[v] = 0;
+        for (const v of touchedList) {
+            pos[v * 3] = base[v * 3];
+            pos[v * 3 + 1] = base[v * 3 + 1];
+            pos[v * 3 + 2] = base[v * 3 + 2];
+        }
+        p.normal.needsUpdate = true;
+        return rewrite.length;
+    }
+}

package/dist/motion/types.d.ts

@@ -31,4 +31,19 @@ export interface GazeSource {
      * already gone, so a character looking straight at you stares past you.
      */
     readonly residual: EyeGazeDirection;
+    /**
+     * Whether the character is attending to the camera this frame (tracking is
+     * enabled and the camera is within reach). Absent means attending.
+     */
+    readonly attending?: boolean;
+    /**
+     * The world point the character is looking at — the camera, or a brief
+     * glance away from it. The eyes aim here so head and eyes agree. Absent
+     * means the camera.
+     */
+    readonly focus?: {
+        x: number;
+        y: number;
+        z: number;
+    };
 }

package/dist/react/CharacterModel.d.ts

@@ -4,5 +4,7 @@ export interface CharacterModelProps extends UseCharacterOptions {
     /** Called once the body is loaded and the connection is live. */
     onReady?: (character: CharacterHandle) => void;
     onError?: (error: Error) => void;
+    /** Cast and receive shadows on every mesh (the app's lights decide whether any are cast). Default false. */
+    shadows?: boolean;
 }
-export declare function CharacterModel({ onReady, onError, ...opts }: CharacterModelProps): import("react").JSX.Element | null;
+export declare function CharacterModel({ onReady, onError, shadows, ...opts }: CharacterModelProps): import("react").JSX.Element | null;

package/dist/react/CharacterModel.js

@@ -21,8 +21,16 @@ import { jsx as _jsx } from "react/jsx-runtime";
  */
 import { useEffect, useRef } from 'react';
 import { useCharacter } from './useCharacter.js';
-export function CharacterModel({ onReady, onError, ...opts }) {
+export function CharacterModel({ onReady, onError, shadows = false, ...opts }) {
     const { character, error } = useCharacter(opts);
+    useEffect(() => {
+        if (!character)
+            return;
+        character.root.traverse((o) => {
+            if (o.isMesh)
+                o.castShadow = o.receiveShadow = shadows;
+        });
+    }, [character, shadows]);
     // The callbacks are read through refs so that announcing is keyed on the
     // character (or error) alone. Apps pass them inline, `onReady={(c) => …}`,
     // which is a new function on every render; with the callback as an effect

package/dist/react/ConvaiCharacter.js

@@ -26,6 +26,7 @@ import { Canvas } from '@react-three/fiber';
 import { CharacterModel } from './CharacterModel.js';
 import { OrbitRig } from './OrbitRig.js';
 import { RoomLight } from './RoomLight.js';
+import { PortraitLights } from './PortraitLights.js';
 const DEFAULT_POSITION = [0, 1.45, 3.6];
 const DEFAULT_TARGET = [0, 0.92, 0];
 export function ConvaiCharacter({ style, className, background = '#17181c', camera, orbit = true, fallback = null, ...character }) {
@@ -35,10 +36,12 @@ export function ConvaiCharacter({ style, className, background = '#17181c', came
                 // Transparent when background is null, so the character can sit over
                 // existing page content rather than in a box of its own.
                 gl: { antialias: true, alpha: background === null }, 
+                // PCF: soft shadow edges filtered by the character's own receiver.
+                shadows: "percentage", 
                 // Aim at the character's head rather than the origin at its feet;
                 // r3f points the camera at [0,0,0] otherwise. Harmless when orbit is
                 // on — OrbitRig takes the same target and drives the camera from
                 // there — and load-bearing when it is off.
-                onCreated: ({ camera: cam }) => cam.lookAt(...target), children: [background !== null && _jsx("color", { attach: "background", args: [background] }), _jsx("hemisphereLight", { args: [0xffffff, 0x334455, 1.4] }), _jsx("directionalLight", { position: [2, 4, 3], intensity: 2.2 }), _jsx(RoomLight, {}), orbit !== false && (_jsx(OrbitRig, { target: target, options: orbit === true ? undefined : orbit })), _jsx(Suspense, { fallback: null, children: _jsx(CharacterModel, { ...character }) })] }), fallback] }));
+                onCreated: ({ camera: cam }) => cam.lookAt(...target), children: [background !== null && _jsx("color", { attach: "background", args: [background] }), _jsx(PortraitLights, { target: target }), _jsx(RoomLight, { intensity: 0.2 }), orbit !== false && (_jsx(OrbitRig, { target: target, options: orbit === true ? undefined : orbit })), _jsx(Suspense, { fallback: null, children: _jsx(CharacterModel, { shadows: true, ...character }) })] }), fallback] }));
 }
 export default ConvaiCharacter;

package/dist/react/PortraitLights.d.ts

@@ -0,0 +1,3 @@
+export declare function PortraitLights({ target }: {
+    target: [number, number, number];
+}): import("react").JSX.Element;