Skip to content

3D engine that AI agents drive

Refuse NaN rest values, malformed custom solvers and bad aim joints in skeleton poses (#2505)

Nguyen Xuan An567223ef95c2
diff --git a/changes/2505.md b/changes/2505.md
new file mode 100644
index 00000000..70caa1bf
--- /dev/null
+++ b/changes/2505.md
@@ -0,0 +1 @@
+Skeleton poses refuse rig rest values that are NaN or a zero quaternion, custom solvers without joints or solve, and an aim solver whose joints is not a list.
diff --git a/changes/2505.size.md b/changes/2505.size.md
new file mode 100644
index 00000000..7c1e0db6
--- /dev/null
+++ b/changes/2505.size.md
@@ -0,0 +1 @@
+- scene:agent-scene+lazy: three input guards in createSkeletonPose (NaN or zero-quaternion rest values, custom solver shape, aim joints type) stop a silent NaN pose and two undefined-property crashes; 209 bytes gzip.
diff --git a/docs/skeleton-pose.md b/docs/skeleton-pose.md
index 416dd06a..4f7bdb5c 100644
--- a/docs/skeleton-pose.md
+++ b/docs/skeleton-pose.md
@@ -139,3 +139,4 @@ root rather than of the lower leg, so two-bone IK refuses them with an error; it
- Clip layers and masks are code only. Recipes and imported assets get IK through MCP with [`motion.ik`](agent-motion.md#inverse-kinematics).
- The [animation mixer](https://crucible.codepawl.com/animation-mixer.md) works on rigid part transforms and has no layers, masks or IK. Use this addon
for skinned rigs.
+- `createSkeletonPose` refuses a rig joint whose rest translation or rotation is NaN, or whose rotation is the zero quaternion, and a custom solver whose `create` returns no `joints` list or `solve` function.
diff --git a/src/skeleton-pose.js b/src/skeleton-pose.js
index d6775535..67012cdd 100644
--- a/src/skeleton-pose.js
+++ b/src/skeleton-pose.js
@@ -332,12 +332,29 @@ function bendWarnings(solver, state, prepared) {
return warnings;
}
+/** A NaN or zero-quaternion rest value poses its joint and everything below as NaN, with no error. */
+function checkRestValues(joints) {
+ joints.forEach(({ name, translation, rotation, scale }) => {
+ const finite = values => Array.from(values ?? []).every(Number.isFinite);
+ if (!finite(translation) || !finite(rotation) || !finite(scale?.slice(0, 1)) || !Math.hypot(...rotation)) {
+ throw new RangeError(`Pose rig joint ${name} needs finite translation and scale and a nonzero rotation, such as [0, 0, 0, 1].`);
+ }
+ });
+}
+
+function checkedCustomSolver(created, jointCount, label) {
+ const validJoints = Array.isArray(created?.joints) && created.joints.every(index => index >= 0 && index < jointCount);
+ if (!validJoints || typeof created.solve !== 'function') throw new TypeError(`${label} create must return { joints, solve } with rig joint indices.`);
+ return created;
+}
+
function createSolver(definition, position, prepared, resolveJoint) {
const label = `IK ${position}`;
+ if (!definition || typeof definition !== 'object') throw new TypeError(`${label} must be an object with a type.`);
const weight = weightFunction(definition?.weight ?? 1, `${label} weight`);
if (definition?.type === 'custom') {
if (typeof definition.create !== 'function') throw new TypeError(`${label} type custom needs create(prepared, resolveJoint, label) => { joints, solve(time, context, weight) }.`);
- return { type: 'custom', label, weight, ...definition.create(prepared, resolveJoint, label) };
+ return { type: 'custom', label, weight, ...checkedCustomSolver(definition.create(prepared, resolveJoint, label), prepared.joints.length, label) };
}
const solverType = definition?.type === 'ik' ? 'chain' : definition?.type === 'spline_ik' ? 'spline' : definition?.type;
if (solverType !== 'spline' && typeof definition?.target !== 'function') checkedVector(definition?.target, `${label} target`);
@@ -363,6 +380,7 @@ function createSolver(definition, position, prepared, resolveJoint) {
}
if (definition.type === 'aim') {
const names = definition.joints ?? (definition.joint === undefined ? [] : [definition.joint]);
+ if (!Array.isArray(names)) throw new TypeError(`${label} joints must be a list of joint names.`);
if (!names.length) throw new TypeError(`${label} needs joint, or joints listed from the base of the chain to the aiming joint.`);
const joints = names.map(name => resolveJoint(name, label));
joints.slice(1).forEach((joint, slot) => {
@@ -974,6 +992,7 @@ export function createAssetPose(asset, { layers = [], ik = [] } = {}) {
export function createSkeletonPose({ skin, rig = skin && createRigFromSkin(skin), meshWorldMatrix, layers = [], ik = [] } = {}) {
if (!rig) throw new TypeError('createSkeletonPose needs a skin or a rig.');
validateRigJoints(rig.joints, 'Pose');
+ checkRestValues(rig.joints);
if (!Array.isArray(layers) || !Array.isArray(ik)) throw new TypeError('layers and ik must be arrays.');
const prepared = prepareRigGeometry(rig, 'Pose');
const resolveJoint = jointResolver(rig, prepared);
diff --git a/tests/skeleton-pose-input-guards.test.js b/tests/skeleton-pose-input-guards.test.js
index b961eeee..e22ef1ff 100644
--- a/tests/skeleton-pose-input-guards.test.js
+++ b/tests/skeleton-pose-input-guards.test.js
@@ -25,3 +25,25 @@ test('a morph-only additive layer refuses a reference time that is not finite, s
const morphs = morphClipFromGltfAnimation(dance, { loop: true });
assert.throws(() => createAssetPose(asset, { layers: [{ morphs, additive: true, reference: Number.NaN }] }), /reference/);
});
+
+test('a rig joint with a NaN translation, a NaN rotation or a zero quaternion is refused instead of posing NaN', () => {
+ const withBroken = patch => ({ joints: [restJoint('a', -1, 0), { ...restJoint('b', 0, 1), ...patch }] });
+ assert.throws(() => createSkeletonPose({ rig: withBroken({ translation: [0, Number.NaN, 0] }) }), /joint b needs/);
+ assert.throws(() => createSkeletonPose({ rig: withBroken({ rotation: [Number.NaN, 0, 0, 1] }) }), /joint b needs/);
+ assert.throws(() => createSkeletonPose({ rig: withBroken({ rotation: [0, 0, 0, 0] }) }), /joint b needs/);
+ assert.throws(() => createSkeletonPose({ rig: withBroken({ scale: [Number.NaN, 1, 1] }) }), /joint b needs/);
+ assert.doesNotThrow(() => createSkeletonPose({ rig: withBroken({}) }));
+});
+
+test('a custom solver whose create returns no joints list or no solve function is refused with a message naming both', () => {
+ const custom = created => ({ rig: chainRig, ik: [{ type: 'custom', create: () => created }] });
+ assert.throws(() => createSkeletonPose(custom({ solve() {} })), /joints, solve/);
+ assert.throws(() => createSkeletonPose(custom({ joints: [1] })), /joints, solve/);
+ assert.throws(() => createSkeletonPose(custom({ joints: [9], solve() {} })), /joints, solve/);
+ assert.equal(createSkeletonPose(custom({ joints: [1], solve() {} })).solvedJointNames[0], 'b');
+});
+
+test('an aim solver with joints that is not a list, or a null IK entry, says what to pass', () => {
+ assert.throws(() => createSkeletonPose({ rig: chainRig, ik: [{ type: 'aim', joints: 'b', target: [0, 1, 0] }] }), /joints must be a list/);
+ assert.throws(() => createSkeletonPose({ rig: chainRig, ik: [null] }), /IK 0 must be an object/);
+});