3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import './support/load-agent-scene-modules.mjs';
import assert from 'node:assert/strict';
import test from 'node:test';
import { createAgentScene } from '../src/agent-scene.js';
import { exposureProblems, framingProblems, lumaShares, mergeFrameDiagnostics, pathTracerFindingsLimit, pathTracerSkippedPassesWarning, placementProblems, textureProblems } from '../src/frame-checks.js';
import { closedRoom, closedRoomWithoutBake, freezeBakeClockForFile } from './support/agent-bake-rooms.mjs';
freezeBakeClockForFile();
// These tests read bake staleness, not light quality, so the bake is as coarse as it can be.
const SMALL_BAKE = { samples: 1, bounces: 1, texelsPerUnit: 1 };
function sceneWithCamera(camera) {
return {
format: 'crucible.scene', schemaVersion: 1,
geometries: [{ id: 'box', type: 'box' }],
materials: [{ id: 'red', color: [0.8, 0.2, 0.2] }],
nodes: [{ id: 'cube', geometry: 'box', material: 'red' }],
camera,
};
}
function framingOf(recipe) {
const scene = createAgentScene(recipe);
return framingProblems({ camera: scene.camera, aspect: 1, boxes: scene.worldBounds() });
}
function kinds(problems) {
return problems.map(problem => problem.kind);
}
test('a subject in view gives no framing warning', () => {
assert.deepEqual(framingOf(sceneWithCamera({ eye: [3, 2, 4], target: [0, 0, 0], fov: 45 })), []);
assert.deepEqual(framingOf(closedRoom()), []);
});
test('a scene with no parts is an empty frame and says what to add', () => {
const problems = framingOf({ ...sceneWithCamera({}), nodes: [] });
assert.deepEqual(kinds(problems), ['empty-frame']);
assert.match(problems[0].fix, /add-node/);
});
test('a camera that looks away from the subject names a camera.target and camera.eye that frame it', () => {
const problems = framingOf(sceneWithCamera({ eye: [3, 2, 4], target: [30, 2, -40], fov: 45 }));
assert.deepEqual(kinds(problems), ['subject-out-of-frame']);
assert.match(problems[0].fix, /camera\.target to \[0,0,0\].*camera\.eye to \[/);
});
test('a subject far away fills so little of the frame that it is called too small', () => {
const problems = framingOf(sceneWithCamera({ eye: [0, 0, 400], target: [0, 0, 0], fov: 45, far: 2000 }));
assert.deepEqual(kinds(problems), ['subject-too-small']);
});
test('hidden parts do not count and orthographic cameras are not judged', () => {
const hidden = sceneWithCamera({ eye: [3, 2, 4], target: [0, 0, 0] });
hidden.nodes[0].visible = false;
assert.deepEqual(kinds(framingOf(hidden)), ['empty-frame']);
assert.deepEqual(framingOf(sceneWithCamera({ eye: [3, 2, 4], target: [30, 2, -40], projection: 'orthographic' })), []);
});
function frameOf(luma, count = 100) {
return new Uint8Array(count * 4).fill(luma);
}
test('exposure warns on a black or clipped frame and not on a normal one', () => {
const black = exposureProblems({ shares: lumaShares(frameOf(0)), exposure: 1 });
assert.deepEqual(kinds(black), ['exposure-black']);
assert.match(black[0].fix, /effects\.exposure from 1 to 4/);
const white = exposureProblems({ shares: lumaShares(frameOf(255)), exposure: 1 });
assert.deepEqual(kinds(white), ['exposure-clipped']);
assert.match(white[0].fix, /effects\.exposure from 1 to 0\.5/);
assert.deepEqual(exposureProblems({ shares: lumaShares(frameOf(120)), exposure: 1 }), []);
const mostlyMid = frameOf(120);
mostlyMid.fill(255, 0, 40);
assert.deepEqual(exposureProblems({ shares: lumaShares(mostlyMid), exposure: 1 }), []);
});
function lightMoves() {
return closedRoom({ bake: SMALL_BAKE, motion: { duration: 2, loop: false, tracks: [
{ kind: 'light', id: 'point:0', property: 'position', keyframes: [{ time: 0, value: [0, 2.7, 0] }, { time: 2, value: [1, 2.7, 0] }] },
] } });
}
test('an unchanged baked scene gives no stale warning at the rest pose', () => {
assert.deepEqual(createAgentScene(closedRoom({ bake: SMALL_BAKE })).bakeStaleness(), []);
const scene = createAgentScene(lightMoves());
scene.sampleMotion(0);
assert.deepEqual(scene.bakeStaleness(), []);
assert.deepEqual(createAgentScene(closedRoomWithoutBake()).bakeStaleness(), []);
});
test('moving a light after a bake gives bake-stale with the fix', () => {
const scene = createAgentScene(lightMoves());
scene.sampleMotion(2);
const problems = scene.bakeStaleness();
assert.deepEqual(kinds(problems), ['bake-stale']);
assert.match(problems[0].fix, /bake.rebake/);
scene.sampleMotion(null);
assert.deepEqual(scene.bakeStaleness(), []);
});
test('moving a part after a bake gives bake-stale', () => {
const scene = createAgentScene(closedRoom({ bake: SMALL_BAKE, motion: { duration: 2, loop: false, tracks: [
{ kind: 'node', id: 'block', property: 'translation', keyframes: [{ time: 0, value: [-0.7, 0.6, -0.4] }, { time: 2, value: [0.5, 0.6, -0.4] }] },
] } }));
scene.sampleMotion(2);
const problems = scene.bakeStaleness();
assert.deepEqual(kinds(problems), ['bake-stale']);
});
test('job metrics keep one entry per warning across frames', () => {
const metrics = {};
const warning = { kind: 'exposure-black', target: 'effects.exposure', message: 'm', fix: 'f' };
mergeFrameDiagnostics(metrics, [warning]);
mergeFrameDiagnostics(metrics, [{ ...warning }]);
mergeFrameDiagnostics(metrics, undefined);
assert.equal(metrics.diagnostics.length, 1);
});
function boxScene(nodes) {
return {
format: 'crucible.scene', schemaVersion: 1,
geometries: [{ id: 'box', type: 'box' }],
materials: [{ id: 'red', color: [0.8, 0.2, 0.2] }],
nodes: nodes.map(node => ({ geometry: 'box', material: 'red', ...node })),
camera: { eye: [0, 3, 8], target: [0, 0.5, 0], fov: 45 },
};
}
function placementOf(nodes) {
return placementProblems({ boxes: createAgentScene(boxScene(nodes)).worldBounds() });
}
test('a box in the air is a floating part with its gap in metres and the nearest part', () => {
const problems = placementOf([
{ id: 'floor', scale: [10, 0.2, 10], translation: [0, 0, 0] },
{ id: 'hover', translation: [0, 1.1, 0] },
]);
assert.deepEqual(kinds(problems), ['floating-node']);
assert.deepEqual(problems[0].nodes, ['hover']);
assert.equal(problems[0].nearest, 'floor');
assert.equal(problems[0].gapMeters, 0.5);
});
test('a box resting on the floor or on another box is not floating', () => {
assert.deepEqual(placementOf([
{ id: 'floor', scale: [10, 0.2, 10], translation: [0, 0, 0] },
{ id: 'rest', translation: [0, 0.6, 0] },
{ id: 'stacked', scale: [0.5, 0.5, 0.5], translation: [0, 1.35, 0] },
]), []);
});
test('two boxes that overlap name both parts and how deep', () => {
const problems = placementOf([
{ id: 'floor', scale: [10, 0.2, 10], translation: [0, 0, 0] },
{ id: 'first', translation: [-0.4, 0.6, 0] },
{ id: 'second', translation: [0.4, 0.6, 0] },
]);
assert.deepEqual(kinds(problems), ['intersecting-nodes']);
assert.deepEqual(problems[0].nodes, ['first', 'second']);
assert.equal(problems[0].penetrationMeters, 0.2);
});
test('a box behind the camera is named as outside the frame while the rest stays in view', () => {
const scene = createAgentScene(boxScene([
{ id: 'seen', translation: [0, 0, 0] },
{ id: 'also-seen', translation: [1, 0, 0] },
{ id: 'behind', translation: [0, 0, 20] },
]));
const problems = framingProblems({ camera: scene.camera, aspect: 1.5, boxes: scene.worldBounds() });
assert.deepEqual(kinds(problems), ['part-outside-frame']);
assert.deepEqual(problems[0].nodes, ['behind']);
assert.equal(problems[0].outsideCount, 1);
assert.equal(problems[0].partCount, 3);
});
test('placement findings are capped and say how many were left out', () => {
const nodes = Array.from({ length: 12 }, (_, index) => ({ id: `hover-${index}`, translation: [index * 3, 1 + index, 0] }));
const problems = placementOf([{ id: 'floor', scale: [60, 0.2, 10], translation: [15, 0, 0] }, ...nodes]);
assert.equal(problems.length, 8);
assert.equal(problems[0].droppedCount, 4);
});
test('parts resting inside a large terrain box do not intersect it, but a real clash beside them does', () => {
const trees = Array.from({ length: 10 }, (_, index) => ({ id: `tree-${index}`, scale: [0.5, 2, 0.5], translation: [index * 4 - 18, 3.9, 0] }));
const terrain = { id: 'terrain', scale: [100, 4, 100], translation: [0, 2, 0] };
assert.deepEqual(placementOf([terrain, ...trees]), []);
const clash = placementOf([
terrain, ...trees,
{ id: 'crate-a', translation: [30, 4.5, 0] },
{ id: 'crate-b', translation: [30.4, 4.5, 0] },
]);
assert.deepEqual(kinds(clash), ['intersecting-nodes']);
assert.deepEqual(clash[0].nodes, ['crate-a', 'crate-b']);
});
test('a cup half inside a table still intersects it', () => {
const problems = placementOf([
{ id: 'table', scale: [2, 0.1, 2], translation: [0, 1, 0] },
{ id: 'cup', scale: [0.2, 0.3, 0.2], translation: [0, 1.1, 0] },
]);
assert.deepEqual(kinds(problems), ['intersecting-nodes']);
});
test('parts outside the frame are left out of per-frame job checks and repeats collapse in job metrics', () => {
const scene = createAgentScene(boxScene([{ id: 'a', translation: [0, 0, 0] }, { id: 'b', translation: [1, 0, 0] }, { id: 'c', translation: [-1, 0, 0] }, { id: 'd', translation: [0, 0, 0.5] }]));
const boxes = scene.worldBounds();
const metrics = {};
for (let frame = 0; frame < 6; frame++) {
const camera = { ...scene.camera, eye: [frame * 0.8, 3, 8], target: [frame * 0.8, 0.5, 0] };
const jobFrame = framingProblems({ camera, aspect: 1.5, boxes, reportPartsOutside: false });
assert.equal(jobFrame.filter(problem => problem.kind === 'part-outside-frame').length, 0);
mergeFrameDiagnostics(metrics, framingProblems({ camera, aspect: 1.5, boxes }));
}
assert.ok((metrics.diagnostics ?? []).filter(problem => problem.kind === 'part-outside-frame').length <= 1);
mergeFrameDiagnostics(metrics, [{ kind: 'subject-out-of-frame', target: 'camera', message: 'x', outsideCount: 3 }]);
mergeFrameDiagnostics(metrics, [{ kind: 'subject-out-of-frame', target: 'camera', message: 'y', outsideCount: 4 }]);
assert.equal(metrics.diagnostics.filter(problem => problem.kind === 'subject-out-of-frame').length, 1);
});
test('a blown-out frame reports how much is clipped', () => {
const [finding] = exposureProblems({ shares: lumaShares(frameOf(255)), exposure: 1 });
assert.equal(finding.kind, 'exposure-clipped');
assert.equal(finding.whitePercent, 100);
const [black] = exposureProblems({ shares: lumaShares(frameOf(0)), exposure: 1 });
assert.equal(black.blackPercent, 100);
});
test('a clipped frame names the strongest lights and the field to lower', () => {
const environment = { keyIntensity: 40, pointLights: [{ intensity: 3 }, { intensity: 12 }], spotLights: [{ intensity: 5 }] };
const [finding] = exposureProblems({ shares: lumaShares(frameOf(255)), exposure: 1, environment });
assert.deepEqual(finding.lights, [
{ field: 'environment.keyIntensity', intensity: 40 },
{ field: 'environment.pointLights[1].intensity', intensity: 12 },
{ field: 'environment.spotLights[0].intensity', intensity: 5 },
]);
assert.match(finding.fix, /effects\.exposure from 1 to 0\.5, or lower the strongest light, environment\.keyIntensity \(now 40\)/);
const lampFirst = exposureProblems({ shares: lumaShares(frameOf(255)), exposure: 1, environment: { keyIntensity: 1, areaLights: [{ intensity: 90 }] } })[0];
assert.match(lampFirst.fix, /environment\.areaLights\[0\]\.intensity \(now 90\)/);
});
test('a clipped frame without an environment keeps the plain fix and no lights field', () => {
const [finding] = exposureProblems({ shares: lumaShares(frameOf(255)), exposure: 1 });
assert.equal(finding.lights, undefined);
assert.match(finding.fix, /or lower environment\.keyIntensity\./);
});
function partWith(name, material) {
return { name, material };
}
const goodImage = { width: 2, height: 2, data: new Uint8ClampedArray(16) };
test('a material whose map has no image is a texture-missing finding that names the parts and the field', () => {
const broken = { id: 'brick', map: { colorSpace: 'srgb' } };
const problems = textureProblems({ parts: [partWith('wall', broken), partWith('floor', broken), partWith('lamp', { id: 'steel' })] });
assert.equal(problems.length, 1);
const [problem] = problems;
assert.equal(problem.kind, 'texture-missing');
assert.deepEqual(problem.nodes, ['wall', 'floor']);
assert.equal(problem.field, 'map');
assert.equal(problem.material, 'brick');
assert.match(problem.message, /2 parts use material brick whose map has no image/);
assert.match(problem.fix, /set-material/);
});
test('empty and truncated texture images are reported and a good image is not', () => {
const parts = [
partWith('a', { id: 'm1', normalMap: { image: { width: 0, height: 0 } } }),
partWith('b', { id: 'm2', map: { image: { width: 4, height: 4, data: new Uint8ClampedArray(8) } } }),
partWith('c', { id: 'm3', map: { image: goodImage }, emissiveMap: { image: { width: 4, height: 4, compressed: { name: 'bc7' } } } }),
];
const problems = textureProblems({ parts });
assert.deepEqual(problems.map(problem => [problem.target, problem.field]), [['a', 'normalMap'], ['b', 'map']]);
assert.match(problems[0].message, /image of no size/);
assert.match(problems[1].message, /fewer pixel bytes/);
assert.deepEqual(textureProblems({ parts: [partWith('ok', { id: 'm', map: { image: goodImage } })] }), []);
});
test('texture findings are capped at 8 per scene', () => {
const parts = Array.from({ length: 12 }, (unused, index) => partWith(`p${index}`, { id: `m${index}`, map: {} }));
assert.equal(textureProblems({ parts }).length, 8);
});
test('a path traced job says why exposure findings and passes are unavailable', () => {
const limit = pathTracerFindingsLimit();
assert.equal(limit.kind, 'findings-unavailable');
assert.equal(limit.severity, 'info');
assert.match(limit.message, /object ID, depth and normal/);
assert.match(limit.fix, /scene_look/);
});
test('a path traced job names the postPasses it skipped, and says nothing when the scene has none', () => {
const warning = pathTracerSkippedPassesWarning([{ name: 'toon-water' }, { name: 'dither' }]);
assert.equal(warning.kind, 'post-passes-skipped');
assert.equal(warning.severity, 'warning');
assert.match(warning.message, /passes toon-water, dither did not touch the image/);
assert.match(warning.fix, /raster job/);
assert.equal(pathTracerSkippedPassesWarning([]), undefined);
assert.equal(pathTracerSkippedPassesWarning(undefined), undefined);
});
test('the path traced exposure advice says a daylit interior traces brighter and to lower the exposure, not raise it', () => {
const { fix } = pathTracerFindingsLimit();
assert.match(fix, /brighter than the raster one/);
assert.match(fix, /lower effects\.exposure/);
});
test('a scene reports the z-fighting its ranking left over, and none when it opted out', async () => {
const { loadAgentSceneModules } = await import('../src/agent-scene-modules.js');
await loadAgentSceneModules({ environment: { resolveCoplanar: 'offset' } });
const scene = createAgentScene({ ...sceneWithCamera({ eye: [3, 2, 4], target: [0, 0, 0], fov: 45 }), environment: { resolveCoplanar: false } });
assert.deepEqual(scene.flushLeftovers(), []);
});
test('the findings-unavailable note survives 20 part findings when it is merged first', () => {
const partFindings = Array.from({ length: 20 }, (unused, index) => ({ kind: 'floating-node', severity: 'warning', target: `part${index}`, message: `part${index} floats` }));
const metrics = {};
mergeFrameDiagnostics(metrics, [pathTracerFindingsLimit(), ...partFindings]);
assert.equal(metrics.diagnostics.length, 16);
assert.equal(metrics.diagnostics[0].kind, 'findings-unavailable');
const droppedWhenLast = {};
mergeFrameDiagnostics(droppedWhenLast, [...partFindings, pathTracerFindingsLimit()]);
assert.equal(droppedWhenLast.diagnostics.some(entry => entry.kind === 'findings-unavailable'), false);
});