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.

feat(motion): solve the IK chain through one shared solver

nirholasf4ce17edd160
diff --git a/packages/motion/src/rig/ik.js b/packages/motion/src/rig/ik.js
index 164682393..94838307c 100644
--- a/packages/motion/src/rig/ik.js
+++ b/packages/motion/src/rig/ik.js
@@ -13,8 +13,11 @@
// last step is the difference between a solved limb and a broken-looking one.
import {
+ IDENTITY,
clamp,
orientQuat,
+ qBetween,
+ qSlerp,
qAxisAngle,
qConj,
qMul,
@@ -93,6 +96,40 @@ export function solveTwoBone(pose, chain, target, pole, reach) {
};
}
+/** Longest the clavicle is allowed to swing toward a target, in degrees. */
+const MAX_CLAVICLE_ASSIST = 38;
+
+/**
+ * Let the shoulder girdle help.
+ *
+ * An arm is not two bones hanging off a fixed socket: the clavicle protracts,
+ * elevates, and rotates, and that is worth ten to fifteen centimetres of reach
+ * plus most of what makes a reach read as a whole body reaching. Without it the
+ * reference rig cannot put a wrist on its own thigh, which is not a limit of
+ * human anatomy, it is a limit of pretending the shoulder is bolted down.
+ *
+ * The assist only engages past a comfort radius and scales in from there, so a
+ * gesture inside easy reach keeps a still, quiet shoulder line.
+ */
+function assistWithClavicle(pose, side, target) {
+ const clavicle = `${side}Shoulder`;
+ if (!hasBone(clavicle)) return;
+ const shoulder = pose.worldPos(`${side}Arm`);
+ const reach = boneLength(`${side}Arm`) + boneLength(`${side}ForeArm`);
+ const distance = vLen(vSub(target, shoulder));
+ const comfort = reach * 0.82;
+ if (distance <= comfort) return;
+ const assist = clamp((distance - comfort) / (reach * 0.45), 0, 1);
+
+ // Aim the clavicle a fraction of the way from where it points to where the
+ // target is, which both carries the socket toward the target and gives the
+ // shoulder the rise a real reach has.
+ const from = pose.worldDir(clavicle);
+ const to = vNorm(vSub(target, pose.worldPos(clavicle)));
+ const swing = qSlerp(IDENTITY, qBetween(from, to), assist * (MAX_CLAVICLE_ASSIST / 90));
+ pose.setWorldQuat(clavicle, qMul(swing, pose.worldQuat(clavicle)));
+}
+
/**
* Place a `side` wrist at a world point with a natural elbow, then orient the
* hand.
@@ -108,7 +145,9 @@ export function solveTwoBone(pose, chain, target, pole, reach) {
*
* @param {import('./pose.js').Pose} pose mutated in place
* @param {'Left'|'Right'} side
- * @param {{ wrist: number[], fingers?: number[], palm?: number[], pole?: number[], reach?: number }} spec
+ * @param {{ wrist: number[], fingers?: number[], palm?: number[], pole?: number[], reach?: number, clavicle?: boolean }} spec
+ * `clavicle` defaults to true and lets the shoulder girdle assist a long
+ * reach; pass false when a caller is driving the clavicle itself.
* @returns {import('./pose.js').Pose} the same pose
*/
export function solveArm(pose, side, spec) {
@@ -118,6 +157,8 @@ export function solveArm(pose, side, spec) {
const outSign = side === 'Right' ? -1 : 1;
const pole = spec.pole ?? [outSign * 0.42, -1, -0.3];
+ if (spec.clavicle !== false) assistWithClavicle(pose, side, spec.wrist);
+
const solved = solveTwoBone(
pose,
{ upper, lower, end: hand },
diff --git a/packages/motion/src/solve.js b/packages/motion/src/solve.js
index 6b306d78a..1d1775653 100644
--- a/packages/motion/src/solve.js
+++ b/packages/motion/src/solve.js
@@ -237,19 +237,23 @@ function placeArm(pose, side, spec) {
const palm = spec.palm ? bodyDirection(pose, spec.palm, side) : null;
const fingers = spec.point ? bodyDirection(pose, spec.point, side) : null;
- const shoulder = pose.worldPos(`${side}Arm`);
- const distance = vLen(vSub(wrist, shoulder));
- const reachable = distance <= (boneLength(`${side}Arm`) + boneLength(`${side}ForeArm`)) * 0.99;
-
solveArm(pose, side, {
wrist,
palm,
fingers,
...(pole ? { pole } : {}),
});
- return reachable;
+
+ // Measured after the solve, not before: the clavicle assist moves the socket
+ // toward a long target, so a pre-solve distance check reports misses the arm
+ // went on to make. A few millimetres short is the soft-elbow cap doing its
+ // job, not a failure, so only a real shortfall is worth telling anyone about.
+ return vLen(vSub(pose.worldPos(`${side}Hand`), wrist)) <= REACH_SLACK;
}
+/** How far short of a target a wrist may land before it counts as out of reach. */
+const REACH_SLACK = 0.02;
+
function poleDirection(pose, side, name) {
const spec = ELBOW_POLES[name];
const outward = side === 'Left' ? spec.out : -spec.out;