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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
/**
* Free sculpt: the "change literally anything" guarantee.
*
* The morph library and the proportion table cover the shapes MakeHuman
* authored and the shapes a skeleton can express. Neither can give someone a
* dent in one temple, a crooked nose bridge, or a brow ridge that exists in no
* catalogue. This module does: a radius-and-falloff brush that pushes vertices
* along their own surface normal, recorded as ONE extra morph target on each
* mesh it touches.
*
* Recording it as a morph target rather than editing POSITION is the whole
* design. It means a free-sculpt edit:
* - composes additively with every library slider instead of fighting it,
* - survives GLTFExporter untouched (Avatar Studio saves the live scene),
* - can be re-applied to the pristine base from a serialized document, which
* is what api/_lib/bake-sculpt.js does for the /avatars/:id/edit path,
* - is reversible: clearing the target restores the catalogue body exactly.
*
* Space matters and is easy to get wrong. Morph deltas live in BIND space, but
* the user is pointing at a skinned, morphed, proportion-edited body on screen.
* Every stroke therefore builds the exact per-vertex bind-to-world map
* (bindMatrixInverse x blended bone matrices x bindMatrix, then the mesh's
* world matrix), moves the point in world space, and maps the displacement back
* through the inverse of that map. That map is sampled once per drag, at
* pointer-down: sculpting is correct for the pose you sculpted on, so the host
* settles the rig before enabling the brush rather than painting onto a moving
* target. That same cache is what the hit test picks against, because three's
* skinned raycast is far too slow on a 300-slider base to run per pointer move
* (see `_hit`).
*
* Symmetry is a mirror of the BRUSH, not of the vertices: the stroke is applied
* a second time at the point reflected across the avatar's own X = 0 plane. On
* an asymmetric body that still does the right thing, and turning it off is
* what makes asymmetry reachable at all.
*/
import { Matrix4, Raycaster, Vector2, Vector3, Float32BufferAttribute } from 'three';
import {
SCULPT_TARGET_NAME,
SCULPT_VERSION,
SCULPT_MAX_VERTS,
clampDisplacement,
bytesToBase64,
decodeSculptMesh,
} from './avatar-sculpt-doc.js';
// Re-exported so a caller that already holds the brush does not need to know
// the document module exists.
export {
SCULPT_TARGET_NAME,
SCULPT_VERSION,
SCULPT_MAX_VERTS,
SCULPT_MAX_DISPLACEMENT,
decodeSculptMesh,
sanitizeSculptDoc,
sculptVertexCount,
sculptEqual,
} from './avatar-sculpt-doc.js';
/** Brush defaults, in metres and metres-per-stroke-step. */
export const BRUSH_DEFAULTS = Object.freeze({
radius: 0.05,
strength: 0.006,
direction: 1, // +1 pulls the surface out, -1 pushes it in
symmetry: true,
});
/** Slider ranges for the brush controls, in the same units. */
export const BRUSH_LIMITS = Object.freeze({
radius: { min: 0.01, max: 0.3, step: 0.005 },
strength: { min: 0.001, max: 0.03, step: 0.001 },
});
/* ────────────────────────────────────────────────────────────────────────── *
* Morph-target plumbing
* ────────────────────────────────────────────────────────────────────────── */
/**
* The custom morph attribute for `mesh`, created (zeroed, influence 1) if the
* mesh does not carry one yet.
*
* A mesh with no morphs at all also gets `morphTargetsRelative = true`, because
* a delta target read as absolute positions collapses the mesh to a point.
*
* @param {import('three').Mesh} mesh
* @returns {import('three').BufferAttribute}
*/
export function ensureSculptTarget(mesh) {
const geo = mesh.geometry;
if (!geo?.attributes?.position) return null;
geo.morphAttributes = geo.morphAttributes || {};
const list = (geo.morphAttributes.position = geo.morphAttributes.position || []);
mesh.morphTargetDictionary = mesh.morphTargetDictionary || {};
mesh.morphTargetInfluences = mesh.morphTargetInfluences || [];
const existing = mesh.morphTargetDictionary[SCULPT_TARGET_NAME];
if (existing !== undefined && list[existing]) {
mesh.morphTargetInfluences[existing] = 1;
return list[existing];
}
if (list.length === 0) geo.morphTargetsRelative = true;
const attr = new Float32BufferAttribute(new Float32Array(geo.attributes.position.count * 3), 3);
attr.name = SCULPT_TARGET_NAME;
const index = list.length;
list.push(attr);
mesh.morphTargetDictionary[SCULPT_TARGET_NAME] = index;
mesh.morphTargetInfluences[index] = 1;
// The target count is part of the shader's cache key; three rebuilds the
// morph texture on its own but the program has to be told.
if (mesh.material) {
for (const m of Array.isArray(mesh.material) ? mesh.material : [mesh.material]) {
m.needsUpdate = true;
}
}
return attr;
}
/** The custom morph attribute for `mesh`, or null when it has never been sculpted. */
export function getSculptTarget(mesh) {
const index = mesh?.morphTargetDictionary?.[SCULPT_TARGET_NAME];
if (index === undefined) return null;
return mesh.geometry?.morphAttributes?.position?.[index] || null;
}
/** Every sculptable mesh under `root`, in traversal order. */
export function sculptableMeshes(root) {
const out = [];
root?.traverse?.((node) => {
if (node.isMesh && node.geometry?.attributes?.position) out.push(node);
});
return out;
}
/**
* Drop a custom target that is still all zeros.
*
* Adding a morph target makes three reallocate the whole morph texture (one
* dense RGBA32F layer per target: ~70 MB on this base), so the brush creates
* its target when it is switched ON rather than paying that stall inside the
* user's first drag. The cost of that trade is an empty target on a mesh nobody
* ended up painting, which would then ride into the exported GLB, so switching
* the brush off takes it back out again.
*
* Only ever removes the LAST target, which `ensureSculptTarget` guarantees the
* custom one is: removing from the middle would renumber every morph above it
* and silently rebind every slider the user had set.
*
* @returns {number} meshes pruned
*/
export function pruneEmptySculptTargets(root) {
let pruned = 0;
for (const mesh of sculptableMeshes(root)) {
const index = mesh.morphTargetDictionary?.[SCULPT_TARGET_NAME];
if (index === undefined) continue;
const list = mesh.geometry?.morphAttributes?.position;
if (!list || index !== list.length - 1) continue;
const attr = list[index];
if (!attr || attr.array.some((v) => v !== 0)) continue;
list.pop();
mesh.morphTargetInfluences.pop();
delete mesh.morphTargetDictionary[SCULPT_TARGET_NAME];
for (const m of Array.isArray(mesh.material) ? mesh.material : [mesh.material]) {
if (m) m.needsUpdate = true;
}
pruned++;
}
return pruned;
}
/** Zero every custom target under `root`. Returns the number of meshes reset. */
export function clearSculpt(root) {
let n = 0;
for (const mesh of sculptableMeshes(root)) {
const attr = getSculptTarget(mesh);
if (!attr) continue;
attr.array.fill(0);
attr.needsUpdate = true;
n++;
}
return n;
}
/** True when no mesh under `root` carries a non-zero free-sculpt delta. */
export function sculptIsEmpty(root) {
for (const mesh of sculptableMeshes(root)) {
const attr = getSculptTarget(mesh);
if (!attr) continue;
for (let i = 0; i < attr.array.length; i++) if (attr.array[i] !== 0) return false;
}
return true;
}
/* ────────────────────────────────────────────────────────────────────────── *
* Serialization: sparse, quantised, self-describing
* ────────────────────────────────────────────────────────────────────────── */
/**
* Serialize every non-zero free-sculpt delta under `root` into the document
* that `appearance.sculpt` carries (specs/PARAMETRIC_AVATAR.md).
*
* Sparse because a stroke touches hundreds of vertices out of ~15k, and
* quantised to int16 because a 0.12 m range at 16 bits resolves to under
* 4 micrometres, which is four orders of magnitude finer than anything a
* viewer can see. Together those turn a megabyte of floats into tens of KB of
* JSON-safe text.
*
* @param {object} root three.js Object3D
* @returns {{version:number, meshes:Record<string, object>}|null} null when nothing is sculpted
*/
export function serializeSculpt(root) {
const meshes = {};
for (const mesh of sculptableMeshes(root)) {
const attr = getSculptTarget(mesh);
if (!attr) continue;
const arr = attr.array;
const indices = [];
let peak = 0;
for (let i = 0, n = arr.length / 3; i < n; i++) {
const x = arr[i * 3];
const y = arr[i * 3 + 1];
const z = arr[i * 3 + 2];
if (x === 0 && y === 0 && z === 0) continue;
indices.push(i);
peak = Math.max(peak, Math.abs(x), Math.abs(y), Math.abs(z));
if (indices.length >= SCULPT_MAX_VERTS) break;
}
if (!indices.length || peak === 0) continue;
const scale = peak / 32767;
const idx = new Uint32Array(indices);
const deltas = new Int16Array(indices.length * 3);
for (let k = 0; k < indices.length; k++) {
const i = indices[k];
deltas[k * 3] = Math.round(arr[i * 3] / scale);
deltas[k * 3 + 1] = Math.round(arr[i * 3 + 1] / scale);
deltas[k * 3 + 2] = Math.round(arr[i * 3 + 2] / scale);
}
meshes[mesh.name || 'Mesh'] = {
count: indices.length,
vertexCount: arr.length / 3,
scale,
indices: bytesToBase64(new Uint8Array(idx.buffer)),
deltas: bytesToBase64(new Uint8Array(deltas.buffer)),
};
}
return Object.keys(meshes).length ? { version: SCULPT_VERSION, meshes } : null;
}
/**
* Re-apply a serialized document to a freshly loaded model. Meshes named in the
* document that this model does not have (a different base) are skipped, and a
* vertex index past the end of a mesh is dropped: a sculpt is tied to a
* topology, and refusing to load the rest of a valid document over one stale
* entry would be worse than ignoring it.
*
* @returns {{applied: string[], skipped: string[]}}
*/
export function applySculptToRoot(root, doc) {
const applied = [];
const skipped = [];
if (!doc || doc.version !== SCULPT_VERSION || !doc.meshes) return { applied, skipped };
const byName = new Map(sculptableMeshes(root).map((m) => [m.name, m]));
for (const [name, entry] of Object.entries(doc.meshes)) {
const mesh = byName.get(name);
const decoded = decodeSculptMesh(entry);
if (!mesh || !decoded) {
skipped.push(name);
continue;
}
const attr = ensureSculptTarget(mesh);
if (!attr) {
skipped.push(name);
continue;
}
attr.array.fill(0);
const limit = attr.array.length / 3;
for (let k = 0; k < decoded.indices.length; k++) {
const i = decoded.indices[k];
if (i >= limit) continue;
attr.array[i * 3] = decoded.deltas[k * 3];
attr.array[i * 3 + 1] = decoded.deltas[k * 3 + 1];
attr.array[i * 3 + 2] = decoded.deltas[k * 3 + 2];
}
attr.needsUpdate = true;
applied.push(name);
}
return { applied, skipped };
}
/* ────────────────────────────────────────────────────────────────────────── *
* The brush
* ────────────────────────────────────────────────────────────────────────── */
const _ndc = new Vector2();
const _v = new Vector3();
const _n = new Vector3();
const _delta = new Vector3();
const _a = new Vector3();
const _b = new Vector3();
const _skin = new Matrix4();
const _bone = new Matrix4();
const _inv = new Matrix4();
const _rootInv = new Matrix4();
const _pickMatrix = new Matrix4();
/** Blender-style smooth falloff: 1 at the centre, 0 at the rim, flat at both. */
function falloff(t) {
const s = 1 - t * t;
return s * s * s;
}
/**
* The bind-space-to-world matrix for one vertex of `mesh`, i.e. everything
* between the morph-target space the deltas live in and the pixels the user is
* pointing at. For a plain Mesh that is just the world matrix.
*/
function vertexBindToWorld(mesh, index, target) {
if (!mesh.isSkinnedMesh || !mesh.skeleton) return target.copy(mesh.matrixWorld);
const skinIndex = mesh.geometry.attributes.skinIndex;
const skinWeight = mesh.geometry.attributes.skinWeight;
if (!skinIndex || !skinWeight) return target.copy(mesh.matrixWorld);
_skin.set(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0);
let total = 0;
for (let i = 0; i < 4; i++) {
const w = skinWeight.getComponent(index, i);
if (w === 0) continue;
const b = skinIndex.getComponent(index, i);
const bone = mesh.skeleton.bones[b];
const inverse = mesh.skeleton.boneInverses[b];
if (!bone || !inverse) continue;
_bone.multiplyMatrices(bone.matrixWorld, inverse);
for (let e = 0; e < 16; e++) _skin.elements[e] += _bone.elements[e] * w;
total += w;
}
if (total === 0) return target.copy(mesh.matrixWorld);
// bindMatrixInverse x blendedBones x bindMatrix, then out to world.
target.copy(mesh.bindMatrixInverse).multiply(_skin).multiply(mesh.bindMatrix);
return target.premultiply(mesh.matrixWorld);
}
/**
* A free-sculpt brush bound to one canvas, one camera and one model root.
*
* Lifecycle: `new SculptBrush(opts)` then `enable()` / `disable()`. While
* enabled, a pointer press that hits the model sculpts and suppresses the
* orbit controls for that drag; a press that misses the model orbits as usual,
* so the camera never becomes unreachable.
*/
export class SculptBrush {
/**
* @param {object} opts
* @param {object} opts.root model root (three.js Object3D)
* @param {object} opts.camera
* @param {HTMLElement} opts.domElement the renderer canvas
* @param {object} [opts.controls] OrbitControls, suppressed during a stroke
* @param {(info: {vertices:number}) => void} [opts.onStroke] after each stroke step
* @param {() => void} [opts.onStrokeEnd] after the pointer lifts
*/
constructor({ root, camera, domElement, controls = null, onStroke, onStrokeEnd }) {
this.root = root;
this.camera = camera;
this.domElement = domElement;
this.controls = controls;
this.onStroke = onStroke;
this.onStrokeEnd = onStrokeEnd;
this.params = { ...BRUSH_DEFAULTS };
this.enabled = false;
this._raycaster = new Raycaster();
this._meshes = [];
this._pointerId = null;
this._controlsWere = null;
this._cursor = null;
this._worldCache = new WeakMap(); // mesh -> Float32Array of world positions
this._touched = 0;
// Pointer moves are coalesced onto animation frames. A stroke step costs
// a raycast against a 27k-triangle skinned mesh, and a fast drag can
// deliver several moves per frame; without this the queue backs up and
// the brush lags a visibly growing distance behind the cursor.
this._raf = null;
this._pending = null;
this._onDown = this._onDown.bind(this);
this._onMove = this._onMove.bind(this);
this._onUp = this._onUp.bind(this);
this._onLeave = this._onLeave.bind(this);
}
setParams(patch) {
Object.assign(this.params, patch);
this._syncCursorSize();
}
enable() {
if (this.enabled || !this.domElement) return;
this.enabled = true;
this._meshes = sculptableMeshes(this.root);
this.domElement.addEventListener('pointerdown', this._onDown);
this.domElement.addEventListener('pointermove', this._onMove);
this.domElement.addEventListener('pointerleave', this._onLeave);
window.addEventListener('pointerup', this._onUp);
this.domElement.style.cursor = 'crosshair';
this._ensureCursor();
// Allocate the custom target up front: see pruneEmptySculptTargets for
// why the morph-texture reallocation belongs on the toggle and not
// inside the first stroke.
for (const mesh of this._meshes) ensureSculptTarget(mesh);
}
disable() {
if (!this.enabled) return;
this.enabled = false;
this._endStroke();
this.domElement.removeEventListener('pointerdown', this._onDown);
this.domElement.removeEventListener('pointermove', this._onMove);
this.domElement.removeEventListener('pointerleave', this._onLeave);
window.removeEventListener('pointerup', this._onUp);
this.domElement.style.cursor = '';
this._cursor?.remove();
this._cursor = null;
pruneEmptySculptTargets(this.root);
}
dispose() {
this.disable();
this.root = null;
this._meshes = [];
}
/* ── pointer plumbing ──────────────────────────────────────────────── */
_ndcFrom(event) {
const rect = this.domElement.getBoundingClientRect();
_ndc.set(
((event.clientX - rect.left) / rect.width) * 2 - 1,
-((event.clientY - rect.top) / rect.height) * 2 + 1,
);
return _ndc;
}
/**
* Which vertex is under the pointer.
*
* NOT three's `Raycaster.intersectObjects`. `SkinnedMesh.raycast` calls
* `getVertexPosition` for all three corners of every triangle, and that
* method walks the whole morph-target list per corner. On this base that is
* 27k triangles x 3 x 306 targets, measured at ~200 ms per hit test, so a
* drag ran at four frames a second and the brush trailed the cursor by half
* a screen.
*
* The stroke already needs every vertex's world position, and the rig is
* frozen for the duration of the drag, so that array is built once and this
* picks against it: for each vertex, its distance along the ray and its
* perpendicular distance from it, keeping the nearest vertex in front of the
* camera that lies within a few pixels of the ray. One linear pass over
* 14.5k points, under a millisecond, and it is the front-most surface by
* construction because ties break on ray distance.
*
* @param {{clientX:number, clientY:number}} coords
* @returns {{object: object, index: number, point: Vector3, distance: number}|null}
*/
_hit(coords) {
if (!this._meshes.length) this._meshes = sculptableMeshes(this.root);
this._raycaster.setFromCamera(this._ndcFrom(coords), this.camera);
const { origin, direction } = this._raycaster.ray;
// A ray this many pixels from a vertex still counts as pointing at it.
// It has to exceed half the on-screen spacing between neighbouring
// vertices or a ray landing mid-quad finds nothing and the press falls
// through to the orbit controls, which reads as a brush that ignores
// half its clicks. The world-space floor covers the same gap at close
// zoom, where that spacing grows without bound.
const PICK_PX = 14;
const MIN_WORLD = 0.02;
const height = this.domElement?.clientHeight || 1;
const fov = ((this.camera.fov || 35) * Math.PI) / 180;
const worldPerPixelAt = (2 * Math.tan(fov / 2)) / height;
let best = null;
for (const mesh of this._meshes) {
const world = this._worldPositions(mesh);
for (let i = 0, n = world.length / 3; i < n; i++) {
const ox = world[i * 3] - origin.x;
const oy = world[i * 3 + 1] - origin.y;
const oz = world[i * 3 + 2] - origin.z;
const t = ox * direction.x + oy * direction.y + oz * direction.z;
if (t <= 0 || (best && t >= best.distance)) continue;
const px = ox - t * direction.x;
const py = oy - t * direction.y;
const pz = oz - t * direction.z;
const thr = Math.max(PICK_PX * worldPerPixelAt * t, MIN_WORLD);
if (px * px + py * py + pz * pz > thr * thr) continue;
best = { object: mesh, index: i, distance: t };
}
}
if (!best) return null;
const world = this._worldPositions(best.object);
best.point = new Vector3(
world[best.index * 3],
world[best.index * 3 + 1],
world[best.index * 3 + 2],
);
return best;
}
_onDown(event) {
if (!this.enabled || event.button !== 0) return;
const hit = this._hit(event);
if (!hit) return; // background press: let the orbit controls have it
event.preventDefault();
this._pointerId = event.pointerId;
this._touched = 0;
if (this.controls) {
this._controlsWere = this.controls.enabled;
this.controls.enabled = false;
}
this._worldCache = new WeakMap();
this.domElement.setPointerCapture?.(event.pointerId);
this._stroke(hit);
}
_onMove(event) {
if (!this.enabled) return;
this._moveCursor(event);
if (this._pointerId === null || event.pointerId !== this._pointerId) return;
event.preventDefault();
this._pending = { clientX: event.clientX, clientY: event.clientY };
if (this._raf !== null) return;
this._raf = requestAnimationFrame(() => {
this._raf = null;
const pending = this._pending;
this._pending = null;
if (!pending || this._pointerId === null) return;
const hit = this._hit(pending);
if (hit) this._stroke(hit);
});
}
_onUp(event) {
if (this._pointerId === null || event.pointerId !== this._pointerId) return;
this._endStroke();
}
_onLeave() {
if (this._cursor) this._cursor.style.opacity = '0';
}
_endStroke() {
if (this._raf !== null) {
cancelAnimationFrame(this._raf);
this._raf = null;
}
// One last step at the position the pointer stopped on, so a flick that
// ended between frames is not silently dropped.
if (this._pending && this._pointerId !== null) {
const hit = this._hit(this._pending);
if (hit) this._stroke(hit);
}
this._pending = null;
if (this._pointerId !== null) {
this.domElement?.releasePointerCapture?.(this._pointerId);
this._pointerId = null;
if (this.controls && this._controlsWere !== null) {
this.controls.enabled = this._controlsWere;
this._controlsWere = null;
}
if (this._touched > 0) this.onStrokeEnd?.();
}
}
/* ── the stroke itself ─────────────────────────────────────────────── */
/**
* Cached skinned+morphed world positions for one mesh. Recomputed at the
* start of every drag: the whole point of caching is that the rig does not
* move during a stroke, and a stale cache after an animation frame would
* sculpt the wrong vertices.
*/
_worldPositions(mesh) {
let cached = this._worldCache.get(mesh);
if (cached) return cached;
const geometry = mesh.geometry;
const position = geometry.attributes.position;
const count = position.count;
cached = new Float32Array(count * 3);
// three's Mesh.getVertexPosition walks EVERY morph target per vertex,
// which on a 306-slider base is 4.4 million comparisons for a body that
// typically has a handful of non-zero sliders. Resolve the active set
// once instead.
const morphAttributes = geometry.morphAttributes?.position || [];
const influences = mesh.morphTargetInfluences || [];
const relative = geometry.morphTargetsRelative !== false;
const active = [];
for (let m = 0; m < morphAttributes.length; m++) {
const w = influences[m];
if (w) active.push([morphAttributes[m], w]);
}
for (let i = 0; i < count; i++) {
_v.fromBufferAttribute(position, i);
for (const [attribute, weight] of active) {
_a.fromBufferAttribute(attribute, i);
if (relative) _v.addScaledVector(_a, weight);
else _v.addScaledVector(_a.sub(_v), weight);
}
if (mesh.isSkinnedMesh) mesh.applyBoneTransform(i, _v);
_v.applyMatrix4(mesh.matrixWorld);
cached[i * 3] = _v.x;
cached[i * 3 + 1] = _v.y;
cached[i * 3 + 2] = _v.z;
}
this._worldCache.set(mesh, cached);
return cached;
}
_stroke(hit) {
const mesh = hit.object;
if (!mesh?.geometry?.attributes?.position) return;
const normal = this._vertexNormal(mesh, hit.index);
const touched = this.applyStroke({ mesh, point: hit.point, normal });
if (touched) {
this._touched += touched;
this.onStroke?.({ vertices: touched });
}
}
/**
* World-space surface normal at a picked vertex. The vertex normal is
* authored in bind space like the positions, so it goes out through the same
* bind-to-world map rather than through the mesh's world matrix alone: on a
* posed or proportion-edited rig those differ, and a stroke along the wrong
* normal digs sideways into the mesh.
*/
_vertexNormal(mesh, index) {
const normals = mesh.geometry.attributes.normal;
if (normals) {
vertexBindToWorld(mesh, index, _pickMatrix);
return _n.fromBufferAttribute(normals, index).transformDirection(_pickMatrix).clone();
}
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;
this.root.updateMatrixWorld();
const local = this.root.worldToLocal(_a.copy(point));
local.x *= -1;
return this.root.localToWorld(local).clone();
}
/**
* Apply one stroke step centred on `center` with world direction `normal`.
* Returns the number of vertices moved.
*/
_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 { 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.
_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
// renormalises, which is exactly what a unit normal wants.
_rootInv.copy(this.root.matrixWorld).invert();
_n.transformDirection(_rootInv);
_n.x *= -1;
_n.transformDirection(this.root.matrixWorld);
}
let moved = 0;
const count = positions.count;
for (let i = 0; i < count; i++) {
const dx = world[i * 3] - center.x;
const dy = world[i * 3 + 1] - center.y;
const dz = world[i * 3 + 2] - center.z;
const d2 = dx * dx + dy * dy + dz * dz;
if (d2 > r2) continue;
const w = falloff(Math.sqrt(d2) / radius) * strength * direction;
if (w === 0) continue;
// World displacement -> bind-space displacement through the exact
// inverse of this vertex's own skinning map.
vertexBindToWorld(mesh, i, _inv);
_inv.invert();
_a.set(world[i * 3], world[i * 3 + 1], world[i * 3 + 2]);
_b.copy(_a).addScaledVector(_n, w);
_a.applyMatrix4(_inv);
_b.applyMatrix4(_inv);
_delta.subVectors(_b, _a);
const o = i * 3;
attr.array[o] = clampDisplacement(attr.array[o] + _delta.x);
attr.array[o + 1] = clampDisplacement(attr.array[o + 1] + _delta.y);
attr.array[o + 2] = clampDisplacement(attr.array[o + 2] + _delta.z);
moved++;
}
if (moved) attr.needsUpdate = true;
return moved;
}
/* ── on-canvas brush ring ──────────────────────────────────────────── */
_ensureCursor() {
if (this._cursor || typeof document === 'undefined') return;
const ring = document.createElement('div');
ring.className = 'ae-brush-ring';
ring.setAttribute('aria-hidden', 'true');
ring.style.cssText = [
'position:fixed',
'pointer-events:none',
'z-index:40',
'border:1.5px solid rgba(255,255,255,0.9)',
'box-shadow:0 0 0 1px rgba(0,0,0,0.45)',
'border-radius:50%',
'transform:translate(-50%,-50%)',
'opacity:0',
'transition:opacity 0.12s',
].join(';');
document.body.appendChild(ring);
this._cursor = ring;
}
_moveCursor(event) {
if (!this._cursor) return;
this._cursor.style.left = `${event.clientX}px`;
this._cursor.style.top = `${event.clientY}px`;
this._cursor.style.opacity = '1';
this._syncCursorSize();
}
/**
* Size the ring to the brush's real footprint by projecting a point one
* radius to the camera's right of the orbit target. A fixed-pixel ring
* would lie about the brush every time the user zoomed.
*/
_syncCursorSize() {
if (!this._cursor || !this.camera || !this.domElement) return;
const target = this.controls?.target || _a.set(0, 1.4, 0);
const dist = this.camera.position.distanceTo(target) || 1;
const fov = ((this.camera.fov || 35) * Math.PI) / 180;
const worldHeight = 2 * Math.tan(fov / 2) * dist;
const px = (this.params.radius * 2 * this.domElement.clientHeight) / worldHeight;
const size = Math.max(8, Math.min(400, px));
this._cursor.style.width = `${size}px`;
this._cursor.style.height = `${size}px`;
}
}