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 { existsSync, statSync } from 'node:fs';
import { readFile } from 'node:fs/promises';
import { constants, setPriority } from 'node:os';
import * as RealThree from 'three';
import * as core from '../src/index.js';
import { loadGltf } from '../src/gltf.js';
import { createThreeCompat, unsupportedNames } from '../packages/three-compat/index.mjs';
import { snippets } from './fixtures/three-compat/snippets.mjs';
const THREE = createThreeCompat({ ...core, loadGltf });
const fakeCanvas = { style: {}, addEventListener() {} };
const fakeServices = { canvas: fakeCanvas, checkerboard: () => ({ width: 64, height: 64 }) };
function litScene(light) {
const scene = new THREE.Scene();
scene.add(light);
const camera = new THREE.PerspectiveCamera(60, 1, 0.5, 50);
camera.position.set(0, 1, 5);
return { scene, camera };
}
test('the addon does not import three or the core by name', async () => {
const { readFile } = await import('node:fs/promises');
const source = await readFile(new URL('../packages/three-compat/index.mjs', import.meta.url), 'utf8');
assert.doesNotMatch(source, /^\s*import\s/m, 'the addon has no import statement');
assert.throws(() => createThreeCompat({}), /needs the Crucible export CrucibleRenderer/);
});
test('every snippet that needs no browser builds parts, an environment and a frame', async () => {
const runnable = snippets.filter(snippet => !snippet.browserOnly);
assert.ok(runnable.length >= 10);
for (const snippet of runnable) {
const { scene, camera } = await snippet.build(THREE, fakeServices);
const { parts, environment, frame } = THREE.collectScene(scene, camera);
assert.ok(parts.length >= 2, `${snippet.name} has parts`);
assert.equal(new Set(parts.map(part => part.name)).size, parts.length, `${snippet.name} has unique part names`);
for (const part of parts) {
assert.equal(part.matrix.length, 16, `${snippet.name} ${part.name} has a 4 x 4 matrix`);
assert.ok(part.matrix.every(Number.isFinite), `${snippet.name} ${part.name} matrix is finite`);
assert.ok(part.geometry.positions.length > 0, `${snippet.name} ${part.name} has a geometry`);
assert.ok(part.material.color.every(Number.isFinite));
}
assert.equal(frame.eye.length, 3);
assert.equal(frame.target.length, 3);
assert.ok(environment);
}
});
test('a mesh matrix places and scales the unit geometry, in the order of three.js', () => {
const scene = new THREE.Scene();
const group = new THREE.Group();
group.position.set(10, 0, 0);
const mesh = new THREE.Mesh(new THREE.BoxGeometry(2, 4, 6), new THREE.MeshStandardMaterial());
mesh.position.set(1, 2, 3);
group.add(mesh);
scene.add(group);
const { parts } = THREE.collectScene(scene, new THREE.PerspectiveCamera());
const matrix = parts[0].matrix;
assert.deepEqual([...matrix.slice(12, 15)], [11, 2, 3]);
assert.deepEqual([matrix[0], matrix[5], matrix[10]], [2, 4, 6]);
});
test('Euler rotation XYZ turns a mesh like three.js does', () => {
const scene = new THREE.Scene();
const mesh = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshStandardMaterial());
mesh.rotation.z = Math.PI / 2;
scene.add(mesh);
const { parts } = THREE.collectScene(scene, new THREE.PerspectiveCamera());
// A quarter turn about Z sends the X axis to Y.
assert.ok(Math.abs(parts[0].matrix[1] - 1) < 1e-6);
assert.ok(Math.abs(parts[0].matrix[4] + 1) < 1e-6);
});
test('MeshStandardMaterial and MeshPhysicalMaterial become Crucible materials in linear colour', () => {
const standard = new THREE.MeshStandardMaterial({ color: 0xff8000, metalness: 0.7, roughness: 0.2, emissive: 0x00ff00, emissiveIntensity: 2, side: THREE.DoubleSide }).toMaterial();
assert.ok(Math.abs(standard.color[0] - 1) < 1e-6);
assert.ok(Math.abs(standard.color[1] - 0.2158605) < 1e-5, 'sRGB 0x80 is linear 0.2159');
assert.equal(standard.metallic, 0.7);
assert.equal(standard.roughness, 0.2);
assert.equal(standard.emission, 2);
assert.deepEqual(standard.emissiveColor, [0, 1, 0]);
assert.equal(standard.doubleSided, true);
const physical = new THREE.MeshPhysicalMaterial({ clearcoat: 1, transmission: 0.5, ior: 1.4, specularIntensity: 0.8 }).toMaterial();
assert.deepEqual([physical.clearcoat, physical.transmission, physical.ior, physical.specular], [1, 0.5, 1.4, 0.8]);
const blended = new THREE.MeshStandardMaterial({ transparent: true, opacity: 0.3 }).toMaterial();
assert.deepEqual([blended.alphaMode, blended.opacity], ['blend', 0.3]);
const cutout = new THREE.MeshStandardMaterial({ alphaTest: 0.4 }).toMaterial();
assert.deepEqual([cutout.alphaMode, cutout.alphaCutoff], ['mask', 0.4]);
});
test('lights fill the environment of the frame', () => {
const directional = new THREE.DirectionalLight(0xffffff, 3);
directional.position.set(2, 4, 6);
const { scene, camera } = litScene(directional);
scene.add(new THREE.AmbientLight(0xffffff, 0.5));
const lit = THREE.collectScene(scene, camera).environment;
assert.deepEqual(lit.lightDirection, [2, 4, 6]);
assert.equal(lit.keyIntensity, 3);
assert.equal(lit.ambientIntensity, 0.5);
assert.equal(lit.fillIntensity, 0, 'a scene with its own lights switches the studio fill off');
const point = new THREE.PointLight(0xffffff, 12, 9);
point.position.set(1, 2, 3);
const pointEnvironment = THREE.collectScene(litScene(point).scene, camera).environment;
assert.deepEqual(pointEnvironment.pointLights, [{ position: [1, 2, 3], color: [1, 1, 1], intensity: 12, range: 9 }]);
assert.equal(pointEnvironment.keyIntensity, 0);
const spot = new THREE.SpotLight(0xffffff, 50, 0, 0.5, 0.3);
spot.position.set(0, 5, 0);
const spotLight = THREE.collectScene(litScene(spot).scene, camera).environment.spotLights[0];
assert.deepEqual(spotLight.direction, [0, -5, 0]);
assert.deepEqual([spotLight.angle, spotLight.penumbra, spotLight.range], [0.5, 0.3, undefined]);
const panel = new THREE.RectAreaLight(0xffffff, 5, 3, 2);
panel.position.set(0, 3, 0);
panel.lookAt(0, 0, 0);
const area = THREE.collectScene(litScene(panel).scene, camera).environment.areaLights[0];
assert.deepEqual([area.width, area.height, ...area.direction], [3, 2, 0, -3, 0]);
const dark = THREE.collectScene(new THREE.Scene(), camera).environment;
assert.equal(dark.keyIntensity, undefined, 'a scene with no light keeps the studio rig');
});
test('cameras become frames', () => {
const perspective = new THREE.PerspectiveCamera(35, 2, 0.2, 80);
perspective.position.set(1, 2, 3);
perspective.lookAt(0, 0, 0);
const frame = THREE.collectScene(new THREE.Scene(), perspective).frame;
assert.deepEqual([frame.eye, frame.target, frame.fov, frame.near, frame.far], [[1, 2, 3], [0, 0, 0], 35, 0.2, 80]);
const orthographic = new THREE.OrthographicCamera(-4, 4, 3, -3, 0.1, 50);
orthographic.position.set(0, 0, 5);
const orthographicFrame = THREE.collectScene(new THREE.Scene(), orthographic).frame;
assert.equal(orthographicFrame.projection, 'orthographic');
assert.equal(orthographicFrame.orthographicHeight, 6);
assert.deepEqual(orthographicFrame.target, [0, 0, 4], 'a camera without lookAt looks down its -Z axis');
});
test('OrbitControls moves the camera around its target', () => {
const camera = new THREE.PerspectiveCamera();
camera.position.set(0, 0, 4);
const controls = new THREE.OrbitControls(camera, fakeCanvas);
controls.target.set(0, 0, 0);
controls.rotate(Math.PI / 2, 0);
assert.ok(Math.abs(camera.position.x - 4) < 1e-6);
assert.ok(Math.abs(camera.position.z) < 1e-6);
});
test('MeshLambertMaterial and MeshPhongMaterial build matte Crucible materials', () => {
const lambert = new THREE.MeshLambertMaterial({ color: 0xff0000, metalness: 1, roughness: 0 }).toMaterial();
assert.equal(lambert.metallic, 0);
assert.equal(lambert.roughness, 1);
assert.deepEqual(lambert.color, new THREE.Color(0xff0000).toArray());
const defaultPhong = new THREE.MeshPhongMaterial({ color: 0x00ff00 }).toMaterial();
assert.equal(defaultPhong.metallic, 0);
assert.ok(Math.abs(defaultPhong.roughness - 0.5) < 1e-9);
const shiny = new THREE.MeshPhongMaterial({ shininess: 198, specular: 0xffffff }).toMaterial();
assert.ok(Math.abs(shiny.roughness - 0.01 ** 0.25) < 1e-9);
const mesh = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshPhongMaterial());
assert.ok(mesh.material instanceof THREE.MeshStandardMaterial);
assert.ok(!unsupportedNames.includes('MeshLambertMaterial') && !unsupportedNames.includes('MeshPhongMaterial'));
});
test('unsupported three.js names throw an error that names the Crucible replacement', () => {
const cases = [
['MeshBasicMaterial', /MeshStandardMaterial.*emission/],
['ShaderMaterial', /no custom shaders/],
['ConeGeometry', /createModel/],
['WebGLRenderTarget', /toBlob/],
['Fog', /fogDensity/],
['EffectComposer', /resolveEffects/],
['AnimationMixer', /createAnimationMixer/],
['TextureLoader', /material\.map/],
['SomethingElse', /not part of the common subset/],
];
for (const [name, replacement] of cases) {
assert.throws(() => THREE[name], error => error.message.includes(`THREE.${name}`) && replacement.test(error.message) && error.message.includes('if-you-know-three-js.md'), name);
}
assert.throws(() => new THREE.MeshStandardMaterial({ aoMap: {} }), /occlusionMap/);
assert.throws(() => new THREE.CylinderGeometry(0, 1, 2), /createModel/);
assert.throws(() => new THREE.MeshStandardMaterial({ side: THREE.BackSide }).toMaterial(), /doubleSided/);
assert.throws(() => new THREE.Color('red'), /hex/);
assert.throws(() => new THREE.Mesh({}, new THREE.MeshStandardMaterial()), /box\(\)/);
assert.equal(THREE.then, undefined, 'lowercase names are plain properties');
});
test('every Crucible call named by an error exists', () => {
const known = new Set([...Object.keys(core), ...Object.getOwnPropertyNames(core.CrucibleRenderer.prototype), 'loadGltf', 'createModel', 'box', 'sphere', 'cylinder', 'torus', 'canvas.toBlob', 'Texture']);
assert.ok(unsupportedNames.length >= 20);
for (const name of unsupportedNames) {
let message = '';
try {
THREE[name];
} catch (error) {
message = error.message;
}
assert.ok(message, `${name} throws`);
for (const [, call] of message.matchAll(/([A-Za-z_.]+)\(/g)) {
assert.ok(known.has(call) || known.has(call.split('.').at(-1)), `${name}: the error names ${call}, which is not a Crucible export`);
}
}
});
// Draws every snippet in Chrome so each gets a real frame. It runs only when asked, because it needs a browser and a GPU:
// RENDER_TESTS=1 node --test tests/three-compat.test.js
// CHROME_PATH names the browser. THREE_COMPAT_ANGLE picks the graphics backend (default d3d11 on Windows, vulkan elsewhere).
const chromePath = process.env.CHROME_PATH ?? 'C:/Program Files/Google/Chrome/Application/chrome.exe';
const renderEnabled = process.env.RENDER_TESTS === '1' && existsSync(chromePath);
const snippetTimeoutMilliseconds = 20000;
// A snippet that never reports a frame fails by name instead of holding the whole test until its own timeout.
async function drawWithin(page, name, milliseconds) {
let timer;
const timeout = new Promise((resolve, reject) => {
timer = setTimeout(() => reject(new Error(`snippet "${name}" reported no frame within ${milliseconds} ms`)), milliseconds);
});
try {
return await Promise.race([page.evaluate(snippetName => window.drawSnippet(snippetName), name), timeout]);
} finally {
clearTimeout(timer);
}
}
test('each three.js-style snippet draws a frame through the addon', { skip: !renderEnabled, timeout: 300000 }, async () => {
setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);
const { chromium } = await import('playwright');
const { createServer } = await import('vite');
const angle = process.env.THREE_COMPAT_ANGLE ?? (process.platform === 'win32' ? 'd3d11' : 'vulkan');
const flags = ['--enable-webgl', '--ignore-gpu-blocklist', `--use-angle=${angle}`, '--enable-gpu', '--no-sandbox'];
if (angle === 'vulkan') flags.push('--enable-features=Vulkan');
const server = await createServer({ root: new URL('..', import.meta.url).pathname.replace(/^\/(\w:)/, '$1'), server: { host: '127.0.0.1', port: 0, fs: { strict: false } }, logLevel: 'silent' });
await server.listen();
const browser = await chromium.launch({ executablePath: chromePath, headless: true, args: flags });
try {
const page = await browser.newPage({ viewport: { width: 256, height: 256 } });
const failures = [];
page.on('pageerror', error => failures.push(error.message));
await page.goto(`http://127.0.0.1:${server.httpServer.address().port}/tests/fixtures/three-compat/page.html`, { timeout: 60000 });
await page.waitForFunction(() => window.drawSnippet, null, { timeout: 60000 });
const hashes = new Set();
for (const snippet of snippets) {
const result = await drawWithin(page, snippet.name, snippetTimeoutMilliseconds);
assert.ok(result.frames >= 1, `${snippet.name} drew a frame`);
assert.ok(result.distinctColors >= 12, `${snippet.name} is not a blank frame (${result.distinctColors} colours)`);
assert.ok(!hashes.has(result.hash), `${snippet.name} differs from every other snippet`);
hashes.add(result.hash);
}
assert.deepEqual(failures, []);
assert.ok(hashes.size >= 10);
} finally {
await browser.close();
await server.close();
}
});
test('OrbitControls.dispose removes every listener it added', () => {
const added = new Map();
const canvas = {
style: {},
addEventListener(type, listener) { added.set(type, listener); },
removeEventListener(type, listener) { if (added.get(type) === listener) added.delete(type); },
};
const controls = new THREE.OrbitControls(new THREE.PerspectiveCamera(), canvas);
assert.deepEqual([...added.keys()].sort(), ['pointerdown', 'pointermove', 'wheel']);
controls.dispose();
assert.equal(added.size, 0, 'listeners still attached after dispose');
});
test('several DirectionalLights add up like in three.js instead of the last one winning', () => {
const first = new THREE.DirectionalLight(0xffffff, 1);
first.position.set(0, 5, 0);
const second = new THREE.DirectionalLight(0xffffff, 2);
second.position.set(4, 0, 0);
const { scene, camera } = litScene(first);
scene.add(second);
const { environment } = THREE.collectScene(scene, camera);
assert.equal(environment.keyIntensity, 3, 'the intensities are summed');
const length = Math.hypot(...environment.lightDirection);
assert.ok(Math.abs(length - 1) < 1e-9, 'a blended direction is a unit vector');
// The stronger light pulls the direction: (1 * up + 2 * right) normalised.
const expected = [2, 1, 0].map(value => value / Math.sqrt(5));
environment.lightDirection.forEach((value, axis) => assert.ok(Math.abs(value - expected[axis]) < 1e-9));
assert.equal(environment.keyColor, undefined, 'white lights leave the key colour alone');
});
test('blended DirectionalLights mix their colours by intensity and survive opposite directions', () => {
const red = new THREE.DirectionalLight(0xff0000, 1);
red.position.set(0, 3, 0);
const blue = new THREE.DirectionalLight(0x0000ff, 3);
blue.position.set(0, -3, 0);
const { scene, camera } = litScene(red);
scene.add(blue);
const { environment } = THREE.collectScene(scene, camera);
assert.equal(environment.keyIntensity, 4);
assert.deepEqual(environment.lightDirection.map(Math.sign), [0, -1, 0], 'the stronger light wins when directions oppose');
const [redShare, , blueShare] = environment.keyColor;
assert.ok(Math.abs(redShare - 0.25) < 1e-9 && Math.abs(blueShare - 0.75) < 1e-9);
const cancelled = new THREE.DirectionalLight(0xffffff, 1);
cancelled.position.set(0, 3, 0);
const opposite = new THREE.DirectionalLight(0xffffff, 1);
opposite.position.set(0, -3, 0);
const equalScene = litScene(cancelled);
equalScene.scene.add(opposite);
const equal = THREE.collectScene(equalScene.scene, equalScene.camera).environment;
assert.ok(equal.lightDirection.every(Number.isFinite), 'equal and opposite lights give a finite direction');
});
test('rotation.order set after construction changes the matrix like three.js', () => {
const angles = [0.4, -0.7, 1.1];
for (const order of ['XYZ', 'YXZ', 'ZXY', 'ZYX', 'YZX', 'XZY']) {
const mesh = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshStandardMaterial());
mesh.rotation.set(...angles);
mesh.rotation.order = order;
const expected = new RealThree.Matrix4().makeRotationFromEuler(new RealThree.Euler(...angles, order)).elements;
const actual = mesh.localMatrix();
for (let index = 0; index < 16; index += 1) {
assert.ok(Math.abs(actual[index] - expected[index]) < 1e-6, `${order} element ${index}`);
}
}
const mesh = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshStandardMaterial());
mesh.rotation.order = 'ABC';
assert.throws(() => mesh.localMatrix(), /Euler order "ABC".*XYZ/);
assert.doesNotThrow(() => new THREE.Euler(0, 0, 0, 'ZYX'));
});
test('a torus with radius 0 throws an error that names the radius', () => {
assert.throws(() => new THREE.TorusGeometry(0, 0.4), /TorusGeometry radius is 0.*positive/);
assert.throws(() => new THREE.TorusGeometry(Number.NaN, 0.4), /TorusGeometry radius is NaN/);
assert.doesNotThrow(() => new THREE.TorusGeometry(2, 0.4));
});
test('the addon stays outside the core bundles and under its size ceiling', async () => {
const addonBytes = statSync(new URL('../packages/three-compat/index.mjs', import.meta.url)).size;
assert.ok(addonBytes < 40000, `the addon is ${addonBytes} bytes; record the growth in changes/986.size.md and raise this ceiling`);
assert.ok(snippets.length >= 10, `only ${snippets.length} three.js-style snippets; the issue asks for at least 10`);
const coreSource = await readFile(new URL('../src/index.js', import.meta.url), 'utf8');
assert.ok(!coreSource.includes('three-compat'), 'the core must not import the addon');
});