3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import test from 'node:test';
import assert from 'node:assert/strict';
import { box } from '../src/geometry.js';
import { exportGlb } from '../src/export.js';
import { BAKE_LIMITS, MAX_BAKE_POINT_LIGHTS, MAX_BAKE_SPOT_LIGHTS, MAX_BAKE_AREA_LIGHTS, bakeLightmaps, normalizeBakeOptions, planLightmaps, MAX_BAKE_PARTS, MAX_GPU_BAKE_PARTS } from '../src/light-bake.js';
import { bakeLightmapsAsync } from '../src/light-bake-gpu.js';
const cube = box(0, 1);
function placed(name, translation, scale, material = {}) {
const matrix = new Float32Array([scale[0], 0, 0, 0, 0, scale[1], 0, 0, 0, 0, scale[2], 0, translation[0], translation[1], translation[2], 1]);
return { name, geometry: cube, matrix, material: { tag: 'surface', color: [0.7, 0.7, 0.7], metallic: 0, roughness: 0.8, emission: 0, ...material } };
}
// A small closed room with a wall that hides the floor behind it from the lamp.
function smallRoom() {
return [
placed('floor', [0, -0.05, 0], [6, 0.1, 6]),
placed('ceiling', [0, 3.05, 0], [6, 0.1, 6]),
placed('back', [0, 1.5, -3.05], [6, 3.2, 0.1]),
placed('left', [-3.05, 1.5, 0], [0.1, 3.2, 6]),
placed('right', [3.05, 1.5, 0], [0.1, 3.2, 6]),
placed('front', [0, 1.5, 3.05], [6, 3.2, 0.1]),
placed('divider', [0, 1.5, 0], [0.1, 3, 3]),
];
}
const lamp = { pointLights: [{ position: [-1.5, 2.5, 0], color: [1, 1, 1], intensity: 8, radius: 0.05 }], keyColor: [0, 0, 0] };
const fastOptions = { samples: 8, bounces: 2, texelsPerUnit: 2, maxResolution: 32 };
function lightmapBytes(part) {
return part.material.emissiveMap.image.data;
}
test('the same input bakes the same bytes', () => {
const first = bakeLightmaps(smallRoom(), lamp, fastOptions);
const second = bakeLightmaps(smallRoom(), lamp, fastOptions);
assert.equal(first.parts.length, second.parts.length);
first.parts.forEach((part, index) => {
assert.deepEqual(Array.from(lightmapBytes(part)), Array.from(lightmapBytes(second.parts[index])));
assert.equal(part.material.emission, second.parts[index].material.emission);
assert.deepEqual(Array.from(part.geometry.uvs), Array.from(second.parts[index].geometry.uvs));
});
});
test('a bake gives each part lightmap UVs and an srgb emissive map, and leaves its input alone', () => {
const parts = smallRoom();
const originalGeometry = parts[0].geometry;
const { parts: baked } = bakeLightmaps(parts, lamp, fastOptions);
const floor = baked[0];
assert.equal(parts[0].geometry, originalGeometry);
assert.equal(parts[0].material.emissiveMap, undefined);
assert.equal(floor.material.emissiveMap.colorSpace, 'srgb');
assert.deepEqual(floor.material.emissiveColor, [1, 1, 1]);
assert.ok(floor.material.emission > 0);
assert.equal(floor.geometry.uvs.length, floor.geometry.positions.length / 3 * 2);
const { width, height, data } = floor.material.emissiveMap.image;
assert.equal(data.length, width * height * 4);
});
test('light reaches a surface the lamp cannot see, and a dark scene bakes nothing', () => {
const { parts: baked } = bakeLightmaps(smallRoom(), lamp, { ...fastOptions, samples: 32 });
// The right half of the floor sits behind the divider, so it gets only bounced light, but not none.
const floor = baked[0];
const bytes = lightmapBytes(floor);
const brightestChannel = Math.max(...bytes.filter((value, index) => index % 4 !== 3));
assert.ok(brightestChannel > 0);
const dark = bakeLightmaps(smallRoom(), { pointLights: [], keyColor: [0, 0, 0] }, fastOptions);
dark.parts.forEach(part => assert.equal(part.material.emissiveMap, undefined));
});
test('a part that sees little of the sky gets a linear occlusion map, and a part that sees all of it gets none', () => {
const closed = bakeLightmaps(smallRoom(), lamp, fastOptions);
const closedFloor = closed.parts[0];
assert.equal(closedFloor.material.occlusionMap.colorSpace, 'linear');
assert.equal(closedFloor.material.occlusionStrength, 1);
assert.ok(Math.min(...closedFloor.material.occlusionMap.image.data.filter((value, index) => index % 4 === 0)) < 8);
// The mean is over texels, and a floor slab is half top face (sees the closed room) and half underside (sees outside), now that texels are spread by area.
assert.ok(Math.abs(closed.report.parts[0].skyVisibility - 0.5) < 0.05);
assert.ok(closed.report.parts[6].skyVisibility < 0.05);
const open = bakeLightmaps([placed('floor', [0, -0.05, 0], [6, 0.1, 6])], lamp, fastOptions);
assert.equal(open.parts[0].material.occlusionMap, undefined);
assert.equal(open.report.parts[0].skyVisibility, 1);
});
test('parts that cannot take a lightmap are skipped with a reason and still block light', () => {
const parts = smallRoom();
parts.push(placed('glass', [1, 0.5, 1], [0.5, 1, 0.5], { alphaMode: 'blend', opacity: 0.4 }));
parts.push(placed('lava', [0, 2, 1], [0.2, 0.2, 0.2], { tag: 'fire' }));
const { parts: baked, report } = bakeLightmaps(parts, lamp, fastOptions);
assert.deepEqual(report.skipped.map(entry => entry.name), ['glass', 'lava']);
assert.equal(baked[7], parts[7]);
assert.equal(baked[8], parts[8]);
});
test('a textured part keeps its map and UV channel 0 and receives light through a second UV set', () => {
const mapImage = { width: 2, height: 2, data: new Uint8ClampedArray([200, 60, 40, 255, 220, 90, 60, 255, 190, 70, 50, 255, 210, 80, 50, 255]) };
const brickMap = { image: mapImage, colorSpace: 'srgb' };
const parts = smallRoom();
const cubeUvs = new Float32Array(cube.positions.length / 3 * 2);
for (let vertex = 0; vertex < cube.positions.length / 3; vertex++) {
cubeUvs[vertex * 2] = cube.positions[vertex * 3] + 0.5;
cubeUvs[vertex * 2 + 1] = cube.positions[vertex * 3 + 1] + 0.5;
}
const texturedCube = { ...cube, uvs: cubeUvs };
parts.push({ ...placed('wall', [1.5, 1, 1.5], [1, 2, 1], { map: brickMap }), geometry: texturedCube });
const { parts: baked, report } = bakeLightmaps(parts, lamp, { ...fastOptions, samples: 16 });
const wall = baked[7];
assert.equal(report.skipped.length, 0);
assert.equal(wall.material.map, brickMap);
assert.equal(wall.material.emissiveMap, undefined);
assert.equal(wall.material.emission, 0);
assert.equal(wall.material.lightMap.colorSpace, 'srgb');
assert.ok(wall.material.lightMapScale > 0);
const vertexCount = wall.geometry.positions.length / 3;
assert.equal(wall.geometry.lightUvs.length, vertexCount * 2);
assert.equal(wall.geometry.uvs.length, vertexCount * 2);
const sourceUvs = new Set();
for (let index = 0; index < cubeUvs.length; index += 2) sourceUvs.add(`${cubeUvs[index]},${cubeUvs[index + 1]}`);
for (let index = 0; index < wall.geometry.uvs.length; index += 2) assert.ok(sourceUvs.has(`${wall.geometry.uvs[index]},${wall.geometry.uvs[index + 1]}`));
const again = bakeLightmaps(parts, lamp, { ...fastOptions, samples: 16 }).parts[7];
assert.deepEqual(Array.from(again.material.lightMap.image.data), Array.from(wall.material.lightMap.image.data));
});
test('an emitting part is baked through the light map slot and still lights the others', () => {
const parts = smallRoom();
parts.push(placed('lamp-shade', [-1.5, 2, 1], [0.2, 0.2, 0.2], { emission: 2 }));
const { parts: baked, report } = bakeLightmaps(parts, lamp, fastOptions);
assert.equal(report.skipped.length, 0);
assert.equal(baked[7].material.emission, 2);
assert.ok(baked[7].material.lightMap);
});
test('a part whose maps read the second UV set is skipped with its material named, keeping its own UVs', () => {
const normalImage = { width: 2, height: 2, data: new Uint8ClampedArray(16).fill(128) };
const parts = smallRoom();
parts.push(placed('floor tiles', [1.5, 1, 1.5], [1, 2, 1], { name: 'Laminate floor', normalMap: { image: normalImage, colorSpace: 'linear', uvChannel: 1 } }));
const { parts: baked, report } = bakeLightmaps(parts, lamp, fastOptions);
assert.deepEqual(report.skipped.map(entry => entry.name), ['floor tiles']);
assert.match(report.skipped[0].reason, /Laminate floor.*normalMap.*TEXCOORD_1/);
assert.equal(baked[7], parts[7]);
});
test('a part with a layer map on the second UV set is skipped with the map named', () => {
const clearcoatImage = { width: 2, height: 2, data: new Uint8ClampedArray(16).fill(128) };
const parts = smallRoom();
parts.push(placed('coated floor', [1.5, 1, 1.5], [1, 2, 1], { name: 'Coated', layerMaps: { clearcoatTexture: { image: clearcoatImage, colorSpace: 'linear', uvChannel: 1 } } }));
const { parts: baked, report } = bakeLightmaps(parts, lamp, fastOptions);
assert.deepEqual(report.skipped.map(entry => entry.name), ['coated floor']);
assert.match(report.skipped[0].reason, /Coated.*clearcoatTexture.*TEXCOORD_1/);
assert.equal(baked[7], parts[7]);
});
test('a part marked as generating its own geometry is skipped', () => {
const parts = smallRoom();
parts[0] = { ...parts[0], generatesGeometry: true };
const { parts: baked, report } = bakeLightmaps(parts, lamp, fastOptions);
assert.deepEqual(report.skipped.map(entry => entry.name), ['floor']);
assert.equal(baked[0], parts[0]);
});
test('options are validated with their bounds', () => {
const fallbacks = Object.fromEntries(Object.entries(BAKE_LIMITS).map(([name, limit]) => [name, limit.fallback]));
assert.deepEqual(normalizeBakeOptions({}), { ...fallbacks, backend: 'cpu' });
for (const [name, bad] of [['samples', 0], ['samples', 513], ['samples', Number.NaN], ['bounces', 9], ['maxResolution', 3], ['maxResolution', 1e9], ['texelsPerUnit', 0], ['texelsPerUnit', Infinity], ['maxSeconds', 0], ['maxSeconds', '60']]) {
assert.throws(() => normalizeBakeOptions({ [name]: bad }), { name: 'RangeError', message: new RegExp(name) }, `${name} ${bad}`);
}
for (const bad of [null, [], 'fast', 3]) assert.throws(() => normalizeBakeOptions(bad), TypeError);
});
test('hostile spot and area lights are refused before any ray is traced', () => {
const spot = { position: [0, 2, 0], direction: [0, -1, 0], intensity: 5 };
const area = { position: [0, 2, 0], direction: [0, -1, 0], width: 1, height: 1, intensity: 5 };
const refused = [
[{ spotLights: [{ ...spot, direction: [0, 0, 0] }] }, /spot light 0.*direction/],
[{ spotLights: [{ ...spot, position: [0, Number.NaN, 0] }] }, /spot light 0/],
[{ spotLights: [{ ...spot, angle: 4 }] }, /spot light 0.*angle/],
[{ spotLights: Array(MAX_BAKE_SPOT_LIGHTS + 1).fill(spot) }, new RegExp(`at most ${MAX_BAKE_SPOT_LIGHTS} spot lights`)],
[{ areaLights: [{ ...area, width: -1 }] }, /area light 0.*width/],
[{ areaLights: [{ ...area, intensity: Infinity }] }, /area light 0/],
[{ areaLights: Array(MAX_BAKE_AREA_LIGHTS + 1).fill(area) }, new RegExp(`at most ${MAX_BAKE_AREA_LIGHTS} area lights`)],
];
for (const [lights, message] of refused) {
assert.throws(() => bakeLightmaps(smallRoom(), { ...lamp, ...lights }, fastOptions), message);
}
});
test('hostile parts and lights are refused before any ray is traced', () => {
const withPosition = value => {
const parts = smallRoom();
const geometry = { ...cube, positions: Float32Array.from(cube.positions) };
geometry.positions[4] = value;
parts[0] = { ...parts[0], geometry };
return parts;
};
assert.throws(() => bakeLightmaps(withPosition(Number.NaN), lamp, fastOptions), /non-finite position/);
assert.throws(() => bakeLightmaps(withPosition(Infinity), lamp, fastOptions), /non-finite position/);
const badIndex = smallRoom();
badIndex[0] = { ...badIndex[0], geometry: { ...cube, indices: Uint32Array.from([0, 1, 9999]) } };
assert.throws(() => bakeLightmaps(badIndex, lamp, fastOptions), /index past its last vertex/);
const badMatrix = smallRoom();
badMatrix[1] = { ...badMatrix[1], matrix: new Float32Array(15) };
assert.throws(() => bakeLightmaps(badMatrix, lamp, fastOptions), /4x4 matrix/);
const nanMatrix = smallRoom();
nanMatrix[1].matrix[0] = Number.NaN;
assert.throws(() => bakeLightmaps(nanMatrix, lamp, fastOptions), /4x4 matrix/);
const noColor = smallRoom();
noColor[1] = { ...noColor[1], material: { tag: 'surface' } };
assert.throws(() => bakeLightmaps(noColor, lamp, fastOptions), /material color/);
assert.throws(() => bakeLightmaps([], lamp, fastOptions), /from 1 to/);
assert.throws(() => bakeLightmaps(null, lamp, fastOptions), /from 1 to/);
const tooManyLights = { pointLights: Array.from({ length: MAX_BAKE_POINT_LIGHTS + 1 }, () => lamp.pointLights[0]) };
assert.throws(() => bakeLightmaps(smallRoom(), tooManyLights, fastOptions), new RegExp(`at most ${MAX_BAKE_POINT_LIGHTS} point lights`));
for (const light of [{ position: [Number.NaN, 0, 0], intensity: 1 }, { position: [0, 0, 0], intensity: -1 }, { position: [0, 0, 0], intensity: Infinity }, { position: [0, 0], intensity: 1 }, { position: [0, 0, 0], intensity: 1, range: -2 }]) {
assert.throws(() => bakeLightmaps(smallRoom(), { pointLights: [light] }, fastOptions), RangeError);
}
assert.throws(() => bakeLightmaps(smallRoom(), { keyColor: [1, 1, Number.NaN], lightDirection: [0, 1, 0] }, fastOptions), /keyColor/);
assert.throws(() => bakeLightmaps(smallRoom(), null, fastOptions), TypeError);
});
test('a bake that would trace too many rays is refused up front', () => {
const heavy = { samples: BAKE_LIMITS.samples.maximum, bounces: BAKE_LIMITS.bounces.maximum, texelsPerUnit: BAKE_LIMITS.texelsPerUnit.maximum, maxResolution: BAKE_LIMITS.maxResolution.maximum };
assert.throws(() => bakeLightmaps(smallRoom(), lamp, heavy), /limit is/);
});
test('a light mapped part exports its second UV set as TEXCOORD_1 and its light map as the emissive texture', () => {
const parts = smallRoom();
const mapImage = { width: 2, height: 2, data: new Uint8ClampedArray(16).fill(180) };
const withMap = placed('wall', [1.5, 1, 1.5], [1, 2, 1], { map: { image: mapImage, colorSpace: 'srgb' } });
parts.push({ ...withMap, geometry: { ...cube, uvs: new Float32Array(cube.positions.length / 3 * 2) } });
const baked = bakeLightmaps(parts, lamp, fastOptions).parts;
const view = new DataView(exportGlb(baked));
const json = JSON.parse(new TextDecoder().decode(new Uint8Array(view.buffer, 20, view.getUint32(12, true))));
const lightMapped = json.meshes.find((mesh, index) => json.nodes.some(node => node.mesh === index && node.name === 'wall'));
assert.ok(lightMapped.primitives[0].attributes.TEXCOORD_1 !== undefined);
assert.ok(lightMapped.primitives[0].attributes.TEXCOORD_0 !== undefined);
const material = json.materials[lightMapped.primitives[0].material];
assert.equal(material.emissiveTexture.texCoord, 1);
assert.ok(material.pbrMetallicRoughness.baseColorTexture);
});
test('a bake that runs out of time throws instead of returning a partial result', () => {
const slow = { samples: 256, bounces: 4, texelsPerUnit: 8, maxResolution: 128, maxSeconds: 1 };
// 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 {
assert.throws(() => bakeLightmaps(smallRoom(), lamp, slow), /maxSeconds/);
} finally {
performance.now = realNow;
}
});
// The mean light a baked part stores, in linear units: the texture is sRGB and is scaled back by the part's emission.
function meanStoredLight(part) {
const bytes = lightmapBytes(part);
let total = 0;
let count = 0;
for (let index = 0; index < bytes.length; index += 4) {
total += (bytes[index] / 255) ** 2.2;
count++;
}
return (total / count) * part.material.emission;
}
test('the default bounces follow most of the light that a closed room keeps, which two bounces cut off', () => {
const { bounces, ...withoutBounces } = fastOptions;
const meanFloorLight = options => meanStoredLight(bakeLightmaps(smallRoom(), lamp, { ...withoutBounces, samples: 48, ...options }).parts[0]);
const byDefault = meanFloorLight({});
const two = meanFloorLight({ bounces: 2 });
const four = meanFloorLight({ bounces: 4 });
assert.ok(two < byDefault && byDefault < four, `2 bounces ${two}, default ${byDefault}, 4 bounces ${four}`);
assert.ok(byDefault > two * 1.05, `default ${byDefault} adds too little over 2 bounces ${two}`);
assert.equal(BAKE_LIMITS.bounces.fallback, 3);
});
test('the backend option is cpu, gpu or webgpu, and the synchronous bake refuses the GPU ones', async () => {
assert.equal(normalizeBakeOptions({ backend: 'gpu' }).backend, 'gpu');
assert.equal(normalizeBakeOptions({ backend: 'webgpu' }).backend, 'webgpu');
assert.throws(() => bakeLightmaps(smallRoom(), lamp, { ...fastOptions, backend: 'webgpu' }), { name: 'TypeError', message: /"webgpu".*light-bake-gpu/ });
for (const bad of ['WebGPU', 'GPU', 1]) assert.throws(() => normalizeBakeOptions({ backend: bad }), { name: 'TypeError', message: /backend/ }, String(bad));
assert.throws(() => bakeLightmaps(smallRoom(), lamp, { ...fastOptions, backend: 'gpu' }), { name: 'TypeError', message: /light-bake-gpu/ });
const asynchronous = await bakeLightmapsAsync(smallRoom(), lamp, fastOptions);
const synchronous = bakeLightmaps(smallRoom(), lamp, fastOptions);
assert.equal(asynchronous.report.backend, 'cpu');
assert.deepEqual(Array.from(lightmapBytes(asynchronous.parts[0])), Array.from(lightmapBytes(synchronous.parts[0])));
});
test('a GPU bake needs a page with WebGL2 and does not take light linking or a sky-only run', async () => {
await assert.rejects(bakeLightmapsAsync(smallRoom(), lamp, { ...fastOptions, backend: 'gpu' }), /WebGL2/);
await assert.rejects(bakeLightmapsAsync(smallRoom(), lamp, { ...fastOptions, backend: 'gpu', skyOnly: true }), /CPU backend only/);
const linked = { pointLights: [{ ...lamp.pointLights[0], affects: ['floor'] }], keyColor: [0, 0, 0] };
await assert.rejects(bakeLightmapsAsync(smallRoom(), linked, { ...fastOptions, backend: 'gpu' }), /light linking/);
});
test('the GPU backend takes up to 1024 parts where the CPU bake takes 256', () => {
const crowd = Array.from({ length: MAX_BAKE_PARTS + 1 }, (_, index) => placed(`part-${index}`, [index, 0, 0], [0.5, 0.5, 0.5]));
assert.throws(() => planLightmaps(crowd, lamp, fastOptions), { name: 'RangeError', message: /1 to 256 parts/ });
assert.equal(planLightmaps(crowd, lamp, { ...fastOptions, backend: 'gpu' }).entries.length, crowd.length);
const tooMany = Array.from({ length: MAX_GPU_BAKE_PARTS + 1 }, (_, index) => placed(`part-${index}`, [index, 0, 0], [0.5, 0.5, 0.5]));
assert.throws(() => planLightmaps(tooMany, lamp, { ...fastOptions, backend: 'gpu' }), { name: 'RangeError', message: /1 to 1024 parts/ });
});
test('a light map that the export skips because the part has an emissive map needs no lightUvs', () => {
const image = { width: 1, height: 1, data: new Uint8ClampedArray([255, 255, 255, 255]) };
const withEmissive = placed('lamp', [0, 0, 0], [1, 1, 1], { lightMap: { image, colorSpace: 'srgb' }, emissiveMap: { image, colorSpace: 'srgb' } });
const part = { ...withEmissive, geometry: { ...cube, uvs: new Float32Array(cube.positions.length / 3 * 2) } };
const view = new DataView(exportGlb([part]));
const json = JSON.parse(new TextDecoder().decode(new Uint8Array(view.buffer, 20, view.getUint32(12, true))));
assert.equal(json.meshes[0].primitives[0].attributes.TEXCOORD_1, undefined);
assert.equal(json.materials[0].emissiveTexture.texCoord, undefined);
});