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
/**
* Skeleton-space proportions: the second axis of the parametric avatar editor.
*
* Morph targets can reshape a limb but they cannot lengthen one: a morph is a
* fixed set of vertex deltas in bind space, so pulling the hand further from
* the elbow drags the skin away from the bone that drives it. Length, width and
* stature live in the *skeleton*: move a joint's rest offset and every vertex
* weighted to it (and to everything below it) follows, skinning intact.
*
* That is what this module does. Each parameter is a ratio around 1.0 that
* rewrites the rest `position` and/or `scale` of a handful of canonical bones:
*
* offset params scale a joint's rest offset from its parent → longer shins,
* longer forearms, a longer neck, a wider set of shoulders.
* scale params scale a joint's rest scale → a bigger head, hands, feet.
* stature scales the armature node that parents the whole skeleton →
* a uniformly taller or shorter person.
*
* Bone *rotations* are never touched, which is what makes this composable with
* everything else: the pre-baked clip library keeps driving the rig (it writes
* rotations plus the root translation, see src/animation-retarget.js), the
* captured rest frames the retargeter relies on stay valid, and the morph
* sliders keep working because morph deltas are applied in bind space before
* skinning.
*
* Two things do need to follow a proportion edit:
* 1. Ground contact. Longer legs push the feet through the floor, so the hips
* are lifted by the exact amount the feet moved (measured, not assumed, so
* it is correct on any rig). See `computeProportionTransforms`.
* 2. Root motion. A walk's hip translation is authored at one hip height and
* rescaled onto the rig's actual height at bind time. Raise the hips and
* that factor is stale: the avatar foot-slides. Callers re-measure via
* `AnimationManager.remeasureRigProportions()` after applying.
*
* The module is dependency-free on purpose: the same parameter table and the
* same math run in the browser (Avatar Studio live preview) and on the server
* (api/_lib/bake.js, which writes the result into the baked GLB), so what the
* user sculpts is what every downstream viewer loads.
*/
/* ────────────────────────────────────────────────────────────────────────── *
* Parameter table: the contract. `id` is the key in appearance.proportions.
* ────────────────────────────────────────────────────────────────────────── */
/**
* @typedef {Object} ProportionParam
* @property {string} id key in `appearance.proportions`
* @property {string} label slider label
* @property {string} group UI grouping
* @property {string} hint one-line description of what it moves
* @property {'offset'|'scale'|'stature'} op
* @property {string[]} bones canonical bones the op writes to (empty for stature)
* @property {'all'|'lateral'} [axis] offset axis: whole vector, or model-X only
* @property {number} min
* @property {number} max
*/
/** @type {ProportionParam[]} */
export const PROPORTION_PARAMS = Object.freeze([
{
id: 'height',
label: 'Height',
group: 'Stature',
hint: 'Overall stature. Scales the whole figure around its feet.',
op: 'stature',
bones: [],
min: 0.85,
max: 1.15,
},
{
id: 'legLength',
label: 'Leg Length',
group: 'Stature',
hint: 'Shin and thigh length. The hips ride up so the feet stay on the floor.',
op: 'offset',
axis: 'all',
bones: ['LeftLeg', 'RightLeg', 'LeftFoot', 'RightFoot'],
min: 0.85,
max: 1.15,
},
{
id: 'torsoLength',
label: 'Torso Length',
group: 'Stature',
hint: 'Distance from hips to shoulders.',
op: 'offset',
axis: 'all',
bones: ['Spine', 'Spine1', 'Spine2'],
min: 0.85,
max: 1.15,
},
{
id: 'neckLength',
label: 'Neck Length',
group: 'Stature',
hint: 'How far the head sits above the shoulders.',
op: 'offset',
axis: 'all',
bones: ['Neck', 'Head'],
min: 0.8,
max: 1.25,
},
{
id: 'armLength',
label: 'Arm Length',
group: 'Frame',
hint: 'Forearm and hand reach.',
op: 'offset',
axis: 'all',
bones: ['LeftForeArm', 'RightForeArm', 'LeftHand', 'RightHand'],
min: 0.85,
max: 1.15,
},
{
id: 'shoulderWidth',
label: 'Shoulder Width',
group: 'Frame',
hint: 'How far apart the shoulders sit. Broad frame vs narrow.',
op: 'offset',
axis: 'lateral',
bones: ['LeftShoulder', 'RightShoulder', 'LeftArm', 'RightArm'],
min: 0.85,
max: 1.2,
},
{
id: 'hipWidth',
label: 'Hip Width',
group: 'Frame',
hint: 'How far apart the legs are set at the hip.',
op: 'offset',
axis: 'lateral',
bones: ['LeftUpLeg', 'RightUpLeg'],
min: 0.85,
max: 1.2,
},
{
id: 'headSize',
label: 'Head Size',
group: 'Extremities',
hint: 'Scales the head and everything parented to it.',
op: 'scale',
bones: ['Head'],
min: 0.85,
max: 1.15,
},
{
id: 'handSize',
label: 'Hand Size',
group: 'Extremities',
hint: 'Scales both hands, fingers included.',
op: 'scale',
bones: ['LeftHand', 'RightHand'],
min: 0.85,
max: 1.2,
},
{
id: 'footSize',
label: 'Foot Size',
group: 'Extremities',
hint: 'Scales both feet. The hips compensate so the soles stay grounded.',
op: 'scale',
bones: ['LeftFoot', 'RightFoot'],
min: 0.85,
max: 1.2,
},
]);
export const PROPORTION_PARAM_BY_ID = new Map(PROPORTION_PARAMS.map((p) => [p.id, p]));
/** Ordered UI groups, derived from the table so adding a param needs no UI edit. */
export const PROPORTION_GROUPS = [...new Set(PROPORTION_PARAMS.map((p) => p.group))];
/** Every canonical bone any parameter reads or writes, plus the chain to the floor. */
export const PROPORTION_BONES = Object.freeze([
...new Set([
'Hips',
...PROPORTION_PARAMS.flatMap((p) => p.bones),
'LeftUpLeg', 'RightUpLeg', 'LeftToeBase', 'RightToeBase',
]),
]);
/**
* Bones used to measure ground contact, left/right paired and best-first. The
* toe is preferred over the ankle because it is the part that actually touches
* the floor on a standing rig; a rig without toes falls back to the foot.
*/
const GROUND_CHAINS = [
['LeftToeBase', 'LeftFoot'],
['RightToeBase', 'RightFoot'],
];
/** A parameter within this of 1.0 is neutral and is dropped on serialization. */
const NEUTRAL_EPSILON = 1e-4;
/* ────────────────────────────────────────────────────────────────────────── *
* Parameter document
* ────────────────────────────────────────────────────────────────────────── */
/**
* Clamp an incoming `{ id: ratio }` record to the declared ranges and drop
* unknown keys, non-finite values, and anything that is neutral anyway. The
* result is the canonical serialized form: an empty object means "default
* body", which is why `collapseAppearance` can omit the field entirely.
*
* @param {Record<string, number>|null|undefined} raw
* @returns {Record<string, number>}
*/
export function normalizeProportions(raw) {
if (!raw || typeof raw !== 'object') return {};
const out = {};
for (const param of PROPORTION_PARAMS) {
const v = Number(raw[param.id]);
if (!Number.isFinite(v)) continue;
const clamped = Math.min(param.max, Math.max(param.min, v));
if (Math.abs(clamped - 1) < NEUTRAL_EPSILON) continue;
out[param.id] = clamped;
}
return out;
}
/** True when two proportion records mean the same body. */
export function proportionsEqual(a, b) {
const na = normalizeProportions(a);
const nb = normalizeProportions(b);
const keys = new Set([...Object.keys(na), ...Object.keys(nb)]);
for (const k of keys) {
if (Math.abs((na[k] ?? 1) - (nb[k] ?? 1)) > NEUTRAL_EPSILON) return false;
}
return true;
}
/* ────────────────────────────────────────────────────────────────────────── *
* Quaternion / vector helpers: plain objects, no three.js dependency, so the
* same math runs in the browser, in Node during a bake, and in vitest.
* ────────────────────────────────────────────────────────────────────────── */
function qMul(a, b) {
return {
x: a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,
y: a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,
z: a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,
w: a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z,
};
}
function qConj(q) {
return { x: -q.x, y: -q.y, z: -q.z, w: q.w };
}
function qRotate(q, v) {
// t = 2 · (q.xyz × v); v' = v + q.w · t + q.xyz × t
const tx = 2 * (q.y * v.z - q.z * v.y);
const ty = 2 * (q.z * v.x - q.x * v.z);
const tz = 2 * (q.x * v.y - q.y * v.x);
return {
x: v.x + q.w * tx + q.y * tz - q.z * ty,
y: v.y + q.w * ty + q.z * tx - q.x * tz,
z: v.z + q.w * tz + q.x * ty - q.y * tx,
};
}
const IDENTITY_Q = Object.freeze({ x: 0, y: 0, z: 0, w: 1 });
function vec3(v, fallback = 0) {
return {
x: Number.isFinite(v?.x) ? v.x : fallback,
y: Number.isFinite(v?.y) ? v.y : fallback,
z: Number.isFinite(v?.z) ? v.z : fallback,
};
}
function quat(q) {
if (!Number.isFinite(q?.x) || !Number.isFinite(q?.w)) return { ...IDENTITY_Q };
return { x: q.x, y: q.y, z: q.z, w: q.w };
}
/* ────────────────────────────────────────────────────────────────────────── *
* The math: pure, rig-agnostic, unit-testable against a synthetic skeleton.
* ────────────────────────────────────────────────────────────────────────── */
/**
* @typedef {Object} RestBone
* @property {{x:number,y:number,z:number}} position local rest offset from the parent
* @property {{x:number,y:number,z:number,w:number}} quaternion local rest rotation
* @property {{x:number,y:number,z:number}} scale local rest scale
* @property {string|null} parent nearest canonical ancestor bone, null for the root
*/
/**
* Accumulated rest rotation of each bone, expressed in the frame that parents
* the Hips (the armature frame). Used to project a lateral edit onto the body's
* true left/right axis on rigs whose bone frames are rotated (Mixamo, VRM),
* rather than assuming local X is lateral.
*
* @param {Map<string, RestBone>} rest
* @returns {Map<string, {x:number,y:number,z:number,w:number}>}
*/
function accumulatedRestRotations(rest) {
const out = new Map();
const resolve = (name, guard) => {
if (out.has(name)) return out.get(name);
if (guard.has(name)) return { ...IDENTITY_Q }; // cyclic parent link: treat as root
guard.add(name);
const bone = rest.get(name);
if (!bone) return { ...IDENTITY_Q };
const parentQ = bone.parent ? resolve(bone.parent, guard) : { ...IDENTITY_Q };
const q = qMul(parentQ, quat(bone.quaternion));
out.set(name, q);
return q;
};
for (const name of rest.keys()) resolve(name, new Set());
return out;
}
/**
* Position of `bone`'s origin in the armature frame (the Hips' parent), walking
* the canonical chain with the supplied local transforms. Returns null when the
* chain is broken.
*
* @param {string} name
* @param {Map<string, RestBone>} rest
* @param {Map<string, {position?:object, scale?:object}>} overrides edited locals
* @returns {{x:number,y:number,z:number}|null}
*/
function boneOrigin(name, rest, overrides) {
const chain = [];
const seen = new Set();
for (let cur = name; cur; cur = rest.get(cur)?.parent || null) {
if (seen.has(cur) || !rest.has(cur)) break;
seen.add(cur);
chain.push(cur);
}
if (!chain.length || !seen.has(name)) return null;
let p = { x: 0, y: 0, z: 0 };
let q = { ...IDENTITY_Q };
let s = { x: 1, y: 1, z: 1 };
for (let i = chain.length - 1; i >= 0; i--) {
const bone = rest.get(chain[i]);
const edit = overrides.get(chain[i]);
const local = vec3(edit?.position ?? bone.position);
const scaled = { x: local.x * s.x, y: local.y * s.y, z: local.z * s.z };
const rotated = qRotate(q, scaled);
p = { x: p.x + rotated.x, y: p.y + rotated.y, z: p.z + rotated.z };
q = qMul(q, quat(bone.quaternion));
const localScale = vec3(edit?.scale ?? bone.scale, 1);
s = { x: s.x * localScale.x, y: s.y * localScale.y, z: s.z * localScale.z };
}
return p;
}
/**
* Resolve a proportion record into the new local `position` / `scale` each
* canonical bone should rest at, plus the uniform stature factor for the
* armature node.
*
* The Hips offset that keeps the feet grounded is measured, not derived from
* the parameter values: both ground chains are located in the armature frame
* before and after the edit and the hips move by the average of the two deltas.
* Averaging cancels the symmetric left/right spread a hip-width edit produces
* while keeping the vertical (and any forward) correction a length edit needs,
* and measuring rather than assuming keeps it exact on a rig whose bone frames
* are rotated.
*
* @param {Map<string, RestBone>} rest bind-pose locals, keyed by canonical bone
* @param {Record<string, number>} proportions
* @returns {{ bones: Map<string, {position:{x:number,y:number,z:number}, scale:{x:number,y:number,z:number}}>, stature: number, applied: string[] }}
*/
export function computeProportionTransforms(rest, proportions) {
const values = normalizeProportions(proportions);
const applied = [];
/** @type {Map<string, {position:{x,y,z}, scale:{x,y,z}}>} */
const bones = new Map();
let stature = 1;
if (!(rest instanceof Map) || rest.size === 0) {
return { bones, stature, applied };
}
const accumulated = accumulatedRestRotations(rest);
const edit = (name) => {
if (!bones.has(name)) {
const bone = rest.get(name);
bones.set(name, {
position: vec3(bone.position),
scale: vec3(bone.scale, 1),
});
}
return bones.get(name);
};
for (const param of PROPORTION_PARAMS) {
const k = values[param.id];
if (k === undefined) continue;
if (param.op === 'stature') {
stature = k;
applied.push(param.id);
continue;
}
let touched = false;
for (const name of param.bones) {
const bone = rest.get(name);
if (!bone) continue;
const target = edit(name);
touched = true;
if (param.op === 'scale') {
target.scale = { x: target.scale.x * k, y: target.scale.y * k, z: target.scale.z * k };
continue;
}
if (param.axis === 'lateral') {
// Scale only the body's left/right component. The offset is authored
// in the parent's frame, so rotate it into the armature frame, scale
// X there, and rotate it back, correct whatever the bone frame is.
const parentQ = bone.parent ? accumulated.get(bone.parent) || IDENTITY_Q : IDENTITY_Q;
const inArmature = qRotate(parentQ, target.position);
inArmature.x *= k;
target.position = qRotate(qConj(parentQ), inArmature);
} else {
target.position = {
x: target.position.x * k,
y: target.position.y * k,
z: target.position.z * k,
};
}
}
if (touched) applied.push(param.id);
}
// Ground compensation. Nothing to do when no bone offset or scale moved.
if (bones.size > 0 && rest.has('Hips')) {
const deltas = [];
for (const chain of GROUND_CHAINS) {
const name = chain.find((n) => rest.has(n));
if (!name) continue;
const before = boneOrigin(name, rest, new Map());
const after = boneOrigin(name, rest, bones);
if (!before || !after) continue;
deltas.push({ x: before.x - after.x, y: before.y - after.y, z: before.z - after.z });
}
if (deltas.length) {
const lift = deltas.reduce(
(acc, d) => ({ x: acc.x + d.x / deltas.length, y: acc.y + d.y / deltas.length, z: acc.z + d.z / deltas.length }),
{ x: 0, y: 0, z: 0 },
);
if (Math.abs(lift.x) > 1e-9 || Math.abs(lift.y) > 1e-9 || Math.abs(lift.z) > 1e-9) {
const hips = edit('Hips');
hips.position = {
x: hips.position.x + lift.x,
y: hips.position.y + lift.y,
z: hips.position.z + lift.z,
};
}
}
}
return { bones, stature, applied };
}
/* ────────────────────────────────────────────────────────────────────────── *
* three.js binding: rest capture and live application
* ────────────────────────────────────────────────────────────────────────── */
/** Rest state per loaded model root. Dropped with the model. */
const REST_BY_ROOT = new WeakMap();
/**
* Fallback canonical-bone resolver used when the caller supplies no bone map.
* Strips the rigger prefixes and separators we see most often. Callers that
* need the full variant coverage (VRM, Unreal, Daz, …) pass an explicit map
* built from `canonicalizeBoneName` in src/glb-canonicalize.js.
*/
function simpleCanonicalKey(name) {
return String(name || '')
.replace(/^mixamorig\d*[_:]?/i, '')
.replace(/^CC_Base_/i, '')
.replace(/^(rig_|DEF-|ORG-|Armature[_:|/])/i, '')
.replace(/[^a-z0-9]/gi, '')
.toLowerCase();
}
const SIMPLE_KEY_TO_CANONICAL = new Map(
PROPORTION_BONES.map((b) => [simpleCanonicalKey(b), b]),
);
/**
* Locate the canonical bones this module edits on a loaded model.
*
* @param {object} root three.js Object3D
* @param {Map<string, object>|null} [boneMap] canonical → node, when the caller
* has already resolved the rig (preferred: it covers every naming convention)
* @returns {Map<string, object>}
*/
function resolveBones(root, boneMap) {
const out = new Map();
if (boneMap instanceof Map) {
for (const name of PROPORTION_BONES) {
const node = boneMap.get(name);
if (node?.isObject3D) out.set(name, node);
}
// Only trust the supplied map when it resolved the root of the chain,
// without Hips there is nothing to measure ground contact against, and a
// full traversal may still find it.
if (out.has('Hips')) return out;
out.clear();
}
root?.traverse?.((node) => {
if (!node?.name) return;
const canonical = SIMPLE_KEY_TO_CANONICAL.get(simpleCanonicalKey(node.name));
if (canonical && !out.has(canonical)) out.set(canonical, node);
});
return out;
}
/**
* Capture the model's bind-pose skeleton so proportion edits are always applied
* from rest rather than compounding on the last edit.
*
* MUST be called while the model is in its authored bind pose, i.e. right
* after the GLB loads and before any clip plays. A capture taken mid-animation
* bakes that frame's pose in as "rest" and the avatar drifts on every slider.
* Idempotent: a second call on the same root returns the existing capture
* unless `{ force: true }`.
*
* @param {object} root three.js Object3D
* @param {{ boneMap?: Map<string, object>, force?: boolean }} [opts]
* @returns {{ bones: Map<string, object>, rest: Map<string, RestBone>, armature: object|null } | null}
*/
export function captureProportionRest(root, opts = {}) {
if (!root) return null;
const existing = REST_BY_ROOT.get(root);
if (existing && !opts.force) return existing;
const bones = resolveBones(root, opts.boneMap);
if (!bones.has('Hips')) return null;
// Nearest canonical ancestor of each bone, so the pure math can walk chains
// without knowing anything about the graph.
const nodeToCanonical = new Map();
for (const [canonical, node] of bones) nodeToCanonical.set(node, canonical);
const parentOf = (node) => {
for (let n = node.parent; n; n = n.parent) {
const canonical = nodeToCanonical.get(n);
if (canonical) return canonical;
}
return null;
};
/** @type {Map<string, RestBone>} */
const rest = new Map();
for (const [canonical, node] of bones) {
rest.set(canonical, {
position: vec3(node.position),
quaternion: quat(node.quaternion),
scale: vec3(node.scale, 1),
parent: parentOf(node),
});
}
// The node that parents the whole skeleton (`Armature`, `ParametricBase`, …).
// Stature scales it, which moves the skeleton and the skinned meshes hanging
// off it together. When the Hips are parented straight to the model root we
// leave it null rather than scale a node the viewer also owns, the Height
// slider then simply isn't offered (see `availableProportionParams`).
const hips = bones.get('Hips');
const armature = hips.parent && hips.parent !== root ? hips.parent : null;
const state = {
bones,
rest,
armature,
armatureRestScale: armature ? vec3(armature.scale, 1) : null,
};
REST_BY_ROOT.set(root, state);
return state;
}
/**
* Which parameters this rig can actually honour. A slider whose bones are
* missing would be a dead control, and the sculpt panel's rule is that what the
* user sees is what the rig can do.
*
* @param {object} root
* @param {{ boneMap?: Map<string, object> }} [opts]
* @returns {string[]} parameter ids
*/
export function availableProportionParams(root, opts = {}) {
const state = captureProportionRest(root, opts);
if (!state) return [];
return PROPORTION_PARAMS.filter((p) => {
if (p.op === 'stature') return !!state.armature;
return p.bones.some((b) => state.rest.has(b));
}).map((p) => p.id);
}
/**
* Apply a proportion record to a loaded model, from rest.
*
* Restores every captured bone (rotation included) to its bind transform first,
* so the result is a function of the record alone and repeated edits never
* compound. The rotation reset is what makes the measurement below trustworthy;
* a running mixer re-poses the rig on its next tick, so it is invisible.
*
* @param {object} root three.js Object3D
* @param {Record<string, number>} proportions
* @param {{ boneMap?: Map<string, object> }} [opts]
* @returns {{ applied: string[], stature: number } | null} null when the rig has no usable skeleton
*/
export function applyProportionsToRoot(root, proportions, opts = {}) {
const state = captureProportionRest(root, opts);
if (!state) return null;
// Rest first: bone locals AND rotations, so a re-apply is idempotent and the
// ground measurement reads the bind pose.
for (const [canonical, node] of state.bones) {
const bone = state.rest.get(canonical);
if (!bone) continue;
node.position.set(bone.position.x, bone.position.y, bone.position.z);
node.quaternion.set(bone.quaternion.x, bone.quaternion.y, bone.quaternion.z, bone.quaternion.w);
node.scale.set(bone.scale.x, bone.scale.y, bone.scale.z);
}
if (state.armature && state.armatureRestScale) {
const s = state.armatureRestScale;
state.armature.scale.set(s.x, s.y, s.z);
}
const { bones, stature, applied } = computeProportionTransforms(state.rest, proportions);
for (const [canonical, local] of bones) {
const node = state.bones.get(canonical);
if (!node) continue;
node.position.set(local.position.x, local.position.y, local.position.z);
node.scale.set(local.scale.x, local.scale.y, local.scale.z);
}
if (state.armature && state.armatureRestScale && stature !== 1) {
const s = state.armatureRestScale;
state.armature.scale.set(s.x * stature, s.y * stature, s.z * stature);
}
root.updateMatrixWorld?.(true);
return { applied, stature };
}
/* ────────────────────────────────────────────────────────────────────────── *
* Panel: rendered inside the Sculpt tab, above the morph groups
* ────────────────────────────────────────────────────────────────────────── */
/**
* Markup for the Proportions group. Returns '' when the rig supports none of
* the parameters, so the caller can concatenate it unconditionally.
*
* @param {string[]} availableIds ids from {@link availableProportionParams}
* @param {Record<string, number>} proportions current values
* @returns {string}
*/
export function proportionsGroupHtml(availableIds, proportions) {
const available = new Set(availableIds || []);
const params = PROPORTION_PARAMS.filter((p) => available.has(p.id));
if (!params.length) return '';
const values = normalizeProportions(proportions);
const changed = params.filter((p) => values[p.id] !== undefined).length;
const sections = PROPORTION_GROUPS.map((group) => {
const rows = params.filter((p) => p.group === group);
if (!rows.length) return '';
return `
<div class="ae-prop-section">
<h4 class="ae-prop-heading">${escHtml(group)}</h4>
${rows.map((p) => proportionRow(p, values[p.id] ?? 1)).join('')}
</div>`;
}).join('');
return `
<details class="ae-sculpt-group ae-prop-group" open>
<summary>
<span>Proportions</span>
<span class="ae-sculpt-count" id="ae-prop-count">${changed ? `${changed} changed` : 'default'}</span>
</summary>
<div class="ae-sculpt-rows ae-prop-rows">
<p class="ae-prop-note">
Bone-level build: length, width and stature. Morph sliders reshape;
these re-proportion. Double-click a slider to reset it.
</p>
${sections}
<button class="ae-btn" type="button" id="ae-prop-reset">Reset proportions</button>
</div>
</details>`;
}
function proportionRow(param, value) {
return `
<div class="ae-sculpt-row ae-prop-row">
<div class="ae-sculpt-label">
<span class="ae-sculpt-name" title="${escAttr(param.hint)}">${escHtml(param.label)}</span>
</div>
<input
type="range"
min="${param.min}" max="${param.max}" step="0.005"
value="${value}"
data-prop="${escAttr(param.id)}"
aria-label="${escAttr(param.label)}"
/>
<output class="ae-sculpt-value" data-prop-for="${escAttr(param.id)}">${formatRatio(value)}</output>
</div>`;
}
/** Human-readable ratio: 1 → "default", 1.06 → "+6%", 0.94 → "-6%". */
export function formatRatio(value) {
const pct = Math.round((Number(value) - 1) * 1000) / 10;
if (Math.abs(pct) < 0.05) return 'default';
return `${pct > 0 ? '+' : ''}${pct}%`;
}
/**
* Wire the Proportions sliders. Each input applies live to the rig; the rig
* re-measure (root-motion rescale) is debounced because it rebuilds every bound
* action and a slider drag fires dozens of events a second.
*
* @param {object} opts
* @param {HTMLElement} opts.container
* @param {object} opts.root three.js Object3D
* @param {object} opts.working appearance object (we own `.proportions`)
* @param {Map<string, object>} [opts.boneMap]
* @param {() => void} [opts.onDirty]
* @param {() => void} [opts.onRigChanged] called after the skeleton settles
* @param {() => void} [opts.rerender] re-render the panel (used by Reset)
*/
export function wireProportionsGroup({ container, root, working, boneMap, onDirty, onRigChanged, rerender }) {
const inputs = container.querySelectorAll('input[type="range"][data-prop]');
if (!inputs.length) return;
working.proportions = normalizeProportions(working.proportions);
const countEl = container.querySelector('#ae-prop-count');
let rigTimer = null;
const scheduleRigChange = () => {
if (!onRigChanged) return;
if (rigTimer) clearTimeout(rigTimer);
rigTimer = setTimeout(() => {
rigTimer = null;
onRigChanged();
}, 140);
};
const commit = () => {
applyProportionsToRoot(root, working.proportions, { boneMap });
if (countEl) {
const n = Object.keys(working.proportions).length;
countEl.textContent = n ? `${n} changed` : 'default';
}
onDirty?.();
scheduleRigChange();
};
inputs.forEach((input) => {
const id = input.dataset.prop;
const param = PROPORTION_PARAM_BY_ID.get(id);
if (!param) return;
const valEl = container.querySelector(`output[data-prop-for="${cssEscape(id)}"]`);
const onChange = () => {
const v = Math.min(param.max, Math.max(param.min, Number(input.value)));
if (Math.abs(v - 1) < NEUTRAL_EPSILON) delete working.proportions[id];
else working.proportions[id] = v;
if (valEl) valEl.textContent = formatRatio(v);
commit();
};
input.addEventListener('input', onChange);
input.addEventListener('dblclick', () => {
input.value = '1';
onChange();
});
});
container.querySelector('#ae-prop-reset')?.addEventListener('click', () => {
working.proportions = {};
applyProportionsToRoot(root, working.proportions, { boneMap });
onDirty?.();
scheduleRigChange();
rerender?.();
});
}
/* ────────────────────────────────────────────────────────────────────────── *
* Helpers
* ────────────────────────────────────────────────────────────────────────── */
function escHtml(s) {
return String(s ?? '').replace(
/[&<>"']/g,
(c) => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[c],
);
}
function escAttr(s) { return escHtml(s); }
function cssEscape(s) { return String(s).replace(/(["\\])/g, '\\$1'); }