3D engine that AI agents drive
Keep the HDRI map cache out of the view-transform entry, size notes, catalog tests (issue #608)
Nguyen Xuan An8d6f89d37ba2
diff --git a/changes/608.size.md b/changes/608.size.mdindex ff044bbe..4859b752 100644--- a/changes/608.size.md+++ b/changes/608.size.md@@ -1,2 +1,6 @@-- scene:agent-scene+lazy: HDRI and .cube catalog entries need a small registry and two validated fields; decoding happens in the preview page, not in the recipe code.-- goal:agent-scene: about 100 KB of shipped HDRI and LUT files in assets/looks (four files, 128 x 64 and 9-point), not in any bundle; a bigger HDRI comes from the asset catalog.+- entry:view-transform-shader: a catalog .cube look is looked up by name in the renderer's look resolver (164 bytes gzip), so a recipe's look can be a shipped or catalog .cube file.+- scene:agent-scene+lazy: HDRI and .cube catalog entries add the name lists, the registry, two validated fields (hdri, look) and a capabilities entry (about 640 bytes gzip); the decoding runs in the preview page, not in the recipe code.+- goal:agent-scene: about 100 KB of shipped files in assets/looks (four files: two 128 x 64 HDRIs, two 9-point looks) sit outside every bundle; a bigger HDRI comes from the asset catalog.+- tool-total: the new hdri field and the wider look field in the one shared environment schema (343 bytes), the only MCP surface for catalog HDRIs and .cube looks.+- tool:scene_create: the hdri field and the wider look field (343 bytes), with names listed as an enum so an agent cannot guess a path.+- result:scene_capabilities: the catalogLooks entry lists the shipped HDRI and look names (308 bytes), so an agent finds them without a call to the docs.diff --git a/docs/mcp.md b/docs/mcp.mdindex c655fe83..27c34f59 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -123,7 +123,7 @@ Inspect or export the recipe before retrying. Context loss still permits recipe| --- | --- | --- || `scene_capabilities` | None | Features, limits, and backend information || `scene_create` | `recipe` | Session ID, revision, inspection, and render status |-| `scene_asset_catalog` | None | Configured catalog and content-bound GLB IDs |+| `scene_asset_catalog` | None | Configured catalog and content-bound GLB, image, `.hdr` (kind `environment`) and `.cube` (kind `look`) IDs; an ID goes in `environment.hdri` or `environment.look`, see [agent-look](agent-look.md#catalog-hdris-and-looks) || `scene_create_asset` | `recipe` using `67js.asset` | Imported scene ID, revision, inspection and render status || `scene_inspect` | `sessionId`, optional `ids`, `limit`, `includeBounds` | Compact node records and revision || `scene_apply` | `sessionId`, `expectedRevision`, `operations` | Updated revision, inspection, and render status |diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex c69ec580..0d061e1a 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -200,7 +200,7 @@ const environment = z.strictObject({ground: z.boolean().optional().describe('false: no automatic floor.'),setup: z.enum(LIGHTING_SETUP_NAMES).optional().describe('Named lighting; resets key, fill and ambient fields. Default daylight.'),environmentIntensity: bounded(0, 100).optional().describe('Scales the setup environment light and its reflections.'),- hdri: z.union([z.enum(BUNDLED_ENVIRONMENT_NAMES), z.string().regex(CATALOG_FILE_ID)]).nullable().optional().describe('HDRI that lights and reflects instead of the setup sky: a shipped name or the ID of a .hdr file in scene_asset_catalog. environmentIntensity and environmentRotation apply; set keyIntensity 0 when it has its own sun.'),+ hdri: z.union([z.enum(BUNDLED_ENVIRONMENT_NAMES), z.string().regex(CATALOG_FILE_ID)]).nullable().optional().describe('HDRI instead of the setup sky; scene_capabilities catalogLooks.'),environmentRotation: bounded(-100, 100).optional().describe('Turns the setup environment around the vertical axis, in radians.'),lightDirection: boundedVector(-1e6, 1e6).optional().describe('Direction toward the key light; shadows follow.'),keyColor: boundedVector(0, 1000).optional(),@@ -254,7 +254,7 @@ const environment = z.strictObject({specularAntiAliasing: z.number().min(0).max(4).optional().describe('Specular anti-aliasing: 0 off, 1 default; widens highlights that sparkle on grainy normal-mapped metal.'),resolveCoplanar: z.union([z.literal('offset'), z.literal(false)]).optional().describe("'offset' biases the smaller part of each coplanar pair at draw time; false clears."),viewTransform: z.enum(VIEW_TRANSFORM_NAMES).optional().describe('Display transform, for example agx to compare with Blender.'),- look: z.union([z.enum([...LOOK_NAMES, ...BUNDLED_CUBE_LOOK_NAMES]), z.string().regex(CATALOG_FILE_ID)]).nullable().optional().describe('Look: a named preset, a shipped .cube name, or the ID of a .cube file in scene_asset_catalog; null clears.'),+ look: z.union([z.enum([...LOOK_NAMES, ...BUNDLED_CUBE_LOOK_NAMES]), z.string().regex(CATALOG_FILE_ID)]).nullable().optional().describe('Look preset or .cube; scene_capabilities catalogLooks. null clears.'),wind: z.strictObject({ strength: bounded(0, 4).optional(), direction: bounded(-360, 360).optional().describe('Degrees: 0 toward +x, 90 toward +z.') }).optional().describe('Sway of foliage and grass materials; strength defaults to 0.3.'),});// The full environment schema is published once, in scene_create. A JSON Schema $ref can not point from one tool'sdiff --git a/src/agent-look.js b/src/agent-look.jsindex 132a4370..37840c8e 100644--- a/src/agent-look.js+++ b/src/agent-look.js@@ -3,10 +3,10 @@ import { createLightingState, updateLightingState, MAX_POINT_LIGHTS, MAX_SPOT_LIimport { resolveEffects } from './effects.js';import { resolveVolumeFog } from './volumetric.js';import { LIQUID_OPTICS, resolveLiquidOptics } from './liquid-optics.js';-import { createLightingSetupMap, lightingSetupFields } from './lighting-setups.js';+import { createLightingSetupMap, createCatalogEnvironmentMap, lightingSetupFields } from './lighting-setups.js';import { agentSceneModule } from './agent-scene-modules.js';import { VIEW_TRANSFORM_NAMES, LOOK_NAMES } from './view-transform-names.js';-import { BUNDLED_ENVIRONMENT_NAMES, BUNDLED_CUBE_LOOK_NAMES, isEnvironmentReference, isCubeLookReference, catalogEnvironmentMap } from './look-catalog.js';+import { BUNDLED_ENVIRONMENT_NAMES, BUNDLED_CUBE_LOOK_NAMES, isEnvironmentReference, isCubeLookReference } from './look-catalog.js';import { DEFAULT_LIGHTING_SETUP, LIGHTING_SETUP_NAMES, DEFAULT_AMBIENT_OCCLUSION } from './agent-scene-capabilities.js';// The longest list in a look is the longest light list.@@ -355,7 +355,7 @@ export function environmentPatchWithSetup(patch) {/** The procedural environment map that lights a normalized environment; the same object returns while inputs hold. */export function agentEnvironmentMap(environment) {if (environment.hdri) {- return catalogEnvironmentMap(environment.hdri, { intensity: environment.environmentIntensity, rotation: environment.environmentRotation, showBackground: environment.world });+ return createCatalogEnvironmentMap(environment.hdri, { intensity: environment.environmentIntensity, rotation: environment.environmentRotation, showBackground: environment.world });}return createLightingSetupMap(environment.setup, {intensity: environment.environmentIntensity,diff --git a/src/agent-scene-capabilities.js b/src/agent-scene-capabilities.jsindex 5f62fd5e..c1636372 100644--- a/src/agent-scene-capabilities.js+++ b/src/agent-scene-capabilities.js@@ -216,7 +216,7 @@ export const AGENT_SCENE_CAPABILITIES = Object.freeze({fixedResources: false, dynamicTopology: true, checkpoints: true, positiveScaleOnly: true,gltfImport: 'Optional extensions and line primitives load with a warning; unlit and punctual lights are read.',authoredLook: true, maxPointLights: MAX_POINT_LIGHTS,- catalogLooks: Object.freeze({ hdri: 'environment.hdri', hdris: BUNDLED_ENVIRONMENT_NAMES, cubeLooks: BUNDLED_CUBE_LOOK_NAMES, look: 'environment.look', catalogId: '64-hex ID of a .hdr or .cube file in scene_asset_catalog', note: 'environmentIntensity is strength, environmentRotation turns it; set keyIntensity 0 when the HDRI has a sun; docs/agent-look.md' }),+ catalogLooks: Object.freeze({ hdri: 'environment.hdri', hdris: BUNDLED_ENVIRONMENT_NAMES, cubeLooks: BUNDLED_CUBE_LOOK_NAMES, look: 'environment.look', catalogId: '64-hex ID of a .hdr or .cube in scene_asset_catalog', note: 'environmentIntensity and environmentRotation apply; keyIntensity 0 if the HDRI has a sun' }),lightingSetups: LIGHTING_SETUP_NAMES, defaultLightingSetup: DEFAULT_LIGHTING_SETUP,ambientOcclusion: Object.freeze({ default: DEFAULT_AMBIENT_OCCLUSION, defaultRadius: 0.5, off: 0 }),// Local lights: spot and rectangular area lights. Shadows share one 2048 x 3072 depth atlas of 24 tiles; a shadoweddiff --git a/src/lighting-setups.js b/src/lighting-setups.jsindex f9958ed5..0c18d52c 100644--- a/src/lighting-setups.js+++ b/src/lighting-setups.js@@ -1,5 +1,6 @@import { createEnvironmentMap } from './environment.js';import { LIGHTING_SETUP_NAMES } from './agent-scene-capabilities.js';+import { catalogEnvironmentSource, environmentRegistrationCount } from './look-catalog.js';const MAP_WIDTH = 128;const MAP_HEIGHT = 64;@@ -113,3 +114,15 @@ export function createLightingSetupMap(name, { intensity = 1, rotation = 0, showmapsByKey.set(key, map);return map;}++/** The environment map of a registered catalog HDRI; the same object returns while name, strength, rotation, background and registered data hold. */+export function createCatalogEnvironmentMap(reference, { intensity = 1, rotation = 0, showBackground = false } = {}) {+ const key = ['catalog', reference, environmentRegistrationCount(), intensity, rotation, showBackground].join('|');+ if (!mapsByKey.has(key)) {+ if (mapsByKey.size >= MAXIMUM_CACHED_MAPS) {+ mapsByKey.clear();+ }+ mapsByKey.set(key, createEnvironmentMap({ ...catalogEnvironmentSource(reference), intensity, rotation, showBackground }));+ }+ return mapsByKey.get(key);+}diff --git a/src/look-catalog.js b/src/look-catalog.jsindex 279b68b9..6cb409e2 100644--- a/src/look-catalog.js+++ b/src/look-catalog.js@@ -1,5 +1,3 @@-import { createEnvironmentMap } from './environment.js';-// HDRI environments and .cube looks a recipe names. A recipe never carries a path or a URL: it names one of the entries// shipped in assets/looks, or the SHA-256 ID of a .hdr or .cube file in the MCP asset catalog. The host (the MCP runtime,// or an app that calls the register functions) decodes the file and registers it here before the scene builds.@@ -13,10 +11,9 @@ export const BUNDLED_CUBE_LOOK_NAMES = Object.freeze(['teal-orange', 'noir']);export const CATALOG_FILE_ID = /^[a-f0-9]{64}$/;export const MAXIMUM_CATALOG_LOOK_BYTES = 4 * 1024 * 1024;-const MAXIMUM_CACHED_MAPS = 16;const environmentSources = new Map();+let registrationCount = 0;const cubeLooks = new Map();-const mapsByKey = new Map();export function isEnvironmentReference(reference) {return BUNDLED_ENVIRONMENT_NAMES.includes(reference) || CATALOG_FILE_ID.test(reference);@@ -30,7 +27,7 @@ export function isCubeLookReference(reference) {export function registerCatalogEnvironment(reference, decoded) {if (!isEnvironmentReference(reference)) throw new RangeError(`environment.hdri must be one of ${BUNDLED_ENVIRONMENT_NAMES.join(', ')} or the 64-character ID of a .hdr file in the asset catalog.`);environmentSources.set(reference, decoded);- mapsByKey.clear();+ registrationCount++;}/** Registers a parsed look ({ size, data } from parseCube) under a bundled name or catalog ID. */@@ -46,16 +43,16 @@ export function catalogLook(reference) {return look;}-/** The environment map of a registered HDRI; the same object returns while name, strength, rotation and background hold. */-export function catalogEnvironmentMap(reference, { intensity = 1, rotation = 0, showBackground = false } = {}) {+/** Changes whenever an HDRI is registered, so a map cache can drop maps built from older data. */+export function environmentRegistrationCount() {+ return registrationCount;+}++/** The decoded data registered for an HDRI reference. */+export function catalogEnvironmentSource(reference) {const source = environmentSources.get(reference);if (!source) throw new Error(`The HDRI ${reference.slice(0, 16)} is not loaded: the host registers it with registerCatalogEnvironment (the MCP runtime does this from assets/looks or the asset catalog).`);- const key = [reference, intensity, rotation, showBackground].join('|');- if (!mapsByKey.has(key)) {- if (mapsByKey.size >= MAXIMUM_CACHED_MAPS) mapsByKey.clear();- mapsByKey.set(key, createEnvironmentMap({ ...source, intensity, rotation, showBackground }));- }- return mapsByKey.get(key);+ return source;}/** The catalog references a recipe or edit list uses: `{ environments, looks }`, each a sorted list of unique strings. */diff --git a/tests/agent-asset-catalog.test.js b/tests/agent-asset-catalog.test.jsindex cf327004..e2cf4973 100644--- a/tests/agent-asset-catalog.test.js+++ b/tests/agent-asset-catalog.test.js@@ -127,3 +127,25 @@ test('a decode limit error names the catalog limit and the value the file hit, wconst other = new Error('unrelated');assert.equal(withCatalogLimitAdvice(other), other);});++test('a Radiance .hdr and a .cube file are listed as environment and look entries and read back by ID', async context => {+ const { directory } = await fixture(context);+ const radiance = await readFile(new URL('../assets/looks/studio-softbox.hdr', import.meta.url));+ const cube = await readFile(new URL('../assets/looks/noir.cube', import.meta.url));+ await writeFile(join(directory, 'room.hdr'), radiance);+ await writeFile(join(directory, 'grade.cube'), cube);+ const catalog = await createAgentAssetCatalog(directory);+ const entries = Object.fromEntries(catalog.list().assets.map(entry => [entry.name, entry]));+ assert.equal(entries['room.hdr'].kind, 'environment');+ assert.equal(entries['grade.cube'].kind, 'look');+ assert.deepEqual(await catalog.read(entries['room.hdr'].assetId), radiance);+});++test('an .hdr that is not Radiance data and a .cube that is not a 3D look are refused', async context => {+ const { directory } = await fixture(context);+ await writeFile(join(directory, 'fake.hdr'), Buffer.alloc(64, 1));+ await assert.rejects(createAgentAssetCatalog(directory), /Radiance/);+ await rm(join(directory, 'fake.hdr'));+ await writeFile(join(directory, 'fake.cube'), 'LUT_1D_SIZE 2\n0 0 0\n1 1 1\n'.padEnd(64, ' '));+ await assert.rejects(createAgentAssetCatalog(directory), /LUT_3D_SIZE/);+});