3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Name animation clips the same in catalog, scene and export (#2075)
Nguyen Xuan An43f40adbce41
diff --git a/changes/2075.md b/changes/2075.mdnew file mode 100644index 00000000..ae0f0f47--- /dev/null+++ b/changes/2075.md@@ -0,0 +1 @@+- An unnamed animation clip is called `animation_<index>` in `scene_asset_catalog`, the scene and the exported GLB, and `scene_export_glb` takes `clip` as an index or a name (an unknown name lists the valid ones).diff --git a/changes/2075.size.md b/changes/2075.size.mdnew file mode 100644index 00000000..379ef3b8--- /dev/null+++ b/changes/2075.size.md@@ -0,0 +1,2 @@+- tool-total: an agent can export a clip by the name the catalog shows, so it no longer needs a lookup of the index first.+- tool:scene_export_glb: clip takes a number or a name, the one change this issue asks for.diff --git a/docs/export-glb.md b/docs/export-glb.mdindex 33ba3ff4..75f2a08c 100644--- a/docs/export-glb.md+++ b/docs/export-glb.md@@ -141,7 +141,7 @@ The file goes to `<jobs>/exports/<uuid>.glb`; the call takes no path and the resThe newest eight files stay, counting the ones an earlier server run left in the folder, the GLB is at most 32 MiB, and `maxTextureSize` goes up to 4096.Without `clip` it writes the current pose: pattern and imported textures, skins, morph weights and IK as posed.`motionTime` seeks authored motion first and leaves the preview there, like `scene_look`.-With `clip` (imported assets) it writes that source clip, translation, rotation, scale and weights, on the source skeleton, so the scene must carry no animation, node overrides or motion.+With `clip` (imported assets, an index or the clip name from `scene_asset_catalog` or `scene_inspect`; an unknown name lists the valid ones) it writes that source clip, translation, rotation, scale and weights, on the source skeleton, so the scene must carry no animation, node overrides or motion.`node scripts/smoke-glb-export.mjs cpu` runs a patterned recipe, the robot with IK and its Walking clip through the real server and leaves the files in `artifacts/`.## OBJ and STLdiff --git a/docs/mcp.md b/docs/mcp.mdindex 68968f1b..3aa5aa94 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -162,7 +162,7 @@ Inspect or export the recipe before retrying. Context loss still permits recipe| `scene_restore` | `sessionId`, `expectedRevision`, and a `checkpointId`, a `revision` or a `branch` | Updated revision and render status || `scene_release_checkpoint` | `sessionId`, `checkpointId` | Release confirmation || `scene_export_recipe` | `sessionId` | Canonical recipe and revision |-| `scene_export_glb` | `sessionId`, optional `clip`, `motionTime`, `maxTextureSize` | A GLB file under `<jobs>/exports/` with a server-chosen name: path, bytes, SHA-256. See [GLB export](export-glb.md) |+| `scene_export_glb` | `sessionId`, optional `clip` (index or name), `motionTime`, `maxTextureSize` | A GLB file under `<jobs>/exports/` with a server-chosen name: path, bytes, SHA-256. See [GLB export](export-glb.md) || `scene_export_web` | `sessionId`, optional `title`, `review` | A static web build folder under `<jobs>/exports/`: path of `index.html`, file count, bytes. Needs a `game` set with `set-game`, unless `review` is true. See [Game](game.md) and [Review link](#review-link) || `scene_dispose` | `sessionId` | Disposal confirmation || `scene_render_submit` | `sessionId`, `expectedRevision`, `settings` | Snapshot job ID and queued record |diff --git a/scripts/agent-asset-catalog.mjs b/scripts/agent-asset-catalog.mjsindex 57a373ca..9567823c 100644--- a/scripts/agent-asset-catalog.mjs+++ b/scripts/agent-asset-catalog.mjs@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';import { open, readdir, realpath, lstat } from 'node:fs/promises';import { dirname, isAbsolute, join, relative, sep } from 'node:path';+import { clipDisplayName } from '../src/clip-name.js';import { AGENT_ASSET_LIMITS, assetBytesLimitMessage } from '../src/agent-asset-limits.js';import { MAXIMUM_CATALOG_ENVIRONMENT_BYTES, MAXIMUM_CATALOG_LOOK_BYTES } from '../src/look-catalog.js';import { imageLimitProblem, readImageDimensions } from '../src/image-header.js';@@ -313,7 +314,7 @@ export function describeCatalogFile(name, { bytes, document, assetId, imageFormaimages: document.images?.length ?? 0,animationCount: animations.length,animationsTruncated: animations.length > 16,- animations: animations.slice(0, 16).map((animation, index) => ({ index, name: String(animation?.name ?? `Clip ${index}`).slice(0, 80) })),+ animations: animations.slice(0, 16).map((animation, index) => ({ index, name: clipDisplayName(animation, index).slice(0, 80) })),});}diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.jsindex c8cbbdcb..71e445e2 100644--- a/scripts/agent-preview-browser.js+++ b/scripts/agent-preview-browser.js@@ -28,6 +28,7 @@ import { groundBounceEnvironment } from '../src/ground-bounce.js';import { createAgentAssetScene } from '../src/agent-asset.js';import { parseGltf } from '../src/gltf.js';import { assetCopyKey, recipeAssetNeeds } from '../src/agent-scene-assets.js';+import { clipDisplayName, resolveClipIndex } from '../src/clip-name.js';import { exportGlb } from '../src/export.js';import '../src/texture-update.js';import { staleRevisionMessage } from '../src/agent-errors.js';@@ -799,17 +800,17 @@ function withoutRoundoffShear(part) {}// A source clip animates the source skeleton, so the scene must not carry a pose of its own that the clip would fight.-function clipExport(record, clipIndex) {+function clipExport(record, clipReference) {const { asset, scene } = record;if (!asset) throw new Error('clip needs an imported asset scene. Recipe scenes export their current pose.');+ const clipIndex = resolveClipIndex(asset.animations, clipReference);const animation = asset.animations[clipIndex];- if (!animation) throw new RangeError(`clip ${clipIndex} does not exist. The asset has ${asset.animations.length} clips.`);const recipe = scene.exportRecipe();if (recipe.animation || recipe.nodeOverrides.length || recipe.motion) {throw new Error('Exporting a clip needs the unposed asset: remove animation, node overrides and motion first, or export without clip for the current pose.');}const sourceClip = clipFromGltfAnimation(animation);- const name = String(animation.name || `clip ${clipIndex}`);+ const name = clipDisplayName(animation, clipIndex);const clip = { ...sourceClip, name, tracks: [...sourceClip.tracks, ...weightTracksFromGltfAnimation(animation)] };// Edited parts export their edited geometry on the source part's own matrix, skin and morph.const parts = asset.parts.map((part, index) => scene.parts[index].geometry === part.geometry ? part : { ...part, geometry: scene.parts[index].geometry });diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex c92fb7d4..e13242c9 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -1093,7 +1093,7 @@ export function createAgentMcpServer(runtime, { version = packageMetadata.versioregister('scene_restore', 'Restore a checkpoint atomically using the current revision. The checkpoint remains available and revision increments. Pass exactly one of checkpointId, revision or branch. With revision (last 4 kept), undo with no checkpoint. With branch, keep that branch (one revision) and drop all branches.', z.strictObject({ ...sessionFields, checkpointId: restoreCheckpointId, revision: z.number().int().min(0).optional(), ...restoreBranchField, expectedRevision }), edit, async argumentsValue => jsonResult(await runtime.restore(argumentsValue)));register('scene_release_checkpoint', 'Release one checkpoint slot. Released or foreign checkpoints fail.', z.strictObject(checkpointFields), destroy, async argumentsValue => jsonResult(await runtime.releaseCheckpoint(argumentsValue)));register('scene_export_recipe', 'Read a detached canonical JSON recipe for reproduction.', z.strictObject(sessionFields), readOnly, async argumentsValue => jsonResult(await runtime.exportRecipe(argumentsValue)));- register('scene_export_glb', 'Write the active scene as a GLB file in the configured jobs folder, under a server-chosen name (the result has the path, byte count and SHA-256). Needs --jobs. Exports the current pose with pattern and imported textures, skins, morph weights and IK as posed; motionTime seeks authored motion first. For an imported asset, clip adds that source clip (translation, rotation, scale and morph weight tracks) on the source skeleton, which needs no animation, node overrides or motion in the scene. At most eight files are kept, oldest removed first; the GLB is at most 32 MiB.', z.strictObject({ ...sessionFields, clip: z.number().int().min(0).max(255).optional().describe('Imported assets only: index of the source clip to write.'), motionTime: z.number().min(0).max(3600).optional().describe('Seek authored motion (and IK) to this time before exporting. Leaves the preview there, like scene_look.'), maxTextureSize: z.number().int().min(1).max(4096).optional().describe('Largest texture side in pixels. Defaults to 2048.') }), edit, async argumentsValue => jsonResult(await runtime.exportGlb(argumentsValue)));+ register('scene_export_glb', 'Write the active scene as a GLB file in the configured jobs folder, under a server-chosen name (the result has the path, byte count and SHA-256). Needs --jobs. Exports the current pose with pattern and imported textures, skins, morph weights and IK as posed; motionTime seeks authored motion first. For an imported asset, clip adds that source clip (translation, rotation, scale and morph weight tracks) on the source skeleton, which needs no animation, node overrides or motion in the scene. At most eight files are kept, oldest removed first; the GLB is at most 32 MiB.', z.strictObject({ ...sessionFields, clip: z.union([z.number().int().min(0).max(255), z.string().min(1).max(256)]).optional().describe('Imported assets only: source clip index or name, as scene_asset_catalog lists.'), motionTime: z.number().min(0).max(3600).optional().describe('Seek authored motion (and IK) to this time before exporting. Leaves the preview there, like scene_look.'), maxTextureSize: z.number().int().min(1).max(4096).optional().describe('Largest texture side in pixels. Defaults to 2048.') }), edit, async argumentsValue => jsonResult(await runtime.exportGlb(argumentsValue)));register('scene_export_web', 'Write the scene with its game as a static web build in the jobs folder: index.html, game.json and engine/, which any static host serves with no server code. Needs --jobs and a game set with set-game. Procedural scenes only; the newest four builds are kept. review: true writes a page of the current view for a person to pin on a phone instead (no game); read its saved file with scene_ask_user reviewFile.', z.strictObject({ ...sessionFields, title: z.string().max(64).optional().describe('Page title.'), review: z.boolean().optional() }), edit, async argumentsValue => jsonResult(await runtime.exportWeb(argumentsValue)));register('scene_dispose', 'Dispose the active scene and its checkpoints, releasing renderer resources.', z.strictObject(sessionFields), destroy, async argumentsValue => jsonResult(await runtime.dispose(argumentsValue)));register('scene_render_submit', 'Start one asynchronous snapshot job in the configured private job store. Requires the current revision. Temporarily leases the preview renderer; does not change source revision or checkpoints.', z.strictObject({ ...sessionFields, expectedRevision, settings: renderSettings }), { ...edit, destructiveHint: false }, async argumentsValue => jsonResult(await runtime.submitJob(argumentsValue)));diff --git a/src/agent-asset.js b/src/agent-asset.jsindex 26990899..07ac918e 100644--- a/src/agent-asset.js+++ b/src/agent-asset.js@@ -7,6 +7,7 @@ import { fitPerspectiveDistance } from './camera.js';import { skinnedWorldBounds, validateSkinGeometry, validateSkinPose } from './skinning.js';import { validateMorphGeometry, validateMorphTransform } from './morph.js';import * as agentMotion from './agent-motion.js';+import { clipDisplayName } from './clip-name.js';import { compileClipStrip } from './clip-strip.js';import { clipLayerContextFromAsset, retargetSourceFromAsset } from './agent-clip-layers.js';import { retargetAssetClip, retargetReport } from './agent-retarget.js';@@ -1135,7 +1136,7 @@ export function createAgentAssetScene(asset, inputRecipe, { sources } = {}) {geometryBytes, animation: structuredClone(recipe.animation),motion: recipe.motion ? { duration: recipe.motion.duration, loop: recipe.motion.loop, tracks: recipe.motion.tracks.length, layers: recipe.motion.layers?.length ?? 0, time: motionTime } : null,physics: physicsSampler ? physicsSampler.report() : null,- animations: asset.animations.map((clip, index) => ({ id: index, label: String(clip.name ?? `Clip ${index}`).slice(0, 256), duration: clip.duration })),+ animations: asset.animations.map((clip, index) => ({ id: index, label: clipDisplayName(clip, index).slice(0, 256), duration: clip.duration })),nodes, offset, truncated: selected.length > offset + nodes.length,};},diff --git a/src/clip-name.js b/src/clip-name.jsnew file mode 100644index 00000000..b510b552--- /dev/null+++ b/src/clip-name.js@@ -0,0 +1,36 @@+// One name for a glTF animation clip, wherever an agent reads it: the catalog, the scene and the GLB export.++/** The name an unnamed clip gets. The glTF decoder, the catalog and the export all use it. */+export function fallbackClipName(clipIndex) {+ return `animation_${clipIndex}`;+}++/** The clip's own name, or its fallback name when the file leaves it empty. */+export function clipDisplayName(animation, clipIndex) {+ const name = animation?.name;+ return typeof name === 'string' && name !== '' ? name : fallbackClipName(clipIndex);+}++/**+ * The index of the clip a caller means, given its index or its name.+ * Throws a RangeError that lists the valid indexes and names when nothing matches, and one that lists the indexes+ * when a name is shared by several clips.+ */+export function resolveClipIndex(animations, clip, field = 'clip') {+ const names = animations.map(clipDisplayName);+ if (typeof clip === 'string') {+ const matches = names.flatMap((name, index) => (name === clip ? [index] : []));+ if (matches.length === 1) return matches[0];+ if (matches.length > 1) throw new RangeError(`${field} "${clip}" names ${matches.length} clips. Pass one of their indexes: ${matches.join(', ')}.`);+ throw new RangeError(`${field} "${clip}" does not exist. ${availableClips(names)}`);+ }+ if (!Number.isInteger(clip) || clip < 0 || clip >= animations.length) {+ throw new RangeError(`${field} ${clip} does not exist. ${availableClips(names)}`);+ }+ return clip;+}++function availableClips(names) {+ if (names.length === 0) return 'The asset has no clips.';+ return `Pass an index or a name: ${names.map((name, index) => `${index} "${name}"`).join(', ')}.`;+}diff --git a/src/gltf-animation.js b/src/gltf-animation.jsindex 2a47ccb1..ae28587d 100644--- a/src/gltf-animation.js+++ b/src/gltf-animation.js@@ -1,3 +1,4 @@+import { clipDisplayName } from './clip-name.js';import { attributeFloats } from './gltf-accessors.js';export const INTERPOLATE_DISCRETE = 2300;@@ -189,7 +190,7 @@ export function createClips(document, nodeAt, readAccessor) {tracks.push(...tracksForChannel(channel, sampler, nodeAt(channel.target.node), readAccessor));}const duration = Math.max(0, ...tracks.map(track => track.times[track.times.length - 1]));- return { name: definition.name ? definition.name : `animation_${animationIndex}`, duration, tracks };+ return { name: clipDisplayName(definition, animationIndex), duration, tracks };});}diff --git a/tests/agent-asset-catalog.test.js b/tests/agent-asset-catalog.test.jsindex f4c327ef..9cb665bb 100644--- a/tests/agent-asset-catalog.test.js+++ b/tests/agent-asset-catalog.test.js@@ -10,6 +10,7 @@ import { exportGlb } from '../src/export.js';import { createAgentAssetCatalog } from '../scripts/agent-asset-catalog.mjs';import { AGENT_ASSET_LIMITS, agentAssetDecodeOptions, withCatalogLimitAdvice } from '../src/agent-asset-limits.js';import { GLTF_CAPABILITIES, parseGltf } from '../src/gltf.js';+import { createClips } from '../src/gltf-animation.js';async function fixture(context) {const directory = await mkdtemp(join(tmpdir(), 'crucible-catalog-'));@@ -335,3 +336,14 @@ test('resolveName refuses an unknown or non-string name with a hint (#1843)', asassert.throws(() => catalog.resolveName('tree.glb'), /Run scene_asset_catalog/);assert.throws(() => catalog.resolveName(7), TypeError);});++test('an unnamed clip has the same name in the catalog as in the decoded asset (#2075)', async context => {+ const { directory, bytes } = await fixture(context);+ const animations = [{ channels: [], samplers: [] }, { name: 'Walk', channels: [], samplers: [] }, { name: '', channels: [], samplers: [] }];+ await writeFile(join(directory, 'cube.glb'), withDocument(bytes, document => { document.animations = animations; }));+ const catalog = await createAgentAssetCatalog(directory);+ const listed = catalog.list().assets[0].animations.map(clip => clip.name);+ assert.deepEqual(listed, ['animation_0', 'Walk', 'animation_2']);+ const decoded = createClips({ animations }, () => undefined, () => undefined).map(clip => clip.name);+ assert.deepEqual(decoded, listed);+});diff --git a/tests/clip-name.test.js b/tests/clip-name.test.jsnew file mode 100644index 00000000..b72261af--- /dev/null+++ b/tests/clip-name.test.js@@ -0,0 +1,28 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { clipDisplayName, fallbackClipName, resolveClipIndex } from '../src/clip-name.js';++const animations = [{ name: 'Survey' }, { name: 'Walk' }, {}, { name: '' }];++test('an unnamed clip gets one fallback name', () => {+ assert.equal(fallbackClipName(0), 'animation_0');+ assert.equal(clipDisplayName({}, 2), 'animation_2');+ assert.equal(clipDisplayName({ name: '' }, 3), 'animation_3');+ assert.equal(clipDisplayName({ name: 'Run' }, 1), 'Run');+});++test('a clip is found by index or by name, and an index keeps working', () => {+ assert.equal(resolveClipIndex(animations, 1), 1);+ assert.equal(resolveClipIndex(animations, 'Walk'), 1);+ assert.equal(resolveClipIndex(animations, 'animation_2'), 2);+});++test('an unknown name or index lists the valid names', () => {+ assert.throws(() => resolveClipIndex(animations, 'Fly'), /clip "Fly" does not exist\. Pass an index or a name: 0 "Survey", 1 "Walk", 2 "animation_2", 3 "animation_3"\./);+ assert.throws(() => resolveClipIndex(animations, 9), /clip 9 does not exist\. Pass an index or a name: 0 "Survey"/);+ assert.throws(() => resolveClipIndex([], 'Walk'), /The asset has no clips\./);+});++test('a name shared by several clips asks for an index', () => {+ assert.throws(() => resolveClipIndex([{ name: 'A' }, { name: 'A' }], 'A'), /names 2 clips\. Pass one of their indexes: 0, 1\./);+});