Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Name the field, the value and an accepted example in agent validation errors (issue #653)

Nguyen Xuan An8c2b59784dd3
diff --git a/changes/653.md b/changes/653.md
new file mode 100644
index 00000000..c442c999
--- /dev/null
+++ b/changes/653.md
@@ -0,0 +1 @@
+- Validation errors for materials, nodes, the camera, lights, fog, bake, mesh edits and motion now read `materials[2].emissiveColor: got [-1,0,0]; expected three numbers of 0 or more, such as [1, 0.5, 0.2].`: the full field path, the value received (cut at 40 characters) and a range, a list of choices or an example. Schema errors from the MCP tools add the received value too (`recipe.materials.0.color.2: Too big: expected number to be <=1 (got 2)`). Mesh edit errors keep the position of the edit (`edits[1].segments`). Not every message in the engine is converted yet; the rest keep their older wording (#653)
diff --git a/changes/653.size.md b/changes/653.size.md
new file mode 100644
index 00000000..4d6c37be
--- /dev/null
+++ b/changes/653.size.md
@@ -0,0 +1,2 @@
+- scene:agent-scene: the field-error helper and the longer messages (path, value, example) grow the scene bundle a little; an agent that reads "emissiveColor: got [-1,0,0]; expected three numbers of 0 or more, such as [1, 0.5, 0.2]" fixes it in one retry instead of guessing.
+- goal:agent-scene: the cost is message text and one 30-line module (field-error.js); no new behaviour runs outside an error.
diff --git a/scripts/mcp-input-errors.mjs b/scripts/mcp-input-errors.mjs
new file mode 100644
index 00000000..5e0aad43
--- /dev/null
+++ b/scripts/mcp-input-errors.mjs
@@ -0,0 +1,22 @@
+import * as z from 'zod/v4';
+import { describeReceived } from '../src/field-error.js';
+
+const ISSUES_WITH_A_REJECTED_VALUE = new Set(['too_big', 'too_small', 'invalid_value', 'invalid_format', 'not_multiple_of']);
+
+// The SDK prefixes each schema message with the field path (recipe.materials.0.color.2). The English wording says what
+// was expected ("Too big: expected number to be <=1") but not what arrived, so the received value is added here.
+function messageWithReceivedValue(issue) {
+ const wording = z.locales.en().localeError(issue);
+ const text = typeof wording === 'string' ? wording : wording?.message;
+ if (!text) {
+ return undefined;
+ }
+ if (ISSUES_WITH_A_REJECTED_VALUE.has(issue.code) && Object.hasOwn(issue, 'input')) {
+ return `${text} (got ${describeReceived(issue.input)})`;
+ }
+ return undefined;
+}
+
+export function describeSchemaInputsWithReceivedValues() {
+ z.config({ customError: messageWithReceivedValue });
+}
diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjs
index d1723c83..618044c7 100644
--- a/scripts/mcp-server.mjs
+++ b/scripts/mcp-server.mjs
@@ -3,6 +3,7 @@ import { BRANCH_NAME_PATTERN } from '../src/agent-branches.js';
import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio, StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';
+import { describeSchemaInputsWithReceivedValues } from './mcp-input-errors.mjs';
import { setPriority, constants } from 'node:os';
import { resolve } from 'node:path';
import { pathToFileURL } from 'node:url';
@@ -15,6 +16,8 @@ import { MATERIAL_LAYER_SCALAR_RANGES, MATERIAL_LAYER_COLOR_RANGES } from '../sr
import { SUBSURFACE_RANGES } from '../src/subsurface-limits.js';
import { MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_AREA_LIGHTS } from '../src/light-limits.js';
+describeSchemaInputsWithReceivedValues();
+
const finite = z.number().min(-3.4028234663852886e38).max(3.4028234663852886e38);
const positive = finite.positive();
const nonnegative = finite.nonnegative();
diff --git a/src/agent-bake.js b/src/agent-bake.js
index 9ba634f7..b809fc3c 100644
--- a/src/agent-bake.js
+++ b/src/agent-bake.js
@@ -1,3 +1,4 @@
+import { invalidField } from './field-error.js';
import { planLightmaps, estimateBake, traceLightmaps } from './light-bake.js';
import { runKernel } from './kernel-offload.js';
import { motionEnvironment } from './agent-motion.js';
@@ -23,7 +24,7 @@ export function normalizeAgentBake(input) {
}
knownKeys(input, BAKE_FIELDS, 'bake');
if (input.preset !== undefined && !Object.hasOwn(BAKE_PRESETS, input.preset)) {
- throw new RangeError(`Bake preset must be one of ${Object.keys(BAKE_PRESETS).join(', ')}.`);
+ throw invalidField('bake.preset', input.preset, `one of ${Object.keys(BAKE_PRESETS).join(', ')}`);
}
const resolved = { ...BAKE_PRESETS[input.preset ?? 'standard'] };
for (const [field, [minimum, maximum]] of Object.entries(BAKE_RANGES)) {
@@ -46,24 +47,24 @@ export function normalizeAgentBake(input) {
}
// Opt in on top of the grid: the grid's paths scatter in the scene's volume fog. Not stored when off, so the default bake keeps its bytes.
if (input.gridFog !== undefined && typeof input.gridFog !== 'boolean') {
- throw new RangeError('bake.gridFog must be a boolean.');
+ throw invalidField('bake.gridFog', input.gridFog, 'true or false');
}
if (input.gridFog === true) {
if (!irradianceGrid) {
- throw new RangeError('bake.gridFog needs bake.irradianceGrid.');
+ throw invalidField('bake.gridFog', input.gridFog, 'true only together with bake.irradianceGrid, such as irradianceGrid: true');
}
resolved.gridFog = true;
}
// Not stored when off, so the default bake keeps its bytes.
if (input.rebake !== undefined && typeof input.rebake !== 'boolean') {
- throw new RangeError('bake.rebake must be a boolean.');
+ throw invalidField('bake.rebake', input.rebake, 'true or false');
}
if (input.rebake === true) {
resolved.rebake = true;
}
for (const field of ['samples', 'bounces']) {
if (!Number.isInteger(resolved[field])) {
- throw new RangeError(`Bake ${field} must be an integer.`);
+ throw invalidField(`bake.${field}`, resolved[field], 'a whole number, such as 64');
}
}
return resolved;
diff --git a/src/agent-look.js b/src/agent-look.js
index 3b29e5cb..a651b2a0 100644
--- a/src/agent-look.js
+++ b/src/agent-look.js
@@ -1,3 +1,4 @@
+import { invalidField, withFieldPrefix } from './field-error.js';
import { mat4 } from 'gl-matrix';
import { createLightingState, updateLightingState, MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_AREA_LIGHTS, MAXIMUM_SPECULAR_ANTI_ALIASING } from './lighting.js';
import { resolveEffects } from './effects.js';
@@ -122,19 +123,26 @@ function copiedJson(input, depth = 0, ancestors = new Set()) {
return result;
}
+function exampleInRange(minimum, maximum) {
+ if (minimum <= 1 && maximum >= 1) return '1';
+ return String(minimum > 0 ? minimum : maximum);
+}
+
function numberInRange(value, minimum, maximum, label) {
if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isFinite(Math.fround(value)) ||
value < minimum || value > maximum) {
- throw new RangeError(`${label} must be a finite Float32 number within ${minimum} and ${maximum}.`);
+ const unbounded = minimum < -1e30 && maximum > 1e30;
+ throw invalidField(label, value, unbounded ? 'a finite number, such as 0.5' : `a number from ${minimum} to ${maximum}, such as ${exampleInRange(minimum, maximum)}`);
}
return value;
}
function vectorInRange(value, minimum, maximum, label) {
if (!Array.isArray(value) || value.length !== 3) {
- throw new TypeError(`${label} needs three JSON numbers.`);
+ const example = exampleInRange(minimum, maximum);
+ throw invalidField(label, value, `an array of three numbers from ${minimum} to ${maximum}, such as [${example}, ${example}, ${example}]`, TypeError);
}
- return value.map(component => numberInRange(component, minimum, maximum, label));
+ return value.map((component, index) => numberInRange(component, minimum, maximum, `${label}[${index}]`));
}
function fallback(value, defaultValue) {
@@ -145,7 +153,7 @@ function directionFrom(value, label = 'lightDirection') {
const direction = vectorInRange(value, -1e6, 1e6, label);
const length = Math.hypot(...direction);
if (length < 1e-6) {
- throw new RangeError(`${label} length must be at least 0.000001.`);
+ throw invalidField(label, direction, 'a direction that is not all zero, such as [0, -1, 0]');
}
return { direction, unitDirection: direction.map(component => component / length) };
}
@@ -153,24 +161,24 @@ function directionFrom(value, label = 'lightDirection') {
function lightListFrom(value, maximum, name) {
const lights = fallback(value, []);
if (!Array.isArray(lights) || lights.length > maximum) {
- throw new RangeError(`${name} must contain at most ${maximum} lights.`);
+ throw invalidField(name, Array.isArray(lights) ? `${lights.length} entries` : lights, `an array of at most ${maximum} lights, such as []`);
}
return lights;
}
-function rangeFrom(light, label) {
- const range = numberInRange(fallback(light.range, 0), 0, 1e6, `${label} range`);
+function rangeFrom(light) {
+ const range = numberInRange(fallback(light.range, 0), 0, 1e6, 'range');
if (range !== 0 && range < 0.001) {
- throw new RangeError(`${label} range must be zero or at least 0.001.`);
+ throw invalidField('range', range, '0 for unlimited, or at least 0.001, such as 10');
}
return range;
}
// Only a light that casts shadows carries the field, so recipes without shadows keep their exported shape.
-function shadowFieldFrom(light, label) {
+function shadowFieldFrom(light) {
const castShadow = fallback(light.castShadow, false);
if (typeof castShadow !== 'boolean') {
- throw new TypeError(`${label} castShadow must be boolean.`);
+ throw invalidField('castShadow', castShadow, 'true or false', TypeError);
}
return castShadow ? { castShadow } : {};
}
@@ -178,12 +186,12 @@ function shadowFieldFrom(light, label) {
function pointLightFrom(light) {
knownKeys(light, POINT_LIGHT_FIELDS, 'point light');
return {
- position: vectorInRange(light.position, -1e6, 1e6, 'point light position'),
- color: vectorInRange(fallback(light.color, [1, 1, 1]), 0, 1, 'point light color'),
- intensity: numberInRange(fallback(light.intensity, 1), 0, 1e5, 'point light intensity'),
- radius: numberInRange(fallback(light.radius, 0.05), 0.001, 1e6, 'point light radius'),
- range: rangeFrom(light, 'point light'),
- ...shadowFieldFrom(light, 'point light'),
+ position: vectorInRange(light.position, -1e6, 1e6, 'position'),
+ color: vectorInRange(fallback(light.color, [1, 1, 1]), 0, 1, 'color'),
+ intensity: numberInRange(fallback(light.intensity, 1), 0, 1e5, 'intensity'),
+ radius: numberInRange(fallback(light.radius, 0.05), 0.001, 1e6, 'radius'),
+ range: rangeFrom(light),
+ ...shadowFieldFrom(light),
...affectsFrom(light, 'point light'),
};
}
@@ -191,15 +199,15 @@ function pointLightFrom(light) {
function spotLightFrom(light) {
knownKeys(light, SPOT_LIGHT_FIELDS, 'spot light');
return {
- position: vectorInRange(light.position, -1e6, 1e6, 'spot light position'),
- direction: directionFrom(light.direction, 'spot light direction').direction,
- angle: numberInRange(fallback(light.angle, Math.PI / 4), 0.01, Math.PI / 2 - 0.01, 'spot light angle'),
- penumbra: numberInRange(fallback(light.penumbra, 0.15), 0, 1, 'spot light penumbra'),
- color: vectorInRange(fallback(light.color, [1, 1, 1]), 0, 1, 'spot light color'),
- intensity: numberInRange(fallback(light.intensity, 1), 0, 1e5, 'spot light intensity'),
- radius: numberInRange(fallback(light.radius, 0.05), 0.001, 1e6, 'spot light radius'),
- range: rangeFrom(light, 'spot light'),
- ...shadowFieldFrom(light, 'spot light'),
+ position: vectorInRange(light.position, -1e6, 1e6, 'position'),
+ direction: directionFrom(light.direction, 'direction').direction,
+ angle: numberInRange(fallback(light.angle, Math.PI / 4), 0.01, Math.PI / 2 - 0.01, 'angle'),
+ penumbra: numberInRange(fallback(light.penumbra, 0.15), 0, 1, 'penumbra'),
+ color: vectorInRange(fallback(light.color, [1, 1, 1]), 0, 1, 'color'),
+ intensity: numberInRange(fallback(light.intensity, 1), 0, 1e5, 'intensity'),
+ radius: numberInRange(fallback(light.radius, 0.05), 0.001, 1e6, 'radius'),
+ range: rangeFrom(light),
+ ...shadowFieldFrom(light),
...affectsFrom(light, 'spot light'),
};
}
@@ -207,14 +215,14 @@ function spotLightFrom(light) {
function areaLightFrom(light) {
knownKeys(light, AREA_LIGHT_FIELDS, 'area light');
const resolved = {
- position: vectorInRange(light.position, -1e6, 1e6, 'area light position'),
- direction: directionFrom(light.direction, 'area light direction').direction,
- width: numberInRange(light.width, 0.001, 1e4, 'area light width'),
- height: numberInRange(light.height, 0.001, 1e4, 'area light height'),
- color: vectorInRange(fallback(light.color, [1, 1, 1]), 0, 1, 'area light color'),
- intensity: numberInRange(fallback(light.intensity, 1), 0, 1e5, 'area light intensity'),
+ position: vectorInRange(light.position, -1e6, 1e6, 'position'),
+ direction: directionFrom(light.direction, 'direction').direction,
+ width: numberInRange(light.width, 0.001, 1e4, 'width'),
+ height: numberInRange(light.height, 0.001, 1e4, 'height'),
+ color: vectorInRange(fallback(light.color, [1, 1, 1]), 0, 1, 'color'),
+ intensity: numberInRange(fallback(light.intensity, 1), 0, 1e5, 'intensity'),
};
- if (light.up !== undefined) resolved.up = directionFrom(light.up, 'area light up').direction;
+ if (light.up !== undefined) resolved.up = directionFrom(light.up, 'up').direction;
return { ...resolved, ...affectsFrom(light, 'area light') };
}
@@ -237,61 +245,61 @@ function environmentFrom(input = {}) {
knownKeys(input, ENVIRONMENT_FIELDS, 'environment');
const world = fallback(input.world, false);
if (typeof world !== 'boolean') {
- throw new TypeError('environment.world must be boolean.');
+ throw invalidField('environment.world', world, 'true or false', TypeError);
}
const setup = fallback(input.setup, DEFAULT_LIGHTING_SETUP);
if (!LIGHTING_SETUP_NAMES.includes(setup)) {
- throw new RangeError(`environment.setup must be one of ${LIGHTING_SETUP_NAMES.join(', ')}.`);
+ throw invalidField('environment.setup', setup, `one of ${LIGHTING_SETUP_NAMES.join(', ')}`);
}
const defaults = lightingSetupFields(setup);
const environment = {
world,
setup,
- environmentIntensity: numberInRange(fallback(input.environmentIntensity, 1), 0, 100, 'environmentIntensity'),
- environmentRotation: numberInRange(fallback(input.environmentRotation, 0), -100, 100, 'environmentRotation'),
- lightDirection: directionFrom(fallback(input.lightDirection, defaults.lightDirection)).direction,
- keyColor: vectorInRange(fallback(input.keyColor, defaults.keyColor), 0, 1000, 'keyColor'),
- keyIntensity: numberInRange(fallback(input.keyIntensity, defaults.keyIntensity), 0, 100, 'keyIntensity'),
- fillIntensity: numberInRange(fallback(input.fillIntensity, defaults.fillIntensity), 0, 100, 'fillIntensity'),
- ambientIntensity: numberInRange(fallback(input.ambientIntensity, defaults.ambientIntensity), 0, 100, 'ambientIntensity'),
- daylight: numberInRange(fallback(input.daylight, 1), 0, 100, 'daylight'),
- pointLights: lightListFrom(input.pointLights, MAX_POINT_LIGHTS, 'pointLights').map(pointLightFrom),
- skyTop: vectorInRange(fallback(input.skyTop, defaults.skyTop), 0, 1, 'skyTop'),
- skyBottom: vectorInRange(fallback(input.skyBottom, defaults.skyBottom), 0, 1, 'skyBottom'),
- fogColor: vectorInRange(fallback(input.fogColor, [0.35, 0.43, 0.43]), 0, 1, 'fogColor'),
- fogDensity: input.fogDensity === undefined || input.fogDensity === null ? null : numberInRange(input.fogDensity, 0, 10, 'fogDensity'),
+ environmentIntensity: numberInRange(fallback(input.environmentIntensity, 1), 0, 100, 'environment.environmentIntensity'),
+ environmentRotation: numberInRange(fallback(input.environmentRotation, 0), -100, 100, 'environment.environmentRotation'),
+ lightDirection: directionFrom(fallback(input.lightDirection, defaults.lightDirection), 'environment.lightDirection').direction,
+ keyColor: vectorInRange(fallback(input.keyColor, defaults.keyColor), 0, 1000, 'environment.keyColor'),
+ keyIntensity: numberInRange(fallback(input.keyIntensity, defaults.keyIntensity), 0, 100, 'environment.keyIntensity'),
+ fillIntensity: numberInRange(fallback(input.fillIntensity, defaults.fillIntensity), 0, 100, 'environment.fillIntensity'),
+ ambientIntensity: numberInRange(fallback(input.ambientIntensity, defaults.ambientIntensity), 0, 100, 'environment.ambientIntensity'),
+ daylight: numberInRange(fallback(input.daylight, 1), 0, 100, 'environment.daylight'),
+ pointLights: lightListFrom(input.pointLights, MAX_POINT_LIGHTS, 'environment.pointLights').map((light, index) => withFieldPrefix(`environment.pointLights[${index}]`, () => pointLightFrom(light))),
+ skyTop: vectorInRange(fallback(input.skyTop, defaults.skyTop), 0, 1, 'environment.skyTop'),
+ skyBottom: vectorInRange(fallback(input.skyBottom, defaults.skyBottom), 0, 1, 'environment.skyBottom'),
+ fogColor: vectorInRange(fallback(input.fogColor, [0.35, 0.43, 0.43]), 0, 1, 'environment.fogColor'),
+ fogDensity: input.fogDensity === undefined || input.fogDensity === null ? null : numberInRange(input.fogDensity, 0, 10, 'environment.fogDensity'),
volumeFog: volumeFogFrom(input.volumeFog),
};
// Optional so recipes without these fields keep their exported shape.
if (input.ground !== undefined) {
if (typeof input.ground !== 'boolean') {
- throw new TypeError('environment.ground must be a boolean.');
+ throw invalidField('environment.ground', input.ground, 'true or false', TypeError);
}
environment.ground = input.ground;
}
if (input.objectReflections !== undefined) {
if (typeof input.objectReflections !== 'boolean') {
- throw new TypeError('environment.objectReflections must be a boolean.');
+ throw invalidField('environment.objectReflections', input.objectReflections, 'true or false', TypeError);
}
environment.objectReflections = input.objectReflections;
}
// `false` opts out of the floor sky trace that src/floor-sky-visibility.js gives sun-lit closed rooms.
if (input.floorSkyTrace !== undefined) {
if (typeof input.floorSkyTrace !== 'boolean') {
- throw new TypeError('environment.floorSkyTrace must be a boolean.');
+ throw invalidField('environment.floorSkyTrace', input.floorSkyTrace, 'true or false', TypeError);
}
environment.floorSkyTrace = input.floorSkyTrace;
}
// Scales the light the sunlit patches of a sun-lit closed room bounce on (src/sun-bounce.js); 0 turns it off.
if (input.sunBounce !== undefined) {
if (!Number.isFinite(input.sunBounce) || input.sunBounce < 0) {
- throw new TypeError('environment.sunBounce must be a number of 0 or more.');
+ throw invalidField('environment.sunBounce', input.sunBounce, 'a number of 0 or more, such as 1', TypeError);
}
environment.sunBounce = input.sunBounce;
}
// Strength of the specular anti-aliasing that widens highlights where normals or normal map detail change within a pixel (src/lighting.js); 0 turns it off.
if (input.specularAntiAliasing !== undefined) {
- environment.specularAntiAliasing = numberInRange(input.specularAntiAliasing, 0, MAXIMUM_SPECULAR_ANTI_ALIASING, 'specularAntiAliasing');
+ environment.specularAntiAliasing = numberInRange(input.specularAntiAliasing, 0, MAXIMUM_SPECULAR_ANTI_ALIASING, 'environment.specularAntiAliasing');
}
// Outlines and line geometry; null clears them. The module checks the fields and loads on demand.
if (input.lines !== undefined && input.lines !== null) {
@@ -299,15 +307,15 @@ function environmentFrom(input = {}) {
}
if (input.resolveCoplanar !== undefined) {
if (input.resolveCoplanar !== 'offset' && input.resolveCoplanar !== false) {
- throw new TypeError("environment.resolveCoplanar must be 'offset' or false.");
+ throw invalidField('environment.resolveCoplanar', input.resolveCoplanar, "'offset' or false", TypeError);
}
environment.resolveCoplanar = input.resolveCoplanar;
}
if (input.spotLights !== undefined) {
- environment.spotLights = lightListFrom(input.spotLights, MAX_SPOT_LIGHTS, 'spotLights').map(spotLightFrom);
+ environment.spotLights = lightListFrom(input.spotLights, MAX_SPOT_LIGHTS, 'environment.spotLights').map((light, index) => withFieldPrefix(`environment.spotLights[${index}]`, () => spotLightFrom(light)));
}
if (input.areaLights !== undefined) {
- environment.areaLights = lightListFrom(input.areaLights, MAX_AREA_LIGHTS, 'areaLights').map(areaLightFrom);
+ environment.areaLights = lightListFrom(input.areaLights, MAX_AREA_LIGHTS, 'environment.areaLights').map((light, index) => withFieldPrefix(`environment.areaLights[${index}]`, () => areaLightFrom(light)));
}
if (input.shadowCascades !== undefined) {
environment.shadowCascades = shadowCascadesFrom(input.shadowCascades);
@@ -316,19 +324,19 @@ function environmentFrom(input = {}) {
// A catalog HDRI replaces the procedural sky map. The setup still supplies the key light: set keyIntensity 0 when the HDRI has its own sun.
if (input.hdri !== undefined && input.hdri !== null) {
if (typeof input.hdri !== 'string' || !isEnvironmentReference(input.hdri)) {
- 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.`);
+ throw invalidField('environment.hdri', input.hdri, `one of ${BUNDLED_ENVIRONMENT_NAMES.join(', ')} or the 64-character ID of a .hdr file in the asset catalog`);
}
environment.hdri = input.hdri;
}
if (input.viewTransform !== undefined) {
if (!VIEW_TRANSFORM_NAMES.includes(input.viewTransform)) {
- throw new RangeError(`environment.viewTransform must be one of ${VIEW_TRANSFORM_NAMES.join(', ')}.`);
+ throw invalidField('environment.viewTransform', input.viewTransform, `one of ${VIEW_TRANSFORM_NAMES.join(', ')}`);
}
environment.viewTransform = input.viewTransform;
}
if (input.look !== undefined && input.look !== null) {
if (!LOOK_NAMES.includes(input.look) && !isCubeLookReference(input.look)) {
- throw new RangeError(`environment.look must be one of ${[...LOOK_NAMES, ...BUNDLED_CUBE_LOOK_NAMES].join(', ')} or the 64-character ID of a .cube file in the asset catalog.`);
+ throw invalidField('environment.look', input.look, `one of ${[...LOOK_NAMES, ...BUNDLED_CUBE_LOOK_NAMES].join(', ')} or the 64-character ID of a .cube file in the asset catalog`);
}
environment.look = input.look;
}
diff --git a/src/agent-motion.js b/src/agent-motion.js
index 8db7294f..285e7fc2 100644
--- a/src/agent-motion.js
+++ b/src/agent-motion.js
@@ -1,4 +1,5 @@
import { createAnimationClip, compileAnimationSampler } from './animation.js';
+import { invalidField, withFieldPrefix } from './field-error.js';
import { createCameraPath } from './camera-path.js';
import { CAMERA_LENS_FIELDS } from './camera.js';
import { createSkeletonPose } from './skeleton-pose.js';
@@ -44,37 +45,37 @@ const MAX_IK_SOLVERS = 16;
const IK_SWEEP_SAMPLES = 33;
const CAMERA_DEFAULTS = { eye: [4, 3, 5], target: [0, 0, 0], up: [0, 1, 0], fov: 45, near: 0.1, far: 1000 };
-function validateValue(kind, property, value) {
+function validateValue(kind, property, value, valuePath = `${kind}.${property}`) {
const components = typeof value === 'number' ? [value] : value;
for (const component of components) {
- finite(component, `${kind} ${property}`);
+ finite(component, valuePath);
}
if (property === 'visible' && components.some(component => component !== 0 && component !== 1)) {
- throw new RangeError('Motion visible must be 1 (shown) or 0 (hidden).');
+ throw invalidField(valuePath, value, '1 (shown) or 0 (hidden)');
}
if (property === 'scale' && components.some(component => Math.fround(component) <= 0)) {
- throw new RangeError('Motion scale must remain positive at Float32 precision.');
+ throw invalidField(valuePath, value, 'positive numbers, such as [1, 1, 1]');
}
if (kind === 'material') {
if (components.some(component => component < 0)) {
- throw new RangeError(`Motion ${property} cannot be negative.`);
+ throw invalidField(valuePath, value, `numbers of 0 or more for ${property}, such as 0.5`);
}
if (['color', 'metallic', 'roughness'].includes(property) && components.some(component => component > 1)) {
- throw new RangeError(`Motion ${property} must stay within zero and one.`);
+ throw invalidField(valuePath, value, `numbers from 0 to 1 for ${property}, such as 0.5`);
}
}
if (kind === 'morph' && components.some(component => component < 0 || component > 1)) {
- throw new RangeError('Motion morph weight must stay within zero and one.');
+ throw invalidField(valuePath, value, 'a morph weight from 0 to 1, such as 0.5');
}
const range = LOOK_RANGES[kind]?.[property];
if (range && components.some(component => component < range[0] || component > range[1])) {
- throw new RangeError(`Motion ${kind} ${property} must stay within ${range[0]} and ${range[1]}.`);
+ throw invalidField(valuePath, value, `${kind} ${property} values from ${range[0]} to ${range[1]}, such as ${Math.min(Math.max(1, range[0]), range[1])}`);
}
if (property === 'direction' && Math.hypot(...components) < 1e-6) {
- throw new RangeError(`Motion ${kind} direction needs a length of at least 0.000001; a blend between opposite directions passes through zero.`);
+ throw invalidField(valuePath, value, 'a direction that is not all zero, such as [0, -1, 0]; keyframes of opposite directions blend through zero');
}
if (kind === 'camera' && property === 'fov' && (Math.fround(value) <= 0 || Math.fround(value) >= 180)) {
- throw new RangeError('Motion fov must stay between zero and 180 at Float32 precision.');
+ throw invalidField(valuePath, value, 'degrees above 0 and below 180, such as 50');
}
}
@@ -102,10 +103,10 @@ function normalizedKeyframe(keyframe, track, duration, interpolation) {
knownKeys(keyframe, ['time', 'value', 'inTangent', 'outTangent', 'easing'], 'motion keyframe');
const size = PROPERTIES[track.kind][track.property];
const result = {
- time: bounded(keyframe.time, 0, duration, 'Keyframe time'),
- value: valueFrom(keyframe.value, size, 'Keyframe value'),
+ time: bounded(keyframe.time, 0, duration, 'time'),
+ value: valueFrom(keyframe.value, size, 'value'),
};
- validateValue(track.kind, track.property, result.value);
+ validateValue(track.kind, track.property, result.value, 'value');
const easing = normalizeKeyframeEasing(keyframe);
if (easing && interpolation !== 'LINEAR' && interpolation !== 'SMOOTH') {
throw new RangeError(`Keyframe easing needs LINEAR or SMOOTH interpolation, not ${interpolation}.`);
@@ -356,10 +357,10 @@ export function normalizeAgentMotion(input, recipe) {
knownKeys(input, ['duration', 'loop', 'tracks', 'ik', 'constraints', 'drivers', 'layers', 'footLock', 'drive'], 'motion');
const drive = input.drive === undefined ? null : normalizedDrive(input.drive, recipe);
// A drive knows how long its path takes, so the motion may leave the duration out.
- const duration = bounded(input.duration === undefined && drive ? Math.ceil(drive.built.duration * 1000) / 1000 : input.duration, 0.1, 30, 'Motion duration');
+ const duration = bounded(input.duration === undefined && drive ? Math.ceil(drive.built.duration * 1000) / 1000 : input.duration, 0.1, 30, 'motion.duration');
const loop = input.loop === undefined ? false : input.loop;
if (typeof loop !== 'boolean') {
- throw new TypeError('Motion loop must be boolean.');
+ throw invalidField('motion.loop', loop, 'true or false', TypeError);
}
const inputTracks = input.tracks ?? [];
denseArray(inputTracks, 128, 'Motion tracks');
@@ -376,7 +377,7 @@ export function normalizeAgentMotion(input, recipe) {
knownKeys(track, ['kind', 'id', 'property', 'interpolation', 'keyframes'], 'motion track');
if (!Object.hasOwn(PROPERTIES, track.kind) || !Object.hasOwn(PROPERTIES[track.kind], track.property)) {
const known = Object.hasOwn(PROPERTIES, track.kind) ? ` ${track.kind} properties: ${Object.keys(PROPERTIES[track.kind]).join(', ')}.` : ` Kinds: ${Object.keys(PROPERTIES).join(', ')}.`;
- throw new RangeError(`Unsupported motion target or property.${known}`);
+ throw invalidField(`motion.tracks[${index}].property`, `${track.kind}.${track.property}`, `a kind and property pair.${known}`);
}
if (SINGLETON_KINDS.has(track.kind)) {
if (Object.hasOwn(track, 'id')) {
@@ -395,19 +396,19 @@ export function normalizeAgentMotion(input, recipe) {
checkLookTarget(track, recipe);
const identity = JSON.stringify([track.kind, track.id ?? null, track.property]);
if (identities.has(identity)) {
- throw new RangeError('Duplicate motion target property.');
+ throw invalidField(`motion.tracks[${index}].property`, `${track.kind}.${track.property}`, 'one track per target and property, but this one repeats an earlier track: merge the keyframes, or drop the duplicate');
}
identities.add(identity);
const interpolation = track.interpolation ?? (track.property === 'visible' ? 'STEP' : 'LINEAR');
if (!INTERPOLATIONS.includes(interpolation)) {
- throw new RangeError('Unsupported motion interpolation.');
+ throw invalidField(`motion.tracks[${index}].interpolation`, interpolation, `one of ${INTERPOLATIONS.join(', ')}`);
}
denseArray(track.keyframes, 64, 'Motion keyframes');
keyframeCount += track.keyframes.length;
if (keyframeCount > 2048) {
throw new RangeError('Motion exceeds 2048 total keyframes.');
}
- const keyframes = track.keyframes.map(keyframe => normalizedKeyframe(keyframe, track, duration, interpolation));
+ const keyframes = track.keyframes.map((keyframe, keyframeIndex) => withFieldPrefix(`motion.tracks[${index}].keyframes[${keyframeIndex}]`, () => normalizedKeyframe(keyframe, track, duration, interpolation)));
const clip = createAnimationClip({
duration, loop,
tracks: [{ target: String(index), property: coreProperty(track), interpolation, keyframes }],
diff --git a/src/agent-scene.js b/src/agent-scene.js
index 88906325..09980d3e 100644
--- a/src/agent-scene.js
+++ b/src/agent-scene.js
@@ -1,6 +1,7 @@
import { mat4, mat3 } from 'gl-matrix';
import { box, circle, cone, cylinder, grid, icoSphere, sphere, torus } from './geometry.js';
import { createSceneGraph } from './scene-graph.js';
+import { invalidField, withFieldPrefix } from './field-error.js';
import { applyProjection, validateCameraShift, CAMERA_LENS_FIELDS } from './camera.js';
import { normalizeAgentLook, environmentPatchWithSetup, environmentLinksLights, agentEnvironmentMap, VOLUME_FOG_FIELDS } from './agent-look.js';
import { postStepSupport } from './shader-registry.js';
@@ -151,16 +152,17 @@ function copiedJson(input, maximum) {
function finite(value, label) {
if (!Number.isFinite(value) || !Number.isFinite(Math.fround(value))) {
- throw new TypeError(`${label} must be a finite Float32 number.`);
+ throw invalidField(label, value, 'a finite number that fits Float32, such as 0.5', TypeError);
}
return value;
}
function vector(value, length, label) {
if (!Array.isArray(value) || value.length !== length) {
- throw new TypeError(`${label} needs ${length} numbers.`);
+ const example = `[${Array.from({ length }, (_, index) => (index === length - 1 && length === 4 ? 1 : 0)).join(', ')}]`;
+ throw invalidField(label, value, `an array of ${length} numbers, such as ${example}`, TypeError);
}
- return value.map(component => finite(component, label));
+ return value.map((component, index) => finite(component, `${label}[${index}]`));
}
function defaultValue(value, fallback) {
@@ -169,14 +171,14 @@ function defaultValue(value, fallback) {
function integer(value, minimum, maximum, label) {
if (!Number.isInteger(value) || value < minimum || value > maximum) {
- throw new RangeError(`${label} must be within ${minimum} and ${maximum}.`);
+ throw invalidField(label, value, `a whole number from ${minimum} to ${maximum}, such as ${minimum}`);
}
return value;
}
-function identifier(value) {
+function identifier(value, label = 'id') {
if (typeof value !== 'string' || !value.trim() || value.length > 128) {
- throw new TypeError('IDs must contain 1 to 128 characters.');
+ throw invalidField(label,value, 'a string of 1 to 128 characters, such as "wall-left"', TypeError);
}
return value;
}
@@ -186,14 +188,14 @@ function resources(values, maximum, label, validate) {
throw new RangeError(`${label} exceeds its resource limit of ${maximum} or is not an array. Pass "${label}": [] for none, or remove some.`);
}
const seen = new Set();
- return values.map(value => {
+ return values.map((value, index) => withFieldPrefix(`${label}[${index}]`, () => {
identifier(value?.id);
if (seen.has(value.id)) {
throw new RangeError(`Duplicate ${label} ID: ${value.id}. IDs must be unique: rename one, or remove the other.`);
}
seen.add(value.id);
return validate(value);
- });
+ }));
}
function copyMaterialLayers(value, result) {
@@ -229,33 +231,36 @@ function materialFrom(value) {
result.opacity = defaultValue(value.opacity, 1);
finite(result.opacity, 'opacity');
if (result.opacity < 0 || result.opacity > 1) {
- throw new RangeError('opacity must be within zero and one.');
+ throw invalidField('opacity', result.opacity, 'a number from 0 to 1, such as 0.5');
}
const requestedAlphaMode = defaultValue(value.alphaMode, 'opaque');
if (!RECIPE_ALPHA_MODES.includes(requestedAlphaMode)) {
- throw new RangeError(`alphaMode must be one of ${RECIPE_ALPHA_MODES.join(', ')}.`);
+ throw invalidField('alphaMode', requestedAlphaMode, `one of ${RECIPE_ALPHA_MODES.join(', ')}`);
}
// The renderer ignores opacity on opaque surfaces, so any opacity below one means blending (additive stays additive).
const graphHasOpacity = graphFactor('opacity', 0);
result.alphaMode = (result.opacity < 1 || graphHasOpacity) && requestedAlphaMode === 'opaque' ? 'blend' : requestedAlphaMode;
result.doubleSided = defaultValue(value.doubleSided, false);
if (typeof result.doubleSided !== 'boolean') {
- throw new TypeError('doubleSided must be boolean.');
+ throw invalidField('doubleSided', result.doubleSided, 'true or false', TypeError);
}
for (const field of ['metallic', 'roughness']) {
finite(result[field], field);
if (result[field] < 0 || result[field] > 1) {
- throw new RangeError(`${field} must be within zero and one.`);
+ throw invalidField(field, result[field], 'a number from 0 to 1, such as 0.5');
}
}
finite(result.emission, 'emission');
- if (result.emission < 0 || result.color.some(component => component < 0 || component > 1)) {
- throw new RangeError('Emission must be nonnegative and color must be within zero and one.');
+ if (result.emission < 0) {
+ throw invalidField('emission', result.emission, 'a number of 0 or more, such as 1');
+ }
+ if (result.color.some(component => component < 0 || component > 1)) {
+ throw invalidField('color', result.color, 'three numbers from 0 to 1, such as [0.8, 0.2, 0.1]');
}
if (value.emissiveColor !== undefined) {
result.emissiveColor = vector(value.emissiveColor, 3, 'emissiveColor');
if (result.emissiveColor.some(component => component < 0)) {
- throw new RangeError('emissiveColor must be nonnegative.');
+ throw invalidField('emissiveColor', result.emissiveColor, 'three numbers of 0 or more, such as [1, 0.5, 0.2]');
}
}
copyMaterialLayers(value, result);
@@ -282,17 +287,17 @@ function nodeFrom(value) {
rotation: vector(defaultValue(value.rotation, [0, 0, 0, 1]), 4, 'rotation'),
scale: vector(defaultValue(value.scale, [1, 1, 1]), 3, 'scale') };
if (result.parent !== null) {
- identifier(result.parent);
+ identifier(result.parent, 'parent');
}
if (result.label !== undefined && (typeof result.label !== 'string' || result.label.length > 256)) {
- throw new TypeError('label must be a string of at most 256 characters.');
+ throw invalidField('label', result.label, 'a string of at most 256 characters, such as "left wall"', TypeError);
}
if (result.scale.some(component => component <= 0 || Math.fround(component) <= 0)) {
- throw new RangeError('scale must remain positive at Float32 precision.');
+ throw invalidField('scale', result.scale, 'three positive numbers, such as [1, 1, 1]');
}
const length = Math.hypot(...result.rotation);
if (length === 0) {
- throw new RangeError('rotation quaternion must be nonzero.');
+ throw invalidField('rotation', result.rotation, 'a nonzero quaternion [x, y, z, w], such as [0, 0, 0, 1] for no rotation');
}
result.rotation = result.rotation.map(component => component / length);
if ((value.geometry !== undefined) !== (value.material !== undefined)) {
@@ -360,22 +365,22 @@ function rejectFovWithFocalLength(fields) {
function checkCameraLens(camera) {
if (camera.projection !== undefined && camera.projection !== 'perspective' && camera.projection !== 'orthographic') {
- throw new RangeError('Camera projection must be perspective or orthographic.');
+ throw invalidField('camera.projection', camera.projection, 'perspective or orthographic');
}
const orthographic = camera.projection === 'orthographic';
if (camera.orthoScale !== undefined) {
if (!orthographic) throw new RangeError('Camera orthoScale needs projection orthographic.');
- if (!Number.isFinite(camera.orthoScale) || camera.orthoScale <= 0) throw new RangeError('Camera orthoScale is the view height in metres and must be positive.');
+ if (!Number.isFinite(camera.orthoScale) || camera.orthoScale <= 0) throw invalidField('camera.orthoScale', camera.orthoScale, 'a positive view height in metres, such as 10');
}
if (camera.sensorWidth !== undefined && camera.focalLength === undefined) throw new RangeError('Camera sensorWidth needs focalLength.');
if (camera.focalLength !== undefined) {
if (orthographic) throw new RangeError('Camera focalLength needs a perspective projection; an orthographic camera is sized by orthoScale.');
- if (!Number.isFinite(camera.focalLength) || camera.focalLength <= 0 || camera.focalLength > 10000) throw new RangeError('Camera focalLength must be between 0 and 10000 millimetres.');
- if (camera.sensorWidth !== undefined && !(Number.isFinite(camera.sensorWidth) && camera.sensorWidth > 0 && camera.sensorWidth <= 1000)) throw new RangeError('Camera sensorWidth must be between 0 and 1000 millimetres.');
+ if (!Number.isFinite(camera.focalLength) || camera.focalLength <= 0 || camera.focalLength > 10000) throw invalidField('camera.focalLength', camera.focalLength, 'a lens length above 0 and up to 10000 millimetres, such as 35');
+ if (camera.sensorWidth !== undefined && !(Number.isFinite(camera.sensorWidth) && camera.sensorWidth > 0 && camera.sensorWidth <= 1000)) throw invalidField('camera.sensorWidth', camera.sensorWidth, 'a width above 0 and up to 1000 millimetres, such as 36');
}
if (camera.shift !== undefined) validateCameraShift(camera.shift);
if (camera.fStop !== undefined && !(Number.isFinite(camera.fStop) && camera.fStop >= 0.7 && camera.fStop <= 64)) {
- throw new RangeError('Camera fStop must be between 0.7 and 64. Smaller numbers blur more.');
+ throw invalidField('camera.fStop', camera.fStop, 'a number from 0.7 to 64, such as 2.8 (smaller numbers blur more)');
}
}
@@ -385,23 +390,26 @@ function cameraFrom(value = {}) {
const result = { ...CAMERA_DEFAULTS, ...value };
if (result.focalLength !== undefined) delete result.fov;
checkCameraLens(result);
- result.eye = vector(result.eye, 3, 'eye');
- result.target = vector(result.target, 3, 'target');
- result.up = vector(result.up, 3, 'up');
+ result.eye = vector(result.eye, 3, 'camera.eye');
+ result.target = vector(result.target, 3, 'camera.target');
+ result.up = vector(result.up, 3, 'camera.up');
const upLength = Math.hypot(...result.up);
if (upLength === 0) {
- throw new RangeError('Camera up must be nonzero.');
+ throw invalidField('camera.up', result.up, 'a nonzero direction, such as [0, 1, 0]');
}
result.up = result.up.map(component => component / upLength);
for (const field of ['fov', 'near', 'far']) {
- if (result[field] !== undefined) finite(result[field], field);
+ if (result[field] !== undefined) finite(result[field], `camera.${field}`);
}
// Without fov the lens is a focal length, which gives a valid angle at any positive size.
if ((result.fov !== undefined && (Math.fround(result.fov) <= 0 || Math.fround(result.fov) >= 180)) || Math.fround(result.near) <= 0 || Math.fround(result.far) <= Math.fround(result.near)) {
- throw new RangeError('Camera needs 0 < fov < 180 and 0 < near < far at Float32 precision.');
+ if (result.fov !== undefined && (Math.fround(result.fov) <= 0 || Math.fround(result.fov) >= 180)) {
+ throw invalidField('camera.fov', result.fov, 'degrees above 0 and below 180, such as 50');
+ }
+ throw invalidField('camera.near', [result.near, result.far], 'near above 0 and far above near, such as near 0.1 and far 100');
}
if (result.eye.every((component, axis) => Math.fround(component) === Math.fround(result.target[axis]))) {
- throw new RangeError('Camera eye and target must differ at Float32 precision.');
+ throw invalidField('camera.target', result.target, `a point different from eye ${JSON.stringify(result.eye)}, such as [0, 0, 0]`);
}
const direction = result.target.map((component, axis) => component - result.eye[axis]);
const directionLength = Math.hypot(...direction);
diff --git a/src/field-error.js b/src/field-error.js
new file mode 100644
index 00000000..42f49cff
--- /dev/null
+++ b/src/field-error.js
@@ -0,0 +1,42 @@
+const MAXIMUM_SHOWN_CHARACTERS = 40;
+
+// A short, safe rendering of a rejected value for an error message: JSON for plain data, cut to a fixed length.
+export function describeReceived(value) {
+ let text;
+ if (value === undefined) {
+ text = 'undefined';
+ } else if (typeof value === 'number' || typeof value === 'bigint') {
+ text = String(value);
+ } else if (typeof value === 'function' || typeof value === 'symbol') {
+ text = typeof value;
+ } else {
+ try {
+ text = JSON.stringify(value) ?? String(value);
+ } catch {
+ text = Object.prototype.toString.call(value);
+ }
+ }
+ return text.length > MAXIMUM_SHOWN_CHARACTERS ? `${text.slice(0, MAXIMUM_SHOWN_CHARACTERS - 3)}...` : text;
+}
+
+// Builds the validation error an agent-facing check throws: the field path, the value received and what is accepted,
+// with an example or a range. withFieldPrefix turns the path into a full recipe path for entries of a list.
+export function invalidField(path, value, expected, ErrorType = RangeError) {
+ const error = new ErrorType(`${path}: got ${describeReceived(value)}; expected ${expected}.`);
+ error.fieldPath = path;
+ return error;
+}
+
+// Runs a check on one entry of a list and puts the list position in front of the field path of any field error it
+// raises, so "emissiveColor: ..." becomes "materials[2].emissiveColor: ...".
+export function withFieldPrefix(prefix, check) {
+ try {
+ return check();
+ } catch (error) {
+ if (typeof error?.fieldPath === 'string' && error.message.startsWith(error.fieldPath)) {
+ error.message = `${prefix}.${error.message}`;
+ error.fieldPath = `${prefix}.${error.fieldPath}`;
+ }
+ throw error;
+ }
+}
diff --git a/src/light-bake.js b/src/light-bake.js
index c628bde3..a9e61446 100644
--- a/src/light-bake.js
+++ b/src/light-bake.js
@@ -1,3 +1,4 @@
+import { invalidField } from './field-error.js';
import { MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, MAX_AREA_LIGHTS } from './light-limits.js';
import { buildTriangleBvh } from './triangle-bvh.js';
import { readTriangle } from './triangle-math.js';
@@ -55,7 +56,7 @@ function boundedNumber(options, name) {
const limit = BAKE_LIMITS[name];
const value = options[name] ?? limit.fallback;
if (!Number.isFinite(value) || value < limit.minimum || value > limit.maximum) {
- throw new RangeError(`Light bake ${name} must be a number from ${limit.minimum} to ${limit.maximum}.`);
+ throw invalidField(`bake.${name}`, value, `a number from ${limit.minimum} to ${limit.maximum}, such as ${limit.fallback}`);
}
return name === 'samples' || name === 'bounces' || name === 'maxResolution' ? Math.floor(value) : value;
}
@@ -66,7 +67,7 @@ export function normalizeBakeOptions(options = {}) {
const normalized = {};
for (const name of Object.keys(BAKE_LIMITS)) normalized[name] = boundedNumber(options, name);
normalized.backend = options.backend ?? 'cpu';
- if (!BAKE_BACKENDS.includes(normalized.backend)) throw new TypeError('Light bake backend must be "cpu", "gpu", "webgpu" or "native".');
+ if (!BAKE_BACKENDS.includes(normalized.backend)) throw invalidField('bake.backend', normalized.backend, 'one of "cpu", "gpu", "webgpu" or "native"', TypeError);
return normalized;
}
diff --git a/src/mesh-recipe.js b/src/mesh-recipe.js
index 9b9e6060..6117ca33 100644
--- a/src/mesh-recipe.js
+++ b/src/mesh-recipe.js
@@ -1,4 +1,5 @@
import { editMesh, meshData } from './mesh-edit.js';
+import { invalidField } from './field-error.js';
import { countSelected, selectFaces } from './mesh-select.js';
import {
extrudeFaceRegion, extrudeIndividual, insetRegion, insetIndividual, deleteFaces, flipFaces, translateFaces, mergeByDistance, tagFaces,
@@ -37,19 +38,23 @@ const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,47}$/;
const MAX_OFFSET = 1e6;
+function editField(index, field, value, expected) {
+ return invalidField(`edits[${index}].${field}`, value, expected, TypeError);
+}
+
function editError(index, message) {
return new TypeError(`Mesh edit ${index} (${message})`);
}
function finiteNumber(value, index, label, { minimum = -MAX_OFFSET, maximum = MAX_OFFSET, exclusiveMinimum = false } = {}) {
if (typeof value !== 'number' || !Number.isFinite(value) || value < minimum || value > maximum || (exclusiveMinimum && value === minimum)) {
- throw editError(index, `${label} must be a number ${exclusiveMinimum ? 'above' : 'from'} ${minimum}${maximum < MAX_OFFSET ? ` to ${maximum}` : ''}`);
+ throw editField(index, label, value, `a number ${exclusiveMinimum ? 'above' : 'from'} ${minimum}${maximum < MAX_OFFSET ? ` to ${maximum}` : ''}, such as ${exclusiveMinimum ? minimum + 1 : Math.min(Math.max(1, minimum), maximum)}`);
}
return value;
}
function vector(value, index, label) {
- if (!Array.isArray(value) || value.length !== 3) throw editError(index, `${label} needs three numbers`);
+ if (!Array.isArray(value) || value.length !== 3) throw editField(index, label, value, 'an array of three numbers, such as [0, 1, 0]');
return value.map(component => finiteNumber(component, index, label));
}
@@ -108,7 +113,7 @@ export function normalizeMeshEdits(edits) {
return edits.map((edit, index) => {
if (!edit || typeof edit !== 'object' || Array.isArray(edit)) throw editError(index, 'each edit must be an object');
const definition = MESH_EDIT_OPERATIONS[edit.op];
- if (!definition) throw editError(index, `op must be one of ${Object.keys(MESH_EDIT_OPERATIONS).join(', ')}`);
+ if (!definition) throw editField(index, 'op', edit.op, `one of ${Object.keys(MESH_EDIT_OPERATIONS).join(', ')}`);
for (const key of Object.keys(edit)) {
if (key !== 'op' && !definition.fields.includes(key)) throw editError(index, `${edit.op} does not take ${key}; fields: ${definition.fields.join(', ')}`);
}
@@ -119,7 +124,7 @@ export function normalizeMeshEdits(edits) {
}
if (definition.fields.includes('name')) {
const name = edit.name ?? (['tag', 'vertex_group'].includes(edit.op) ? undefined : `${edit.op.split('_')[0]}-${index + 1}`);
- if (typeof name !== 'string' || !NAME_PATTERN.test(name)) throw editError(index, 'name must be 1 to 48 letters, digits, dots, dashes or underscores');
+ if (typeof name !== 'string' || !NAME_PATTERN.test(name)) throw editField(index, 'name', name, '1 to 48 letters, digits, dots, dashes or underscores, such as "lid.cap"');
normalized.name = name;
}
switch (edit.op) {
@@ -128,7 +133,7 @@ export function normalizeMeshEdits(edits) {
normalized.offset = finiteNumber(edit.offset, index, 'offset');
if (edit.direction !== undefined) normalized.direction = vector(edit.direction, index, 'direction');
if (edit.alongNormals !== undefined) {
- if (typeof edit.alongNormals !== 'boolean') throw editError(index, 'alongNormals must be boolean');
+ if (typeof edit.alongNormals !== 'boolean') throw editField(index, 'alongNormals', edit.alongNormals, 'true or false');
if (edit.alongNormals && edit.direction !== undefined) throw editError(index, 'alongNormals and direction cannot be combined');
normalized.alongNormals = edit.alongNormals;
}
@@ -147,7 +152,7 @@ export function normalizeMeshEdits(edits) {
if (!['radius', 'curve', 'connected'].includes(key)) throw editError(index, `falloff does not take ${key}`);
}
const curve = falloff.curve ?? 'smooth';
- if (!Object.hasOwn(FALLOFF_CURVES, curve)) throw editError(index, `falloff curve must be one of ${Object.keys(FALLOFF_CURVES).join(', ')}`);
+ if (!Object.hasOwn(FALLOFF_CURVES, curve)) throw editField(index, 'falloff.curve', curve, `one of ${Object.keys(FALLOFF_CURVES).join(', ')}`);
if (falloff.connected !== undefined && typeof falloff.connected !== 'boolean') throw editError(index, 'falloff.connected must be boolean');
normalized.falloff = {
radius: finiteNumber(falloff.radius, index, 'falloff.radius', { minimum: 0, exclusiveMinimum: true }),
@@ -156,7 +161,7 @@ export function normalizeMeshEdits(edits) {
}
break;
case 'boolean': {
- if (!BOOLEAN_OPERATIONS.includes(edit.operation)) throw editError(index, `operation must be one of ${BOOLEAN_OPERATIONS.join(', ')}`);
+ if (!BOOLEAN_OPERATIONS.includes(edit.operation)) throw editField(index, 'operation', edit.operation, `one of ${BOOLEAN_OPERATIONS.join(', ')}`);
normalized.operation = edit.operation;
if (!edit.cutter || typeof edit.cutter !== 'object' || Array.isArray(edit.cutter) || typeof edit.cutter.type !== 'string') {
throw editError(index, 'cutter must be a primitive record such as { "type": "cylinder", "segments": 32 }');
@@ -177,7 +182,7 @@ export function normalizeMeshEdits(edits) {
}
normalized.target = edit.target;
normalizePlacement(edit, normalized, index);
- if (!SHRINKWRAP_MODES.includes(edit.mode ?? 'nearest')) throw editError(index, `mode must be one of ${SHRINKWRAP_MODES.join(', ')}`);
+ if (!SHRINKWRAP_MODES.includes(edit.mode ?? 'nearest')) throw editField(index, 'mode', edit.mode, `one of ${SHRINKWRAP_MODES.join(', ')}`);
normalized.mode = edit.mode ?? 'nearest';
if (normalized.mode === 'project') {
normalized.direction = vector(edit.direction, index, 'direction');
@@ -187,16 +192,16 @@ export function normalizeMeshEdits(edits) {
}
normalized.offset = edit.offset === undefined ? 0 : finiteNumber(edit.offset, index, 'offset', { minimum: 0 });
if (edit.maxDistance !== undefined) normalized.maxDistance = finiteNumber(edit.maxDistance, index, 'maxDistance', { minimum: 0 });
- if (!['error', 'keep'].includes(edit.onMiss ?? 'error')) throw editError(index, 'onMiss must be error or keep');
+ if (!['error', 'keep'].includes(edit.onMiss ?? 'error')) throw editField(index, 'onMiss', edit.onMiss, '"error" or "keep"');
normalized.onMiss = edit.onMiss ?? 'error';
break;
case 'mirror':
- if (!['x', 'y', 'z'].includes(edit.axis ?? 'x')) throw editError(index, 'axis must be x, y or z');
+ if (!['x', 'y', 'z'].includes(edit.axis ?? 'x')) throw editField(index, 'axis', edit.axis, '"x", "y" or "z"');
normalized.axis = edit.axis ?? 'x';
normalized.merge = edit.merge === undefined ? 0.001 : finiteNumber(edit.merge, index, 'merge', { minimum: 0, maximum: 1e3 });
break;
case 'array':
- if (!Number.isInteger(edit.count ?? 2) || (edit.count ?? 2) < 1 || (edit.count ?? 2) > 256) throw editError(index, 'count must be an integer from 1 to 256');
+ if (!Number.isInteger(edit.count ?? 2) || (edit.count ?? 2) < 1 || (edit.count ?? 2) > 256) throw editField(index, 'count', edit.count, 'a whole number from 1 to 256, such as 4');
normalized.count = edit.count ?? 2;
normalized.offset = edit.offset === undefined ? [0, 0, 0] : vector(edit.offset, index, 'offset');
normalized.relativeOffset = edit.relativeOffset === undefined ? (edit.offset === undefined ? [1, 0, 0] : [0, 0, 0]) : vector(edit.relativeOffset, index, 'relativeOffset');
@@ -205,7 +210,7 @@ export function normalizeMeshEdits(edits) {
case 'solidify':
normalized.thickness = finiteNumber(edit.thickness, index, 'thickness', { minimum: 0, exclusiveMinimum: true });
normalized.offset = edit.offset === undefined ? -1 : finiteNumber(edit.offset, index, 'offset', { minimum: -1, maximum: 1 });
- if (edit.evenThickness !== undefined && typeof edit.evenThickness !== 'boolean') throw editError(index, 'evenThickness must be boolean');
+ if (edit.evenThickness !== undefined && typeof edit.evenThickness !== 'boolean') throw editField(index, 'evenThickness', edit.evenThickness, 'true or false');
normalized.evenThickness = edit.evenThickness ?? true;
break;
case 'bevel':
@@ -214,10 +219,10 @@ export function normalizeMeshEdits(edits) {
}
normalized.edges = edit.edges ?? { angle: 30 };
normalized.width = finiteNumber(edit.width, index, 'width', { minimum: 0, exclusiveMinimum: true });
- if (!Number.isInteger(edit.segments ?? 1) || (edit.segments ?? 1) < 1 || (edit.segments ?? 1) > 16) throw editError(index, 'segments must be an integer from 1 to 16');
+ if (!Number.isInteger(edit.segments ?? 1) || (edit.segments ?? 1) < 1 || (edit.segments ?? 1) > 16) throw editField(index, 'segments', edit.segments, 'a whole number from 1 to 16, such as 3');
normalized.segments = edit.segments ?? 1;
normalized.profile = edit.profile === undefined ? 0.5 : finiteNumber(edit.profile, index, 'profile', { minimum: 0, maximum: 1 });
- if (edit.clampOverlap !== undefined && typeof edit.clampOverlap !== 'boolean') throw editError(index, 'clampOverlap must be boolean');
+ if (edit.clampOverlap !== undefined && typeof edit.clampOverlap !== 'boolean') throw editField(index, 'clampOverlap', edit.clampOverlap, 'true or false');
normalized.clampOverlap = edit.clampOverlap ?? true;
break;
case 'loop_cut':
@@ -225,11 +230,11 @@ export function normalizeMeshEdits(edits) {
throw editError(index, 'edges must be a rule that picks the ring, for example { "along": [0, 1, 0] } for the vertical edges');
}
normalized.edges = edit.edges;
- if (!Number.isInteger(edit.cuts ?? 1) || (edit.cuts ?? 1) < 1 || (edit.cuts ?? 1) > 16) throw editError(index, 'cuts must be an integer from 1 to 16');
+ if (!Number.isInteger(edit.cuts ?? 1) || (edit.cuts ?? 1) < 1 || (edit.cuts ?? 1) > 16) throw editField(index, 'cuts', edit.cuts, 'a whole number from 1 to 16, such as 1');
normalized.cuts = edit.cuts ?? 1;
if (edit.factor !== undefined && normalized.cuts !== 1) throw editError(index, 'factor applies only to a single cut');
normalized.factor = edit.factor === undefined ? 0.5 : finiteNumber(edit.factor, index, 'factor', { minimum: 0, maximum: 1 });
- if (normalized.factor === 0 || normalized.factor === 1) throw editError(index, 'factor must be strictly between 0 and 1');
+ if (normalized.factor === 0 || normalized.factor === 1) throw editField(index, 'factor', normalized.factor, 'a number above 0 and below 1, such as 0.5');
break;
case 'uv_unwrap':
if (edit.seams !== undefined && (!edit.seams || typeof edit.seams !== 'object' || Array.isArray(edit.seams))) {
@@ -241,7 +246,7 @@ export function normalizeMeshEdits(edits) {
break;
case 'subdivide':
if (!Number.isInteger(edit.levels ?? 1) || (edit.levels ?? 1) < 1 || (edit.levels ?? 1) > MAX_SUBDIVISION_LEVELS) {
- throw editError(index, `levels must be an integer from 1 to ${MAX_SUBDIVISION_LEVELS}`);
+ throw editField(index, 'levels', edit.levels, `a whole number from 1 to ${MAX_SUBDIVISION_LEVELS}, such as 1`);
}
normalized.levels = edit.levels ?? 1;
if (edit.crease !== undefined) {
@@ -265,7 +270,7 @@ export function normalizeMeshEdits(edits) {
normalized.field = checkedField(edit.field, index, 'field', 'scalar');
normalized.strength = edit.strength === undefined ? 1 : finiteNumber(edit.strength, index, 'strength');
normalized.midlevel = edit.midlevel === undefined ? 0.5 : finiteNumber(edit.midlevel, index, 'midlevel');
- if (edit.direction !== undefined && !DISPLACE_DIRECTIONS.includes(edit.direction)) throw editError(index, `direction must be one of ${DISPLACE_DIRECTIONS.join(', ')}`);
+ if (edit.direction !== undefined && !DISPLACE_DIRECTIONS.includes(edit.direction)) throw editField(index, 'direction', edit.direction, `one of ${DISPLACE_DIRECTIONS.join(', ')}`);
normalized.direction = edit.direction ?? 'normal';
if (edit.group !== undefined) {
if (typeof edit.group !== 'string' || !NAME_PATTERN.test(edit.group)) throw editError(index, 'group must be the name of a vertex group');
diff --git a/src/motion-validation.js b/src/motion-validation.js
index dd49dfdf..bfe9cb46 100644
--- a/src/motion-validation.js
+++ b/src/motion-validation.js
@@ -1,4 +1,5 @@
// Checks shared by the motion normalizers: agent input is untrusted plain data, so every field is named and bounded.
+import { invalidField } from './field-error.js';
export function knownKeys(value, fields, label) {
if (!value || Object.getPrototypeOf(value) !== Object.prototype) {
@@ -14,7 +15,7 @@ export function knownKeys(value, fields, label) {
export function finite(value, label) {
if (!Number.isFinite(value) || !Number.isFinite(Math.fround(value))) {
- throw new RangeError(`${label} must be finite at Float32 precision.`);
+ throw invalidField(label, value, 'a finite number that fits Float32, such as 0.5');
}
return value;
}
@@ -22,7 +23,7 @@ export function finite(value, label) {
export function bounded(value, minimum, maximum, label) {
finite(value, label);
if (value < minimum || value > maximum) {
- throw new RangeError(`${label} must be within ${minimum} and ${maximum}.`);
+ throw invalidField(label, value, `a number from ${minimum} to ${maximum}, such as ${minimum > 0 ? minimum : Math.min(maximum, 1)}`);
}
return value;
}
@@ -46,7 +47,7 @@ export function valueFrom(value, size, label) {
}
denseArray(value, size, label);
if (value.length !== size) {
- throw new TypeError(`${label} needs ${size} components.`);
+ throw invalidField(label, value, `an array of ${size} numbers, such as [${Array(size).fill(0).join(', ')}]`, TypeError);
}
return value.map(component => finite(component, label));
}
diff --git a/tests/actionable-errors.test.js b/tests/actionable-errors.test.js
new file mode 100644
index 00000000..96d412ee
--- /dev/null
+++ b/tests/actionable-errors.test.js
@@ -0,0 +1,128 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createAgentScene } from '../src/agent-scene.js';
+import { loadAgentSceneModules } from '../src/agent-scene-modules.js';
+import { describeReceived, invalidField, withFieldPrefix } from '../src/field-error.js';
+
+function baseRecipe() {
+ return {
+ format: '67js.scene', schemaVersion: 1,
+ geometries: [{ id: 'cube', type: 'box', bevel: 0 }, { id: 'block', type: 'mesh', base: { type: 'box', bevel: 0 } }],
+ materials: [{ id: 'plain', color: [0.5, 0.5, 0.5] }, { id: 'paint', color: [0.2, 0.4, 0.8] }],
+ nodes: [{ id: 'body', geometry: 'cube', material: 'paint' }, { id: 'child', parent: 'body' }],
+ motion: { duration: 1, loop: false, tracks: [{ kind: 'node', id: 'body', property: 'translation', keyframes: [{ time: 0, value: [0, 0, 0] }] }] },
+ };
+}
+
+function badRecipe(change) {
+ return async () => {
+ const recipe = baseRecipe();
+ change(recipe);
+ await loadAgentSceneModules(recipe);
+ return createAgentScene(recipe);
+ };
+}
+
+function badApply(operation) {
+ return async () => {
+ const recipe = baseRecipe();
+ await loadAgentSceneModules(recipe);
+ const scene = createAgentScene(recipe);
+ await loadAgentSceneModules(operation);
+ return scene.apply([operation], { expectedRevision: 0 });
+ };
+}
+
+// Each case: how an agent reaches the error, the full field path it must name, and the value it must echo.
+const CASES = [
+ ['material emissiveColor below zero', badRecipe(recipe => { recipe.materials[1].emissiveColor = [-1, 0, 0]; }), 'materials[1].emissiveColor', '[-1,0,0]'],
+ ['material opacity above one', badRecipe(recipe => { recipe.materials[0].opacity = 2; }), 'materials[0].opacity', '2'],
+ ['material metallic above one', badRecipe(recipe => { recipe.materials[0].metallic = 3; }), 'materials[0].metallic', '3'],
+ ['material color above one', badRecipe(recipe => { recipe.materials[1].color = [2, 0, 0]; }), 'materials[1].color', '[2,0,0]'],
+ ['material roughness as text', badRecipe(recipe => { recipe.materials[0].roughness = 'rough'; }), 'materials[0].roughness', '"rough"'],
+ ['material alphaMode unknown', badRecipe(recipe => { recipe.materials[0].alphaMode = 'glass'; }), 'materials[0].alphaMode', '"glass"'],
+ ['material emission below zero', badRecipe(recipe => { recipe.materials[0].emission = -2; }), 'materials[0].emission', '-2'],
+ ['node scale not positive', badRecipe(recipe => { recipe.nodes[0].scale = [1, 0, 1]; }), 'nodes[0].scale', '[1,0,1]'],
+ ['node rotation all zero', badRecipe(recipe => { recipe.nodes[1].rotation = [0, 0, 0, 0]; }), 'nodes[1].rotation', '[0,0,0,0]'],
+ ['node translation with two numbers', badRecipe(recipe => { recipe.nodes[0].translation = [1, 2]; }), 'nodes[0].translation', '[1,2]'],
+ ['node parent that is not text', badRecipe(recipe => { recipe.nodes[1].parent = 7; }), 'nodes[1].parent', '7'],
+ ['camera fStop out of range', badRecipe(recipe => { recipe.camera = { fStop: 100 }; }), 'camera.fStop', '100'],
+ ['camera fov out of range', badRecipe(recipe => { recipe.camera = { fov: 200 }; }), 'camera.fov', '200'],
+ ['camera focalLength zero', badRecipe(recipe => { recipe.camera = { focalLength: 0 }; }), 'camera.focalLength', '0'],
+ ['camera eye with one number', badRecipe(recipe => { recipe.camera = { eye: [1] }; }), 'camera.eye', '[1]'],
+ ['point light intensity below zero', badRecipe(recipe => { recipe.environment = { pointLights: [{ position: [0, 1, 0], intensity: -1 }] }; }), 'environment.pointLights[0].intensity', '-1'],
+ ['spot light angle too wide', badRecipe(recipe => { recipe.environment = { spotLights: [{ position: [0, 1, 0], direction: [0, -1, 0], angle: 5 }] }; }), 'environment.spotLights[0].angle', '5'],
+ ['area light width zero', badRecipe(recipe => { recipe.environment = { areaLights: [{ position: [0, 1, 0], direction: [0, -1, 0], width: 0, height: 1 }] }; }), 'environment.areaLights[0].width', '0'],
+ ['second point light position short', badRecipe(recipe => { recipe.environment = { pointLights: [{ position: [0, 1, 0] }, { position: [0, 1] }] }; }), 'environment.pointLights[1].position', '[0,1]'],
+ ['fog density too high', badRecipe(recipe => { recipe.environment = { fogDensity: 99 }; }), 'environment.fogDensity', '99'],
+ ['fog color above one', badRecipe(recipe => { recipe.environment = { fogColor: [0.2, 4, 0.2] }; }), 'environment.fogColor[1]', '4'],
+ ['sun direction all zero', badRecipe(recipe => { recipe.environment = { lightDirection: [0, 0, 0] }; }), 'environment.lightDirection', '[0,0,0]'],
+ ['view transform unknown', badRecipe(recipe => { recipe.environment = { viewTransform: 'filmic' }; }), 'environment.viewTransform', '"filmic"'],
+ ['bake preset unknown', badRecipe(recipe => { recipe.bake = { preset: 'ultra' }; }), 'bake.preset', '"ultra"'],
+ ['bake gridFog as text', badRecipe(recipe => { recipe.bake = { irradianceGrid: true, gridFog: 'yes' }; }), 'bake.gridFog', '"yes"'],
+ ['mesh edit subdivide levels too high', badRecipe(recipe => { recipe.geometries[1].edits = [{ op: 'subdivide', levels: 9 }]; }), 'geometries[1].edits[0].levels', '9'],
+ ['mesh edit bevel segments too high', badApply({ type: 'edit-mesh', geometry: 'block', edits: [{ op: 'bevel', edges: { all: true }, width: 0.1, segments: 40 }] }), 'edits[0].segments', '40'],
+ ['mesh edit array count zero', badApply({ type: 'edit-mesh', geometry: 'block', edits: [{ op: 'array', count: 0 }] }), 'edits[0].count', '0'],
+ ['mesh edit unknown op', badApply({ type: 'edit-mesh', geometry: 'block', edits: [{ op: 'knife' }] }), 'edits[0].op', '"knife"'],
+ ['mesh edit offset as text', badApply({ type: 'edit-mesh', geometry: 'block', edits: [{ op: 'extrude_face_region', select: { all: true }, offset: 'far' }] }), 'edits[0].offset', '"far"'],
+ ['motion scale keyframe not positive', badRecipe(recipe => { recipe.motion.tracks[0] = { kind: 'node', id: 'body', property: 'scale', keyframes: [{ time: 0, value: [1, 1, 1] }, { time: 1, value: [0, 1, 1] }] }; }), 'motion.tracks[0].keyframes[1].value', '[0,1,1]'],
+ ['motion keyframe time past the duration', badRecipe(recipe => { recipe.motion.tracks[0].keyframes[0].time = 5; }), 'motion.tracks[0].keyframes[0].time', '5'],
+ ['motion duration too long', badRecipe(recipe => { recipe.motion.duration = 100; }), 'motion.duration', '100'],
+ ['motion loop as text', badRecipe(recipe => { recipe.motion.loop = 'yes'; }), 'motion.loop', '"yes"'],
+ ['motion interpolation unknown', badRecipe(recipe => { recipe.motion.tracks[0].interpolation = 'BOUNCE'; }), 'motion.tracks[0].interpolation', '"BOUNCE"'],
+];
+
+// A message is actionable when it gives a way to fix the input: a range, a list of choices or an example.
+const ACCEPTED = /such as|\bfrom -?[\d.e]+ to -?[\d.e]+|one of |true or false|above \d|\bor more\b/;
+
+assert.ok(CASES.length >= 20, 'the walk covers at least 20 bad inputs');
+
+for (const [label, trigger, path, received] of CASES) {
+ test(`error for ${label} names the field, the value and what is accepted`, async () => {
+ let message;
+ try {
+ await trigger();
+ } catch (error) {
+ message = error.message;
+ }
+ assert.ok(message, `${label} must throw`);
+ assert.ok(message.includes(path), `path ${path} missing in: ${message}`);
+ assert.ok(message.includes(`got ${received}`), `received value ${received} missing in: ${message}`);
+ assert.match(message, /expected /, `no expectation in: ${message}`);
+ assert.match(message, ACCEPTED, `no example or range in: ${message}`);
+ });
+}
+
+test('a long received value is cut so the message stays short', () => {
+ const shown = describeReceived('x'.repeat(500));
+ assert.ok(shown.length <= 40);
+ assert.ok(shown.endsWith('...'));
+ assert.equal(describeReceived(undefined), 'undefined');
+ assert.equal(describeReceived([1, 2]), '[1,2]');
+ const circular = {};
+ circular.self = circular;
+ assert.equal(describeReceived(circular), '[object Object]');
+});
+
+test('withFieldPrefix puts the list position before a field path and leaves other errors alone', () => {
+ assert.throws(() => withFieldPrefix('lights[3]', () => { throw invalidField('color', [2], 'three numbers'); }), /^RangeError: lights\[3\]\.color: got \[2\]/);
+ assert.throws(() => withFieldPrefix('lights[3]', () => { throw new RangeError('Plain failure.'); }), /^RangeError: Plain failure\.$/);
+});
+
+test('a schema error through the MCP layer names the field path and the value received', async () => {
+ const { Client } = await import('@modelcontextprotocol/client');
+ const { InMemoryTransport } = await import('@modelcontextprotocol/server');
+ const { createAgentMcpServer } = await import('../scripts/mcp-server.mjs');
+ const server = createAgentMcpServer({ async close() {}, activeSessionId() { return null; } });
+ const client = new Client({ name: 'actionable-errors-test', version: '1' });
+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+ await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+ try {
+ const recipe = { format: '67js.scene', schemaVersion: 1, materials: [{ id: 'paint', color: [0.5, 0.5, 2] }], nodes: [] };
+ const result = await client.callTool({ name: 'scene_create', arguments: { recipe } });
+ assert.equal(result.isError, true);
+ assert.match(result.content[0].text, /recipe\.materials\.0\.color\.2: Too big: expected number to be <=1 \(got 2\)/);
+ } finally {
+ await client.close();
+ }
+});
diff --git a/tests/agent-asset-retarget.test.js b/tests/agent-asset-retarget.test.js
index e73d41da..61daf73d 100644
--- a/tests/agent-asset-retarget.test.js
+++ b/tests/agent-asset-retarget.test.js
@@ -122,5 +122,5 @@ test('keyed morph weights blink and open the jaw by target name, and seeking rep
assert.deepEqual(face(), atBlink, 'seeking back repeats the earlier weights');
assert.deepEqual(hierarchyOf(target).morphTargetNames, FACE_TARGETS);
await assert.rejects(createTarget({ duration: 1, tracks: [{ kind: 'morph', id: 'cheekPuff', property: 'weight', keyframes: [{ time: 0, value: 1 }] }] }), /Morph targets of this asset: eyeBlinkLeft/);
- await assert.rejects(createTarget({ duration: 1, tracks: [{ kind: 'morph', id: 'jawOpen', property: 'weight', keyframes: [{ time: 0, value: 2 }] }] }), /within zero and one/);
+ await assert.rejects(createTarget({ duration: 1, tracks: [{ kind: 'morph', id: 'jawOpen', property: 'weight', keyframes: [{ time: 0, value: 2 }] }] }), /morph weight from 0 to 1/);
});
diff --git a/tests/agent-bake-stale.test.js b/tests/agent-bake-stale.test.js
index 8fcc6c83..72c935ad 100644
--- a/tests/agent-bake-stale.test.js
+++ b/tests/agent-bake-stale.test.js
@@ -68,5 +68,5 @@ test('bake.rebake keeps the bakes of the last 4 poses and traces nothing for a p
scene.sampleMotion(2);
scene.sampleMotion(1.5);
assert.equal(scene.inspect().bake.reused, true);
- assert.throws(() => createAgentScene(bakedRoom({ rebake: 'yes' })), /rebake must be a boolean/);
+ assert.throws(() => createAgentScene(bakedRoom({ rebake: 'yes' })), /bake\.rebake: got "yes"; expected true or false/);
});
diff --git a/tests/agent-floor-sky-trace.test.js b/tests/agent-floor-sky-trace.test.js
index 26df49a8..bd09527b 100644
--- a/tests/agent-floor-sky-trace.test.js
+++ b/tests/agent-floor-sky-trace.test.js
@@ -43,7 +43,7 @@ test('environment.floorSkyTrace false turns the trace off', () => {
test('environment.floorSkyTrace that is not a boolean is refused, not read as on', () => {
for (const value of ['off', 0, null, { enabled: false }]) {
- assert.throws(() => createAgentScene(room({ keyColor: [3, 3, 3], floorSkyTrace: value })), /floorSkyTrace must be a boolean/);
+ assert.throws(() => createAgentScene(room({ keyColor: [3, 3, 3], floorSkyTrace: value })), /environment\.floorSkyTrace: got .*; expected true or false/);
}
});
diff --git a/tests/agent-motion-ik-limits.test.js b/tests/agent-motion-ik-limits.test.js
index 08767d3e..83e272ee 100644
--- a/tests/agent-motion-ik-limits.test.js
+++ b/tests/agent-motion-ik-limits.test.js
@@ -52,7 +52,7 @@ test('limits and bendToward are validated', () => {
assert.throws(() => build(arm({ limits: { tip: { z: [0, 1] } } })), /Unknown or unsupported/);
assert.throws(() => build(arm({ limits: { middle: { z: [10, -10] } } })), /min first/);
assert.throws(() => build(arm({ limits: { middle: { w: [0, 1] } } })), /Unknown or unsupported/);
- assert.throws(() => build(arm({ bendToward: [0, 1] })), /3 components/);
+ assert.throws(() => build(arm({ bendToward: [0, 1] })), /an array of 3 numbers/);
});
const bytes = readFileSync(new URL('./fixtures/RobotExpressive.glb', import.meta.url));
diff --git a/tests/agent-motion-ik.test.js b/tests/agent-motion-ik.test.js
index 7bf89808..f3193525 100644
--- a/tests/agent-motion-ik.test.js
+++ b/tests/agent-motion-ik.test.js
@@ -165,7 +165,7 @@ test('mistakes say what to pass', () => {
assert.throws(() => create([armIk({ node: 'nope' })]), /target node must be a node ID/);
assert.throws(() => create([armIk('here')]), /target must be \[x, y, z\]/);
assert.throws(() => create([armIk([0, 0, 0], { end: 'ball' })]), /end must descend from middle/);
- assert.throws(() => create([armIk([0, 0, 0], { weight: 3 })]), /weight must be within/);
+ assert.throws(() => create([armIk([0, 0, 0], { weight: 3 })]), /weight: got 3; expected a number from/);
assert.throws(() => create([{ type: 'aim', target: [0, 0, 0] }]), /needs joint, or joints/);
assert.throws(() => create([armIk([0, 0, 0])], { elbow: { scale: [1, 2, 1] } }), /non-uniform scale.*child node/);
assert.doesNotThrow(() => create([armIk([0.4, 1.5, 0.3])], { tip: { scale: [0.1, 0.2, 0.3] } }));
diff --git a/tests/agent-motion-look.test.js b/tests/agent-motion-look.test.js
index fc9f1d45..800a2676 100644
--- a/tests/agent-motion-look.test.js
+++ b/tests/agent-motion-look.test.js
@@ -87,8 +87,8 @@ test('unknown lights, properties and ill-fitting targets name the valid ones', (
failure({ kind: 'light', id: 'point:0', property: 'radius', keyframes: keys(1, 2) }, /light properties: position, direction, color, intensity/);
failure({ kind: 'sun', property: 'angle', keyframes: keys(1, 2) }, /sun properties: direction, color, intensity/);
failure({ kind: 'sun', id: 'x', property: 'intensity', keyframes: keys(1, 2) }, /Sun tracks cannot have an ID/);
- failure({ kind: 'environment', property: 'skyTop', keyframes: keys([0, 0, 0], [2, 0, 0]) }, /skyTop must stay within 0 and 1/);
- failure({ kind: 'sun', property: 'direction', keyframes: keys([0, 0, 0], [0, 1, 0]) }, /direction needs a length/);
+ failure({ kind: 'environment', property: 'skyTop', keyframes: keys([0, 0, 0], [2, 0, 0]) }, /environment skyTop values from 0 to 1/);
+ failure({ kind: 'sun', property: 'direction', keyframes: keys([0, 0, 0], [0, 1, 0]) }, /keyframes\[0\]\.value: got \[0,0,0\]; expected a direction that is not all zero/);
failure({ kind: 'effects', property: 'exposure', keyframes: keys(1, 99) }, /exposure must stay within/);
assert.throws(() => createAgentScene(sceneRecipe([{ kind: 'effects', property: 'focusDistance', keyframes: keys(1, 2) }],
{ effects: {} })), /focusDistance needs effects.depthOfField.blur above 0/);
diff --git a/tests/agent-motion.test.js b/tests/agent-motion.test.js
index b0ef0334..1d455f4a 100644
--- a/tests/agent-motion.test.js
+++ b/tests/agent-motion.test.js
@@ -114,7 +114,7 @@ test('strict schema, final references, duplicate tracks and allocation bounds re
assert.throws(() => normalizeAgentMotion(motion([]), recipe), /at least one/);
assert.throws(() => normalizeAgentMotion({ ...motion([]), unknown: true }, recipe), /field/);
assert.throws(() => normalizeAgentMotion(motion([{ ...track('emission', 0, 1), id: 'missing' }]), recipe), /not found/);
- assert.throws(() => normalizeAgentMotion(motion([track('emission', 0, 1), track('emission', 0, 1)]), recipe), /Duplicate/);
+ assert.throws(() => normalizeAgentMotion(motion([track('emission', 0, 1), track('emission', 0, 1)]), recipe), /repeats an earlier track/);
assert.throws(() => normalizeAgentMotion(motion([{ kind: 'camera', id: 'camera', property: 'fov', keyframes: [{ time: 0, value: 45 }] }]), recipe), /cannot have/);
assert.throws(() => normalizeAgentMotion(motion([{ ...track('emission', 0, 1), keyframes: [{ time: 0, value: 0, outTangent: 1 }] }]), recipe), /Tangents/);
assert.throws(() => normalizeAgentMotion(motion([{ ...track('emission', 0, 1), interpolation: 'CUBICSPLINE' }]), recipe), /tangent/i);
@@ -145,7 +145,7 @@ test('invalid cubic scale and material overshoot throw without clamping or parti
const sampler = compileAgentMotion(motion([track('emission', 0, 1), { ...channel, interpolation: 'CUBICSPLINE' }]), recipe);
const output = sampler.sample(0);
const before = snapshot(output);
- assert.throws(() => sampler.sample(0.5), /positive|negative/);
+ assert.throws(() => sampler.sample(0.5), /positive numbers|numbers of 0 or more/);
assert.deepEqual(snapshot(output), before);
sampler.sample(1);
sampler.sample(0);
diff --git a/tests/agent-object-reflections.test.js b/tests/agent-object-reflections.test.js
index 01935227..01fb7e2a 100644
--- a/tests/agent-object-reflections.test.js
+++ b/tests/agent-object-reflections.test.js
@@ -40,7 +40,7 @@ test('environment.objectReflections false turns the probes off', () => {
const scene = createAgentScene(stillLife(0.05, { objectReflections: false }));
assert.equal(scene.inspect().reflections, undefined);
assert.ok(scene.parts.every(part => part.material.environmentProbe === undefined));
- assert.throws(() => createAgentScene(stillLife(0.05, { objectReflections: 'no' })), /objectReflections must be a boolean/);
+ assert.throws(() => createAgentScene(stillLife(0.05, { objectReflections: 'no' })), /environment\.objectReflections: got "no"; expected true or false/);
});
test('an edit that changes nothing the probe sees keeps the traced probe', () => {
diff --git a/tests/agent-scene-motion.test.js b/tests/agent-scene-motion.test.js
index ad879269..ff876e39 100644
--- a/tests/agent-scene-motion.test.js
+++ b/tests/agent-scene-motion.test.js
@@ -169,5 +169,5 @@ test('failed set-motion initial sampling is atomic across recipe, transforms and
test('motion loop is optional boolean and never accepts null as a hidden default', () => {
const input = recipe();
input.motion.loop = null;
- assert.throws(() => createAgentScene(input), /loop must be boolean/);
+ assert.throws(() => createAgentScene(input), /motion\.loop: got .*; expected true or false/);
});
diff --git a/tests/agent-scene.test.js b/tests/agent-scene.test.js
index 2b7ad9bd..e7c22bf3 100644
--- a/tests/agent-scene.test.js
+++ b/tests/agent-scene.test.js
@@ -648,5 +648,5 @@ test("recipe materials accept alphaMode 'add' and keep it when opacity is below
assert.equal(exported.materials.find(material => material.id === 'spark').alphaMode, 'add');
assert.equal(exported.materials.find(material => material.id === 'faint spark').alphaMode, 'add');
input.materials.push({ id: 'bad', color: [1, 1, 1], alphaMode: 'multiply' });
- assert.throws(() => createAgentScene(input), /alphaMode must be one of opaque, blend, add/);
+ assert.throws(() => createAgentScene(input), /alphaMode: got .*; expected one of opaque, blend, add/);
});
diff --git a/tests/coplanar-overlap.test.js b/tests/coplanar-overlap.test.js
index 10b83209..53ba2817 100644
--- a/tests/coplanar-overlap.test.js
+++ b/tests/coplanar-overlap.test.js
@@ -78,7 +78,7 @@ test('decal, depthLayer and resolveCoplanar all silence the pair without moving
test('node decal and depthLayer are validated', () => {
assert.throws(() => createAgentScene(recipe([wall, { ...sign, decal: 'yes' }])), /decal must be boolean/);
- assert.throws(() => createAgentScene(recipe([wall, { ...sign, depthLayer: 9 }])), /depthLayer must be within 0 and 4/);
+ assert.throws(() => createAgentScene(recipe([wall, { ...sign, depthLayer: 9 }])), /depthLayer: got 9; expected a whole number from 0 to 4/);
assert.throws(() => createAgentScene(recipe([wall], { resolveCoplanar: true })), /resolveCoplanar/);
});
diff --git a/tests/irradiance-grid.test.js b/tests/irradiance-grid.test.js
index d09021b8..07adcf92 100644
--- a/tests/irradiance-grid.test.js
+++ b/tests/irradiance-grid.test.js
@@ -132,8 +132,8 @@ test('bake.gridFog is a boolean that needs the grid, and is not stored when off'
assert.equal(normalizeAgentBake({ irradianceGrid: true, gridFog: true }).gridFog, true);
assert.equal(Object.hasOwn(normalizeAgentBake({ irradianceGrid: true, gridFog: false }), 'gridFog'), false);
assert.equal(Object.hasOwn(normalizeAgentBake({ irradianceGrid: true }), 'gridFog'), false);
- assert.throws(() => normalizeAgentBake({ gridFog: true }), /needs bake\.irradianceGrid/);
- assert.throws(() => normalizeAgentBake({ irradianceGrid: true, gridFog: 'yes' }), /boolean/);
+ assert.throws(() => normalizeAgentBake({ gridFog: true }), /bake\.gridFog: got true; expected true only together with bake\.irradianceGrid/);
+ assert.throws(() => normalizeAgentBake({ irradianceGrid: true, gridFog: 'yes' }), /bake\.gridFog: got "yes"; expected true or false/);
});
test('the grid scatters in the fog only when the lighting carries the fog', () => {
diff --git a/tests/mcp-camera-lights.test.js b/tests/mcp-camera-lights.test.js
index faa7dbe8..3707c185 100644
--- a/tests/mcp-camera-lights.test.js
+++ b/tests/mcp-camera-lights.test.js
@@ -98,7 +98,7 @@ test('a camera takes fov or focalLength, never both, and checks each lens field'
assert.throws(() => make({ sensorWidth: 36 }), /sensorWidth needs focalLength/);
assert.throws(() => make({ projection: 'orthographic', focalLength: 50 }), /perspective projection/);
assert.throws(() => make({ orthoScale: 4 }), /needs projection orthographic/);
- assert.throws(() => make({ projection: 'orthographic', orthoScale: 0 }), /must be positive/);
+ assert.throws(() => make({ projection: 'orthographic', orthoScale: 0 }), /camera\.orthoScale: got 0; expected a positive view height/);
assert.throws(() => make({ projection: 'fisheye' }), /perspective or orthographic/);
assert.throws(() => make({ shift: [2, 0] }), /shift/);
assert.throws(() => make({ fStop: 0.1 }), /fStop/);
diff --git a/tests/mesh-bevel.test.js b/tests/mesh-bevel.test.js
index f3299fc1..de76aeb3 100644
--- a/tests/mesh-bevel.test.js
+++ b/tests/mesh-bevel.test.js
@@ -131,8 +131,8 @@ test('bevel on an open surface keeps the opening as the only problem, and valida
validateTopology(editMesh(beveled.mesh));
assert.deepEqual(lintMesh(beveled.mesh).problems.map(problem => problem.kind), ['boundary-edge']);
assert.equal(beveled.bevelEdges, 8, 'only edges with two faces bevel');
- assert.throws(() => normalizeMeshEdits([{ op: 'bevel', width: 0 }]), /width must be a number above 0/);
- assert.throws(() => normalizeMeshEdits([{ op: 'bevel', width: 0.1, segments: 40 }]), /segments must be an integer from 1 to 16/);
+ assert.throws(() => normalizeMeshEdits([{ op: 'bevel', width: 0 }]), /edits\[0\]\.width: got 0; expected a number above 0/);
+ assert.throws(() => normalizeMeshEdits([{ op: 'bevel', width: 0.1, segments: 40 }]), /edits\[0\]\.segments: got 40; expected a whole number from 1 to 16/);
assert.throws(() => normalizeMeshEdits([{ op: 'bevel', width: 0.1, edges: [] }]), /edges must be a rule/);
assert.deepEqual(normalizeMeshEdits([{ op: 'bevel', width: 0.1 }])[0].edges, { angle: 30 });
});
diff --git a/tests/mesh-boolean.test.js b/tests/mesh-boolean.test.js
index 83a8c9da..10fcc072 100644
--- a/tests/mesh-boolean.test.js
+++ b/tests/mesh-boolean.test.js
@@ -86,7 +86,7 @@ test('boolean errors explain open inputs, empty results and bad fields', () => {
const open = applyMeshEdits(cube(), [{ op: 'delete', select: { tag: 'top' } }]).mesh;
assert.throws(() => meshBoolean(open, cube(), 'union'), /must be closed for a boolean: 4 boundary-edge/);
assert.throws(() => meshBoolean(cube(), transformMesh(cube(), { translation: [5, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] }), 'intersect'), /leaves nothing/);
- assert.throws(() => applyMeshEdits(cube(), [{ op: 'boolean', operation: 'xor', cutter: { type: 'box' } }], { resolveCutter }), /operation must be one of union/);
+ assert.throws(() => applyMeshEdits(cube(), [{ op: 'boolean', operation: 'xor', cutter: { type: 'box' } }], { resolveCutter }), /edits\[0\]\.operation: got "xor"; expected one of union/);
assert.throws(() => applyMeshEdits(cube(), [{ op: 'boolean', operation: 'union', cutter: { type: 'box' }, scale: [1, -1, 1] }], { resolveCutter }), /scale components must be positive/);
assert.throws(() => applyMeshEdits(cube(), [{ op: 'boolean', operation: 'union', cutter: { type: 'box' } }]), /needs a cutter resolver/);
});
diff --git a/tests/mesh-deform-modifiers.test.js b/tests/mesh-deform-modifiers.test.js
index 1d60433d..2351bd2f 100644
--- a/tests/mesh-deform-modifiers.test.js
+++ b/tests/mesh-deform-modifiers.test.js
@@ -65,9 +65,9 @@ test('hook pulls the vertices inside the radius by the falloff weight and none o
near(raised[0], 2.5, 'the one vertex at the centre moves the whole translation');
const soft = run(cube(), { op: 'hook', center: [0.5, 0.5, 0.5], radius: 1.2, translation: [0, 0, 1], strength: 0.5 });
assert.ok(soft.positions[2 + 3 * 6] > 0.5 && soft.positions[2 + 3 * 6] < 1.1);
- assert.throws(() => normalizeMeshEdits([{ op: 'hook', radius: 0 }]), /radius must be a number above 0/);
+ assert.throws(() => normalizeMeshEdits([{ op: 'hook', radius: 0 }]), /edits\[0\]\.radius: got 0; expected a number above 0/);
assert.throws(() => normalizeMeshEdits([{ op: 'hook', falloff: 'sharp' }]), /falloff must be one of smooth, linear, constant/);
- assert.throws(() => normalizeMeshEdits([{ op: 'hook', strength: 2 }]), /strength must be a number from 0 to 1/);
+ assert.throws(() => normalizeMeshEdits([{ op: 'hook', strength: 2 }]), /edits\[0\]\.strength: got 2; expected a number from 0 to 1/);
});
test('wave lifts vertices inside its ring along z, moves with time and can follow the normal', () => {
@@ -83,7 +83,7 @@ test('wave lifts vertices inside its ring along z, moves with time and can follo
const alongNormal = run(flat, { op: 'wave', normal: true });
assert.ok(Math.abs(alongNormal.positions[2]) > 0 && alongNormal.positions[0] === 0);
assert.throws(() => normalizeMeshEdits([{ op: 'wave', axes: 'z' }]), /axes must be one of xy, x, y/);
- assert.throws(() => normalizeMeshEdits([{ op: 'wave', narrowness: 51 }]), /narrowness must be a number from 0 to 50/);
+ assert.throws(() => normalizeMeshEdits([{ op: 'wave', narrowness: 51 }]), /edits\[0\]\.narrowness: got 51; expected a number from 0 to 50/);
assert.throws(() => normalizeMeshEdits([{ op: 'wave', start: [1] }]), /start needs two numbers/);
});
diff --git a/tests/mesh-edit.test.js b/tests/mesh-edit.test.js
index 8681d11f..e481ada1 100644
--- a/tests/mesh-edit.test.js
+++ b/tests/mesh-edit.test.js
@@ -150,11 +150,11 @@ test('translate with connected falloff moves nearby vertices less', () => {
});
test('edit validation names the op, field and allowed values', () => {
- assert.throws(() => normalizeMeshEdits([{ op: 'knife' }]), /op must be one of extrude_face_region/);
+ assert.throws(() => normalizeMeshEdits([{ op: 'knife' }]), /edits\[0\]\.op: got "knife"; expected one of extrude_face_region/);
assert.throws(() => normalizeMeshEdits([{ op: 'extrude_individual', offset: 1, depth: 2 }]), /does not take depth/);
- assert.throws(() => normalizeMeshEdits([{ op: 'inset_region', thickness: 0 }]), /thickness must be a number above 0/);
+ assert.throws(() => normalizeMeshEdits([{ op: 'inset_region', thickness: 0 }]), /edits\[0\]\.thickness: got 0; expected a number above 0/);
assert.throws(() => normalizeMeshEdits([{ op: 'delete' }]), /delete needs select/);
- assert.throws(() => normalizeMeshEdits([{ op: 'tag', select: { all: true }, name: 'bad name' }]), /name must be/);
+ assert.throws(() => normalizeMeshEdits([{ op: 'tag', select: { all: true }, name: 'bad name' }]), /edits\[0\]\.name: got "bad name"; expected 1 to 48 letters/);
assert.throws(() => normalizeMeshEdits([{ op: 'translate', offset: [0, 1, 0], falloff: { radius: 1, curve: 'wobbly' } }]), /curve must be one of smooth/);
assert.throws(() => applyMeshEdits(cube(), [{ op: 'extrude_individual', select: { tag: 'top' }, offset: 1 }, { op: 'delete', select: { faces: [99] } }]), /Mesh edit 1 \(delete\): Face index 99/);
assert.throws(() => applyMeshEdits(cube(), Array.from({ length: 8 }, () => ({ op: 'extrude_individual', offset: 0.1 })), { maxFaces: 1000 }), /over the limit/);
diff --git a/tests/mesh-fields.test.js b/tests/mesh-fields.test.js
index f05df4c1..a2ce8218 100644
--- a/tests/mesh-fields.test.js
+++ b/tests/mesh-fields.test.js
@@ -145,7 +145,7 @@ test('displace moves a sphere along its normals by (field - midlevel) * strength
}
const raised = applyMeshEdits(cube(), [{ op: 'displace', field: 1, strength: 0.4, midlevel: 0, direction: 'y' }]).mesh;
assert.ok(Math.abs(raised.positions[1] - (cube().positions[1] + 0.4)) < 1e-6);
- assert.throws(() => applyMeshEdits(mesh, [{ op: 'displace', field: 1, direction: 'sideways' }]), /direction must be/);
+ assert.throws(() => applyMeshEdits(mesh, [{ op: 'displace', field: 1, direction: 'sideways' }]), /direction: got "sideways"; expected one of/);
});
test('noise is smooth, stays in 0 to 1 and changes with the seed', () => {
diff --git a/tests/mesh-generator-modifiers.test.js b/tests/mesh-generator-modifiers.test.js
index 9ffb11d4..63bfbee6 100644
--- a/tests/mesh-generator-modifiers.test.js
+++ b/tests/mesh-generator-modifiers.test.js
@@ -54,8 +54,8 @@ test('wireframe makes two quads per face edge, stays closed and puts the strut e
test('wireframe refuses a result over the limits and bad fields', () => {
assert.throws(() => run(cube(), { op: 'wireframe' }, { maxVertices: 10, maxFaces: 1000 }), /wireframe would make 40 vertices/);
- assert.throws(() => normalizeMeshEdits([{ op: 'wireframe', thickness: 0 }]), /thickness must be a number above 0/);
- assert.throws(() => normalizeMeshEdits([{ op: 'wireframe', offset: 2 }]), /offset must be a number from -1 to 1/);
+ assert.throws(() => normalizeMeshEdits([{ op: 'wireframe', thickness: 0 }]), /edits\[0\]\.thickness: got 0; expected a number above 0/);
+ assert.throws(() => normalizeMeshEdits([{ op: 'wireframe', offset: 2 }]), /edits\[0\]\.offset: got 2; expected a number from -1 to 1/);
assert.throws(() => normalizeMeshEdits([{ op: 'wireframe', replace: 'yes' }]), /booleans/);
});
@@ -68,7 +68,7 @@ test('skin puts a closed square tube on every edge and takes a radius per vertex
assert.ok(upperReach > 0.6 && upperReach < 0.7);
assert.throws(() => run(cube(), { op: 'skin', radius: { mul: [0, { attr: 'position', component: 'z' }] } }), /radius must be above zero at every vertex/);
assert.throws(() => run(cube(), { op: 'skin' }, { maxVertices: 50, maxFaces: 1000 }), /skin would make 96 vertices/);
- assert.throws(() => normalizeMeshEdits([{ op: 'skin', radius: -1 }]), /radius must be a number above 0/);
+ assert.throws(() => normalizeMeshEdits([{ op: 'skin', radius: -1 }]), /edits\[0\]\.radius: got -1; expected a number above 0/);
});
test('the generating modifiers run as stack nodes', () => {
diff --git a/tests/mesh-loopcut.test.js b/tests/mesh-loopcut.test.js
index 2c6a6472..3b819532 100644
--- a/tests/mesh-loopcut.test.js
+++ b/tests/mesh-loopcut.test.js
@@ -97,7 +97,7 @@ test('a band around a cylinder extrudes along normals as one joined hoop', () =>
test('loop cut validation and errors are explicit', () => {
assert.throws(() => normalizeMeshEdits([{ op: 'loop_cut' }]), /edges must be a rule that picks the ring/);
assert.throws(() => normalizeMeshEdits([{ op: 'loop_cut', edges: { along: [0, 1, 0] }, cuts: 2, factor: 0.3 }]), /factor applies only to a single cut/);
- assert.throws(() => normalizeMeshEdits([{ op: 'loop_cut', edges: { along: [0, 1, 0] }, factor: 1 }]), /strictly between 0 and 1/);
+ assert.throws(() => normalizeMeshEdits([{ op: 'loop_cut', edges: { along: [0, 1, 0] }, factor: 1 }]), /edits\[0\]\.factor: got 1; expected a number above 0 and below 1/);
assert.throws(() => loopCut(cube(), { along: [1, 1, 1], maxAngle: 1 }), /selects no edges/);
assert.throws(() => loopCut(cube(), { all: true }), /rings cross/);
});
diff --git a/tests/mesh-normal-modifiers.test.js b/tests/mesh-normal-modifiers.test.js
index 0d156bf9..97326a08 100644
--- a/tests/mesh-normal-modifiers.test.js
+++ b/tests/mesh-normal-modifiers.test.js
@@ -69,8 +69,8 @@ test('a higher weight leans further toward the large face and sharp bends stay s
});
test('the normal modifiers name their limits and run as stack nodes', () => {
- assert.throws(() => normalizeMeshEdits([{ op: 'weighted_normal', weight: 0 }]), /weight must be a number from 1 to 100/);
- assert.throws(() => normalizeMeshEdits([{ op: 'weighted_normal', angle: 181 }]), /angle must be a number from 0 to 180/);
+ assert.throws(() => normalizeMeshEdits([{ op: 'weighted_normal', weight: 0 }]), /edits\[0\]\.weight: got 0; expected a number from 1 to 100/);
+ assert.throws(() => normalizeMeshEdits([{ op: 'weighted_normal', angle: 181 }]), /edits\[0\]\.angle: got 181; expected a number from 0 to 180/);
assert.throws(() => normalizeMeshEdits([{ op: 'smooth_by_angle', ignoreSharp: 1 }]), /ignoreSharp must be a boolean/);
const outcome = evaluateMeshStack(cube(), [{ op: 'smooth_by_angle', angle: 100 }, { op: 'weighted_normal' }]);
assert.equal(outcome.results.length, 2);
diff --git a/tests/mesh-subdivide.test.js b/tests/mesh-subdivide.test.js
index 999ee3cc..e6477083 100644
--- a/tests/mesh-subdivide.test.js
+++ b/tests/mesh-subdivide.test.js
@@ -98,7 +98,7 @@ test('the budget is checked before the mesh grows', () => {
});
test('the recipe rejects levels out of range and a sharpness without a crease', () => {
- assert.throws(() => normalizeMeshEdits([{ op: 'subdivide', levels: 5 }]), /levels must be an integer from 1 to 4/);
+ assert.throws(() => normalizeMeshEdits([{ op: 'subdivide', levels: 5 }]), /edits\[0\]\.levels: got 5; expected a whole number from 1 to 4/);
assert.throws(() => normalizeMeshEdits([{ op: 'subdivide', levels: 0 }]), /levels/);
assert.throws(() => normalizeMeshEdits([{ op: 'subdivide', sharpness: 2 }]), /sharpness needs a crease rule/);
assert.throws(() => applyMeshEdits(cube(), [{ op: 'subdivide', crease: { angle: 179 } }]), /selects no edges/);
diff --git a/tests/sun-bounce.test.js b/tests/sun-bounce.test.js
index f1b42862..76e5651b 100644
--- a/tests/sun-bounce.test.js
+++ b/tests/sun-bounce.test.js
@@ -87,7 +87,7 @@ test('open ground and a room with no sun get no lights', () => {
test('environment.sunBounce that is not a number of 0 or more is refused', () => {
for (const value of ['strong', true, -1, null]) {
- assert.throws(() => createAgentScene(roomWithOpening({ sunBounce: value })), /sunBounce must be a number/);
+ assert.throws(() => createAgentScene(roomWithOpening({ sunBounce: value })), /environment\.sunBounce: got .*; expected a number of 0 or more/);
}
assert.equal(createAgentScene(roomWithOpening({ sunBounce: 2 })).environment.sunBounce, 2);
});
diff --git a/tests/view-transform.test.js b/tests/view-transform.test.js
index 7cf2a4f3..16ad300c 100644
--- a/tests/view-transform.test.js
+++ b/tests/view-transform.test.js
@@ -104,8 +104,8 @@ test('recipes take a view transform and a named look, and refuse anything else',
assert.equal(look.environment.viewTransform, 'agx');
assert.equal(look.environment.look, 'warm');
assert.equal(normalizeAgentLook({}).environment.viewTransform, undefined);
- assert.throws(() => normalizeAgentLook({ environment: { viewTransform: 'filmic' } }), /viewTransform must be one of aces, agx, neutral/);
- assert.throws(() => normalizeAgentLook({ environment: { look: '../grade.cube' } }), /look must be one of/);
+ assert.throws(() => normalizeAgentLook({ environment: { viewTransform: 'filmic' } }), /environment\.viewTransform: got "filmic"; expected one of aces, agx, neutral/);
+ assert.throws(() => normalizeAgentLook({ environment: { look: '../grade.cube' } }), /environment\.look: got "..\/grade\.cube"; expected one of/);
});
const IDENTITY_CUBE = (size) => {