3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 addonfor 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.jsindex 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.jsindex 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, sconst 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/);+});