3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Play particles, physics and cloth from second 0 when a job sets no motion (#2052)
Nguyen Xuan Andf36fc0377d7
diff --git a/changes/2052.md b/changes/2052.mdnew file mode 100644index 00000000..fd20546a--- /dev/null+++ b/changes/2052.md@@ -0,0 +1 @@+- A stills or video job of a recipe whose only moving content is particles, physics or cloth now plays the motion clock from 0 when `settings.motion` is left out, instead of rendering frozen frames.diff --git a/docs/agent-render-jobs.md b/docs/agent-render-jobs.mdindex 0b75712c..4de2e700 100644--- a/docs/agent-render-jobs.md+++ b/docs/agent-render-jobs.md@@ -398,6 +398,6 @@ The tests use actual temporary files and controlled callbacks.They cover snapshots, persistence, hashes, cancellation, deadlines, restart recovery, quotas, path rejection, and file aliases.The tests do not run browsers, ffmpeg, or GPU rendering.-A recipe whose only moving content is `physics`, `cloth` or `particles` takes the same `motion` setting: the job plays the bake on the motion clock, with no authored motion and no `bake-motion` step (so the 32 node cap does not apply). A video without `duration` runs as long as the bake, counted from `motion.start`, and a longer one is rejected. A recipe with nothing that moves fails with an error that lists authored motion, physics, cloth, particles, placed clips and map sequences as the accepted sources.+A recipe whose only moving content is `physics`, `cloth` or `particles` takes the same `motion` setting, and plays from `motion.start` 0 when the job leaves it out (unless the job is longer than the bake, which then holds the first pose): the job plays the bake on the motion clock, with no authored motion and no `bake-motion` step (so the 32 node cap does not apply). A video without `duration` runs as long as the bake, counted from `motion.start`, and a longer one is rejected. A recipe with nothing that moves fails with an error that lists authored motion, physics, cloth, particles, placed clips and map sequences as the accepted sources.The camera does not move with the bake. A recipe `camera` (`eye`, `target`, lens) is the same on every frame of a physics, cloth or particle film, so shards flying out of frame do not pull the view. Nothing frames the scene by its bounds: only an authored `camera` motion track or a timeline shot changes the camera. Set `camera.eye` and `camera.target` for a locked shot; left out, the default camera is used, also locked. `tests/physics-film.test.js` checks that a static marker stays on the same pixels from the first frame to the last.diff --git a/scripts/agent-render-jobs.mjs b/scripts/agent-render-jobs.mjsindex ae1f4fc2..d7c47e16 100644--- a/scripts/agent-render-jobs.mjs+++ b/scripts/agent-render-jobs.mjs@@ -103,6 +103,15 @@ function playsPhysics(recipe) {return Boolean(recipe?.physics || recipe?.cloth || recipe?.particles);}+/**+ * Whether a job with no `motion` setting should still play the recipe's particles, physics or cloth from second 0.+ * Without a motion clock every frame is frame 0, so such a stills or video job would come out frozen with no warning.+ */+function playsSimulationFromStart(input, recipe, timelineStart) {+ return input.kind !== 'image' && timelineStart === undefined && input.animation === undefined+ && recipe?.format === 'crucible.scene' && playsPhysics(recipe);+}+/** The settings of a job as the store keeps them: every default filled in, every limit checked. */export function normalizeJobSettings(input, clips, recipe) {return settingsFrom(input, clips, recipe);@@ -153,8 +162,10 @@ function settingsFrom(input, clips = [], recipe) {result.encoder = input.encoder;}if (input.audio !== undefined) result.audio = audioFrom(input.audio, input.kind);- if (input.motion !== undefined) {- objectKeys(input.motion, ['start'], 'motion');+ const impliedMotion = input.motion === undefined && playsSimulationFromStart(input, recipe, timelineStart);+ if (input.motion !== undefined || impliedMotion) {+ const motionInput = input.motion ?? { start: 0 };+ objectKeys(motionInput, ['start'], 'motion');// Clips of placed assets play on scene time, so a scene that places one needs no authored motion.const placesClips = recipe?.format === 'crucible.scene' && recipeAssetNeeds(recipe).some(need => need.copies > 1);// A map sequence and a grid volume sequence read the same clock.@@ -167,15 +178,16 @@ function settingsFrom(input, clips = [], recipe) {if (recipe.motion?.loop !== undefined && typeof recipe.motion.loop !== 'boolean') {throw new TypeError('Motion loop must be boolean.');}- const start = boundedNumber(input.motion.start === undefined ? 0 : input.motion.start, 0, 3600, 'motion start');+ const start = boundedNumber(motionInput.start === undefined ? 0 : motionInput.start, 0, 3600, 'motion start');boundedNumber(start + lastSampleTime, 0, 3600, 'motion end');- if (recipe.motion && !recipe.motion.loop && start + lastSampleTime > motionDuration) {- throw new RangeError('Motion range exceeds the authored duration.');- }- if (!recipe.motion && bakeSeconds && start + lastSampleTime > bakeSeconds) {+ const exceedsAuthoredMotion = recipe.motion && !recipe.motion.loop && start + lastSampleTime > motionDuration;+ const exceedsBake = !recipe.motion && bakeSeconds && start + lastSampleTime > bakeSeconds;+ if (exceedsAuthoredMotion && !impliedMotion) throw new RangeError('Motion range exceeds the authored duration.');+ if (exceedsBake && !impliedMotion) {throw new RangeError(`Motion range exceeds the physics bake duration of ${bakeSeconds} s; shorten the job or lengthen physics.duration.`);}- result.motion = { start };+ // An implied start of 0 is only kept while the job fits the motion; a longer job keeps the old held pose rather than failing.+ if (!(impliedMotion && (exceedsAuthoredMotion || exceedsBake))) result.motion = { start };}if (input.animation !== undefined) {objectKeys(input.animation, ['clip', 'start'], 'animation');diff --git a/skills/render-crucible-media/SKILL.md b/skills/render-crucible-media/SKILL.mdindex c6a8ebb4..5d1fd3e0 100644--- a/skills/render-crucible-media/SKILL.md+++ b/skills/render-crucible-media/SKILL.md@@ -47,8 +47,8 @@ submit call fails: tell the user which launch option is missing.job holds the first pose, which is the usual reason a video is a still frame. A recipe with a `timeline` uses`settings.timeline` and rejects `motion` and `animation`.- A recipe whose only motion is `physics` (or `cloth`, `particles`), a grid volume sequence or a texture sequence is- filmed with the same `motion: { "start": 0 }`; the job plays the bake on the scene clock, so do not `bake-motion`- first. Video `duration` defaults to the bake length.+ filmed with `motion: { "start": 0 }`; the job plays the bake on the scene clock, so do not `bake-motion` first. Physics,+ cloth and particles start at 0 when `motion` is left out; sequences need it set. Video `duration` defaults to the bake length.- Imported clips use `settings.animation`; the two clocks are independent.- For compositing, `settings.transparent`, `settings.format` (`png16`, `exr`) and `settings.region` are off by default; atransparent frame sequence is one `stills` job with `stillCount`; video runs up to 60 fps (`references/jobs.md`).diff --git a/tests/render-job-simulation-motion.test.js b/tests/render-job-simulation-motion.test.jsnew file mode 100644index 00000000..3138b2b2--- /dev/null+++ b/tests/render-job-simulation-motion.test.js@@ -0,0 +1,39 @@+import nodeTest from 'node:test';+import assert from 'node:assert/strict';+import { normalizeJobSettings } from '../scripts/agent-render-jobs.mjs';++const particleRecipe = {+ format: 'crucible.scene',+ particles: { systems: [{ node: 'sparks', count: 100, rate: 30, lifetime: 2, speed: 3 }] },+};+const stillsJob = { kind: 'stills', width: 320, height: 180 };+const videoJob = { kind: 'video', width: 320, height: 180, duration: 1 };++nodeTest('a stills job of a particles-only recipe plays the motion clock from 0 without a motion setting', () => {+ assert.deepEqual(normalizeJobSettings(stillsJob, [], particleRecipe).motion, { start: 0 });+});++nodeTest('a video job of a particles-only recipe plays the motion clock from 0 without a motion setting', () => {+ assert.deepEqual(normalizeJobSettings(videoJob, [], particleRecipe).motion, { start: 0 });+});++nodeTest('an explicit motion start is kept', () => {+ assert.deepEqual(normalizeJobSettings({ ...stillsJob, motion: { start: 1 } }, [], particleRecipe).motion, { start: 1 });+});++nodeTest('physics and cloth recipes get the same default', () => {+ assert.deepEqual(normalizeJobSettings(videoJob, [], { format: 'crucible.scene', cloth: { duration: 3 } }).motion, { start: 0 });+ assert.deepEqual(normalizeJobSettings(videoJob, [], { format: 'crucible.scene', physics: { duration: 3, bodies: [] } }).motion, { start: 0 });+});++nodeTest('a job longer than the physics bake keeps the held pose instead of failing', () => {+ const longVideo = { ...videoJob, duration: 5 };+ const recipe = { format: 'crucible.scene', physics: { duration: 2, bodies: [] } };+ assert.equal(normalizeJobSettings(longVideo, [], recipe).motion, undefined);+ assert.throws(() => normalizeJobSettings({ ...longVideo, motion: { start: 0 } }, [], recipe), /physics bake duration/);+});++nodeTest('an image job and a recipe with nothing simulated get no implied motion', () => {+ assert.equal(normalizeJobSettings({ kind: 'image', width: 320, height: 180 }, [], particleRecipe).motion, undefined);+ assert.equal(normalizeJobSettings(stillsJob, [], { format: 'crucible.scene' }).motion, undefined);+});