3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Name the valid hdri and look values in the input error (#2049)
Nguyen Xuan Anb097301f599c
diff --git a/changes/2049.md b/changes/2049.mdnew file mode 100644index 00000000..86ef0188--- /dev/null+++ b/changes/2049.md@@ -0,0 +1 @@+- An invalid `environment.hdri` or `environment.look` now lists the built-in names and the catalog option instead of only the 64-hex pattern (#2049)diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex 3901be31..ef0690ea 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -16,6 +16,7 @@ import packageMetadata from '../package.json' with { type: 'json' };import { MODIFIER_OPERATIONS } from '../src/mesh-operations.js';import { VIEW_TRANSFORM_NAMES, LOOK_NAMES } from '../src/view-transform-names.js';import { BUNDLED_ENVIRONMENT_NAMES, BUNDLED_CUBE_LOOK_NAMES, CATALOG_FILE_ID } from '../src/look-catalog.js';+import { describeReceived } from '../src/field-error.js';import { MATERIAL_PATTERN_TYPES, MATERIAL_MAPPINGS, LIGHTING_SETUP_NAMES, RENDER_PASS_NAMES, RENDER_OUTPUT_FORMATS, MAXIMUM_JOB_FPS, VIDEO_ENCODERS, MAXIMUM_JOB_SIDE, maximumMemoryMiB, memoryRangeError, MAXIMUM_STILLS_FRAMES } from '../src/agent-scene-capabilities.js';import { MATERIAL_LAYER_SCALAR_RANGES, MATERIAL_LAYER_COLOR_RANGES } from '../src/material-layers.js';import { SUBSURFACE_RANGES } from '../src/subsurface-limits.js';@@ -250,12 +251,18 @@ const volumeFog = z.strictObject({const affects = z.array(z.string()).optional();const iesProfile = z.any().optional();const lines = z.record(z.string(), z.unknown()).describe('Outlines, toon light and polylines as plain JSON; fields and limits in scene_capabilities lineArt. null clears.');+// An invalid name says which names work. The union alone reports only its 64-hex branch (issue 2049).+function catalogReference(names, fileKind) {+ const error = issue => `Invalid value: expected a built-in name (${names.join(', ')}), or a 64-character ${fileKind} ID from scene_asset_catalog (got ${describeReceived(issue.input)})`;+ return z.union([z.enum(names, { error }), z.string().regex(CATALOG_FILE_ID, { error })], { error });+}+const environment = z.strictObject({world: z.boolean().optional().describe('Draw the sky and apply surface fog.'),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 instead of the setup sky; scene_capabilities catalogLooks.'),+ hdri: catalogReference(BUNDLED_ENVIRONMENT_NAMES, '.hdr').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(),@@ -314,7 +321,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("Flush faces are ranked at draw time by default ('offset'); false opts out."),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 preset or .cube; scene_capabilities catalogLooks. null clears.'),+ look: catalogReference([...LOOK_NAMES, ...BUNDLED_CUBE_LOOK_NAMES], '.cube').nullable().optional().describe('Look preset or .cube; scene_capabilities catalogLooks. null clears.'),sky: z.record(z.string(), z.unknown()).nullable().optional().describe('Physical sky: {type:"physical", sunElevation, sunRotation, turbidity, groundAlbedo, aerialPerspective}; sets key light, sky and fog. Fields in scene_capabilities physicalSky.'),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.'),});diff --git a/tests/mcp-catalog-reference-errors.test.js b/tests/mcp-catalog-reference-errors.test.jsnew file mode 100644index 00000000..2e1d3fff--- /dev/null+++ b/tests/mcp-catalog-reference-errors.test.js@@ -0,0 +1,60 @@+import './support/load-agent-scene-modules.mjs';+import test from 'node:test';+import assert from 'node:assert/strict';+import { Client } from '@modelcontextprotocol/client';+import { InMemoryTransport } from '@modelcontextprotocol/server';+import { createAgentMcpServer } from '../scripts/mcp-server.mjs';++// Issue 2049: a wrong hdri or look name used to fail against the 64-hex pattern only.++async function connectedClient(context, runtime) {+ const server = createAgentMcpServer(runtime);+ const client = new Client({ name: 'crucible-catalog-reference-test', version: '1' });+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();+ await server.connect(serverTransport);+ await client.connect(clientTransport);+ context.after(async () => {+ await client.close();+ await server.close();+ });+ return client;+}++const idleRuntime = { async close() {}, async capabilities() { return { scene: {}, phase: 'idle' }; }, activeSessionId() { return null; } };++async function rejectedEnvironmentMessage(context, environment) {+ const client = await connectedClient(context, idleRuntime);+ const operations = [{ type: 'set-environment', environment }];+ try {+ const result = await client.callTool({ name: 'scene_apply', arguments: { expectedRevision: 0, operations } });+ return result.content?.[0]?.text ?? '';+ } catch (error) {+ return error.message;+ }+}++test('a wrong environment.hdri lists the built-in names and the catalog option', async context => {+ const message = await rejectedEnvironmentMessage(context, { hdri: 'no-such-hdri' });+ assert.match(message, /environment\.hdri: .*built-in name \(sky-clouds, studio-softbox\)/);+ assert.match(message, /64-character \.hdr ID from scene_asset_catalog/);+ assert.match(message, /got "no-such-hdri"/);+ assert.doesNotMatch(message, /must match pattern/);+});++test('a wrong environment.look lists the preset and bundled look names', async context => {+ const message = await rejectedEnvironmentMessage(context, { look: 'nope' });+ assert.match(message, /environment\.look: .*built-in name \(.*warm.*cool.*contrast.*faded.*teal-orange.*noir/);+ assert.match(message, /64-character \.cube ID from scene_asset_catalog/);+ assert.doesNotMatch(message, /must match pattern/);+});++test('built-in names and 64-hex IDs still pass input validation', async context => {+ const reachedRuntime = [];+ const runtime = { ...idleRuntime, async apply(argumentsValue) { reachedRuntime.push(argumentsValue); return { revision: 1 }; } };+ const client = await connectedClient(context, runtime);+ for (const environment of [{ hdri: 'sky-clouds' }, { look: 'noir' }, { hdri: 'a'.repeat(64) }]) {+ const operations = [{ type: 'set-environment', environment }];+ const result = await client.callTool({ name: 'scene_apply', arguments: { expectedRevision: 0, operations } }).catch(error => ({ text: error.message }));+ assert.doesNotMatch(result.text ?? result.content?.[0]?.text ?? '', /Input validation error/);+ }+});