3D engine that AI agents drive
Fix web export retention and game disposal (#777)
Nguyen Xuan Anf7eee5896a3b
diff --git a/bench/parity/blender-inventory-report.md b/bench/parity/blender-inventory-report.mdindex 1827189a..3ac5bef0 100644--- a/bench/parity/blender-inventory-report.md+++ b/bench/parity/blender-inventory-report.md@@ -1,6 +1,6 @@# Blender 5.2.2 LTS inventory against 67js-Generated by `node scripts/blender-inventory-compare.mjs` from `bench/parity/blender-inventory.json` (`scripts/blender-inventory.py`, factory settings). 67js side: `docs/parity.md`, `scene_capabilities` and 23 MCP tools.+Generated by `node scripts/blender-inventory-compare.mjs` from `bench/parity/blender-inventory.json` (`scripts/blender-inventory.py`, factory settings). 67js side: `docs/parity.md`, `scene_capabilities` and 24 MCP tools.Node-tree, physics and render statuses are read from the ledger notes and the capability lists by hand-kept tables in the compare script; they are inferred, not measured. Modifier and constraint statuses are the ledger's own rows.@@ -10,8 +10,8 @@ Blender build: 2499 operators in 77 categories, 1239 panels, 790 menus, 83 modif| Area | Blender items | done | partial | missing | out of scope | not in ledger | Basis || --- | --- | --- | --- | --- | --- | --- | --- |-| Modifiers | 83 | 10 | 23 | 23 | 27 | 0 | per-item ledger rows |-| Constraints (object and bone share one list) | 29 | 0 | 12 | 14 | 3 | 0 | per-item ledger rows |+| Modifiers | 83 | 10 | 25 | 21 | 27 | 0 | per-item ledger rows |+| Constraints (object and bone share one list) | 29 | 0 | 24 | 2 | 3 | 0 | per-item ledger rows || Geometry nodes | 321 | 8 | 150 | 145 | 18 | 0 | status by category (inferred) || Shader nodes | 100 | 1 | 93 | 2 | 4 | 0 | status by category (inferred) || Compositor nodes | 90 | 1 | 32 | 53 | 4 | 0 | status by category (inferred) |@@ -21,17 +21,17 @@ Blender build: 2499 operators in 77 categories, 1239 panels, 790 menus, 83 modif## Modifiers-Missing: Data Transfer, Mesh Cache, Normal Edit, UV Warp, Vertex Weight Edit, Vertex Weight Mix, Vertex Weight Proximity, Build, Mask, Mesh to Volume, Multiresolution, Volume to Mesh, Laplacian Deform, Mesh Deform, Smooth Corrective, Smooth Laplacian, Surface Deform, Warp, Volume Displace, Dynamic Paint, Explode, Ocean, Soft Body.+Missing: Data Transfer, Mesh Cache, Normal Edit, UV Warp, Vertex Weight Edit, Vertex Weight Mix, Vertex Weight Proximity, Mask, Mesh to Volume, Multiresolution, Volume to Mesh, Laplacian Deform, Mesh Deform, Smooth Corrective, Smooth Laplacian, Surface Deform, Warp, Volume Displace, Dynamic Paint, Explode, Soft Body.-Partial: Mesh Sequence Cache, Weighted Normal, UV Project, Boolean, Decimate, Geometry Nodes, Remesh, Screw, Skin, Wireframe, Armature, Cast, Curve, Hook, Lattice, Shrinkwrap, Simple Deform, Wave, Cloth, Collision, Fluid, Particle Instance, Particle System.+Partial: Mesh Sequence Cache, Weighted Normal, UV Project, Boolean, Build, Decimate, Geometry Nodes, Remesh, Screw, Skin, Wireframe, Armature, Cast, Curve, Hook, Lattice, Shrinkwrap, Simple Deform, Wave, Cloth, Collision, Fluid, Ocean, Particle Instance, Particle System.Not in the ledger: none.## Constraints-Missing: Copy Transforms, Limit Distance, Limit Scale, Maintain Volume, Transformation, Transform Cache, Clamp To, Locked Track, Spline IK, Stretch To, Action, Armature, Geometry Attribute, Pivot.+Missing: Transform Cache, Geometry Attribute.-Partial: Copy Location, Copy Rotation, Copy Scale, Limit Location, Limit Rotation, Damped Track, Inverse Kinematics, Track To, Child Of, Floor, Follow Path, Shrinkwrap.+Partial: Copy Location, Copy Rotation, Copy Scale, Copy Transforms, Limit Distance, Limit Location, Limit Rotation, Limit Scale, Maintain Volume, Transformation, Clamp To, Damped Track, Inverse Kinematics, Locked Track, Spline IK, Stretch To, Track To, Action, Armature, Child Of, Floor, Follow Path, Pivot, Shrinkwrap.Out of scope: Camera Solver, Follow Track, Object Solver.@@ -192,12 +192,12 @@ Blender has 1239 panels in 14 editors: CLIP_EDITOR 42, DOPESHEET_EDITOR 22, FILE| Material | 25 | 8 | Displacement, Preview, Settings, Surface, Volume, CYCLES_PT_context_material | materialTags, materialLayers, materialSubsurface, materialGraph, materialPatterns, materialMappings, alphaModes | scene_apply || Texture | 18 | 7 | Animation, Blend, Clouds, Colors, TEXTURE_PT_context, Custom Properties | materialPatterns, materialGraph | scene_apply |-Capability keys that fit no tab: format, schemaVersion, navigation, maxMaterialPatterns, importedMeshEdits, fixedResources, dynamicTopology, positiveScaleOnly, gltfImport, authoredLook, defaultLightingSetup, localShadows, proceduralMotion, motionLimits.+Capability keys that fit no tab: format, schemaVersion, camera, navigation, meshAttributes, meshUv, meshBoolean, meshShapeKeys, maxMaterialPatterns, importedMeshEdits, fixedResources, dynamicTopology, positiveScaleOnly, gltfImport, authoredLook, catalogLooks, physicalSky, defaultLightingSetup, localShadows, localVolumes, renderFlags, proceduralMotion, motionLook, motionModifiers, motionLimits, motionBake.## Suggestions-1. Add a `tabs` index to `scene_capabilities` that lists, in the Properties editor order (Render, Output, View Layer, Scene, World, Object, Modifiers, Particles, Physics, Constraints, Data, Material, Texture), the capability keys and the tool that edits each. `scene_capabilities` is a flat object of 55 keys; an agent that knows Blender looks for a tab, not a key name. The table above is a first draft of that index.-2. Offer Blender's terms as aliases in the index, without renaming keys: `meshModifiers` and `meshStack` under "Modifiers", `motionConstraints` under "Constraints", `viewTransform` under "Color Management", `renderPasses` under "View Layer". Stack operations without a Blender modifier name: uv_unwrap, set_position, smooth_by_angle (`subdivide` is Blender's Subdivision Surface; accept `subdivision_surface` and `subsurf` as input aliases).+1. Add a `tabs` index to `scene_capabilities` that lists, in the Properties editor order (Render, Output, View Layer, Scene, World, Object, Modifiers, Particles, Physics, Constraints, Data, Material, Texture), the capability keys and the tool that edits each. `scene_capabilities` is a flat object of 67 keys; an agent that knows Blender looks for a tab, not a key name. The table above is a first draft of that index.+2. Offer Blender's terms as aliases in the index, without renaming keys: `meshModifiers` and `meshStack` under "Modifiers", `motionConstraints` under "Constraints", `viewTransform` under "Color Management", `renderPasses` under "View Layer". Stack operations without a Blender modifier name: uv_unwrap, uv_pack, set_position, smooth_by_angle, bounding_box, convex_hull (`subdivide` is Blender's Subdivision Surface; accept `subdivision_surface` and `subsurf` as input aliases).3. Order `docs/guide.md` and the tool descriptions by the same tab order, and give each tab one line that names the Blender tab, so a search for "Physics tab" or "Modifiers tab" lands on the right page.4. Keep Blender's identifiers where 67js already matches them (weld, edge_split, simple_deform, smooth_by_angle, weighted_normal); constraints without a Blender name: none.diff --git a/scripts/agent-runtime.mjs b/scripts/agent-runtime.mjsindex 1f304f2a..be1ae2d2 100644--- a/scripts/agent-runtime.mjs+++ b/scripts/agent-runtime.mjs@@ -1061,10 +1061,17 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', brow// Same name rule as GLB exports: the server picks the folder, and only the newest few are kept.const directory = join(jobRoot, EXPORT_DIRECTORY_NAME);await mkdir(directory, { recursive: true, mode: 0o700 });- while (savedWebBuildPaths.length >= MAXIMUM_KEPT_WEB_BUILDS) await rm(savedWebBuildPaths.shift(), { recursive: true, force: true });const outputDirectory = join(directory, `web-${randomUUID()}`);+ let summary;+ try {+ summary = await writeWebBuild({ recipe, buildDirectory: fileURLToPath(new URL('../', previewUrl)), outputDirectory, title });+ } catch (error) {+ // A refused or half-written build never uses up a retention slot or evicts a good one.+ await rm(outputDirectory, { recursive: true, force: true });+ throw error;+ }savedWebBuildPaths.push(outputDirectory);- const summary = await writeWebBuild({ recipe, buildDirectory: fileURLToPath(new URL('../', previewUrl)), outputDirectory, title });+ while (savedWebBuildPaths.length > MAXIMUM_KEPT_WEB_BUILDS) await rm(savedWebBuildPaths.shift(), { recursive: true, force: true });return { sessionId, revision, ...summary, entry: join(outputDirectory, 'index.html'), host: 'Serve the folder with any static file server; no server code runs.' };});},diff --git a/src/game.js b/src/game.jsindex 11caee89..7598bf4d 100644--- a/src/game.js+++ b/src/game.js@@ -83,9 +83,33 @@ function describeState(state) {/*** Start the game a recipe describes on a canvas and return its parts: `scene`, `runtime`, `rules`, `input`, `controller`, `renderer`- * and `dispose()`. Options: `replay` (a recording from recordInput; the keyboard is not attached) and `showStatus` (default true).+ * and `dispose()`. Options: `replay` (a recording from recordInput; the keyboard is not attached) `showStatus` (default true) and `createRenderer` (tests pass a stand-in for the WebGL renderer).*/-export async function startGame(canvas, recipe, { replay, showStatus = true } = {}) {+export async function startGame(canvas, recipe, options = {}) {+ const cleanups = [];+ try {+ const game = await buildGame(canvas, recipe, options, cleanups);+ let disposed = false;+ return {+ ...game,+ dispose() {+ if (disposed) return;+ disposed = true;+ runCleanups(cleanups);+ },+ };+ } catch (error) {+ runCleanups(cleanups);+ throw error;+ }+}++// Each resource registers its cleanup as it is created; they run newest first.+function runCleanups(cleanups) {+ while (cleanups.length > 0) cleanups.pop()();+}++async function buildGame(canvas, recipe, { replay, showStatus = true, createRenderer = (...rendererArguments) => new Renderer67(...rendererArguments) }, cleanups) {const setup = recipe.game;if (!setup) throw new Error('startGame needs a recipe with a game section. Add one with the set-game operation.');await loadAgentSceneModules(recipe);@@ -93,7 +117,7 @@ export async function startGame(canvas, recipe, { replay, showStatus = true } =const { game } = scene.exportRecipe();const placement = agentGroundPlacement(scene.parts, scene.environment);const environment = litEnvironment(scene, Boolean(placement));- const renderer = new Renderer67(canvas, scene.parts, {+ const renderer = createRenderer(canvas, scene.parts, {ground: placement ? createAgentGround(placement) : false,hdr: true,depth: true,@@ -101,6 +125,7 @@ export async function startGame(canvas, recipe, { replay, showStatus = true } =environment,pixelRatio: Math.min(globalThis.devicePixelRatio ?? 1, 2),});+ cleanups.push(() => renderer.dispose());const { actions, axes } = inputDefinition(game.input);const input = createInput({ sources: replay ? [replaySource(replay)] : inputSources(game.input, canvas), actions, axes });@@ -126,6 +151,7 @@ export async function startGame(canvas, recipe, { replay, showStatus = true } =const shownNodes = new Map();let drawnTopology = scene.topologyRevision;const status = showStatus && rules ? createStatusLine(canvas) : null;+ if (status) cleanups.push(() => status.remove());const sceneSystem = {name: 'scene',@@ -154,17 +180,12 @@ export async function startGame(canvas, recipe, { replay, showStatus = true } =systems: [input, controller, rig, ...(rules ? [rules] : []), sceneSystem],frame: context => ({ ...baseCamera, ...rig.pose(context), environment, time: context.elapsedSeconds }),});+ cleanups.push(() => runtime.dispose());const resize = () => renderer.resize();globalThis.addEventListener?.('resize', resize);+ cleanups.push(() => globalThis.removeEventListener?.('resize', resize));resize();runtime.start();- return {- scene, runtime, rules, input, controller, renderer,- dispose() {- globalThis.removeEventListener?.('resize', resize);- runtime.dispose();- status?.remove();- },- };+ return { scene, runtime, rules, input, controller, renderer };}diff --git a/tests/agent-runtime.test.js b/tests/agent-runtime.test.jsindex d674f980..fb6b7333 100644--- a/tests/agent-runtime.test.js+++ b/tests/agent-runtime.test.js@@ -1,8 +1,13 @@-import test from 'node:test';+import test, { after } from 'node:test';import assert from 'node:assert/strict';import { createAgentRuntime } from '../scripts/agent-runtime.mjs';import { isPreviewHost } from '../scripts/preview-host.mjs';-import { readFile } from 'node:fs/promises';+import { mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { isAbsolute, join } from 'node:path';+import { fileURLToPath, pathToFileURL } from 'node:url';+import { writeWebBuild } from '../scripts/web-export.mjs';+import { EXPORT_DIRECTORY_NAME } from '../scripts/agent-render-jobs.mjs';import { createServer } from 'node:http';import { randomUUID } from 'node:crypto';import { createContext, Script } from 'node:vm';@@ -44,7 +49,7 @@ test('runtime reports real scene capabilities without launching a browser and cl});async function reviewRuntimeHarness({ failShot, blockShot = false, oversize = false, deadlineMs,- failDispose = false, heapSize = 1024, stallPrivatePage = false, resumeDelayMs = 0, sceneBake } = {}) {+ failDispose = false, heapSize = 1024, stallPrivatePage = false, resumeDelayMs = 0, sceneBake, exportedRecipe, runtimeOptions = {}, contextOverrides = {} } = {}) {const events = [];const deadlines = [];let privatePage;@@ -69,6 +74,7 @@ async function reviewRuntimeHarness({ failShot, blockShot = false, oversize = faasync evaluate(callback, { method, input }) {events.push(`${this.privateTarget ? 'private' : 'source'}:${method}`);if (method === 'create') return { sessionId: input.sessionId, revision: 0 };+ if (method === 'exportRecipe') return { recipe: exportedRecipe, revision: 1 };if (method === 'snapshot') {if (input.expectedRevision !== sourceRevision) throw new Error('Stale revision for render snapshot.');return { sourceRevision, recipe };@@ -117,9 +123,10 @@ async function reviewRuntimeHarness({ failShot, blockShot = false, oversize = farecipeAssetNeeds, sequenceFrameIds, catalogLookReferences, BUNDLED_ENVIRONMENT_NAMES, BUNDLED_CUBE_LOOK_NAMES, TEXTURE_SEQUENCE_CAPABILITIES, AGENT_ASSET_LIMITS, assertCombinedAssetBytes,audioInputArguments, createAudioLibrary, measureStreamSeconds, filmTimelineDuration, filmTimelineShotStarts, sampleFilmTimeline, normalizeReview, REVIEW_LIMITS, isPreviewHost, BRANCH_LIMITS, validateBranchName, sessionProblem, SCENE_STORE_LIMITS,chromium: { launch: async () => browser }, URL, Buffer, process, performance, clearTimeout,+ runtimeOptions, mkdir, rm, join, isAbsolute, fileURLToPath, writeWebBuild, EXPORT_DIRECTORY_NAME, createAgentRenderJobs: async () => ({ list: () => [], close: async () => {} }), ...contextOverrides,setTimeout: (callback, delay) => { deadlines.push(delay); return setTimeout(callback, delay); },});- new Script(`${source}\nglobalThis.runtime = createAgentRuntime({ backend: 'cpu' });`).runInContext(context);+ new Script(`${source}\nglobalThis.runtime = createAgentRuntime({ backend: 'cpu', ...runtimeOptions });`).runInContext(context);const runtime = context.runtime;const created = await runtime.create({ recipe });return { runtime, sessionId: created.sessionId, deadlines, events, shotStarted, acquisitionStarted, resolvePrivatePage };@@ -306,3 +313,70 @@ test('the preview server accepts only its own loopback host', () => {assert.equal(isPreviewHost('127.0.0.1:4101', 4100), false);assert.equal(isPreviewHost(undefined, 4100), false);});++async function webExportHarness({ exportedRecipe, failCopy = () => false } = {}) {+ const root = await mkdtemp(join(tmpdir(), '67js-web-runtime-'));+ const buildDirectory = join(root, 'build');+ await mkdir(join(buildDirectory, 'mcp'), { recursive: true });+ await writeFile(join(buildDirectory, 'game.js'), 'export {};');+ const jobsDirectory = join(root, 'jobs');+ await mkdir(jobsDirectory);+ const failingWriteWebBuild = async options => {+ if (failCopy()) {+ await mkdir(join(options.outputDirectory, 'engine'), { recursive: true });+ throw new Error('Injected copy failure');+ }+ return writeWebBuild(options);+ };+ const harness = await reviewRuntimeHarness({+ exportedRecipe,+ runtimeOptions: { jobs: jobsDirectory, previewUrl: pathToFileURL(join(buildDirectory, 'mcp', 'preview.js')) },+ contextOverrides: { writeWebBuild: failingWriteWebBuild },+ });+ const keptBuilds = async () => (await readdir(join(jobsDirectory, EXPORT_DIRECTORY_NAME))).filter(name => name.startsWith('web-'));+ after(() => harness.runtime.close());+ return { ...harness, keptBuilds };+}++const PLAYABLE_RECIPE = { format: '67js.scene', schemaVersion: 1, geometries: [], materials: [], nodes: [], game: { player: { node: 'creature' }, physics: false } };++test('exportWeb keeps only the newest four builds and returns a real entry page', async () => {+ const { runtime, sessionId, keptBuilds } = await webExportHarness({ exportedRecipe: PLAYABLE_RECIPE });+ const entries = [];+ for (let index = 0; index < 5; index++) entries.push((await runtime.exportWeb({ sessionId })).entry);+ assert.equal((await keptBuilds()).length, 4);+ await assert.rejects(stat(entries[0]), { code: 'ENOENT' });+ for (const entry of entries.slice(1)) assert.ok((await stat(entry)).isFile());+});++test('a half-written web export is removed and never evicts or uses up a kept build', async () => {+ let breakCopy = false;+ const { runtime, sessionId, keptBuilds } = await webExportHarness({ exportedRecipe: PLAYABLE_RECIPE, failCopy: () => breakCopy });+ const goodEntries = [];+ for (let index = 0; index < 4; index++) goodEntries.push((await runtime.exportWeb({ sessionId })).entry);+ breakCopy = true;+ for (let attempt = 0; attempt < 5; attempt++) await assert.rejects(runtime.exportWeb({ sessionId }), /Injected copy failure/);+ assert.equal((await keptBuilds()).length, 4);+ for (const entry of goodEntries) assert.ok((await stat(entry)).isFile());+});++test('exportWeb refuses a scene without a game or with physics, and earlier builds stay', async () => {+ const { runtime, sessionId, keptBuilds } = await webExportHarness({ exportedRecipe: PLAYABLE_RECIPE });+ await runtime.exportWeb({ sessionId });+ const refused = [+ [{ ...PLAYABLE_RECIPE, game: undefined }, /no game/],+ [{ ...PLAYABLE_RECIPE, game: { ...PLAYABLE_RECIPE.game, physics: true } }, /game\.physics is true/],+ ];+ for (const [recipe, message] of refused) {+ const refusing = await webExportHarness({ exportedRecipe: recipe });+ for (let attempt = 0; attempt < 5; attempt++) await assert.rejects(refusing.runtime.exportWeb({ sessionId: refusing.sessionId }), message);+ assert.equal((await refusing.keptBuilds().catch(() => [])).length, 0);+ }+ assert.equal((await keptBuilds()).length, 1);+});++test('exportWeb needs a jobs folder', async () => {+ const harness = await reviewRuntimeHarness({ exportedRecipe: PLAYABLE_RECIPE });+ after(() => harness.runtime.close());+ await assert.rejects(harness.runtime.exportWeb({ sessionId: harness.sessionId }), /--jobs/);+});diff --git a/tests/game-start.test.js b/tests/game-start.test.jsnew file mode 100644index 00000000..d3965f35--- /dev/null+++ b/tests/game-start.test.js@@ -0,0 +1,68 @@+import './support/load-agent-scene-modules.mjs';+import test from 'node:test';+import assert from 'node:assert/strict';+import { createAgentScene } from '../src/agent-scene.js';+import { startGame } from '../src/game.js';++const EMPTY_RECORDING = { version: 1, samples: 0, events: [] };++function gameRecipe() {+ const scene = createAgentScene({+ format: '67js.scene', schemaVersion: 1,+ geometries: [{ id: 'block', type: 'box' }], materials: [{ id: 'paint', color: [0.5, 0.5, 0.5] }],+ nodes: [{ id: 'creature', geometry: 'block', material: 'paint' }],+ });+ scene.apply([{ type: 'set-game', game: { player: { node: 'creature' } } }], { expectedRevision: scene.revision });+ return scene.exportRecipe();+}++function standInRenderer() {+ const renderer = {+ disposeCalls: 0,+ render() {},+ resize() {},+ updateParts() {},+ replaceParts() {},+ dispose() { renderer.disposeCalls++; },+ };+ return renderer;+}++function withAnimationFrameStubs() {+ const previous = { request: globalThis.requestAnimationFrame, cancel: globalThis.cancelAnimationFrame };+ globalThis.requestAnimationFrame = () => 1;+ globalThis.cancelAnimationFrame = () => {};+ return () => {+ globalThis.requestAnimationFrame = previous.request;+ globalThis.cancelAnimationFrame = previous.cancel;+ };+}++test('disposing a started game disposes its renderer exactly once', async () => {+ const restore = withAnimationFrameStubs();+ try {+ const renderer = standInRenderer();+ const game = await startGame({}, gameRecipe(), { replay: EMPTY_RECORDING, showStatus: false, createRenderer: () => renderer });+ assert.equal(renderer.disposeCalls, 0);+ game.dispose();+ game.dispose();+ assert.equal(renderer.disposeCalls, 1);+ } finally {+ restore();+ }+});++test('a start that fails after the renderer exists disposes the renderer and rethrows', async () => {+ const restore = withAnimationFrameStubs();+ try {+ const renderer = standInRenderer();+ const badReplay = { version: 1, samples: 0, events: 'not a list' };+ await assert.rejects(+ startGame({}, gameRecipe(), { replay: badReplay, showStatus: false, createRenderer: () => renderer }),+ /replaySource needs a recording/,+ );+ assert.equal(renderer.disposeCalls, 1);+ } finally {+ restore();+ }+});