Turn one illustration into an animated 2D mesh avatar with a coding agent and a local editor
/** @param {ReturnType<import('./rig.js').createRig>} engine
* @param {import('../rig/types').Rig} rig */
export function createPhysics(engine, rig) {
const { applyHead, applyBody, TASSELS, tasselAnchor } = engine;
const STRANDS = (rig.strands ?? []).map(strand => {
if (strand.nodes.length === 4) return strand;
const nodes = Array.from({ length: 4 }, (_, i) => {
const f = i / 3 * (strand.nodes.length - 1);
const k = Math.min(strand.nodes.length - 2, Math.floor(f));
const t = f - k;
return [0, 1].map(axis => strand.nodes[k][axis] + (strand.nodes[k + 1][axis] - strand.nodes[k][axis]) * t);
});
return { ...strand, nodes };
});
// Secondary motion: spring chains for hair strands, spring-mass points for the buns
// and 2-segment verlet chains for tassels.
// Strand chain tuning: stiffness per node (root .. tip), how much of the parent's lag each
// node inherits (this is what makes a swing travel down the strand), and damping.
const STRAND_K = [0, 300, 200, 140], STRAND_COUPLE = 0.9, STRAND_DAMP = 7;
// Overall hair feel, tuned against measured runs (see README). Once motions made the head
// move ~4x faster, the chains whipped and neighbouring strands split apart by up to 16px,
// which smeared the hair between them.
// stiff / damp / couple: scale the chain springs, damping and the root-to-tip lag
// reach: soft limit of the tip offset, as a share of each strand's `max`
// bind: smoothing passes across the fringe strands (more = moves more as one sheet)
const HAIR_TUNE = { stiff: 1.7, damp: 1.6, couple: 0.85, reach: 0.9, bind: 4 };
const FRINGE = Math.min(6, STRANDS.filter(s => s.name.startsWith('bang')).length);
// Tassel pendulum: swing frequency (Hz), damping ratio, how much head tilt it counters,
// how strongly knot acceleration pushes it, gentle wind (rad), limit (rad), accel smoothing (1/s)
const TASSEL_TUNE = { freq: 0.7, zeta: 0.22, hang: 0.85, inertia: 0.32, wind: 0.03, max: 0.55, smooth: 6 };
const rotV = (v, a) => [v[0] * Math.cos(a) - v[1] * Math.sin(a), v[0] * Math.sin(a) + v[1] * Math.cos(a)]; // STRANDS[0..5] are the fringe, 6 and 7 the side locks
const softLimit = (v, m) => { const l = Math.hypot(v[0], v[1]); if (l < 1e-6) return v; const k = m * Math.tanh(l / m) / l; return [v[0] * k, v[1] * k]; };
const HAIR = Object.fromEntries(Object.entries(rig.buns ?? {}).map(([key, area]) => [key, { at: [area.cx, area.cy], k: 260, c: 11, hang: 3, max: 4 }]));
const clampLen = (v, m) => { const l = Math.hypot(v[0], v[1]); if (l > m) { v[0] *= m / l; v[1] *= m / l; } };
class Physics {
constructor() {
this.gain = 1; // "sway gain"
this.out = { gain: 1, bunL: [0, 0], bunR: [0, 0] };
this.hair = {};
for (const k of Object.keys(HAIR)) {
this.hair[k] = { p: null, v: [0, 0] };
this.out[k] = [0, 0];
}
this.strands = STRANDS.map(() => ({ p: null, v: [[0, 0], [0, 0], [0, 0], [0, 0]] }));
this.out.strands = STRANDS.map(() => [[0, 0], [0, 0], [0, 0], [0, 0]]);
this.chains = TASSELS.map(t => {
const dx = t.tip[0] - t.pivot[0], dy = t.tip[1] - t.pivot[1], L = Math.hypot(dx, dy);
const dir = [dx / L, dy / L];
return { t, dir, L1: L * t.split, L2: L * (1 - t.split), pts: null, prev: null, phi: [0, 0], anchor: [0, 0] };
});
this.time = 0;
}
hairAnchor(at, P) {
const p = [at[0], at[1]];
applyHead(p, 1, P);
applyBody(p, at[1], P);
return p;
}
step(P, dt) {
engine.stepBody?.(P, dt);
const sub = Math.max(1, Math.ceil(dt / (1 / 240)));
const h = Math.min(dt, 0.05) / sub;
const roll = -P.angleZ / 30 * rig.head.maxRoll - P.bodyAngleZ / 10 * rig.body.maxRoll;
const g = this.gain;
STRANDS.forEach((cfg, si) => {
const st = this.strands[si], out = this.out.strands[si];
const target = cfg.nodes.map(n => this.hairAnchor(n, P));
if (!st.p) st.p = target.map(t => [...t]);
const phase = si * 1.7;
for (let i = 0; i < sub; i++) {
const t = this.time + i * h;
for (let j = 1; j < 4; j++) {
// hanging hair stays vertical when the head rolls (grows with distance from the root)
const hang = Math.hypot(cfg.nodes[j][0] - cfg.nodes[0][0], cfg.nodes[j][1] - cfg.nodes[0][1]);
// mostly one shared breeze, with a little per-strand flutter
const wind = (Math.sin(t * 1.3) * 0.5 + Math.sin(t * 3.1) * 0.3 + Math.sin(t * 4.7 + phase) * 0.2) * cfg.max * 0.1 * j / 3;
const parent = [st.p[j - 1][0] - target[j - 1][0], st.p[j - 1][1] - target[j - 1][1]];
const tx = target[j][0] + parent[0] * STRAND_COUPLE * HAIR_TUNE.couple - Math.sin(roll) * hang * 0.12 + wind;
const ty = target[j][1] + parent[1] * STRAND_COUPLE * HAIR_TUNE.couple;
const k = STRAND_K[j] * cfg.k * HAIR_TUNE.stiff / Math.max(0.35, g), c = STRAND_DAMP * HAIR_TUNE.damp * Math.sqrt(HAIR_TUNE.stiff) / Math.max(0.5, Math.sqrt(g));
const v = st.v[j], q = st.p[j];
v[0] += (k * (tx - q[0]) - c * v[0]) * h;
v[1] += (k * (ty - q[1]) - c * v[1]) * h;
q[0] += v[0] * h; q[1] += v[1] * h;
}
st.p[0] = [...target[0]];
}
for (let j = 0; j < 4; j++) {
const o = [st.p[j][0] - target[j][0], st.p[j][1] - target[j][1]];
out[j] = softLimit(o, Math.max(0.5, cfg.max * HAIR_TUNE.reach * Math.max(1, g) * j / 3));
}
});
for (const [k, cfg] of Object.entries(HAIR)) {
const s = this.hair[k];
const a = this.hairAnchor(cfg.at, P);
// hanging hair keeps pointing down when the head rolls; plus a light breeze
const wind = Math.sin(this.time * 1.3 + cfg.at[0] * 0.01) * 0.6 + Math.sin(this.time * 2.9 + cfg.at[1] * 0.02) * 0.4;
const tx = a[0] - Math.sin(roll) * cfg.hang + wind * cfg.max * 0.12;
const ty = a[1];
if (!s.p) s.p = [tx, ty];
const k2 = cfg.k / Math.max(0.35, g), c2 = cfg.c / Math.max(0.5, Math.sqrt(g));
for (let i = 0; i < sub; i++) {
s.v[0] += (k2 * (tx - s.p[0]) - c2 * s.v[0]) * h;
s.v[1] += (k2 * (ty - s.p[1]) - c2 * s.v[1]) * h;
s.p[0] += s.v[0] * h; s.p[1] += s.v[1] * h;
}
const o = [s.p[0] - a[0], s.p[1] - a[1]];
clampLen(o, cfg.max * Math.max(1, g));
this.out[k] = o;
}
this.out.gain = 1;
// pull each fringe strand towards the average of its neighbours so the fringe moves
// as one sheet with a little variation, instead of strands splitting apart
const O = this.out.strands;
for (let pass = 0; pass < HAIR_TUNE.bind; pass++) for (let j = 1; j < 4; j++) {
const snap = O.slice(0, FRINGE).map(o => [...o[j]]);
for (let i = 0; i < FRINGE; i++) {
const l = snap[Math.max(0, i - 1)], r = snap[Math.min(FRINGE - 1, i + 1)];
for (const a of [0, 1]) O[i][j][a] = snap[i][a] * 0.5 + (l[a] + r[a]) * 0.25;
}
}
// Tassels: a two-joint angular pendulum. The old verlet chain was pulled back to its
// drawn shape every substep, which made it buzz (~10 direction changes/s, 1deg swing).
// Here each joint is a slow damped spring (~0.7 Hz) driven by the smoothed acceleration
// of the knot, so it swings in long arcs and lags behind the head like the hair does.
for (const ch of this.chains) {
const A = tasselAnchor(ch.t, P, this.out, [0, 0]);
if (!ch.st) ch.st = { th: [0, 0], w: [0, 0], pos: [...A], vel: [0, 0], acc: [0, 0] };
const st = ch.st, T = TASSEL_TUNE;
// knot velocity / acceleration, low-passed so spring overshoot of the head doesn't jitter it
const vel = [(A[0] - st.pos[0]) / Math.max(dt, 1e-3), (A[1] - st.pos[1]) / Math.max(dt, 1e-3)];
const kf = 1 - Math.exp(-dt * T.smooth);
const acc = [(vel[0] - st.vel[0]) / Math.max(dt, 1e-3), (vel[1] - st.vel[1]) / Math.max(dt, 1e-3)];
st.acc = [st.acc[0] + (acc[0] - st.acc[0]) * kf, st.acc[1] + (acc[1] - st.acc[1]) * kf];
st.vel = [st.vel[0] + (vel[0] - st.vel[0]) * kf, st.vel[1] + (vel[1] - st.vel[1]) * kf];
st.pos = [...A];
// perpendicular to the hanging direction: pushes the pendulum sideways
const nrm = [-ch.dir[1], ch.dir[0]];
const push = -(st.acc[0] * nrm[0] + st.acc[1] * nrm[1]) / (ch.L1 + ch.L2) * T.inertia;
const wind = (Math.sin(this.time * 0.9 + ch.t.pivot[0]) * 0.6 + Math.sin(this.time * 0.37 + ch.t.pivot[1]) * 0.4) * T.wind;
const target = -roll * T.hang + wind; // keeps hanging down when the head tilts
const w1 = 2 * Math.PI * T.freq / Math.sqrt(Math.max(0.4, g)), w2 = w1 * 1.35;
for (let i = 0; i < sub; i++) {
const a1 = -w1 * w1 * (st.th[0] - target) - 2 * T.zeta * w1 * st.w[0] + push;
st.w[0] += a1 * h; st.th[0] += st.w[0] * h;
// the lower half follows the upper one with its own lag (a soft whip at the tip)
const a2 = -w2 * w2 * (st.th[1] - st.th[0]) - 2 * T.zeta * w2 * st.w[1] + push * 0.4 + a1 * 0.5;
st.w[1] += a2 * h; st.th[1] += st.w[1] * h;
}
st.th[0] = Math.max(-T.max, Math.min(T.max, st.th[0]));
st.th[1] = Math.max(-T.max * 1.4, Math.min(T.max * 1.4, st.th[1]));
ch.phi = [st.th[0], st.th[1]];
// joint positions for skinning and the debug overlay
const d1 = rotV(ch.dir, st.th[0]), d2 = rotV(ch.dir, st.th[1]);
const p1 = [A[0] + d1[0] * ch.L1, A[1] + d1[1] * ch.L1];
ch.pts = [[...A], p1, [p1[0] + d2[0] * ch.L2, p1[1] + d2[1] * ch.L2]];
ch.anchor = A;
}
this.time += dt;
return this.out;
}
}
return { Physics };
}