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 { cookModule, cookTest } from './support/cook.js';
import {
encodedExportLength,
exportNativeSceneTables,
NATIVE_EXPORT_MAXIMUM_CHARACTERS,
NATIVE_JOB_MAXIMUM_INSTANCES,
NATIVE_JOB_MAXIMUM_TRIANGLES,
requireTableSizesFit,
V8_MAXIMUM_STRING_LENGTH,
} from '../scripts/native-bake-page.js';
import { createCamera } from '../src/path-tracer.js';
import * as pack from '../src/path-tracer-gpu-pack.js';
import {
buildTraceScene,
MAX_NATIVE_TRACE_INSTANCES,
MAX_TRACE_INSTANCES,
refuseLocalVolumes,
resolveTexture,
} from '../src/path-tracer-scene.js';
const jobInputModule = await cookModule('job-input');
const packInputModule = await cookModule('pack-input');
const { buildFlattenedJobNativeInput, buildJobNativeInput } = jobInputModule ?? {};
const { buildNativeInput } = packInputModule ?? {};
// One shared triangle: valid for the builder and cheap to copy many times.
const TRIANGLE = {
positions: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]),
normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]),
indices: new Uint32Array([0, 1, 2]),
};
const SHARED_MATERIAL = { color: [0.8, 0.8, 0.8] };
const ENVIRONMENT = { keyColor: [1, 1, 1], lightDirection: [0, 1, 0] };
function copiesOfTriangle(copyCount) {
return Array.from({ length: copyCount }, (_, index) => ({
name: `copy-${index}`,
geometry: TRIANGLE,
matrix: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, index * 2, 0, 0, 1]),
material: SHARED_MATERIAL,
}));
}
test('the CPU and WebGL instance bound is still 65,536 and a build without the option keeps its message', () => {
assert.equal(MAX_TRACE_INSTANCES, 65_536);
assert.throws(() => buildTraceScene(copiesOfTriangle(MAX_TRACE_INSTANCES + 1), ENVIRONMENT, { instancing: true }), {
name: 'RangeError',
message: 'An instanced path trace takes at most 65536 instances, got 65537. Pass fewer parts, or merge small copies into one mesh.',
});
});
test('an instanced scene above 65,536 copies builds with maximumInstances and keeps every instance', () => {
const copyCount = MAX_TRACE_INSTANCES + 1_000;
const scene = buildTraceScene(copiesOfTriangle(copyCount), ENVIRONMENT, { instancing: true, maximumInstances: copyCount });
assert.equal(scene.instances.length, copyCount);
assert.equal(new Set(scene.instances.map(instance => instance.geometry)).size, 1);
assert.equal(scene.materials.length, copyCount);
});
test('a scene over the instance bound that was asked for is refused with the bound and what to pass', () => {
assert.equal(buildTraceScene(copiesOfTriangle(10), ENVIRONMENT, { instancing: true, maximumInstances: 10 }).instances.length, 10);
assert.throws(() => buildTraceScene(copiesOfTriangle(11), ENVIRONMENT, { instancing: true, maximumInstances: 10 }),
{ name: 'RangeError', message: 'An instanced native path trace takes at most 10 instances, got 11. Pass fewer parts, or merge small copies into one mesh.' });
});
test('maximumInstances can lower the bound under 65,536 and leaves the triangle bound alone', () => {
assert.throws(() => buildTraceScene(copiesOfTriangle(3), ENVIRONMENT, { instancing: true, maximumInstances: 2 }), /at most 2 instances, got 3/);
assert.throws(() => buildTraceScene(copiesOfTriangle(5), ENVIRONMENT, { instancing: true, maximumInstances: 10, maximumTriangles: 1 }), /at most 4 triangles with every copy counted, got 5/);
});
test('the instance ceiling is MAX_NATIVE_TRACE_INSTANCES and a value outside 1 to the ceiling is refused with the range', () => {
assert.equal(MAX_NATIVE_TRACE_INSTANCES, 1_000_000);
const parts = copiesOfTriangle(2);
for (const value of [0, -5, 1.5, Number.NaN, Infinity, '1000', null, MAX_NATIVE_TRACE_INSTANCES + 1]) {
assert.throws(() => buildTraceScene(parts, ENVIRONMENT, { instancing: true, maximumInstances: value }),
{ name: 'RangeError', message: /maximumInstances is an integer from 1 to 1000000 for the native path tracer.*65536 instances/ }, `value ${String(value)}`);
}
});
test('a flattened scene ignores maximumInstances and keeps its part bound', () => {
const parts = Array.from({ length: 3 }, (_, index) => ({ name: `own-${index}`, geometry: { ...TRIANGLE, positions: Float32Array.from(TRIANGLE.positions) }, material: SHARED_MATERIAL }));
assert.equal(buildTraceScene(parts, ENVIRONMENT, { maximumInstances: 1 }).indices.length, 9);
});
const camera = createCamera({ eye: [0, 0, 8], target: [0, 0, 0], fov: 50 }, 8, 8);
const packOptions = { width: 8, height: 8, bounces: 2, seed: 1, fireflyClamp: 20, noiseThreshold: 0 };
const modules = { buildTraceScene, refuseLocalVolumes, resolveTexture, buildNativeInput, buildJobNativeInput, buildFlattenedJobNativeInput, pack };
cookTest('a native render job with the cycles kernel exports more than 65,536 instances of one geometry', () => {
assert.ok(NATIVE_JOB_MAXIMUM_INSTANCES > MAX_TRACE_INSTANCES && NATIVE_JOB_MAXIMUM_INSTANCES <= MAX_NATIVE_TRACE_INSTANCES);
const copyCount = MAX_TRACE_INSTANCES + 100;
const exported = exportNativeSceneTables({ parts: copiesOfTriangle(copyCount), environment: ENVIRONMENT, camera, options: packOptions, kernel: 'cycles', instancing: true, modules });
assert.equal(exported.instances, copyCount);
assert.equal(exported.instancing, undefined);
assert.equal(exported.triangleCount, 1);
});
cookTest('a native render job past its instance bound says so and does not hide the refusal', () => {
const smallBound = (sceneParts, environment, options) => buildTraceScene(sceneParts, environment, { ...options, maximumInstances: 5 });
assert.throws(() => exportNativeSceneTables({ parts: copiesOfTriangle(6), environment: ENVIRONMENT, camera, options: packOptions, kernel: 'cycles', instancing: true,
modules: { ...modules, buildTraceScene: smallBound } }), { name: 'RangeError', message: /at most 5 instances, got 6\. Pass fewer parts, or merge small copies into one mesh\./ });
});
cookTest('a native render job with the legacy kernel keeps its flattened bounds, not the instance bound', () => {
assert.throws(() => exportNativeSceneTables({ parts: copiesOfTriangle(MAX_TRACE_INSTANCES + 1), environment: ENVIRONMENT, camera, options: packOptions, kernel: 'legacy', instancing: true, modules }),
{ name: 'RangeError', message: /1 to 1024 parts/ });
});
const TRIANGLE_RECORD_BYTES = 224;
const INSTANCE_AND_MATERIAL_BYTES = 160 + 256;
test('the base64 length of tables is 4 * ceil(bytes / 3) each, as Buffer measures it', () => {
for (const bytes of [0, 1, 2, 3, 4, 5, 299, 1000]) {
assert.equal(encodedExportLength([bytes]), Buffer.alloc(bytes).toString('base64').length, `${bytes} bytes`);
}
assert.equal(encodedExportLength([1, 2, 3]), 4 + 4 + 4);
assert.equal(encodedExportLength([]), 0);
});
test('the export share is under the V8 string limit', () => {
assert.equal(V8_MAXIMUM_STRING_LENGTH, 536_870_888);
assert.ok(NATIVE_EXPORT_MAXIMUM_CHARACTERS < V8_MAXIMUM_STRING_LENGTH);
assert.ok(NATIVE_EXPORT_MAXIMUM_CHARACTERS > 0.9 * V8_MAXIMUM_STRING_LENGTH);
});
test('the job triangle bound with the 65,536 instances of before still fits one message', () => {
const tables = [['triangles', NATIVE_JOB_MAXIMUM_TRIANGLES * TRIANGLE_RECORD_BYTES], ['instances and materials', 65_536 * INSTANCE_AND_MATERIAL_BYTES]];
requireTableSizesFit(tables);
});
test('both job bounds at once are refused before encoding, with the totals and what to pass', () => {
const tables = [['triangles', NATIVE_JOB_MAXIMUM_TRIANGLES * TRIANGLE_RECORD_BYTES], ['materials', 150_000 * 256], ['instances', 150_000 * 160]];
assert.throws(() => requireTableSizesFit(tables), error => {
assert.equal(error.name, 'RangeError');
assert.equal(error.exportTooLarge, true);
assert.match(error.message, new RegExp(`${encodedExportLength(tables.map(([, bytes]) => bytes))} base64 characters in total`));
assert.match(error.message, /largest tables: triangles 448000000, materials 51200000/);
assert.match(error.message, /Pass fewer parts.*fewer unique triangles/);
return true;
});
});
cookTest('an export over one message is rethrown, not flattened or packed another way', () => {
const huge = new Uint8Array(1);
Object.defineProperty(huge, 'byteLength', { value: 400_000_000 });
let flattenedCalls = 0;
const countingFlatten = () => {
flattenedCalls++;
throw new Error('the flattened packer must not run');
};
const oversized = () => ({ triangles: huge, triangleCount: 1, instanceCount: 2 });
assert.throws(() => exportNativeSceneTables({ parts: copiesOfTriangle(2), environment: ENVIRONMENT, camera, options: packOptions, kernel: 'cycles', instancing: true,
modules: { ...modules, buildJobNativeInput: oversized, buildFlattenedJobNativeInput: countingFlatten } }),
error => error.exportTooLarge === true && /base64 characters in total/.test(error.message));
assert.equal(flattenedCalls, 0);
});