Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
index 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.md
index 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.mjs
index 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's
diff --git a/src/agent-look.js b/src/agent-look.js
index 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_LI
import { 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.js
index 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 shadowed
diff --git a/src/lighting-setups.js b/src/lighting-setups.js
index 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, show
mapsByKey.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.js
index 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.js
index 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, w
const 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/);
+});