3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
// A local volume casts the key light's shadow on opaque surfaces (#1047): castShadow, off by default so the default frame does not change, dims the sun's direct light at a surface by the optical depth the volume
// puts between it and the sun. The CPU path tracer does it exactly; the rasterizer's post pass scales the finished colour by a share (the raster test checks that).
import test from 'node:test';
import assert from 'node:assert/strict';
import { resolveLocalVolumes, createLocalVolumeBuffers, packLocalVolumes } from '../src/local-volumes.js';
import { bindLocalVolumeParts } from '../src/local-volume-parts.js';
import { encodeVolumeGrid, registerVolumeGrid } from '../src/volume-grid.js';
import { createLocalVolumeSurfaceShadow } from '../src/path-tracer-volume.js';
import { renderPathTracedImage } from '../src/path-tracer.js';
const SMOKE = { castShadow: true, shape: 'box', center: [0, 2, 0], size: [4, 2, 4], density: 0.6, falloff: 0.3, absorption: [0.7, 0.8, 1], noiseAmount: 0.6, noiseScale: 2, steps: 16 };
const SUN_TOWARD = [0.6, 1, 0].map(component => component / Math.hypot(0.6, 1, 0));
test('castShadow defaults to false and takes only true or false', () => {
const { castShadow: _castShadow, ...withoutFlag } = SMOKE;
assert.equal(resolveLocalVolumes([withoutFlag])[0].castShadow, false);
assert.equal(resolveLocalVolumes([SMOKE])[0].castShadow, true);
assert.equal(resolveLocalVolumes([{ ...SMOKE, castShadow: false }])[0].castShadow, false);
for (const bad of ['no', 0, null]) {
assert.throws(() => resolveLocalVolumes([{ ...SMOKE, castShadow: bad }], 'environment.localVolumes'), /environment\.localVolumes\[0\]\.castShadow must be true or false/);
}
});
test('the packed grid vector carries the flag in its third component for a box', () => {
const buffers = createLocalVolumeBuffers();
const { castShadow: _castShadow, ...withoutFlag } = SMOKE;
packLocalVolumes(resolveLocalVolumes([SMOKE, { ...SMOKE, castShadow: false }, withoutFlag]), buffers);
assert.deepEqual([buffers.grid[2], buffers.grid[6], buffers.grid[10]], [1, 0, 0]);
});
test('a point under the smoke is dimmed along the sun, a point the sun reaches past it is not, and castShadow false takes the volume out', () => {
const write = createLocalVolumeSurfaceShadow(resolveLocalVolumes([SMOKE]));
const factor = new Float64Array(3);
write(-1.2, 0, 0, ...SUN_TOWARD, factor);
assert.ok(factor.every(value => value > 0 && value < 0.5), `under the smoke ${factor}`);
write(4, 0, 0, ...SUN_TOWARD, factor);
assert.deepEqual(Array.from(factor), [1, 1, 1]);
assert.equal(createLocalVolumeSurfaceShadow(resolveLocalVolumes([{ ...SMOKE, castShadow: false }])), null);
const bluer = createLocalVolumeSurfaceShadow(resolveLocalVolumes([SMOKE]));
bluer(-1.2, 0, 0, ...SUN_TOWARD, factor);
assert.ok(factor[2] < factor[0], `the volume absorbs blue more than red, so less blue gets through: ${factor}`);
});
registerVolumeGrid('surface-shadow-block', encodeVolumeGrid({ resolution: [8, 4, 8], channels: { density: new Float32Array(8 * 4 * 8).fill(1) }, size: [4, 2, 4] }));
const GRID_SMOKE = { castShadow: true, shape: 'grid', grid: 'surface-shadow-block', center: [0, 2, 0], density: 0.6, absorption: [0.7, 0.8, 1], steps: 16 };
const boundGrid = overrides => bindLocalVolumeParts(resolveLocalVolumes([{ ...GRID_SMOKE, ...overrides }]), []);
test('a grid volume that casts packs 2 in the first component of the packed grid vector, a plain grid still packs 1', () => {
const buffers = createLocalVolumeBuffers();
packLocalVolumes(boundGrid({}), buffers);
assert.equal(buffers.grid[0], 2);
packLocalVolumes(boundGrid({ castShadow: false }), buffers);
assert.equal(buffers.grid[0], 1);
});
test('a point under a grid smoke is dimmed along the sun by its density, a point the sun reaches past it is not, and castShadow false takes it out', () => {
const write = createLocalVolumeSurfaceShadow(boundGrid({}));
const factor = new Float64Array(3);
write(-1.2, 0, 0, ...SUN_TOWARD, factor);
assert.ok(factor.every(value => value > 0 && value < 0.8), `under the smoke ${factor}`);
assert.ok(factor[2] < factor[0], `the grid absorbs blue more than red: ${factor}`);
write(4, 0, 0, ...SUN_TOWARD, factor);
assert.deepEqual(Array.from(factor), [1, 1, 1]);
assert.equal(createLocalVolumeSurfaceShadow(boundGrid({ castShadow: false })), null);
const thin = createLocalVolumeSurfaceShadow(boundGrid({ density: 0.1 }));
const thick = createLocalVolumeSurfaceShadow(boundGrid({ density: 2 }));
const thinFactor = new Float64Array(3);
thin(-1.2, 0, 0, ...SUN_TOWARD, thinFactor);
thick(-1.2, 0, 0, ...SUN_TOWARD, factor);
assert.ok(factor[1] < thinFactor[1], 'a denser grid casts a darker shadow');
});
test('a mesh volume casts no surface shadow yet', () => {
assert.equal(createLocalVolumeSurfaceShadow([{ ...resolveLocalVolumes([SMOKE])[0], mesh: true }]), null);
assert.equal(createLocalVolumeSurfaceShadow([{ ...resolveLocalVolumes([SMOKE])[0], shape: 'grid' }]), null);
});
const FLOOR = {
name: 'ground',
geometry: { positions: new Float32Array([-20, 0, 20, 20, 0, 20, 20, 0, -20, -20, 0, -20]), 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]) },
material: { tag: 'surface', metallic: 0, roughness: 1, color: [0.8, 0.8, 0.8], ior: 1.5 },
};
const SIZE = 32;
async function floorFrom(volume) {
const { linear } = await renderPathTracedImage(
{ parts: [FLOOR], environment: { lightDirection: SUN_TOWARD, keyColor: [3, 3, 3], localVolumes: [volume] }, camera: { eye: [0, 12, 0], target: [0, 0, 0], up: [0, 0, -1], fov: 50 } },
{ width: SIZE, height: SIZE, denoise: false, threads: 1, bounces: 1, samples: 8, seed: 3 },
);
return linear;
}
// The floor of the frame is 11.2 m across, so a column is 0.35 m; column 16 is x = 0.
function columnMean(values, column) {
let total = 0;
for (let row = 12; row < 20; row++) total += values[(row * SIZE + column) * 3 + 1];
return total / 8;
}
test('a volume without the flag leaves the frame bit for bit as castShadow false draws it', async () => {
const { castShadow: _castShadow, ...withoutFlag } = SMOKE;
const byDefault = await floorFrom(withoutFlag);
const off = await floorFrom({ ...SMOKE, castShadow: false });
assert.deepEqual(Array.from(byDefault), Array.from(off));
assert.equal(createLocalVolumeSurfaceShadow(resolveLocalVolumes([withoutFlag])), null);
});
test('the floor under a noisy smoke box is darker than the open floor, and castShadow false leaves it as it was', async () => {
const shadowed = await floorFrom(SMOKE);
const open = await floorFrom({ ...SMOKE, castShadow: false });
const underColumn = 12;
const openColumn = 29;
assert.ok(columnMean(open, underColumn) > 0.05, 'the floor is lit');
assert.equal(columnMean(shadowed, openColumn), columnMean(open, openColumn), 'the floor the sun reaches past the smoke is not touched');
const ratio = columnMean(shadowed, underColumn) / columnMean(open, underColumn);
assert.ok(ratio < 0.8, `the floor under the smoke keeps ${ratio.toFixed(3)} of its light`);
assert.ok(ratio > 0.2, `the shadow is soft, not black: ${ratio.toFixed(3)}`);
});