Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Make the sequence job check static apart from its edit, document when a job reuses the session (#896)

Nguyen Xuan An7e5a68deae38
diff --git a/bench/native-tracer/sequence-job.mjs b/bench/native-tracer/sequence-job.mjs
index 1a97a31e..9c4856be 100644
--- a/bench/native-tracer/sequence-job.mjs
+++ b/bench/native-tracer/sequence-job.mjs
@@ -1,8 +1,12 @@
// Runs real multi-frame native stills jobs through the MCP server, once with sessions and once with JS67_NATIVE_SESSIONS=off, and checks
// that every frame of the two runs has the same bytes and that the frames after the first took the route the sequence calls for.
// node bench/native-tracer/sequence-job.mjs <output directory> [--browser <chrome path>] [--runtime-backend gpu|cpu] [--samples 8] [--width 480] [--height 270]
-// Variants (the demo room with its motion edited): camera (camera tracks only), material (plus a roughness track), light (plus a point light
-// intensity track), transform (the recipe's own tracks, where a pendant swings: the exported triangles change, so each frame gets a session).
+// Variants (the demo room with its motion edited and, except "particles", its particle systems removed, since sparks and swaying hair rebuild the
+// triangles and the emissive list at every time and a session is only reused when the exported tables are equal): camera (camera tracks only,
+// every later frame `reused`), material (plus a roughness track: `updated`), light (plus a point light intensity track: `updated`), transform
+// (the recipe's own tracks, where a pendant swings: the exported triangles change, so a frame gets a new session unless the swing has returned to an earlier pose) and particles (camera tracks
+// with the sparks left in: a new session per frame, as costly as a one-shot trace).
+// A run with sessions off carries no `nativeSession` in its reports, so its route list is empty by design.
// Prints one SEQUENCE_JOB line of JSON and exits 1 when a frame differs or a route is not the expected one.
import { createHash } from 'node:crypto';
import { mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';
@@ -32,12 +36,14 @@ function keyframes(first, last) {
function buildVariants(recipe) {
const cameraTracks = recipe.motion.tracks.filter(track => track.kind === 'camera');
const materialId = recipe.nodes.find(node => node.id === 'left-wall').material;
- const withMotion = tracks => ({ ...recipe, motion: { ...recipe.motion, tracks } });
+ const withoutParticles = Object.fromEntries(Object.entries(recipe).filter(([key]) => key !== 'particles'));
+ const withMotion = tracks => ({ ...withoutParticles, motion: { ...recipe.motion, tracks } });
return {
- camera: { recipe: withMotion(cameraTracks), expectedLaterRoutes: ['reused'] },
- material: { recipe: withMotion([...cameraTracks, { kind: 'material', id: materialId, property: 'roughness', interpolation: 'LINEAR', keyframes: keyframes(0.9, 0.2) }]), expectedLaterRoutes: ['reused', 'updated'] },
- light: { recipe: withMotion([...cameraTracks, { kind: 'light', id: 'point:0', property: 'intensity', interpolation: 'LINEAR', keyframes: keyframes(14, 4) }]), expectedLaterRoutes: ['reused', 'updated'] },
- transform: { recipe: withMotion(recipe.motion.tracks), expectedLaterRoutes: ['reused', 'updated', 'new-session'] },
+ camera: { recipe: withMotion(cameraTracks), expectedLaterRoute: 'reused' },
+ material: { recipe: withMotion([...cameraTracks, { kind: 'material', id: materialId, property: 'roughness', interpolation: 'LINEAR', keyframes: keyframes(0.9, 0.2) }]), expectedLaterRoute: 'updated' },
+ light: { recipe: withMotion([...cameraTracks, { kind: 'light', id: 'point:0', property: 'intensity', interpolation: 'LINEAR', keyframes: keyframes(14, 4) }]), expectedLaterRoute: 'updated' },
+ transform: { recipe: withMotion(recipe.motion.tracks), expectedLaterRoute: 'new-session', allowedRoutes: ['new-session', 'reused'] },
+ particles: { recipe: { ...recipe, motion: { ...recipe.motion, tracks: cameraTracks } }, expectedLaterRoute: 'new-session' },
};
}
@@ -85,7 +91,7 @@ await mkdir(outputDirectory, { recursive: true });
const variants = buildVariants(JSON.parse(await readFile('tests/fixtures/demo-room.recipe.json', 'utf8')));
const report = { width, height, samples, frames: STILLS_PER_JOB, variants: {} };
let failed = false;
-for (const [name, { recipe, expectedLaterRoutes }] of Object.entries(variants)) {
+for (const [name, { recipe, expectedLaterRoute, allowedRoutes = [expectedLaterRoute] }] of Object.entries(variants)) {
let withSessions;
let withoutSessions;
try {
@@ -98,8 +104,7 @@ for (const [name, { recipe, expectedLaterRoutes }] of Object.entries(variants))
}
const identical = withSessions.frameHashes.length === STILLS_PER_JOB && withSessions.frameHashes.every((hash, index) => hash === withoutSessions.frameHashes[index]);
const laterRoutes = withSessions.routes.slice(1);
- const routesAsExpected = withSessions.routes[0] === 'new-session' && withSessions.routes.length === STILLS_PER_JOB && laterRoutes.every(route => expectedLaterRoutes.includes(route))
- && (name === 'camera' ? laterRoutes.every(route => route === 'reused') : laterRoutes.some(route => route !== 'new-session'));
+ const routesAsExpected = withSessions.routes[0] === 'new-session' && withSessions.routes.length === STILLS_PER_JOB && laterRoutes.every(route => allowedRoutes.includes(route)) && laterRoutes.includes(expectedLaterRoute);
const sessionsOffRoutes = withoutSessions.routes;
report.variants[name] = { identical, routes: withSessions.routes, routesAsExpected, sessionsOffRoutes, backend: withSessions.backend, backendNote: withSessions.backendNote, lastFrameSession: withSessions.lastSession };
if (!identical || !routesAsExpected || sessionsOffRoutes.length > 0) failed = true;
diff --git a/docs/agent-render-jobs.md b/docs/agent-render-jobs.md
index 887d37f0..60c9a647 100644
--- a/docs/agent-render-jobs.md
+++ b/docs/agent-render-jobs.md
@@ -185,7 +185,7 @@ An `image`, `stills` or `video` job can ask for the offline [path tracer](https:
"renderer": { "type": "pathTracer", "backend": "gpu", "samples": 64, "bounces": 8, "denoise": true, "seed": 0, "maxSeconds": 120 } }
```
-Every field after `type` is optional. `backend` is `cpu` (the default, byte-identical on SwiftShader smokes), `gpu`, which traces in a WebGL2 shader and needs a runtime started on the GPU backend (a `--backend cpu` runtime refuses it), or `native`, which traces on hardware ray queries (Vulkan) through the optional `@codepawlhq/67js-render-native` package. A native job exports the scene from the job page, traces it in the job runner with the Cycles-matching kernel (`JS67_NATIVE_KERNEL=legacy` keeps the older one), then denoises (OIDN runs on a device kept alive between frames when the OIDN library is installed, so only the first frame pays for the device and the filter commit; `metrics.pathTracer.oidnMode` says `in-process` or `cli`) and writes the PNG as the other backends do: `denoise: true` means OIDN with the albedo and normal guides when `@codepawlhq/67js-denoise-oidn` and its binary are installed, else (or when OIDN fails) the GPU a-trous filter of the native tracer with a note in `metrics.pathTracer.denoiserNote` (`denoiser: "atrous"`; it is biased, it smooths; `denoise: "wavelet"` asks for the CPU filter). The report carries `kernel` and `averageSamples`. It never fails for lack of the package: without it, without its built binary or without a Vulkan ray query adapter the job runs on `gpu` (`cpu` on a cpu runtime) and `metrics.pathTracer.backendNote` says why; `metrics.pathTracer.backend` always names what ran. The look up costs one import and is cached per process. Native traces volume fog and subsurface scattering with the same walk as the WebGPU megakernel, honours `maxSeconds`, and honours `noiseThreshold` on the GPU (after 16 samples, and then every 8, a converged pixel draws no more; `report.averageSamples` is the mean a pixel drew). The `gpu` fallback ignores `noiseThreshold`. The report in `metrics.pathTracer` names the `backend` that ran, the `gpu`, `gpuCompileSeconds` and `gpuKernelCompiles`. A `stills` or `video` job traces every frame with the same options: the kernel compiles once per job page and each frame reuses it, so a film shows `gpuKernelCompiles: 1`. A native `stills` or `video` job (the Cycles-matching kernel) also keeps one native session for the whole job: a frame that only moves the camera reuses the uploaded scene, the compiled kernel and the acceleration structures; changed materials, lights or instance transforms are sent to the session; a frame whose counts, geometry, textures or environment changed gets a new session, and a failed session update or render falls back to a new session or a one-shot trace for that frame. `metrics.pathTracer.nativeSession` says which one each frame took (`path` is `new-session`, `reused`, `updated` or `one-shot`, with `reason`, `changedTables`, `pipelineReused` and `accelerationReused`); `metrics.nativeSessionRoutes` lists the `path` of every frame. A single-frame job and `JS67_NATIVE_KERNEL=legacy` trace one-shot and carry no `nativeSession`; `JS67_NATIVE_SESSIONS=off` in the server's environment traces every frame one-shot (default on). The session is closed when the job ends or fails, and every frame equals the one-shot render byte for byte. A video of traced frames goes through the ffmpeg encoder (the browser H.264 encoder has no drawn frame to read), `maxSeconds` limits each frame, and the job deadline is `maxSeconds` times the frame count plus 60 seconds, up to the job ceiling. Limits: `samples` 1 to 1024, `bounces` 1 to 16, `seed` 0 to 2147483647, `maxSeconds` 1 to 600 (the job's deadline is `maxSeconds` plus 60 seconds; a 1920 by 1080 still of a 180,000 triangle room at 64 samples took 246 s, so give a large still `maxSeconds` 600). `passes` are refused with it. The tracer loads in the job page on demand, uses eight threads at below-normal priority, stops pixels that have converged (`report.averageSamples`), and writes `render.png`; `scene_render_result` metrics carry `pathTracer` with the samples, threads, seconds and what the scene asked for that was not drawn. The same recipe and seed give the same PNG on the cpu and gpu backends; the native Cycles-matching kernel is not always byte-identical between runs (on the demo room at 960 by 540 and 256 samples two jobs differed in a few bytes; a 480 by 270 job with OIDN did not). A job that passes `maxSeconds` fails and writes no image.
+Every field after `type` is optional. `backend` is `cpu` (the default, byte-identical on SwiftShader smokes), `gpu`, which traces in a WebGL2 shader and needs a runtime started on the GPU backend (a `--backend cpu` runtime refuses it), or `native`, which traces on hardware ray queries (Vulkan) through the optional `@codepawlhq/67js-render-native` package. A native job exports the scene from the job page, traces it in the job runner with the Cycles-matching kernel (`JS67_NATIVE_KERNEL=legacy` keeps the older one), then denoises (OIDN runs on a device kept alive between frames when the OIDN library is installed, so only the first frame pays for the device and the filter commit; `metrics.pathTracer.oidnMode` says `in-process` or `cli`) and writes the PNG as the other backends do: `denoise: true` means OIDN with the albedo and normal guides when `@codepawlhq/67js-denoise-oidn` and its binary are installed, else (or when OIDN fails) the GPU a-trous filter of the native tracer with a note in `metrics.pathTracer.denoiserNote` (`denoiser: "atrous"`; it is biased, it smooths; `denoise: "wavelet"` asks for the CPU filter). The report carries `kernel` and `averageSamples`. It never fails for lack of the package: without it, without its built binary or without a Vulkan ray query adapter the job runs on `gpu` (`cpu` on a cpu runtime) and `metrics.pathTracer.backendNote` says why; `metrics.pathTracer.backend` always names what ran. The look up costs one import and is cached per process. Native traces volume fog and subsurface scattering with the same walk as the WebGPU megakernel, honours `maxSeconds`, and honours `noiseThreshold` on the GPU (after 16 samples, and then every 8, a converged pixel draws no more; `report.averageSamples` is the mean a pixel drew). The `gpu` fallback ignores `noiseThreshold`. The report in `metrics.pathTracer` names the `backend` that ran, the `gpu`, `gpuCompileSeconds` and `gpuKernelCompiles`. A `stills` or `video` job traces every frame with the same options: the kernel compiles once per job page and each frame reuses it, so a film shows `gpuKernelCompiles: 1`. A native `stills` or `video` job (the Cycles-matching kernel) also keeps one native session for the whole job: a frame that only moves the camera reuses the uploaded scene, the compiled kernel and the acceleration structures; changed materials, lights or instance transforms are sent to the session; a frame whose counts, geometry, textures or environment changed gets a new session, and a failed session update or render falls back to a new session or a one-shot trace for that frame. `metrics.pathTracer.nativeSession` says which one each frame took (`path` is `new-session`, `reused`, `updated` or `one-shot`, with `reason`, `changedTables`, `pipelineReused` and `accelerationReused`); `metrics.nativeSessionRoutes` lists the `path` of every frame. A job reuses the session only when the tables the page exports are equal to the previous frame's apart from the camera (`reused`), or differ in material values, lights or instance transforms only (`updated`). Anything that rebuilds geometry from the time, such as particle systems (sparks, swaying hair), a moved node in a scene exported as flattened triangles, or a changed emissive triangle count, gives every frame a new session, which costs what a one-shot trace costs and is byte-identical to it; `reason` names the first table that differed. A single-frame job and `JS67_NATIVE_KERNEL=legacy` trace one-shot and carry no `nativeSession`; `JS67_NATIVE_SESSIONS=off` in the server's environment traces every frame one-shot (default on). The session is closed when the job ends or fails, and every frame equals the one-shot render byte for byte. A video of traced frames goes through the ffmpeg encoder (the browser H.264 encoder has no drawn frame to read), `maxSeconds` limits each frame, and the job deadline is `maxSeconds` times the frame count plus 60 seconds, up to the job ceiling. Limits: `samples` 1 to 1024, `bounces` 1 to 16, `seed` 0 to 2147483647, `maxSeconds` 1 to 600 (the job's deadline is `maxSeconds` plus 60 seconds; a 1920 by 1080 still of a 180,000 triangle room at 64 samples took 246 s, so give a large still `maxSeconds` 600). `passes` are refused with it. The tracer loads in the job page on demand, uses eight threads at below-normal priority, stops pixels that have converged (`report.averageSamples`), and writes `render.png`; `scene_render_result` metrics carry `pathTracer` with the samples, threads, seconds and what the scene asked for that was not drawn. The same recipe and seed give the same PNG on the cpu and gpu backends; the native Cycles-matching kernel is not always byte-identical between runs (on the demo room at 960 by 540 and 256 samples two jobs differed in a few bytes; a 480 by 270 job with OIDN did not). A job that passes `maxSeconds` fails and writes no image.
## Controller API
diff --git a/docs/cycles-parity.md b/docs/cycles-parity.md
index 2ecbc09a..3bd3debe 100644
--- a/docs/cycles-parity.md
+++ b/docs/cycles-parity.md
@@ -923,6 +923,10 @@ Measured on one NVIDIA RTX 4090 (Vast instance, 24 frames, 480 x 270, 16 samples
What the numbers say `[inferred]`: a session removes the acceleration build and most of the upload from frame 2 on (camera-only: 0 ms against 0.9 to 2.0 ms of build, 0.1 against 0.3 ms of upload), and `pipelineReused` and `accelerationReused` are true on every later frame. Compile does not read zero: the 1.8 ms is the lookup of the process-wide compiled-kernel cache, which a one-shot trace also hits from its second frame, so a one-shot sequence in a warm process already skips the 33 ms compile and the 240 to 320 ms device start. These scenes hold about 3,000 triangles, so the saving is 1 to 3 ms of a 18 to 25 ms frame and the sequence totals sit within run-to-run noise (the instanced rows show the spread: 0.73 to 1.04 s for the same work). A moving object in the flattened scene changes the `triangles` table, so every frame there is a new session (as costly as a one-shot trace); only a scene packed with shared geometry turns a moved object into an instance-transform update.
+### Real jobs (8 stills through the MCP server, RTX 4090, page on SwiftShader, native tracer on the GPU)
+
+`bench/native-tracer/sequence-job.mjs` on the demo room, each variant run with sessions and with `JS67_NATIVE_SESSIONS=off`: every frame of every variant is byte-identical between the two runs. Routes of frames 2 to 8 `[measured]`: camera tracks only, `reused` on all 7; plus a roughness track, `updated` on all 7 (table `materials`); plus a point light intensity track, `updated` on all 7 (tables `lights`, `lightTreeNodes`, `lightTreeEmitters`); the recipe's own motion (a pendant swings), `new-session` on 6 and `reused` on 1 (the swing returned to an earlier pose), because the flattened export holds the pendant's triangles; with the sparks and fur particle systems left in, `new-session` on all 7 (`emissiveTriangleCount` changes from frame to frame). Cause, found by diffing the page export between times in Node (`[measured]`): the demo room's `particles` (sparks emit glowing triangles over time, hair sways) rebuild the triangle and emissive tables at every time, so a camera-only edit of the recipe with its particles left in still changes `triangles`; with them removed only the camera block differs. The export itself is deterministic and does not cull by camera. A session cannot keep the acceleration structure across a change of the emissive or triangle count: `update` refuses a count change by design, because the BLAS holds the triangles and the session's buffers and bind group are sized at creation; allowing it needs a Rust change to re-create the emissive, light and light tree buffers and the bind group (and re-specialize the kernel) while keeping the BLAS, which is not worth it while the triangles change in the same frames.
+
### Large scenes (12 frames, same card)
Generated scenes from `bench/cycles-parity/large-scene.mjs` through `large-sequence-timing.mjs` (480 x 270, 16 samples, medians of three runs, session against one-shot on identical inputs; every frame of every run is byte-identical between the two modes). "Camera" orbits the camera and runs first in the process, so its frame 1 includes the 300 to 400 ms start of the device; "moving" orbits the camera and alternates one instance between two placements every frame (an instance-table update, the TLAS rebuilt over the kept BLAS), and runs second in a warm process. `[measured]`