3D engine that AI agents drive
Add Follow Path, Clamp To, Shrinkwrap, Damped Track, Pivot, Maintain Volume and Armature constraints (#691) (#738)
Nguyen Xuan An399ca7d63baf
diff --git a/changes/691.md b/changes/691.mdnew file mode 100644index 00000000..5e2e4cb3--- /dev/null+++ b/changes/691.md@@ -0,0 +1 @@+- Add `maintain_volume`, `damped_track`, `pivot`, `follow_path`, `clamp_to`, `shrinkwrap` and `armature` motion constraints, plus `floor` `useRotation` and `copy_transforms`/`transformation` `mix` modes (#691).diff --git a/changes/691.size.md b/changes/691.size.mdnew file mode 100644index 00000000..5872ef36--- /dev/null+++ b/changes/691.size.md@@ -0,0 +1,3 @@+- scene:agent-scene+lazy: `maintain_volume`, `damped_track`, `pivot`, `follow_path`, `clamp_to`, `shrinkwrap` and `armature` constraints in `src/node-constraints.js` (#691).+- entry:agent-asset: `maintain_volume`, `damped_track`, `pivot`, `follow_path`, `clamp_to`, `shrinkwrap` and `armature` constraints in `src/node-constraints.js` (#691).+- goal:agent-scene: 38 B gzip for the 7 new constraint names in `motionConstraints` in `agent-scene-capabilities.js` (#691).diff --git a/docs/agent-motion.md b/docs/agent-motion.mdindex 283b91ed..36c5e9d6 100644--- a/docs/agent-motion.md+++ b/docs/agent-motion.md@@ -279,15 +279,22 @@ own transform under its parent.| `limit_rotation` | `x`, `y`, `z` as `[min, max]` degrees, `space` | Clamp the Euler angles per axis || `track_to` | `target`, `trackAxis` (default `-z`), `upAxis` (default `y`), `worldUp` (default `[0, 1, 0]`) | Turn the node so its track axis points at the target and its up axis leans toward `worldUp`. Blender's up is Z, so its numbers match with `worldUp: [0, 0, 1]` || `child_of` | `target`, `inverse` (`rest` or `none`) | The node follows the target: its world matrix becomes target * inverse * its own. `rest` uses the inverse of the target's rest matrix, so the node stays put until the target moves; Blender's default is `none` |-| `floor` | `target`, `axis` (default `+y`), `offset` | Keep the node on the positive side of the plane through the target, along `axis`, plus `offset` |+| `floor` | `target`, `axis` (default `+y`), `offset`, `useRotation` | Keep the node on the positive side of the plane through the target, along `axis` (rotated by the target when `useRotation` is true), plus `offset` |-| `copy_transforms` | `target` | The node's world matrix becomes the target's |+| `copy_transforms` | `target`, `mix` (`replace`, `before`, `after`) | The node's world matrix becomes or multiplies with the target's || `limit_distance` | `target`, `distance`, `mode` (`inside` default, `outside`, `surface`) | Keep the node's world position inside, outside or on the sphere of that radius around the target || `limit_scale` | `x`, `y`, `z` as `[min, max]` above 0, `space` | Clamp the scale per axis || `stretch_to` | `target`, `restLength` (default: the rest distance), `volume` (`xz` default, `x`, `z`, `none`), `bulge` (0 to 4, default 1), `worldUp` | Aim +y at the target, scale y by distance over `restLength` and x and z by that ratio to the power of minus `bulge` (its square root for `xz`). Z leans toward `worldUp` || `locked_track` | `target`, `trackAxis` (default `+y`), `lockAxis` (default `z`) | Turn only about the node's own lock axis so the track axis points toward the target |-| `transformation` | `target`, `source`, `destination` (`translation`, `rotation` or `scale`), `map` (the source axis for each destination x, y, z), `fromMin`, `fromMax` (per source axis), `toMin`, `toMax` (per destination axis), `space` | The target's channel, clamped to its range, sets the node's channel over its range. Rotation is Euler degrees |+| `transformation` | `target`, `source`, `destination` (`translation`, `rotation` or `scale`), `map` (the source axis for each destination x, y, z), `fromMin`, `fromMax` (per source axis), `toMin`, `toMax` (per destination axis), `mix` (`replace`, `add`, `multiply`), `space` | The target's channel, clamped to its range, sets, adds to or multiplies the node's channel over its range. Rotation is Euler degrees || `action` | `target`, `source`, `axis`, `min`, `max`, `destination`, `keys` (2 to 16 of `{ at, value }`, `at` 0 to 1 rising), `space` | Read the curve where the target's channel sits between `min` and `max`; its value sets the node's channel |+| `maintain_volume` | `freeAxis` (default `y`), `volume` (default `1`), `space` | Scale the two non-free axes by `sqrt(volume / freeScale)` to preserve volume |+| `damped_track` | `target`, `trackAxis` (default `+y`) | Rotate the node by the shortest arc that aligns `trackAxis` with the vector to the target |+| `pivot` | `target` (optional), `offset` (default `[0, 0, 0]`) | Orbit the node's translation around `target + offset` (or rest position + `offset`) by its rotation |+| `follow_path` | `points` (2 to 64 `[x, y, z]`), `closed`, `followCurve`, `forwardAxis` (default `-z`), `upAxis` (default `y`), `offset`, `duration` (default `1`) | Move the node along the Catmull-Rom curve over `duration`, optionally orienting `forwardAxis` along the tangent |+| `clamp_to` | `points` (2 to 64 `[x, y, z]`), `mainAxis` (`auto`, `x`, `y`, `z`), `cyclic` | Place the node along the curve where its coordinate on `mainAxis` sits within the curve's span |+| `shrinkwrap` | `target`, `mode` (`nearest`, `project`, `surface`), `projectAxis` (default `-y`), `distance` (default `0`) | Snap the node onto the target's bounding surface or along `projectAxis` at `distance` |+| `armature` | `targets` (1 to 8 of `{ target, weight }`) | Blend `child_of` transforms from multiple target nodes by their weights |Over MCP, the seven newest types (`copy_transforms` to `action`) take `node`, `type` and `args`, an object holding every otherfield above (`target`, `influence` and the type's own); the validator names the allowed fields when one is wrong. Direct fieldsdiff --git a/docs/parity.md b/docs/parity.mdindex 83a646b6..57af54eb 100644--- a/docs/parity.md+++ b/docs/parity.md@@ -145,29 +145,29 @@ To move to a new Blender release, run `node scripts/parity-manual-snapshot.mjs`.| Animation & Rigging > Constraints > Transform > Copy Location Constraint | partial | `copy_location` in `motion.constraints`: axes, invert, offset, world or local space, influence. Matches Blender where tested. | [agent-motion-constraints](../tests/agent-motion-constraints.test.js), [src/expression.js](../src/expression.js) | #58, #98 || Animation & Rigging > Constraints > Transform > Copy Rotation Constraint | partial | `copy_rotation`: Euler axes, invert, replace or add, world or local. World matrices match Blender 5.2 in 2 cases. | [blender-constraints](../tests/blender-constraints.test.js) | #58 || Animation & Rigging > Constraints > Transform > Copy Scale Constraint | partial | `copy_scale`: axes and offset, world or local. | [agent-motion-constraints](../tests/agent-motion-constraints.test.js) | #58 |-| Animation & Rigging > Constraints > Transform > Copy Transforms Constraint | partial | `copy_transforms`: the node takes the target world matrix; influence blends it. No mix modes. | [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js) | #595 |+| Animation & Rigging > Constraints > Transform > Copy Transforms Constraint | partial | `copy_transforms`: the node takes or multiplies (`mix`: `replace`, `before`, `after`) the target world matrix; influence blends it. | [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js) | #595, #691 || Animation & Rigging > Constraints > Transform > Limit Distance Constraint | partial | `limit_distance`: `distance` and `mode` inside, outside or surface, from the target origin. The distance is required, not set from the first frame. | [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js) | #595 || Animation & Rigging > Constraints > Transform > Limit Location Constraint | partial | `limit_location`: per-axis clamp, world or local. | [agent-motion-constraints](../tests/agent-motion-constraints.test.js) | #58 || Animation & Rigging > Constraints > Transform > Limit Rotation Constraint | partial | `limit_rotation` constraint and per-axis `limits` on two-bone IK joints, reported in `motionIk`. Matches Blender 5.2. | [blender-constraints](../tests/blender-constraints.test.js), [skeleton-pose-limits](../tests/skeleton-pose-limits.test.js) | #58 || Animation & Rigging > Constraints > Transform > Limit Scale Constraint | partial | `limit_scale`: per-axis clamp, world or local; the minimum must be above 0. | [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js) | #595 |-| Animation & Rigging > Constraints > Transform > Maintain Volume Constraint | missing | No constraint. | | |-| Animation & Rigging > Constraints > Transform > Transformation Constraint | partial | `transformation`: maps a target translation, rotation or scale range onto the node, per axis, clamped. Replace only, no add or multiply. | [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js) | #595 |+| Animation & Rigging > Constraints > Transform > Maintain Volume Constraint | partial | `maintain_volume`: scales the two non-free axes around `freeAxis` (`x`, `y` or `z`) to keep `volume`, in world or local space. | [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js) | #691 |+| Animation & Rigging > Constraints > Transform > Transformation Constraint | partial | `transformation`: maps a target translation, rotation or scale range onto the node, per axis, clamped, with `mix` (`replace`, `add`, `multiply`). | [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js) | #595, #691 || Animation & Rigging > Constraints > Transform > Transform Cache Constraint | missing | No constraint. | | |-| Animation & Rigging > Constraints > Tracking > Clamp To Constraint | missing | No constraint. | | |-| Animation & Rigging > Constraints > Tracking > Damped Track Constraint | partial | Aim IK turns one joint toward a target. It is not a general constraint. | [agent-motion-ik](../tests/agent-motion-ik.test.js) | #58 |+| Animation & Rigging > Constraints > Tracking > Clamp To Constraint | partial | `clamp_to`: maps the node position along `mainAxis` (`auto`, `x`, `y`, `z`) onto a Catmull-Rom curve (`points`, `cyclic`). | [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js) | #691 |+| Animation & Rigging > Constraints > Tracking > Damped Track Constraint | partial | `damped_track` in `motion.constraints` turns the node by the shortest swing so `trackAxis` aims at the target; Aim IK also turns joints. | [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js), [agent-motion-ik](../tests/agent-motion-ik.test.js) | #58, #691 || Animation & Rigging > Constraints > Tracking > Inverse Kinematics Constraint | partial | Two-bone, multi-bone `chain` (CCD with `pole`, `poleAngle`, `stretch` and joint `limits`) and `aim` IK, in code and in `motion.ik`. | [agent-motion-ik](../tests/agent-motion-ik.test.js), [agent-asset-ik](../tests/agent-asset-ik.test.js), [skeleton-pose](../tests/skeleton-pose.test.js) | #58, #689 || Animation & Rigging > Constraints > Tracking > Locked Track Constraint | partial | `locked_track`: turns only about the node's own lock axis so the track axis aims at the target as near as it can. | [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js) | #595 || Animation & Rigging > Constraints > Tracking > Spline IK Constraint | partial | `spline` in `addons/skeleton-pose` and `motion.ik`: fits a bone chain along a Catmull-Rom curve (points or control nodes) with optional arc-length `stretch`. | [skeleton-pose](../tests/skeleton-pose.test.js), [agent-motion-ik](../tests/agent-motion-ik.test.js) | #689 || Animation & Rigging > Constraints > Tracking > Stretch To Constraint | partial | `stretch_to`: aims +y and stretches it to the distance over `restLength`; `volume` and `bulge` keep volume on x and z. The up axis is fixed to z leaning toward `worldUp`. | [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js) | #595 || Animation & Rigging > Constraints > Tracking > Track To Constraint | partial | `track_to` on nodes: track and up axes, `worldUp`. Matches Blender 5.2 in 2 cases. Cameras still use camera paths. | [blender-constraints](../tests/blender-constraints.test.js), [camera-path](../tests/camera-path.test.js) | #58 || Animation & Rigging > Constraints > Relationship > Action Constraint | partial | `action`: a keyed curve of up to 16 keys, read where a target channel sits between `min` and `max`, sets the node translation, rotation or scale. No stored actions or frame ranges. | [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js) | #595 |-| Animation & Rigging > Constraints > Relationship > Armature Constraint | missing | No constraint. | | |+| Animation & Rigging > Constraints > Relationship > Armature Constraint | partial | `armature`: blends up to 8 `{ target, weight }` rest-relative transforms onto the constrained node. | [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js) | #691 || Animation & Rigging > Constraints > Relationship > Child Of Constraint | partial | `child_of` in `motion.constraints`: follows a moving target from its rest inverse (or none), with an influence that can be animated by an expression. Matches Blender 5.2 in 2 cases. No per-channel switches. | [blender-constraints](../tests/blender-constraints.test.js), [scene-graph](../tests/scene-graph.test.js) | #58 |-| Animation & Rigging > Constraints > Relationship > Floor Constraint | partial | `floor`: keeps a node on one side of a plane through the target, axis and offset. Matches Blender 5.2 for the Z floor with an offset; no `use_rotation`. | [blender-constraints](../tests/blender-constraints.test.js) | #58 |-| Animation & Rigging > Constraints > Relationship > Follow Path Constraint | partial | Camera paths only. | [camera-path](../tests/camera-path.test.js) | |+| Animation & Rigging > Constraints > Relationship > Floor Constraint | partial | `floor`: keeps a node on one side of a plane through the target, axis, offset and optional `useRotation`. Matches Blender 5.2 for the Z floor with an offset. | [blender-constraints](../tests/blender-constraints.test.js), [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js) | #58, #691 |+| Animation & Rigging > Constraints > Relationship > Follow Path Constraint | partial | `follow_path` in `motion.constraints` moves a node along a Catmull-Rom curve (`points`, `closed`, `followCurve`, `forwardAxis`, `upAxis`, `offset`, `duration`), plus camera paths. | [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js), [camera-path](../tests/camera-path.test.js) | #691 || Animation & Rigging > Constraints > Relationship > Geometry Attribute Constraint | missing | No constraint. | | |-| Animation & Rigging > Constraints > Relationship > Pivot Constraint | missing | No constraint. | | |-| Animation & Rigging > Constraints > Relationship > Shrinkwrap Constraint | partial | `addons/surface-attachment` binds points to a surface in code. | [surface-attachment](../tests/surface-attachment.test.js) | |+| Animation & Rigging > Constraints > Relationship > Pivot Constraint | partial | `pivot`: orbits a node around `target` + `offset` (or rest position + `offset`) as it rotates. | [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js) | #691 |+| Animation & Rigging > Constraints > Relationship > Shrinkwrap Constraint | partial | `shrinkwrap` in `motion.constraints` snaps a node to a target surface (`nearest`, `project`, `surface`, `projectAxis`, `distance`), and `addons/surface-attachment` binds points to a mesh in code. | [agent-motion-constraints-more](../tests/agent-motion-constraints-more.test.js), [surface-attachment](../tests/surface-attachment.test.js) | #691 || Animation & Rigging > Actions | partial | Clips, weights and crossfades in code. An asset through MCP plays several clips as masked layers at motion time; there are no crossfades or state machines there. | [animation-mixer](../tests/animation-mixer.test.js), [agent-asset-layers](../tests/agent-asset-layers.test.js) | #59 || Animation & Rigging > Drivers | partial | `motion.drivers`: a node component or material property from a bounded expression over time and other nodes. No custom properties, shape keys or variables. | [agent-motion-constraints](../tests/agent-motion-constraints.test.js) | #58 || Animation & Rigging > Markers | partial | Recipe timeline shots are named, listed with their start second in job metrics, and cut with their own camera, motion start and an optional dip through black (no strips, layers or crossfades; the video sequence editor is a non-goal). No markers inside a shot and no events. | [film-timeline](../tests/film-timeline.test.js) | #60 |diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.jsindex 0710da53..4945350b 100644--- a/src/agent-scene-capabilities.js+++ b/src/agent-scene-capabilities.js@@ -274,7 +274,7 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({notes: 'Region (mesh tag): target faces only. One relation per axis, no loops, mesh nodes only. A relation sets translation on its axes. set-node with relations [] removes them.',}),rigging: Object.freeze({ presets: Object.freeze(['humanoid', 'quadruped']), maxArmatures: 16, maxBones: 128, maxInfluences: 4, weights: 'bone-distance' }),- motionConstraints: Object.freeze(['copy_location', 'copy_rotation', 'copy_scale', 'limit_location', 'limit_rotation', 'track_to', 'child_of', 'floor', 'copy_transforms', 'limit_distance', 'limit_scale', 'stretch_to', 'locked_track', 'transformation', 'action']),+ motionConstraints: Object.freeze(['copy_location', 'copy_rotation', 'copy_scale', 'limit_location', 'limit_rotation', 'track_to', 'child_of', 'floor', 'copy_transforms', 'limit_distance', 'limit_scale', 'stretch_to', 'locked_track', 'transformation', 'action', 'maintain_volume', 'damped_track', 'pivot', 'follow_path', 'clamp_to', 'shrinkwrap', 'armature']),motionDrivers: Object.freeze({ maxDrivers: 32, maxConstraints: 32, maxExpressionParts: 64, maxExpressionDepth: 8 }),// Recipe physics: Rapier (an optional peer) bakes bodies on nodes offline; playback is a seek into the bake.physics: Object.freeze({diff --git a/src/node-constraints.js b/src/node-constraints.jsindex a718e4b9..7a4df530 100644--- a/src/node-constraints.js+++ b/src/node-constraints.js@@ -31,14 +31,21 @@ const CONSTRAINT_FIELDS = {limit_rotation: ['x', 'y', 'z', 'space'],track_to: ['target', 'trackAxis', 'upAxis', 'worldUp'],child_of: ['target', 'inverse'],- floor: ['target', 'axis', 'offset'],- copy_transforms: ['target'],+ floor: ['target', 'axis', 'offset', 'useRotation'],+ copy_transforms: ['target', 'mix'],limit_distance: ['target', 'distance', 'mode'],limit_scale: ['x', 'y', 'z', 'space'],stretch_to: ['target', 'restLength', 'volume', 'bulge', 'worldUp'],locked_track: ['target', 'trackAxis', 'lockAxis'],- transformation: ['target', 'source', 'destination', 'map', 'fromMin', 'fromMax', 'toMin', 'toMax', 'space'],+ transformation: ['target', 'source', 'destination', 'map', 'fromMin', 'fromMax', 'toMin', 'toMax', 'mix', 'space'],action: ['target', 'source', 'axis', 'min', 'max', 'destination', 'keys', 'space'],+ maintain_volume: ['freeAxis', 'volume', 'space'],+ damped_track: ['target', 'trackAxis'],+ pivot: ['target', 'offset'],+ follow_path: ['points', 'closed', 'followCurve', 'forwardAxis', 'upAxis', 'offset', 'duration'],+ clamp_to: ['points', 'mainAxis', 'cyclic'],+ shrinkwrap: ['target', 'mode', 'projectAxis', 'distance'],+ armature: ['targets'],};const PROPERTIES = ['translation', 'rotation', 'scale'];const MAX_ACTION_KEYS = 16;@@ -83,7 +90,7 @@ function influenceFrom(value, nodeIds, label) {return structuredClone(value);}-const ARGUMENT_TYPES = ['copy_transforms', 'limit_distance', 'limit_scale', 'stretch_to', 'locked_track', 'transformation', 'action'];+const ARGUMENT_TYPES = ['copy_transforms', 'limit_distance', 'limit_scale', 'stretch_to', 'locked_track', 'transformation', 'action', 'maintain_volume', 'damped_track', 'pivot', 'follow_path', 'clamp_to', 'shrinkwrap', 'armature'];// The newer types may carry their own fields in `args`, so the MCP schema stays small; they merge into the flat shape.function withArguments(input, label) {@@ -104,7 +111,7 @@ function normalizeConstraint(rawInput, position, movableIds, visibleIds) {knownKeys(input, [...COMMON_FIELDS, ...CONSTRAINT_FIELDS[input.type]], label);if (!movableIds.has(input.node)) throw new RangeError(`${label} node must be a node ID in this recipe; got ${JSON.stringify(input.node)}.`);const result = { type: input.type, node: input.node, influence: influenceFrom(input.influence, visibleIds, label) };- if (CONSTRAINT_FIELDS[input.type].includes('target')) {+ if (CONSTRAINT_FIELDS[input.type].includes('target') && (input.type !== 'pivot' || input.target !== undefined)) {if (!visibleIds.has(input.target)) throw new RangeError(`${label} target must be a node ID in this recipe; got ${JSON.stringify(input.target)}.`);if (input.target === input.node) throw new RangeError(`${label} target cannot be the constrained node itself.`);result.target = input.target;@@ -145,16 +152,27 @@ function normalizeConstraint(rawInput, position, movableIds, visibleIds) {case 'floor':result.axis = oneOf(input.axis, SIGNED_AXES, '+y', `${label} axis`);result.offset = input.offset === undefined ? 0 : bounded(input.offset, -MAX_COORDINATE, MAX_COORDINATE, `${label} offset`);+ if (input.useRotation !== undefined) {+ if (typeof input.useRotation !== 'boolean') throw new TypeError(`${label} useRotation must be a boolean.`);+ result.useRotation = input.useRotation;+ }break;default:- normalizeExtraConstraint(input, result, label);+ normalizeExtraConstraint(input, result, label, visibleIds);}return result;}-function normalizeExtraConstraint(input, result, label) {+function curvePathPoints(points, label) {+ denseArray(points, 64, `${label} points`);+ if (points.length < 2) throw new RangeError(`${label} points needs at least 2 points.`);+ return points.map((point, index) => valueFrom(point, 3, `${label} points[${index}]`));+}++function normalizeExtraConstraint(input, result, label, visibleIds) {switch (input.type) {case 'copy_transforms':+ result.mix = oneOf(input.mix, ['replace', 'before', 'after'], 'replace', `${label} mix`);break;case 'limit_distance':result.distance = bounded(input.distance, 0, MAX_COORDINATE, `${label} distance`);@@ -187,6 +205,51 @@ function normalizeExtraConstraint(input, result, label) {result[field] = input[field] === undefined ? [fallback, fallback, fallback] : valueFrom(input[field], 3, `${label} ${field}`);}if (result.fromMin.some((value, index) => value === result.fromMax[index])) throw new RangeError(`${label} fromMax must differ from fromMin on every axis.`);+ result.mix = oneOf(input.mix, ['replace', 'add', 'multiply'], 'replace', `${label} mix`);+ if (result.mix === 'multiply' && result.destination !== 'scale') throw new RangeError(`${label} mix multiply is only for scale destination.`);+ break;+ case 'maintain_volume':+ result.freeAxis = oneOf(input.freeAxis, AXES, 'y', `${label} freeAxis`);+ result.volume = input.volume === undefined ? 1 : bounded(input.volume, 0.001, 1000, `${label} volume`);+ break;+ case 'damped_track':+ result.trackAxis = oneOf(input.trackAxis, SIGNED_AXES, '+y', `${label} trackAxis`);+ break;+ case 'pivot':+ result.offset = input.offset === undefined ? [0, 0, 0] : valueFrom(input.offset, 3, `${label} offset`);+ break;+ case 'follow_path':+ result.points = curvePathPoints(input.points, label);+ if (input.closed !== undefined && typeof input.closed !== 'boolean') throw new TypeError(`${label} closed must be a boolean.`);+ if (input.followCurve !== undefined && typeof input.followCurve !== 'boolean') throw new TypeError(`${label} followCurve must be a boolean.`);+ result.closed = input.closed ?? false;+ result.followCurve = input.followCurve ?? false;+ result.forwardAxis = oneOf(input.forwardAxis, SIGNED_AXES, '-z', `${label} forwardAxis`);+ result.upAxis = oneOf(input.upAxis, AXES, 'y', `${label} upAxis`);+ if (result.forwardAxis.slice(1) === result.upAxis) throw new RangeError(`${label} forwardAxis and upAxis must be different axes.`);+ result.offset = input.offset === undefined ? 0 : bounded(input.offset, -MAX_COORDINATE, MAX_COORDINATE, `${label} offset`);+ result.duration = input.duration === undefined ? 1 : bounded(input.duration, 0.001, MAX_COORDINATE, `${label} duration`);+ break;+ case 'clamp_to':+ result.points = curvePathPoints(input.points, label);+ result.mainAxis = oneOf(input.mainAxis, ['auto', ...AXES], 'auto', `${label} mainAxis`);+ if (input.cyclic !== undefined && typeof input.cyclic !== 'boolean') throw new TypeError(`${label} cyclic must be a boolean.`);+ result.cyclic = input.cyclic ?? false;+ break;+ case 'shrinkwrap':+ result.mode = oneOf(input.mode, ['nearest', 'project', 'surface'], 'nearest', `${label} mode`);+ result.projectAxis = oneOf(input.projectAxis, SIGNED_AXES, '-y', `${label} projectAxis`);+ result.distance = input.distance === undefined ? 0 : bounded(input.distance, -MAX_COORDINATE, MAX_COORDINATE, `${label} distance`);+ break;+ case 'armature':+ denseArray(input.targets, 8, `${label} targets`);+ if (!input.targets.length) throw new RangeError(`${label} targets needs at least 1 target.`);+ result.targets = input.targets.map((entry, index) => {+ knownKeys(entry, ['target', 'weight'], `${label} targets[${index}]`);+ if (!visibleIds.has(entry.target)) throw new RangeError(`${label} targets[${index}] target must be a node ID in this recipe; got ${JSON.stringify(entry.target)}.`);+ if (entry.target === input.node) throw new RangeError(`${label} target cannot be the constrained node itself.`);+ return { target: entry.target, weight: entry.weight === undefined ? 1 : bounded(entry.weight, 0, 1, `${label} targets[${index}] weight`) };+ });break;default:normalizeActionConstraint(input, result, label);@@ -367,11 +430,23 @@ function transformation(owner, target, constraint) {const from = axisIndex(sourceAxis);const fraction = (source[from] - constraint.fromMin[from]) / (constraint.fromMax[from] - constraint.fromMin[from]);const clamped = Math.min(1, Math.max(0, fraction));- result[index] = constraint.toMin[index] + clamped * (constraint.toMax[index] - constraint.toMin[index]);+ const mapped = constraint.toMin[index] + clamped * (constraint.toMax[index] - constraint.toMin[index]);+ if (constraint.mix === 'add') result[index] += mapped;+ else if (constraint.mix === 'multiply') result[index] *= mapped;+ else result[index] = mapped;});writeChannel(owner, constraint.destination, result);}+function maintainVolume(owner, target, constraint) {+ const freeIndex = axisIndex(constraint.freeAxis);+ const freeScale = Math.max(NEAR_ZERO, owner.scale[freeIndex]);+ const sideScale = Math.sqrt(constraint.volume / freeScale);+ for (let index = 0; index < 3; index++) {+ if (index !== freeIndex) owner.scale[index] *= sideScale;+ }+}+/** The owner's channel follows a keyed curve, read where the target's channel sits between min and max. */function action(owner, target, constraint) {const value = channelOf(target, constraint.source)[axisIndex(constraint.axis)];@@ -387,7 +462,8 @@ function action(owner, target, constraint) {const FRAME_CONSTRAINTS = {copy_location: copyLocation, copy_rotation: copyRotation, copy_scale: copyScale,- limit_location: limitLocation, limit_rotation: limitRotation, limit_scale: limitScale, transformation, action,+ limit_location: limitLocation, limit_rotation: limitRotation, limit_scale: limitScale,+ transformation, action, maintain_volume: maintainVolume,};function perpendicularTo(direction) {@@ -464,6 +540,10 @@ function stretchTo(ownerWorld, targetWorld, constraint, restLength) {function floorConstraint(ownerWorld, targetWorld, constraint) {const normal = new Float64Array(3);normal[axisIndex(constraint.axis)] = signOf(constraint.axis);+ if (constraint.useRotation) {+ vec3.transformQuat(normal, normal, decompose(targetWorld).rotation);+ vec3.normalize(normal, normal);+ }const position = mat4.getTranslation(new Float64Array(3), ownerWorld);const planePoint = mat4.getTranslation(new Float64Array(3), targetWorld);const height = vec3.dot(vec3.subtract(new Float64Array(3), position, planePoint), normal);@@ -474,6 +554,148 @@ function floorConstraint(ownerWorld, targetWorld, constraint) {return lifted;}+/** Rotate the owner by the shortest arc that aligns its trackAxis with the vector to the target. */+function dampedTrack(ownerWorld, targetWorld, constraint) {+ const frame = decompose(ownerWorld);+ const wanted = vec3.subtract(new Float64Array(3), mat4.getTranslation(new Float64Array(3), targetWorld), frame.translation);+ if (vec3.length(wanted) < NEAR_ZERO) return ownerWorld;+ vec3.normalize(wanted, wanted);+ const localAxis = new Float64Array(3);+ localAxis[axisIndex(constraint.trackAxis)] = signOf(constraint.trackAxis);+ const currentAxis = vec3.transformQuat(new Float64Array(3), localAxis, frame.rotation);+ vec3.normalize(currentAxis, currentAxis);+ const turn = quat.rotationTo(new Float64Array(4), currentAxis, wanted);+ frame.rotation = quat.normalize(new Float64Array(4), quat.multiply(new Float64Array(4), turn, frame.rotation));+ return compose(frame);+}++/** Orbit the owner's translation around a pivot point (target + offset, or rest translation + offset) by its rotation. */+function pivotConstraint(ownerWorld, targetWorld, restOwnerWorld, constraint) {+ const frame = decompose(ownerWorld);+ const restFrame = decompose(restOwnerWorld);+ const base = targetWorld ? mat4.getTranslation(new Float64Array(3), targetWorld) : restFrame.translation;+ const pivotPoint = vec3.add(new Float64Array(3), base, constraint.offset);+ const arm = vec3.subtract(new Float64Array(3), frame.translation, pivotPoint);+ vec3.transformQuat(arm, arm, frame.rotation);+ vec3.add(frame.translation, pivotPoint, arm);+ return compose(frame);+}++function sampleCatmullRom(points, closed, parameter) {+ const count = points.length;+ const segments = closed ? count : count - 1;+ const wrapped = closed ? ((parameter % 1) + 1) % 1 : Math.min(1, Math.max(0, parameter));+ const scaled = wrapped * segments;+ const segment = Math.min(segments - 1, Math.floor(scaled));+ const localT = scaled - segment;+ const pick = index => {+ if (closed) return points[((index % count) + count) % count];+ if (index < 0) return points[0].map((v, i) => 2 * v - points[1][i]);+ if (index >= count) return points[count - 1].map((v, i) => 2 * v - points[count - 2][i]);+ return points[index];+ };+ const p0 = pick(segment - 1);+ const p1 = pick(segment);+ const p2 = pick(segment + 1);+ const p3 = pick(segment + 2);+ const t2 = localT * localT;+ const t3 = t2 * localT;+ const position = new Float64Array(3);+ const tangent = new Float64Array(3);+ for (let axis = 0; axis < 3; axis++) {+ position[axis] = 0.5 * ((2 * p1[axis]) + (-p0[axis] + p2[axis]) * localT + (2 * p0[axis] - 5 * p1[axis] + 4 * p2[axis] - p3[axis]) * t2 + (-p0[axis] + 3 * p1[axis] - 3 * p2[axis] + p3[axis]) * t3);+ tangent[axis] = 0.5 * ((-p0[axis] + p2[axis]) + 2 * (2 * p0[axis] - 5 * p1[axis] + 4 * p2[axis] - p3[axis]) * localT + 3 * (-p0[axis] + 3 * p1[axis] - 3 * p2[axis] + p3[axis]) * t2);+ }+ return { position, tangent };+}++function followPathConstraint(ownerWorld, constraint, time) {+ const parameter = (time / constraint.duration) + constraint.offset;+ const { position, tangent } = sampleCatmullRom(constraint.points, constraint.closed, parameter);+ const moved = mat4.clone(ownerWorld);+ moved.set(position, 12);+ if (!constraint.followCurve || vec3.length(tangent) < NEAR_ZERO) return moved;+ const targetPoint = vec3.add(new Float64Array(3), position, tangent);+ const targetMatrix = mat4.fromTranslation(new Float64Array(16), targetPoint);+ return trackTo(moved, targetMatrix, { trackAxis: constraint.forwardAxis, upAxis: constraint.upAxis, worldUp: [0, 1, 0] });+}++function clampToConstraint(ownerWorld, constraint) {+ const points = constraint.points;+ let axis = axisIndex(constraint.mainAxis);+ if (constraint.mainAxis === 'auto') {+ const spans = [0, 1, 2].map(index => {+ const coords = points.map(point => point[index]);+ return Math.max(...coords) - Math.min(...coords);+ });+ axis = spans.indexOf(Math.max(...spans));+ }+ const coords = points.map(point => point[axis]);+ const minCoord = Math.min(...coords);+ const maxCoord = Math.max(...coords);+ const ownerPos = mat4.getTranslation(new Float64Array(3), ownerWorld);+ const span = Math.max(NEAR_ZERO, maxCoord - minCoord);+ let fraction = (ownerPos[axis] - minCoord) / span;+ fraction = constraint.cyclic ? ((fraction % 1) + 1) % 1 : Math.min(1, Math.max(0, fraction));+ const { position } = sampleCatmullRom(points, constraint.cyclic, fraction);+ const moved = mat4.clone(ownerWorld);+ moved.set(position, 12);+ return moved;+}++function shrinkwrapConstraint(ownerWorld, targetWorld, constraint) {+ const ownerPos = mat4.getTranslation(new Float64Array(3), ownerWorld);+ const targetFrame = decompose(targetWorld);+ const moved = mat4.clone(ownerWorld);+ if (constraint.mode === 'project') {+ const dir = new Float64Array(3);+ dir[axisIndex(constraint.projectAxis)] = signOf(constraint.projectAxis);+ const axis = axisIndex(constraint.projectAxis);+ const sign = signOf(constraint.projectAxis);+ const surfaceCoord = targetFrame.translation[axis] - sign * (targetFrame.scale[axis] * 0.5 + constraint.distance);+ ownerPos[axis] = surfaceCoord;+ moved.set(ownerPos, 12);+ return moved;+ }+ const offset = vec3.subtract(new Float64Array(3), ownerPos, targetFrame.translation);+ const radius = Math.max(...targetFrame.scale) * 0.5 + constraint.distance;+ const dist = vec3.length(offset);+ if (dist < NEAR_ZERO) {+ moved[13] = targetFrame.translation[1] + radius;+ return moved;+ }+ vec3.scaleAndAdd(ownerPos, targetFrame.translation, offset, radius / dist);+ moved.set(ownerPos, 12);+ return moved;+}++function armatureConstraint(ownerWorld, worlds, restWorlds, indexById, constraint) {+ let totalWeight = 0;+ const translations = new Float64Array(3);+ const scales = new Float64Array(3);+ const accumRotation = new Float64Array(4);+ let firstQuat = null;+ for (const entry of constraint.targets) {+ if (entry.weight <= 0) continue;+ const targetIdx = indexById.get(entry.target);+ const inverse = mat4.invert(new Float64Array(16), restWorlds[targetIdx]);+ const delta = mat4.multiply(new Float64Array(16), worlds[targetIdx], inverse);+ const transformed = decompose(mat4.multiply(new Float64Array(16), delta, ownerWorld));+ totalWeight += entry.weight;+ vec3.scaleAndAdd(translations, translations, transformed.translation, entry.weight);+ vec3.scaleAndAdd(scales, scales, transformed.scale, entry.weight);+ const q = transformed.rotation;+ if (!firstQuat) firstQuat = q;+ const sign = quat.dot(firstQuat, q) < 0 ? -entry.weight : entry.weight;+ for (let i = 0; i < 4; i++) accumRotation[i] += q[i] * sign;+ }+ if (totalWeight <= NEAR_ZERO) return ownerWorld;+ vec3.scale(translations, translations, 1 / totalWeight);+ vec3.scale(scales, scales, 1 / totalWeight);+ quat.normalize(accumRotation, accumRotation);+ return compose({ translation: translations, rotation: accumRotation, scale: scales });+}+// ---------------------------------------------------------------------------------------------------------------// Evaluation@@ -588,7 +810,9 @@ export function createNodeConstraintEvaluator({ hierarchy, rootMatrix, constrain} else if (constraint.type === 'floor') {result = floorConstraint(ownerWorld, worlds[targetIndex], constraint);} else if (constraint.type === 'copy_transforms') {- result = worlds[targetIndex];+ if (constraint.mix === 'before') result = mat4.multiply(new Float64Array(16), ownerWorld, worlds[targetIndex]);+ else if (constraint.mix === 'after') result = mat4.multiply(new Float64Array(16), worlds[targetIndex], ownerWorld);+ else result = worlds[targetIndex];} else if (constraint.type === 'limit_distance') {result = limitDistance(ownerWorld, worlds[targetIndex], constraint);} else if (constraint.type === 'locked_track') {@@ -596,6 +820,18 @@ export function createNodeConstraintEvaluator({ hierarchy, rootMatrix, constrain} else if (constraint.type === 'stretch_to') {const restLength = constraint.restLength || vec3.distance(mat4.getTranslation(new Float64Array(3), restWorlds[ownerIndex]), mat4.getTranslation(new Float64Array(3), restWorlds[targetIndex]));result = stretchTo(ownerWorld, worlds[targetIndex], constraint, restLength);+ } else if (constraint.type === 'damped_track') {+ result = dampedTrack(ownerWorld, worlds[targetIndex], constraint);+ } else if (constraint.type === 'pivot') {+ result = pivotConstraint(ownerWorld, targetIndex >= 0 ? worlds[targetIndex] : null, restWorlds[ownerIndex], constraint);+ } else if (constraint.type === 'follow_path') {+ result = followPathConstraint(ownerWorld, constraint, context.time);+ } else if (constraint.type === 'clamp_to') {+ result = clampToConstraint(ownerWorld, constraint);+ } else if (constraint.type === 'shrinkwrap') {+ result = shrinkwrapConstraint(ownerWorld, worlds[targetIndex], constraint);+ } else if (constraint.type === 'armature') {+ result = armatureConstraint(ownerWorld, worlds, restWorlds, indexById, constraint);} else {const inverse = constraint.inverse === 'rest' ? mat4.invert(new Float64Array(16), restWorlds[targetIndex]) : mat4.create();const parent = mat4.multiply(new Float64Array(16), worlds[targetIndex], inverse);diff --git a/tests/agent-motion-constraints-more.test.js b/tests/agent-motion-constraints-more.test.jsindex aa9b56d2..100f727d 100644--- a/tests/agent-motion-constraints-more.test.js+++ b/tests/agent-motion-constraints-more.test.js@@ -125,3 +125,76 @@ test('the newer types accept their fields in args, the shape the MCP schema usestest('scene_capabilities lists every constraint type', () => {assert.deepEqual([...AGENT_SCENE_CAPABILITIES.motionConstraints].sort(), [...CONSTRAINT_TYPES].sort());});++test('maintain_volume, damped_track, pivot, follow_path, clamp_to, shrinkwrap and armature constraints work deterministically', () => {+ // maintain_volume+ const vol = sampled([{ ...owner, scale: [1, 4, 1] }], { type: 'maintain_volume', freeAxis: 'y', volume: 1 });+ assertClose([column(vol, 0)[0], column(vol, 1)[1], column(vol, 2)[2]], [0.5, 4, 0.5], 'maintain_volume');++ // damped_track+ const damped = sampled([owner, targetAt([0, 0, 5])], { type: 'damped_track', target: 'target', trackAxis: '+y' });+ assertClose(column(damped, 1), [0, 0, 1], 'damped_track +y aims at +z');++ // pivot+ const rotatedOwner = { id: 'owner', translation: [0, 0, 0], rotation: Array.from(quaternionFromEuler(new Float64Array(4), 0, 0, 90 * DEGREES)) };+ const pivoted = sampled([rotatedOwner, targetAt([1, 0, 0])], { type: 'pivot', target: 'target', offset: [0, 0, 0] });+ assertClose(translationOf(pivoted), [1, -1, 0], 'pivot 90 deg around [1,0,0]');++ // follow_path+ const pathScene = createAgentScene({+ format: '67js.scene', schemaVersion: 1,+ geometries: [{ id: 'box', type: 'box', bevel: 0 }],+ materials: [{ id: 'paint', color: [0.6, 0.6, 0.6] }],+ nodes: [{ id: 'owner', geometry: 'box', material: 'paint' }],+ motion: {+ duration: 1, tracks: [],+ constraints: [{ type: 'follow_path', node: 'owner', points: [[0, 0, 0], [0, 0, 4]], followCurve: true, forwardAxis: '+z', upAxis: 'y', duration: 1 }],+ },+ });+ pathScene.sampleMotion(0.5);+ const pathMat = pathScene.parts[0].matrix;+ assertClose(translationOf(pathMat), [0, 0, 2], 'follow_path midpoint');+ assertClose(column(pathMat, 2), [0, 0, 1], 'follow_path tangent +z');++ // clamp_to+ const clamped = sampled([{ ...owner, translation: [3, 5, 0] }], { type: 'clamp_to', points: [[0, 0, 0], [4, 2, 0]], mainAxis: 'x' });+ assertClose(translationOf(clamped), [3, 1.5, 0], 'clamp_to along x');++ // shrinkwrap nearest & project+ const nearest = sampled([{ ...owner, translation: [0, 5, 0] }, { id: 'target', translation: [0, 0, 0], scale: [2, 2, 2] }], { type: 'shrinkwrap', target: 'target', mode: 'nearest', distance: 0.5 });+ assertClose(translationOf(nearest), [0, 1.5, 0], 'shrinkwrap nearest');+ const projected = sampled([{ ...owner, translation: [0.5, 5, 0] }, { id: 'target', translation: [0, 0, 0], scale: [2, 2, 2] }], { type: 'shrinkwrap', target: 'target', mode: 'project', projectAxis: '-y', distance: 0.2 });+ assertClose(translationOf(projected), [0.5, 1.2, 0], 'shrinkwrap project');++ // armature constraint+ const armScene = createAgentScene({+ format: '67js.scene', schemaVersion: 1,+ geometries: [{ id: 'box', type: 'box', bevel: 0 }],+ materials: [{ id: 'paint', color: [0.6, 0.6, 0.6] }],+ nodes: [+ { id: 'owner', geometry: 'box', material: 'paint', translation: [0, 0, 0] },+ { id: 'b1', geometry: 'box', material: 'paint', translation: [0, 0, 0] },+ { id: 'b2', geometry: 'box', material: 'paint', translation: [0, 0, 0] },+ ],+ motion: {+ duration: 1,+ tracks: [+ { kind: 'node', id: 'b1', property: 'translation', keyframes: [{ time: 0, value: [0, 0, 0] }, { time: 1, value: [4, 0, 0] }] },+ { kind: 'node', id: 'b2', property: 'translation', keyframes: [{ time: 0, value: [0, 0, 0] }, { time: 1, value: [0, 4, 0] }] },+ ],+ constraints: [{ type: 'armature', node: 'owner', targets: [{ target: 'b1', weight: 0.75 }, { target: 'b2', weight: 0.25 }] }],+ },+ });+ armScene.sampleMotion(1);+ assertClose(translationOf(armScene.parts.find(p => p.name === 'owner').matrix), [3, 1, 0], 'armature weighted blend');++ // floor useRotation and transformation mix+ const tiltedFloor = { id: 'target', translation: [0, 0, 0], rotation: Array.from(quaternionFromEuler(new Float64Array(4), 0, 0, -45 * DEGREES)) };+ const floored = sampled([{ ...owner, translation: [0, -1, 0] }, tiltedFloor], { type: 'floor', target: 'target', axis: '+y', useRotation: true });+ assert.ok(floored[13] > -0.6, 'tilted floor lifts owner');++ const added = sampled([{ ...owner, translation: [1, 2, 3] }, targetAt([5, 0, 0])], {+ type: 'transformation', target: 'target', fromMax: [10, 10, 10], toMax: [2, 0, 0], mix: 'add',+ });+ assertClose(translationOf(added), [2, 2, 3], 'transformation add');+});