3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import assert from 'node:assert/strict';
import test from 'node:test';
import { box, sphere } from '../src/geometry.js';
import { createEnvironmentMap } from '../src/environment.js';
import { PATH_TRACER_JOB_LIMITS } from '../src/path-tracer-capabilities.js';
import {
createCamera, describeIgnoredFeatures, MAX_TRACE_PIXELS, normalizePathTracerOptions, PATH_TRACER_LIMITS, renderBand, renderPathTracedImage, toneMapToRgba8,
} from '../src/path-tracer.js';
import { attachTracer, buildTraceScene } from '../src/path-tracer-scene.js';
function placed(translation, scale) {
return new Float32Array([scale[0], 0, 0, 0, 0, scale[1], 0, 0, 0, 0, scale[2], 0, translation[0], translation[1], translation[2], 1]);
}
function surface(color, extra = {}) {
return { tag: 'surface', metallic: 0, roughness: 0.5, emission: 0, color, ...extra };
}
const FLOOR_ALBEDO = 0.5;
const SUN_STRENGTH = 3;
const FLOOR_ONLY = [{ name: 'floor', geometry: box(0, 1), matrix: placed([0, -0.05, 0], [40, 0.1, 40]), material: surface([FLOOR_ALBEDO, FLOOR_ALBEDO, FLOOR_ALBEDO], { roughness: 1 }) }];
const OVERHEAD_SUN = { keyColor: [SUN_STRENGTH, SUN_STRENGTH, SUN_STRENGTH], lightDirection: [0, 1, 0] };
const LOOKING_DOWN = { eye: [0, 3, 0], target: [0, 0, 0], up: [0, 0, -1], fov: 40 };
const SMALL = { width: 32, height: 24, samples: 4, bounces: 3, threads: 1 };
function checkerScene() {
return {
parts: [
...FLOOR_ONLY,
{ name: 'ball', geometry: sphere(24, 16), matrix: placed([0, 0.6, 0], [0.6, 0.6, 0.6]), material: surface([0.8, 0.3, 0.2], { metallic: 0.5, clearcoat: 0.5 }) },
{ name: 'glass', geometry: sphere(24, 16), matrix: placed([1.2, 0.5, 0], [0.5, 0.5, 0.5]), material: surface([1, 1, 1], { transmission: 1, roughness: 0.05 }) },
],
environment: {
...OVERHEAD_SUN,
pointLights: [{ position: [0, 2, 1], color: [1, 1, 1], intensity: 4, radius: 0.1 }],
map: createEnvironmentMap({ width: 8, height: 4, data: new Float32Array(8 * 4 * 3).fill(0.4) }),
},
camera: { eye: [0, 2, 5], target: [0, 0.5, 0], up: [0, 1, 0], fov: 40 },
};
}
test('the job limits listed for agents match the limits the tracer enforces', () => {
for (const name of ['samples', 'bounces', 'seed']) {
assert.equal(PATH_TRACER_JOB_LIMITS[name].minimum, PATH_TRACER_LIMITS[name].minimum, name);
assert.equal(PATH_TRACER_JOB_LIMITS[name].maximum, PATH_TRACER_LIMITS[name].maximum, name);
assert.equal(PATH_TRACER_JOB_LIMITS[name].default, PATH_TRACER_LIMITS[name].fallback, name);
}
assert.ok(PATH_TRACER_JOB_LIMITS.maxSeconds.maximum <= PATH_TRACER_LIMITS.maxSeconds.maximum);
assert.ok(PATH_TRACER_JOB_LIMITS.noiseThreshold.maximum <= PATH_TRACER_LIMITS.noiseThreshold.maximum);
assert.equal(PATH_TRACER_JOB_LIMITS.noiseThreshold.default, PATH_TRACER_LIMITS.noiseThreshold.fallback);
});
test('options are validated with their bounds', () => {
assert.equal(normalizePathTracerOptions().samples, 64);
assert.equal(normalizePathTracerOptions().width, 960);
const refused = [
{ samples: 0 }, { samples: 1025 }, { samples: 1.5 }, { samples: Number.NaN }, { samples: '8' }, { bounces: 17 }, { bounces: 0 },
{ width: 4097 }, { width: 8 }, { height: -1 }, { seed: -1 }, { seed: 2 ** 31 }, { threads: 9 }, { threads: 0 },
{ maxSeconds: 0 }, { maxSeconds: 1801 }, { maxSeconds: Infinity }, { fireflyClamp: 0 }, { denoise: 'yes' },
{ width: 4096, height: 4096 },
{ width: 2000, height: 1000, samples: 1024, bounces: 16 },
];
for (const options of refused) assert.throws(() => normalizePathTracerOptions(options), /Path tracer|too much|at most/, JSON.stringify(options));
assert.throws(() => normalizePathTracerOptions(null), TypeError);
assert.ok(MAX_TRACE_PIXELS >= 1920 * 1080);
});
test('hostile cameras and scenes are refused before any ray is traced', async () => {
const { parts, environment } = checkerScene();
const badCameras = [
undefined,
{ eye: [0, 0, 0], target: [0, 0, 0], up: [0, 1, 0], fov: 40 },
{ eye: [0, 0, 5], target: [0, 0, 0], up: [0, 0, 1], fov: 40 },
{ eye: [0, 0, Number.NaN], target: [0, 0, 0], up: [0, 1, 0], fov: 40 },
{ eye: [0, 0, 5], target: [0, 0, 0], up: [0, 1, 0], fov: 0 },
{ eye: [0, 0, 5], target: [0, 0, 0], up: [0, 1, 0], fov: 179 },
{ eye: [0, 0, 5, 1], target: [0, 0, 0], up: [0, 1, 0], fov: 40 },
];
for (const camera of badCameras) await assert.rejects(renderPathTracedImage({ parts, environment, camera }, SMALL), /camera|Cannot read/i);
const camera = checkerScene().camera;
await assert.rejects(renderPathTracedImage({ parts: [], environment, camera }, SMALL), /1 to/);
await assert.rejects(renderPathTracedImage({ parts: 'floor', environment, camera }, SMALL), /1 to/);
const nonFinite = [{ ...parts[0], matrix: placed([Number.NaN, 0, 0], [1, 1, 1]) }];
await assert.rejects(renderPathTracedImage({ parts: nonFinite, environment, camera }, SMALL), /finite/);
const brokenIndices = [{ ...parts[0], geometry: { ...parts[0].geometry, indices: new Uint32Array([0, 1, 999999]) } }];
await assert.rejects(renderPathTracedImage({ parts: brokenIndices, environment, camera }, SMALL), /index/i);
const flooded = { ...environment, pointLights: Array.from({ length: 40 }, () => ({ position: [0, 2, 0], color: [1, 1, 1], intensity: 1 })) };
await assert.rejects(renderPathTracedImage({ parts, environment: flooded, camera }, SMALL), /at most/);
});
test('the same scene and seed give the same bytes, and another seed does not', async () => {
const first = await renderPathTracedImage(checkerScene(), SMALL);
const second = await renderPathTracedImage(checkerScene(), SMALL);
assert.deepEqual(first.rgba, second.rgba);
assert.deepEqual(first.linear, second.linear);
const other = await renderPathTracedImage(checkerScene(), { ...SMALL, seed: 7 });
assert.notDeepEqual(first.rgba, other.rgba);
assert.ok(first.linear.every(Number.isFinite));
assert.equal(first.report.width, SMALL.width);
assert.equal(first.report.threads, 1);
});
test('a floor lit by an overhead sun matches the diffuse closed form', async () => {
const { linear } = await renderPathTracedImage(
{ parts: FLOOR_ONLY, environment: OVERHEAD_SUN, camera: LOOKING_DOWN },
{ width: 16, height: 16, samples: 32, bounces: 1, denoise: false, threads: 1 },
);
const centre = (8 * 16 + 8) * 3;
// Radiance of a diffuse surface under irradiance E is albedo * E / pi, shrunk by the Fresnel share the specular lobe
// takes (4 percent at normal incidence). That lobe adds F0 * D(0) / 4 * E, and a fully rough GGX has D(0) = 1 / pi.
const expected = FLOOR_ALBEDO * (1 - 0.04) * SUN_STRENGTH / Math.PI + 0.04 / (4 * Math.PI) * SUN_STRENGTH;
assert.ok(Math.abs(linear[centre] - expected) / expected < 0.05, `got ${linear[centre]}, expected near ${expected}`);
});
test('a rough floor keeps its diffuse light when seen at a grazing angle', async () => {
const GRAZING = { eye: [0, 0.3, 6], target: [0, 0, 0], up: [0, 1, 0], fov: 10 };
const options = { width: 16, height: 16, samples: 32, bounces: 1, denoise: false, threads: 1 };
const down = await renderPathTracedImage({ parts: FLOOR_ONLY, environment: OVERHEAD_SUN, camera: LOOKING_DOWN }, options);
const grazing = await renderPathTracedImage({ parts: FLOOR_ONLY, environment: OVERHEAD_SUN, camera: GRAZING }, options);
const centre = (8 * 16 + 8) * 3;
// Cycles does not dim a rough dielectric's diffuse layer toward the horizon: its specular layer reflects little there.
assert.ok(grazing.linear[centre] > 0.9 * down.linear[centre], `grazing ${grazing.linear[centre]} against ${down.linear[centre]} looking down`);
});
test('a block between the sun and the floor leaves a shadow', async () => {
const blocker = { name: 'block', geometry: box(0, 1), matrix: placed([0, 1, 0], [2, 0.2, 2]), material: surface([0.5, 0.5, 0.5]) };
// Sun from +x at 45 degrees: the block (x from -1 to 1, 1 m up) shades the floor from x = -2 to 0. Seen from above,
// the floor at x = -1.5 is clear of the block's top and inside its shadow.
const slantedSun = { keyColor: [3, 3, 3], lightDirection: [1, 1, 0] };
const render = parts => renderPathTracedImage({ parts, environment: slantedSun, camera: { eye: [0, 8, 0], target: [0, 0, 0], up: [0, 0, -1], fov: 30 } },
{ width: 16, height: 16, samples: 16, bounces: 1, denoise: false, threads: 1 });
const lit = await render(FLOOR_ONLY);
const shaded = await render([...FLOOR_ONLY, blocker]);
const pixel = (8 * 16 + 2) * 3;
assert.ok(lit.linear[pixel] > 0.2, `unshaded floor: ${lit.linear[pixel]}`);
assert.ok(shaded.linear[pixel] < 0.01, `shaded floor: ${shaded.linear[pixel]}`);
});
test('a render that runs out of time throws and returns nothing', async () => {
// Each clock read costs a second, so the limit is passed on any machine.
const realNow = performance.now;
let clockReads = 0;
performance.now = () => {
clockReads += 1;
return clockReads * 1000;
};
try {
await assert.rejects(
renderPathTracedImage(checkerScene(), { width: 256, height: 256, samples: 1024, bounces: 4, maxSeconds: 1, threads: 1 }),
/1 second limit/,
);
} finally {
performance.now = realNow;
}
});
test('denoising keeps the mean of a noisy image and removes some of its noise', async () => {
const scene = checkerScene();
const options = { width: 48, height: 32, samples: 2, bounces: 3, threads: 1 };
const noisy = await renderPathTracedImage(scene, { ...options, denoise: false });
const clean = await renderPathTracedImage(scene, { ...options, denoise: true });
const mean = buffer => buffer.reduce((sum, value) => sum + value, 0) / buffer.length;
const roughness = buffer => {
let total = 0;
for (let index = 3; index < buffer.length; index++) total += Math.abs(buffer[index] - buffer[index - 3]);
return total / buffer.length;
};
assert.ok(Math.abs(mean(clean.linear) - mean(noisy.linear)) / mean(noisy.linear) < 0.1);
assert.ok(roughness(clean.linear) < roughness(noisy.linear));
assert.ok(clean.linear.every(Number.isFinite));
});
test('the display transform matches the rasterizer post pass at known values', () => {
const pixels = toneMapToRgba8(new Float32Array([0, 0, 0, 1, 1, 1]), 2, 1);
assert.deepEqual([...pixels.slice(0, 4)], [0, 0, 0, 255]);
// (1 * (2.51 + 0.03)) / (1 * (2.43 + 0.59) + 0.14) = 0.8038, then 0.8038 ^ (1 / 2.2) = 0.9055.
assert.equal(pixels[4], Math.round(0.9055 * 255));
});
test('what the tracer does not draw is named in the report', () => {
const notes = describeIgnoredFeatures(
[{ material: { occlusionMap: {}, tag: 'liquid' } }, { material: { alphaMode: 'blend', anisotropy: 0.5, iridescence: 1 } }],
{ volumeFog: { density: 1 } },
);
assert.ok(notes.some(note => note.includes('volumeFog')));
assert.ok(notes.some(note => note.includes('occlusionMap')));
assert.ok(notes.some(note => note.includes('anisotropy')));
assert.ok(notes.some(note => note.includes('iridescence')));
assert.ok(notes.some(note => note.includes('liquid')));
assert.ok(notes.some(note => note.includes('Blended')));
assert.ok(notes.some(note => note.includes('environment map')));
});
// ---- Maps, light selection and band independence (issue #129) ----
function floorQuad() {
const half = 20;
return {
positions: new Float32Array([-half, 0, half, half, 0, half, half, 0, -half, -half, 0, -half]),
normals: new Float32Array([0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0]),
uvs: new Float32Array([0, 1, 1, 1, 1, 0, 0, 0]),
indices: new Uint32Array([0, 1, 2, 0, 2, 3]),
};
}
function singleTexel(red, green, blue) {
return { image: { data: new Uint8Array([red, green, blue, 255]), width: 1, height: 1 }, colorSpace: 'linear' };
}
async function renderMappedFloor(materialExtra) {
const parts = [{ name: 'floor', geometry: floorQuad(), material: surface([0.5, 0.5, 0.5], { roughness: 1, ...materialExtra }) }];
const slantedSun = { keyColor: [3, 3, 3], lightDirection: [1, 1, 0] };
const { linear } = await renderPathTracedImage({ parts, environment: slantedSun, camera: LOOKING_DOWN },
{ width: 16, height: 16, samples: 16, bounces: 1, denoise: false, threads: 1 });
return linear[(8 * 16 + 8) * 3];
}
test('a normal map tilts the surface toward or away from the light', async () => {
const flat = await renderMappedFloor({});
const flatMap = await renderMappedFloor({ normalMap: singleTexel(128, 128, 255) });
const towardSun = await renderMappedFloor({ normalMap: singleTexel(204, 128, 230) });
const awayFromSun = await renderMappedFloor({ normalMap: singleTexel(51, 128, 230) });
assert.ok(Math.abs(flatMap - flat) / flat < 0.02, `flat map ${flatMap} against none ${flat}`);
assert.ok(towardSun > flat * 1.2, `tilted toward the sun ${towardSun} against flat ${flat}`);
assert.ok(awayFromSun < flat * 0.5, `tilted away ${awayFromSun} against flat ${flat}`);
});
test('a metallic-roughness map scales the metallic and roughness of the material', async () => {
const plain = await renderMappedFloor({ metallic: 0 });
const metalMasked = await renderMappedFloor({ metallic: 1, metallicRoughnessMap: singleTexel(0, 255, 0) });
const unmasked = await renderMappedFloor({ metallic: 1 });
assert.equal(metalMasked, plain, 'blue channel 0 removes the metal');
assert.notEqual(unmasked, plain);
const smoothed = await renderMappedFloor({ metallicRoughnessMap: singleTexel(0, 0, 0) });
assert.notEqual(smoothed, plain, 'green channel 0 makes the surface smooth');
});
test('normal and roughness maps on box-projected materials are drawn through the projection UVs', async () => {
const notes = describeIgnoredFeatures([{ material: { normalMap: {}, metallicRoughnessMap: {}, boxMapScale: 2 } }], {});
assert.ok(!notes.some(note => note.includes('normalMap') || note.includes('metallicRoughnessMap')), notes.join(' '));
const boxed = { boxMapScale: 2, boxMapAxis: 1 };
const flat = await renderMappedFloor({ ...boxed });
const towardSun = await renderMappedFloor({ ...boxed, normalMap: singleTexel(204, 128, 230) });
const awayFromSun = await renderMappedFloor({ ...boxed, normalMap: singleTexel(51, 128, 230) });
assert.ok(towardSun > flat * 1.2, `tilted toward the sun ${towardSun} against flat ${flat}`);
assert.ok(awayFromSun < flat * 0.5, `tilted away ${awayFromSun} against flat ${flat}`);
const plain = await renderMappedFloor({ ...boxed, metallic: 0 });
const metalMasked = await renderMappedFloor({ ...boxed, metallic: 1, metallicRoughnessMap: singleTexel(0, 255, 0) });
assert.equal(metalMasked, plain, 'blue channel 0 removes the metal on a box-projected material');
});
test('drawing one light at random past the first hit keeps the average', async () => {
const room = lights => ({
parts: [
...FLOOR_ONLY,
{ name: 'wall', geometry: box(0, 1), matrix: placed([0, 1, -2], [6, 2, 0.1]), material: surface([0.7, 0.7, 0.7], { roughness: 1 }) },
],
environment: { pointLights: lights },
camera: { eye: [0, 1.5, 3], target: [0, 0.8, -2], up: [0, 1, 0], fov: 50 },
});
const light = intensity => ({ position: [0.5, 1.5, -0.5], color: [1, 1, 1], intensity, radius: 0 });
const options = { width: 16, height: 16, samples: 256, bounces: 4, denoise: false, threads: 1 };
const mean = image => image.linear.reduce((sum, value) => sum + value, 0) / image.linear.length;
const single = mean(await renderPathTracedImage(room([light(8)]), options));
const split = mean(await renderPathTracedImage(room([light(4), light(4)]), options));
assert.ok(Math.abs(single - split) / single < 0.03, `one light ${single}, the same light split in two ${split}`);
});
test('bands drawn in any order and split anywhere give the pixels of the whole image', () => {
const { parts, environment, camera } = checkerScene();
const options = normalizePathTracerOptions({ width: 24, height: 18, samples: 3, bounces: 3, threads: 1 });
const scene = buildTraceScene(parts, environment);
const view = createCamera(camera, options.width, options.height);
const whole = renderBand(scene, view, options, 0, options.height);
const rowFloats = options.width * 3;
for (const [start, end] of [[11, 18], [0, 5], [5, 11]]) {
const band = renderBand(scene, view, options, start, end);
assert.deepEqual(band.color, whole.color.slice(start * rowFloats, end * rowFloats), `rows ${start} to ${end}`);
assert.deepEqual(band.depth, whole.depth.slice(start * options.width, end * options.width));
}
});
test('a scene sent to a worker gets its ray query back from the arrays', () => {
const { parts, environment } = checkerScene();
const scene = buildTraceScene(parts, environment);
const { tracer: _removed, ...sent } = scene;
const revived = attachTracer(structuredClone(sent));
const hit = revived.tracer.trace(0, 5, 0, 0, -1, 0, 100, false);
assert.ok(hit.nearestTriangle >= 0);
});
// ---- Adaptive sampling (issue #129) ----
const NOISY_AND_QUIET = { width: 24, height: 18, samples: 48, bounces: 3, threads: 1, denoise: false };
test('a threshold of zero draws every sample, and a threshold stops the pixels that have converged', async () => {
const fixed = await renderPathTracedImage(checkerScene(), NOISY_AND_QUIET);
assert.equal(fixed.report.averageSamples, 48);
const adaptive = await renderPathTracedImage(checkerScene(), { ...NOISY_AND_QUIET, noiseThreshold: 0.05 });
assert.ok(adaptive.report.averageSamples < 48, `average ${adaptive.report.averageSamples}`);
assert.ok(adaptive.report.averageSamples >= 16, 'no pixel stops before its minimum');
const mean = image => image.linear.reduce((sum, value) => sum + value, 0) / image.linear.length;
assert.ok(Math.abs(mean(adaptive) - mean(fixed)) / mean(fixed) < 0.05, `mean ${mean(adaptive)} against ${mean(fixed)}`);
});
test('adaptive bands split anywhere give the pixels of the whole image', () => {
const { parts, environment, camera } = checkerScene();
const options = normalizePathTracerOptions({ ...NOISY_AND_QUIET, noiseThreshold: 0.05 });
const scene = buildTraceScene(parts, environment);
const view = createCamera(camera, options.width, options.height);
const whole = renderBand(scene, view, options, 0, options.height);
assert.ok(new Set(whole.samplesTaken).size > 1, 'the pixels stop at different sample counts');
const rowFloats = options.width * 3;
for (const [start, end] of [[7, 18], [0, 9]]) {
const band = renderBand(scene, view, options, start, end);
assert.deepEqual(band.color, whole.color.slice(start * rowFloats, end * rowFloats), `rows ${start} to ${end}`);
assert.deepEqual(band.samplesTaken, whole.samplesTaken.slice(start * options.width, end * options.width));
}
});
test('the noise threshold is validated', () => {
for (const noiseThreshold of [-0.1, 1.5, Number.NaN, '0.1']) assert.throws(() => normalizePathTracerOptions({ noiseThreshold }), /noiseThreshold/);
});
test('a camera ray and a shadow ray pass through a deep stack of transparent cutouts', async () => {
const transparentTexel = { image: { data: new Uint8Array([255, 255, 255, 0]), width: 1, height: 1 }, colorSpace: 'linear' };
const floor = { name: 'floor', geometry: floorQuad(), material: surface([0.5, 0.5, 0.5], { roughness: 1 }) };
const layerCount = 24;
const layers = Array.from({ length: layerCount }, (unused, layer) => ({
name: `layer-${layer}`,
geometry: floorQuad(),
matrix: placed([0, 0.1 + layer * 0.05, 0], [1, 1, 1]),
material: surface([1, 1, 1], { map: transparentTexel, alphaMode: 'mask', alphaCutoff: 0.5, doubleSided: true }),
}));
const options = { width: 16, height: 16, samples: 4, bounces: 1, denoise: false, threads: 1 };
const scene = parts => ({ parts, environment: OVERHEAD_SUN, camera: LOOKING_DOWN });
const plain = await renderPathTracedImage(scene([floor]), options);
const stacked = await renderPathTracedImage(scene([floor, ...layers]), options);
const centre = (8 * 16 + 8) * 3;
assert.ok(plain.linear[centre] > 0.1, 'the plain floor is lit');
assert.equal(stacked.linear[centre], plain.linear[centre], 'transparent layers change neither the hit nor the shadow');
});