Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Move drive validation out of the core bundles and accept the size note

Nguyen Xuan Anaee8078e1f4f
diff --git a/changes/322.size.md b/changes/322.size.md
new file mode 100644
index 00000000..10c27248
--- /dev/null
+++ b/changes/322.size.md
@@ -0,0 +1,8 @@
+- entry:agent-scene+lazy: motion.drive and asset.drive load the vehicle kit (about 12 KB gzip) as the on-demand `drive` module; a recipe without a drive never fetches it.
+- entry:agent-asset+lazy: the same on-demand `drive` module, counted because the lazy row adds every on-demand module.
+- scene:agent-scene: the drive hooks in motion sampling, placement expansion and module registration (448 bytes gzip); the vehicle code itself stays in the lazy row.
+- scene:agent-scene+lazy: the on-demand `drive` module (vehicle kit and its sampler) that the lazy row adds.
+- tool-total: one clause in the shared motion description and the drive entry in scene_capabilities.
+- tool:scene_apply: the motion description now names `drive`, the entry that lets an agent drive a car GLB.
+- tool:scene_create_asset: the same motion description, shared with scene_apply.
+- result:scene_capabilities: the `motionDrive` entry and the placed-asset `drive` field, which is where the drive fields are documented instead of in each tool schema.
diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjs
index de45676a..cf0ced70 100644
--- a/scripts/mcp-server.mjs
+++ b/scripts/mcp-server.mjs
@@ -512,7 +512,7 @@ const cloth = z.strictObject({
}).describe('Baked at 60 fps, seeked by motionTime. Units, defaults: scene_capabilities cloth.');
// The full motion schema (tracks, ik, constraints, drivers) is in scene_create's recipe. scene_apply and asset recipes
// take the same object, validated by the backend, without repeating about 35 KB of schema in each tool.
-const recipeMotionReference = z.record(z.string(), z.unknown()).describe('The same object as recipe.motion in scene_create: duration, loop, tracks, ik, constraints, drivers. Read that tool for the fields. On an imported asset it also takes layers, up to 8 clips played at motion time before tracks and ik: { clip (scene_inspect animations id), mask: { joints, descendants, exclude } of node IDs, weight, speed, offset, loop, additive, reference, bones: { clip node: asset node } to retarget by name, morph } or from: { asset, clip } for a clip of another catalog asset retargeted onto this humanoid (scale, rootMotion). motion also takes drive (a car along a path with Ackermann steering, reversing legs and lights; see scene_capabilities motionDrive; scene_inspect motionDrive) and footLock (true or { contactHeight, contactSpeed, blend, ground }) and { kind: "morph", id: target name, property: "weight" } tracks. A masked layer waves while another walks.');
+const recipeMotionReference = z.record(z.string(), z.unknown()).describe('The same object as recipe.motion in scene_create: duration, loop, tracks, ik, constraints, drivers. Read that tool for the fields. On an imported asset it also takes layers, up to 8 clips played at motion time before tracks and ik: { clip (scene_inspect animations id), mask: { joints, descendants, exclude } of node IDs, weight, speed, offset, loop, additive, reference, bones: { clip node: asset node } to retarget by name, morph } or from: { asset, clip } for a clip of another catalog asset retargeted onto this humanoid (scale, rootMotion). motion also takes drive (a car along a path, see scene_capabilities motionDrive) and footLock (true or { contactHeight, contactSpeed, blend, ground }) and { kind: "morph", id: target name, property: "weight" } tracks. A masked layer waves while another walks.');
const boneRecord = z.strictObject({
name: z.string().min(1).max(64).describe('Unique within the armature. Humanoid rigs use the canonical names (hips, spine, chest, neck, head, leftUpperArm, leftLowerArm, leftHand, leftUpperLeg, leftLowerLeg, leftFoot, leftToes, and right...) so retarget works.'),
parent: z.string().min(1).max(64).nullable().optional().describe('Parent bone name, or null for a root bone.'),
diff --git a/src/agent-asset.js b/src/agent-asset.js
index 59f46fcd..8b2c3177 100644
--- a/src/agent-asset.js
+++ b/src/agent-asset.js
@@ -36,7 +36,7 @@ export const AGENT_ASSET_CAPABILITIES = Object.freeze({
'set-camera', 'set-environment', 'set-effects', 'set-shadow',
'set-root', 'set-animation', 'set-material', 'set-asset-node', 'set-motion', 'set-physics', 'edit-mesh',
]),
- motionDrive: 'drive {path | legs [{path, direction forward|reverse, pause}], speed | cruiseSpeed (+ acceleration, braking, maxLateralAcceleration), wheels auto | [{id,node|nodes,side,axle,radius,steerable,spinSign}], body, forwardAxis, wheelbase, steering ackermann|shared, lights {headlights [{id,position,direction}], tailLights [{material,signal brake|reverse,off,on}]}}: a car driven along a path (points or a camera path), wheels rolling and steering, tail lights glowing with the brake. duration may be left out: it becomes the drive time. scene_inspect motionDrive lists the wheels found, rejectedNames and the light signals at the motion time. See docs/vehicle.md',
+ motionDrive: 'drive {path | legs [{path, direction forward|reverse, pause}], cruiseSpeed | speed, wheels auto | [{id,node,side,axle,radius}], lights {headlights, tailLights [{material,signal brake|reverse,off,on}]}}: a car along a path; duration may be left out. scene_inspect motionDrive reports wheels, rejectedNames and light signals; docs/vehicle.md has every field',
ragdoll: 'physics {duration, floor?, ragdoll {}}: joints fall limp onto a floor at world height floor (default 0)',
boundsKind: 'authored-base-world',
});
@@ -527,7 +527,7 @@ export function createAgentAssetScene(asset, inputRecipe, { sources } = {}) {
return {
nodes: [...sourceNodes.values()].filter(node => node.editable),
materials: [...baselines.values()], camera: candidate.camera,
- buildDrive, ikHierarchy: [...sourceNodes.values()], clipLayerContext, morphTargets: [...morphTargetIndex.keys()],
+ buildDrive, normalizeDrive: input => agentSceneModule('drive').normalizeDrive(input), ikHierarchy: [...sourceNodes.values()], clipLayerContext, morphTargets: [...morphTargetIndex.keys()],
ikRootMatrix: Array.from(mat4.fromRotationTranslationScale(mat4.create(), root.rotation, root.translation, [root.scale[0], root.scale[0], root.scale[0]])),
};
}
diff --git a/src/agent-drive.js b/src/agent-drive.js
index 39e54129..ab4981ed 100644
--- a/src/agent-drive.js
+++ b/src/agent-drive.js
@@ -4,6 +4,8 @@ import { createVehicleRig, driveAlongLegs, createVehicleNodeOverrides } from './
// The `drive` entry of an asset recipe's motion and of a placed asset: a car driven along a path by the vehicle kit.
// Loaded on demand (module 'drive'); sampling is a pure function of time, so frames render in any order.
+export { normalizeDrive } from './agent-drive-schema.js';
+
function resolvePath(path) {
return Array.isArray(path) ? path : createCameraPath({ loop: false, ...path });
}
diff --git a/src/agent-motion.js b/src/agent-motion.js
index 4a29cbd6..af9ad921 100644
--- a/src/agent-motion.js
+++ b/src/agent-motion.js
@@ -5,7 +5,6 @@ import { createNodeConstraintEvaluator, normalizeConstraints, normalizeDrivers }
import { normalizeClipLayers } from './agent-clip-layers.js';
import { normalizeKeyframeEasing } from './easing.js';
import { normalizeFootLock } from './foot-lock.js';
-import { normalizeDrive } from './agent-drive-schema.js';
import { bounded, denseArray, finite, knownKeys, valueFrom } from './motion-validation.js';
const PROPERTIES = {
@@ -282,10 +281,10 @@ function ikKeyframeCount(ik) {
/** Normalize bounded authored data without storing bindings or sampled poses. */
/** The canonical drive entry and the drive built from it, which proves the wheels, path and speeds are usable. */
function normalizedDrive(input, recipe) {
- if (!recipe.buildDrive) {
+ if (!recipe.normalizeDrive) {
throw new RangeError('motion.drive moves an imported asset recipe. For an asset placed in a scene, give the placement a drive: { asset: { id, drive } }.');
}
- const canonical = normalizeDrive(input);
+ const canonical = recipe.normalizeDrive(input);
return { canonical, built: recipe.buildDrive(canonical) };
}
@@ -304,7 +303,7 @@ export function normalizeAgentMotion(input, recipe) {
const inputTracks = input.tracks ?? [];
denseArray(inputTracks, 128, 'Motion tracks');
if (!inputTracks.length && !input.layers?.length && !input.ik?.length && !input.constraints?.length && !input.drivers?.length && !drive) {
- throw new RangeError('Motion needs at least one track, IK solver, constraint, driver or drive. Use null to clear it.');
+ throw new RangeError('Motion needs at least one track, IK solver, constraint or driver. Use null to clear it.');
}
const nodes = new Set((recipe.nodes ?? []).map(node => node.id));
const materials = new Set((recipe.materials ?? []).map(material => material.id));
diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.js
index 8bde13bc..7409067c 100644
--- a/src/agent-scene-capabilities.js
+++ b/src/agent-scene-capabilities.js
@@ -155,7 +155,7 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({
format: '67js.scene', schemaVersion: 1,
geometryTypes: Object.freeze(['box', 'cylinder', 'sphere', 'torus', 'lathe', 'extrude', 'tube', 'curve', 'text', 'grid', 'terrain', 'mesh']),
terrain: 'One mesh, x and z from -size/2 to size/2, hills about y = 0. size 40 m (1-2000), resolution 64 cells (2-256), seed 1, amplitude 1 m (0-200), holes up to 16 of {center:[x,z],radius} with no surface inside; radius a few cells or more.',
- placedAssets: 'Node field asset:{id,materials?,clip?,drive?} turns a group node into a catalog GLB (id from asset_catalog; scene_create_asset is one asset alone). Its transform places it. materials:[{name,color,metallic,roughness,opacity,emission,emissiveColor}] override source materials by name. clip:{index,start=0,speed=1,loop=true} plays that clip from scene time start, on a decoded copy of its own; scene_apply set-motion tracks move the node as usual and scene time seeks the clip. Copies of one asset share geometry and materials and draw as one batch. drive:{path | legs, cruiseSpeed | speed, wheels (auto or a list), lights:{headlights}} drives a car along a path in the placement frame (scene time is drive time; same fields as an asset recipe motion.drive, see docs/vehicle.md), also on its own copy; tail-light glow needs an asset recipe. scene_inspect assets lists id, bounds, clips, material names and the wheels of a drive, rejectedNames and light signals. At most 512 placements, 16 assets, 16 playing a clip or driving. Render jobs do not draw placed assets yet; scene_look does.',
+ placedAssets: 'Node field asset:{id,materials?,clip?,drive?} turns a group node into a catalog GLB (id from asset_catalog; scene_create_asset is one asset alone). Its transform places it. materials:[{name,color,metallic,roughness,opacity,emission,emissiveColor}] override source materials by name. clip:{index,start=0,speed=1,loop=true} plays that clip from scene time start, on a decoded copy of its own; scene_apply set-motion tracks move the node as usual and scene time seeks the clip. Copies of one asset share geometry and materials and draw as one batch. drive:{path | legs, cruiseSpeed | speed, wheels, lights} drives a car along a path in the placement frame on a decoded copy of its own (fields as motion.drive in an asset recipe, docs/vehicle.md; no tail-light glow). scene_inspect assets adds its wheels, rejectedNames and light signals. At most 512 placements, 16 assets, 16 playing a clip or driving. Render jobs do not draw placed assets yet; scene_look does.',
navigation: 'scene_inspect path:{ground,from:[x,z],to:[x,z]} returns a route over the ground node around its holes, steep slopes and the nodes in avoid:[ids] (box footprints), as keyframes [{time,value:[x,y,z]}] for a node translation track with interpolation LINEAR. radius 0.3 m is how far the walker position stays from holes and avoided nodes; maxSlope 40 degrees; cellSize defaults to radius; give seconds for the whole walk or speed (1.4 m/s); lift raises y, such as half the walker height. Ground and avoided nodes are read at their authored pose. Errors name an unwalkable start or goal, or one that cannot be reached.',
meshEdits: Object.freeze({ operations: Object.freeze(Object.keys(MESH_EDIT_OPERATIONS)), maxEdits: MAX_MESH_EDITS }),
meshStack: Object.freeze({ operations: STACK_OPERATIONS, maxNodes: MAX_STACK_NODES }),