3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
// Animated grid volumes (#1045): the frame list, its byte budget, the time to frame mapping and the guarantee that a render at one time draws one frame.
import test from 'node:test';
import assert from 'node:assert/strict';
import { encodeVolumeGrid, registerVolumeGrid } from '../src/volume-grid.js';
import { findVolumeGridSequence, volumeGridFrameIndex, volumeGridBytes, VOLUME_GRID_SEQUENCE_MAX_BYTES, VOLUME_GRID_SEQUENCE_MAX_FRAMES } from '../src/volume-grid-sequence.js';
import { resolveLocalVolumes } from '../src/local-volumes.js';
import { bindLocalVolumeParts } from '../src/local-volume-parts.js';
import { renderPathTracedImage } from '../src/path-tracer.js';
const RESOLUTION = [2, 2, 2];
const IMAGE = { width: 16, height: 16, denoise: false, threads: 1, bounces: 1, samples: 1 };
const LOOKING_DOWN = { eye: [0, 3, 0], target: [0, 0, 0], up: [0, 0, -1], fov: 40 };
const CENTER_PIXEL = (8 * 16 + 8) * 3;
function registerUniformFrame(name, density, resolution = RESOLUTION) {
const voxels = resolution[0] * resolution[1] * resolution[2];
registerVolumeGrid(name, encodeVolumeGrid({ resolution, size: [20, 1, 20], channels: { density: new Float32Array(voxels).fill(density) } }));
}
test('time picks the frame: floor(time * fps), wrapped when it loops and held on the last frame when it does not', () => {
assert.equal(volumeGridFrameIndex(4, 2, 0), 0);
assert.equal(volumeGridFrameIndex(4, 2, 0.49), 0);
assert.equal(volumeGridFrameIndex(4, 2, 0.5), 1);
assert.equal(volumeGridFrameIndex(4, 2, 1.5), 3);
assert.equal(volumeGridFrameIndex(4, 2, 2), 0, 'loops back to the first frame');
assert.equal(volumeGridFrameIndex(4, 2, 2, false), 3, 'holds the last frame without a loop');
assert.equal(volumeGridFrameIndex(4, 24, -3), 0, 'before 0 reads the first frame');
assert.equal(volumeGridFrameIndex(4, 24, Number.NaN), 0);
assert.equal(volumeGridFrameIndex(30, 30, 0.1 * 3, true), 9, 'a time that lands on a frame boundary does not fall back one frame to rounding');
});
test('a volume takes grid or frames with fps and loop, and says which it needs', () => {
const [volume] = resolveLocalVolumes([{ shape: 'grid', frames: ['a', 'b'], center: [0, 1, 0], fps: 12 }]);
assert.deepEqual(volume.frames, ['a', 'b']);
assert.equal(volume.fps, 12);
assert.equal(volume.loop, true);
assert.equal(volume.grid, undefined);
assert.equal(resolveLocalVolumes([{ shape: 'grid', frames: ['a'], center: [0, 0, 0] }])[0].fps, 24);
assert.throws(() => resolveLocalVolumes([{ shape: 'grid', grid: 'a', frames: ['a'], center: [0, 0, 0] }]), /either grid.*or frames/);
assert.throws(() => resolveLocalVolumes([{ shape: 'grid', grid: 'a', fps: 12, center: [0, 0, 0] }]), /fps belongs to a grid volume with frames/);
assert.throws(() => resolveLocalVolumes([{ shape: 'grid', frames: [], center: [0, 0, 0] }]), /frames must be a list of 1 to 512 grid names/);
assert.throws(() => resolveLocalVolumes([{ shape: 'grid', frames: ['a', 3], center: [0, 0, 0] }]), /frames\[1\] must be the name of a grid file/);
assert.throws(() => resolveLocalVolumes([{ shape: 'grid', frames: ['a'], fps: 0, center: [0, 0, 0] }]), /fps must be between/);
assert.throws(() => resolveLocalVolumes([{ shape: 'grid', frames: ['a'], loop: 'yes', center: [0, 0, 0] }]), /loop must be true or false/);
assert.throws(() => resolveLocalVolumes([{ shape: 'box', frames: ['a'], center: [0, 0, 0], size: [1, 1, 1] }]), /frames belongs to shape "grid"/);
assert.equal(VOLUME_GRID_SEQUENCE_MAX_FRAMES, 512);
});
test('a sequence needs one resolution and one size, and names the frame that differs', () => {
registerUniformFrame('same-0', 0);
registerUniformFrame('same-1', 1);
registerUniformFrame('other-res', 1, [3, 2, 2]);
assert.equal(findVolumeGridSequence(['same-0', 'same-1'], 'volume').length, 2);
assert.throws(() => findVolumeGridSequence(['same-0', 'other-res'], 'volume'), /frames\[1\] \("other-res"\) is 3x2x2 but frame 0 is 2x2x2/);
assert.throws(() => findVolumeGridSequence(['same-0', 'never-loaded'], 'volume'), /frames\[1\]\.grid "never-loaded" is not loaded/);
});
test('a sequence over the byte budget is refused with its size and the limit, before it is all loaded', () => {
const resolution = [256, 256, 256];
const frame = { resolution, channels: { density: new Uint16Array(1) } };
assert.equal(volumeGridBytes(frame), 256 ** 3 * 2, 'one channel at 256 cubed is 32 MiB');
assert.equal(VOLUME_GRID_SEQUENCE_MAX_BYTES, 256 * 1024 * 1024);
// The decoded grid is shared by reference: nine of 32 MiB cross 256 MiB at the ninth.
const shared = { resolution, size: null, channels: { density: new Uint16Array(256 ** 3) } };
registerVolumeGrid('big', shared);
const names = Array.from({ length: 9 }, () => 'big');
assert.throws(() => findVolumeGridSequence(names, 'environment.localVolumes[0]'), /environment\.localVolumes\[0\]\.frames hold 301989888 bytes by frame 9 of 9, over the 268435456 byte limit/);
assert.equal(findVolumeGridSequence(names.slice(0, 8), 'volume').length, 8, 'eight frames are exactly at the limit');
});
test('binding picks the frame for the time, and the same time binds the same grid every time', () => {
for (let index = 0; index < 4; index++) registerUniformFrame(`bind-${index}`, index);
const resolved = resolveLocalVolumes([{ shape: 'grid', frames: ['bind-0', 'bind-1', 'bind-2', 'bind-3'], center: [0, 0, 0], fps: 2 }]);
const boundAt = time => bindLocalVolumeParts(resolved, [], { time })[0].gridData;
assert.equal(boundAt(0), boundAt(0.4));
assert.notEqual(boundAt(0), boundAt(0.5));
assert.equal(boundAt(1.5), boundAt(1.5));
assert.equal(boundAt(2), boundAt(0), 'the loop returns to frame 0');
assert.equal(bindLocalVolumeParts(resolved, [])[0].gridData, boundAt(0), 'without a time the first frame binds');
});
function ground() {
const half = 20;
const geometry = {
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]),
};
return [{ name: 'ground', geometry, material: { tag: 'surface', metallic: 0, roughness: 1, color: [0, 0, 0], ior: 1, emission: 1, emissiveColor: [1, 1, 1] } }];
}
async function tracedAt(volumeTime) {
const localVolumes = [{ shape: 'grid', frames: ['trace-0', 'trace-1', 'trace-2'], fps: 2, loop: false, center: [0, 1.5, 0], size: [20, 1, 20], steps: 128 }];
const { linear } = await renderPathTracedImage({ parts: ground(), environment: { localVolumes, volumeTime }, camera: LOOKING_DOWN }, IMAGE);
return Array.from(linear);
}
test('the CPU path tracer draws the frame its time selects, the same pixels every time, and holds the last frame', async () => {
const deep = [4, 128, 4]; // 128 voxels deep, so the half voxel ramp at the faces (#1752) stays under the tolerance
registerUniformFrame('trace-0', 0, deep);
registerUniformFrame('trace-1', 1, deep);
registerUniformFrame('trace-2', 2, deep);
const first = await tracedAt(0);
const second = await tracedAt(0.5);
const third = await tracedAt(1);
assert.ok(Math.abs(first[CENTER_PIXEL] - 1) < 2e-3, `frame 0 is clear: ${first[CENTER_PIXEL]}`);
assert.ok(Math.abs(second[CENTER_PIXEL] - Math.exp(-1)) < 2e-3, `frame 1 transmits e^-1: ${second[CENTER_PIXEL]}`);
assert.ok(Math.abs(third[CENTER_PIXEL] - Math.exp(-2)) < 2e-3, `frame 2 transmits e^-2: ${third[CENTER_PIXEL]}`);
assert.deepEqual(await tracedAt(0.5), second, 'one time, one image');
assert.deepEqual(await tracedAt(9), third, 'past the end the last frame stays');
});