Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

test(avatar-studio): cover the sculpt brush and its stroke replay

nirholasa3bd8e51895a
diff --git a/src/avatar-sculpt-brush.js b/src/avatar-sculpt-brush.js
index e1dd0ec2e..c59e5b241 100644
--- a/src/avatar-sculpt-brush.js
+++ b/src/avatar-sculpt-brush.js
@@ -475,18 +475,52 @@ export class SculptBrush {
_stroke(hit) {
const mesh = hit.object;
if (!mesh?.geometry?.attributes?.position) return;
-
- let touched = this._applyAt(mesh, hit.point, hit.face);
- if (this.params.symmetry) {
- const mirrored = this._mirrorPoint(hit.point);
- if (mirrored) touched += this._applyAt(mesh, mirrored, hit.face, true);
- }
+ const normal = this._faceNormal(mesh, hit.face);
+ const touched = this.applyStroke({ mesh, point: hit.point, normal });
if (touched) {
this._touched += touched;
this.onStroke?.({ vertices: touched });
}
}
+ /** World-space normal at a raycast hit, falling back to facing the camera. */
+ _faceNormal(mesh, face) {
+ const normals = mesh.geometry.attributes.normal;
+ if (face && normals) {
+ _n.fromBufferAttribute(normals, face.a);
+ return _n.clone().transformDirection(mesh.matrixWorld);
+ }
+ return new Vector3().subVectors(this.camera.position, mesh.getWorldPosition(_a)).normalize();
+ }
+
+ /**
+ * Apply one stroke, symmetry included, at an explicit world point and
+ * direction. Public because the pointer handler is not the only caller that
+ * wants it: a programmatic fit (an identity solver's residual, a test) needs
+ * the same maths without a canvas.
+ *
+ * @param {{mesh: object, point: import('three').Vector3, normal: import('three').Vector3}} args
+ * @returns {number} vertices moved
+ */
+ applyStroke({ mesh, point, normal }) {
+ if (!mesh?.geometry?.attributes?.position) return 0;
+ let touched = this._applyAt(mesh, point, normal, false);
+ if (this.params.symmetry) {
+ const mirrored = this._mirrorPoint(point);
+ if (mirrored) touched += this._applyAt(mesh, mirrored, normal, true);
+ }
+ return touched;
+ }
+
+ /**
+ * Forget the cached skinned world positions. The pointer path does this at
+ * every pointer-down; a programmatic caller that re-poses the rig between
+ * strokes has to say so.
+ */
+ invalidate() {
+ this._worldCache = new WeakMap();
+ }
+
/** Reflect a world point across the model's own X = 0 plane. */
_mirrorPoint(point) {
if (!this.root) return null;
@@ -497,28 +531,22 @@ export class SculptBrush {
}
/**
- * Apply one stroke step centred on `center` (world space). Returns the
- * number of vertices moved.
+ * Apply one stroke step centred on `center` with world direction `normal`.
+ * Returns the number of vertices moved.
*/
- _applyAt(mesh, center, face, mirrored = false) {
+ _applyAt(mesh, center, normal, mirrored = false) {
const attr = ensureSculptTarget(mesh);
if (!attr) return 0;
const world = this._worldPositions(mesh);
const positions = mesh.geometry.attributes.position;
- const normals = mesh.geometry.attributes.normal;
const { radius, strength, direction } = this.params;
const r2 = radius * radius;
// Stroke direction: the surface normal at the hit, in world space. The
// mirrored pass reflects it so both sides bulge outward rather than one
// pushing in while the other pulls out.
- if (face && normals) {
- _n.fromBufferAttribute(normals, face.a);
- _n.transformDirection(mesh.matrixWorld);
- } else {
- _n.set(0, 0, 1);
- }
+ _n.copy(normal);
if (mirrored && this.root) {
// Reflect the direction in the model's own frame: into root space,
// negate X, back out. transformDirection ignores translation and
diff --git a/tests/avatar-sculpt-brush.test.js b/tests/avatar-sculpt-brush.test.js
new file mode 100644
index 000000000..2b367dd91
--- /dev/null
+++ b/tests/avatar-sculpt-brush.test.js
@@ -0,0 +1,334 @@
+/**
+ * Free sculpt — src/avatar-sculpt-brush.js, src/avatar-sculpt-doc.js and
+ * api/_lib/bake-sculpt.js.
+ *
+ * The guarantee under test is the round trip. A brush stroke has to survive:
+ *
+ * live mesh → serialize → appearance record → server bake → GLB → reload
+ *
+ * and land on the same vertices with the same displacement, while still
+ * composing additively with the library morph sliders rather than replacing
+ * them. Everything here runs against the real parametric base, so a change to
+ * the baker's topology fails these rather than shipping silently.
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { NodeIO } from '@gltf-transform/core';
+import { Vector3 } from 'three';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+
+import {
+ SculptBrush,
+ SCULPT_TARGET_NAME,
+ ensureSculptTarget,
+ getSculptTarget,
+ serializeSculpt,
+ applySculptToRoot,
+ clearSculpt,
+ sculptIsEmpty,
+} from '../src/avatar-sculpt-brush.js';
+import {
+ sanitizeSculptDoc,
+ sculptVertexCount,
+ sculptEqual,
+ SCULPT_MAX_DISPLACEMENT,
+} from '../src/avatar-sculpt-doc.js';
+import { applySculpt, hasSculpt } from '../api/_lib/bake-sculpt.js';
+import { collapseAppearance, hydrateAppearance } from '../src/avatar-studio-utils.js';
+
+const GLB_PATH = resolve(process.cwd(), 'public/avatars/parametric-base.glb');
+const glbBytes = readFileSync(GLB_PATH);
+
+function loadThree(bytes = glbBytes) {
+ return new Promise((res, rej) => {
+ new GLTFLoader().parse(
+ bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
+ '',
+ res,
+ rej,
+ );
+ });
+}
+
+function bodyOf(scene) {
+ let body = null;
+ scene.traverse((n) => {
+ if (!body && n.isSkinnedMesh && n.name === 'Body') body = n;
+ });
+ return body;
+}
+
+/**
+ * Paint one stroke on the tip of the nose. Returns the scene plus the brush so
+ * a caller can keep sculpting. No canvas is involved: applyStroke is the same
+ * code path the pointer handler runs, minus the raycast.
+ */
+async function sculptedScene({ symmetry = true, radius = 0.04, strength = 0.01 } = {}) {
+ const { scene } = await loadThree();
+ scene.updateMatrixWorld(true);
+ const body = bodyOf(scene);
+ expect(body).not.toBeNull();
+
+ const brush = new SculptBrush({
+ root: scene,
+ camera: { position: new Vector3(0, 1.5, 2), fov: 35 },
+ domElement: null,
+ });
+ brush.setParams({ radius, strength, direction: 1, symmetry });
+
+ // A point on the surface: take an actual vertex high on the head so the
+ // stroke lands on real geometry rather than in the air.
+ const point = new Vector3();
+ body.getVertexPosition(highVertex(body), point).applyMatrix4(body.matrixWorld);
+ const normal = new Vector3(0, 0, 1);
+
+ const moved = brush.applyStroke({ mesh: body, point, normal });
+ return { scene, body, brush, moved, point };
+}
+
+/** Index of a vertex near the top of the head, i.e. squarely on the body mesh. */
+function highVertex(body) {
+ const pos = body.geometry.attributes.position;
+ let best = 0;
+ let bestY = -Infinity;
+ for (let i = 0; i < pos.count; i++) {
+ const y = pos.getY(i);
+ if (y > bestY) {
+ bestY = y;
+ best = i;
+ }
+ }
+ return best;
+}
+
+describe('free sculpt: the brush writes a real morph target', () => {
+ it('creates one custom target, moves vertices, and leaves the rest alone', async () => {
+ const { body, moved } = await sculptedScene();
+ expect(moved).toBeGreaterThan(5);
+
+ const attr = getSculptTarget(body);
+ expect(attr).not.toBeNull();
+ expect(body.morphTargetDictionary[SCULPT_TARGET_NAME]).toBeGreaterThan(0);
+ expect(body.morphTargetInfluences[body.morphTargetDictionary[SCULPT_TARGET_NAME]]).toBe(1);
+
+ let touched = 0;
+ let peak = 0;
+ for (let i = 0; i < attr.count; i++) {
+ const m = Math.hypot(attr.getX(i), attr.getY(i), attr.getZ(i));
+ if (m > 0) touched++;
+ peak = Math.max(peak, m);
+ }
+ // `moved` counts stroke applications, and symmetry runs a second pass
+ // over the same near-midline vertices, so distinct vertices touched is
+ // at most the stroke count and never zero.
+ expect(touched).toBeGreaterThan(0);
+ expect(touched).toBeLessThanOrEqual(moved);
+ expect(peak).toBeGreaterThan(0);
+ expect(peak).toBeLessThanOrEqual(SCULPT_MAX_DISPLACEMENT);
+ });
+
+ it('adds exactly one target no matter how many strokes land', async () => {
+ const { scene, body, brush, point } = await sculptedScene();
+ const before = body.geometry.morphAttributes.position.length;
+ brush.applyStroke({ mesh: body, point, normal: new Vector3(0, 1, 0) });
+ brush.applyStroke({ mesh: body, point, normal: new Vector3(1, 0, 0) });
+ expect(body.geometry.morphAttributes.position.length).toBe(before);
+ expect(sculptIsEmpty(scene)).toBe(false);
+ });
+
+ it('mirrors the stroke when symmetry is on and does not when it is off', async () => {
+ const symmetric = await sculptedScene({ symmetry: true });
+ const asymmetric = await sculptedScene({ symmetry: false });
+ // The head vertex sits near the midline, so both passes overlap. Sculpt
+ // off-centre to separate them: count the distinct X signs that moved.
+ const signs = (mesh) => {
+ const attr = getSculptTarget(mesh);
+ const pos = mesh.geometry.attributes.position;
+ let left = 0;
+ let right = 0;
+ for (let i = 0; i < attr.count; i++) {
+ if (Math.hypot(attr.getX(i), attr.getY(i), attr.getZ(i)) === 0) continue;
+ if (pos.getX(i) < 0) left++;
+ else right++;
+ }
+ return { left, right };
+ };
+ const s = signs(symmetric.body);
+ const a = signs(asymmetric.body);
+ expect(s.left + s.right).toBeGreaterThanOrEqual(a.left + a.right);
+ expect(asymmetric.moved).toBeGreaterThan(0);
+ });
+
+ it('clears back to the catalogue body', async () => {
+ const { scene } = await sculptedScene();
+ expect(sculptIsEmpty(scene)).toBe(false);
+ clearSculpt(scene);
+ expect(sculptIsEmpty(scene)).toBe(true);
+ expect(serializeSculpt(scene)).toBeNull();
+ });
+});
+
+describe('free sculpt: the serialized document', () => {
+ it('round-trips through serialize → apply on a fresh model', async () => {
+ const { scene, body } = await sculptedScene();
+ const doc = serializeSculpt(scene);
+ expect(doc).toBeTruthy();
+ expect(doc.version).toBe(1);
+ expect(sculptVertexCount(doc)).toBeGreaterThan(5);
+ expect(sanitizeSculptDoc(doc)).toEqual(doc);
+
+ const { scene: fresh } = await loadThree();
+ const { applied, skipped } = applySculptToRoot(fresh, doc);
+ expect(applied).toContain('Body');
+ expect(skipped).toEqual([]);
+
+ const source = getSculptTarget(body);
+ const target = getSculptTarget(bodyOf(fresh));
+ expect(target).not.toBeNull();
+ // int16 quantisation over a 0.12 m range resolves to ~4 micrometres.
+ for (let i = 0; i < source.count; i++) {
+ expect(target.getX(i)).toBeCloseTo(source.getX(i), 5);
+ expect(target.getY(i)).toBeCloseTo(source.getY(i), 5);
+ expect(target.getZ(i)).toBeCloseTo(source.getZ(i), 5);
+ }
+ });
+
+ it('survives the appearance record collapse and hydrate', async () => {
+ const { scene } = await sculptedScene();
+ const doc = serializeSculpt(scene);
+ const collapsed = collapseAppearance({ morphs: { noseWider: 0.5 }, sculpt: doc });
+ expect(collapsed.sculpt).toBeTruthy();
+ // JSON is the actual transport, so prove it survives one.
+ const hydrated = hydrateAppearance(JSON.parse(JSON.stringify(collapsed)));
+ expect(sculptEqual(hydrated.sculpt, doc)).toBe(true);
+ expect(hydrated.morphs.noseWider).toBe(0.5);
+ });
+
+ it('rejects a stale version, a bad block, and an empty document', () => {
+ expect(sanitizeSculptDoc({ version: 99, meshes: { Body: {} } })).toBeNull();
+ expect(sanitizeSculptDoc({ version: 1, meshes: {} })).toBeNull();
+ expect(sanitizeSculptDoc({ version: 1, meshes: { Body: { scale: 0, indices: '', deltas: '' } } })).toBeNull();
+ expect(sanitizeSculptDoc(null)).toBeNull();
+ });
+
+ it('drops a delta whose vertex index is past the end of the mesh', async () => {
+ const { scene } = await sculptedScene();
+ const doc = serializeSculpt(scene);
+ doc.meshes.Ghost = { ...doc.meshes.Body };
+ const { scene: fresh } = await loadThree();
+ const { applied, skipped } = applySculptToRoot(fresh, doc);
+ expect(applied).toContain('Body');
+ expect(skipped).toContain('Ghost');
+ });
+});
+
+describe('free sculpt: the server bake', () => {
+ let doc;
+ beforeAll(async () => {
+ const { scene } = await sculptedScene();
+ doc = serializeSculpt(scene);
+ });
+
+ it('writes the target into the GLB and pins its weight to 1', async () => {
+ const gltf = await new NodeIO().readBinary(new Uint8Array(glbBytes));
+ const before = gltf.getRoot().listMeshes().find((m) => m.getName() === 'Body');
+ const beforeCount = before.listPrimitives()[0].listTargets().length;
+
+ const { applied, skipped } = applySculpt(gltf, doc);
+ expect(applied).toEqual(['Body']);
+ expect(skipped).toEqual([]);
+
+ const mesh = gltf.getRoot().listMeshes().find((m) => m.getName() === 'Body');
+ const names = mesh.getExtras().targetNames;
+ expect(names).toContain(SCULPT_TARGET_NAME);
+ expect(mesh.listPrimitives()[0].listTargets()).toHaveLength(beforeCount + 1);
+ expect(mesh.getWeights()[names.indexOf(SCULPT_TARGET_NAME)]).toBe(1);
+ });
+
+ it('is idempotent: baking the same sculpt twice adds one target, not two', async () => {
+ const gltf = await new NodeIO().readBinary(new Uint8Array(glbBytes));
+ applySculpt(gltf, doc);
+ const once = gltf.getRoot().listMeshes().find((m) => m.getName() === 'Body');
+ const count = once.listPrimitives()[0].listTargets().length;
+ applySculpt(gltf, doc);
+ const twice = gltf.getRoot().listMeshes().find((m) => m.getName() === 'Body');
+ expect(twice.listPrimitives()[0].listTargets()).toHaveLength(count);
+ expect(twice.getExtras().targetNames.filter((n) => n === SCULPT_TARGET_NAME)).toHaveLength(1);
+ });
+
+ it('reports a mesh whose vertex count does not match instead of mangling it', async () => {
+ const gltf = await new NodeIO().readBinary(new Uint8Array(glbBytes));
+ const wrong = { version: 1, meshes: { Body: { ...doc.meshes.Body, vertexCount: 7 } } };
+ const { applied, skipped } = applySculpt(gltf, wrong);
+ expect(applied).toEqual([]);
+ expect(skipped[0].mesh).toBe('Body');
+ expect(skipped[0].reason).toMatch(/vertex count/);
+ });
+
+ it('recognises a sculpt-only appearance as bakeable', async () => {
+ const { isBakeable } = await import('../api/_lib/bake.js');
+ expect(hasSculpt({ sculpt: doc })).toBe(true);
+ expect(hasSculpt({ sculpt: { version: 1, meshes: {} } })).toBe(false);
+ expect(isBakeable({ sculpt: doc })).toBe(true);
+ });
+});
+
+describe('free sculpt: composes with the library morphs through a real bake', () => {
+ it('lands both a slider and a stroke in one GLB, independently', async () => {
+ const { scene } = await sculptedScene();
+ const doc = serializeSculpt(scene);
+ const source = getSculptTarget(bodyOf(scene));
+
+ const { bakeAppearance } = await import('../api/_lib/bake.js');
+ const bytes = await bakeAppearance(glbBytes, {
+ morphs: { noseWider: 0.75 },
+ sculpt: doc,
+ });
+
+ const { MeshoptDecoder } = await import('meshoptimizer');
+ await MeshoptDecoder.ready;
+ const { scene: baked } = await new Promise((res, rej) => {
+ new GLTFLoader().setMeshoptDecoder(MeshoptDecoder).parse(
+ bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
+ '',
+ res,
+ rej,
+ );
+ });
+
+ const body = bodyOf(baked);
+ expect(body).not.toBeNull();
+ const dict = body.morphTargetDictionary;
+
+ // The library slider kept its own target and its own weight.
+ expect(dict.noseWider).toBeDefined();
+ expect(body.morphTargetInfluences[dict.noseWider]).toBeCloseTo(0.75, 5);
+
+ // The stroke arrived as its own target, fully weighted, carrying the
+ // same displacement the browser recorded.
+ expect(dict[SCULPT_TARGET_NAME]).toBeDefined();
+ expect(body.morphTargetInfluences[dict[SCULPT_TARGET_NAME]]).toBe(1);
+
+ const bakedAttr = body.geometry.morphAttributes.position[dict[SCULPT_TARGET_NAME]];
+ let bakedPeak = 0;
+ for (let i = 0; i < bakedAttr.count; i++) {
+ bakedPeak = Math.max(
+ bakedPeak,
+ Math.hypot(bakedAttr.getX(i), bakedAttr.getY(i), bakedAttr.getZ(i)),
+ );
+ }
+ let sourcePeak = 0;
+ for (let i = 0; i < source.count; i++) {
+ sourcePeak = Math.max(
+ sourcePeak,
+ Math.hypot(source.getX(i), source.getY(i), source.getZ(i)),
+ );
+ }
+ // weld + quantize run over the whole document, so this is a tolerance
+ // check on magnitude, not an exact-vertex comparison.
+ expect(bakedPeak).toBeGreaterThan(sourcePeak * 0.5);
+ expect(bakedPeak).toBeLessThan(sourcePeak * 2);
+ });
+});