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 { createModel } from '../src/model.js';
import { exportGlb } from '../src/export.js';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { box } from '../src/geometry.js';
import { createMorphPose } from '../src/morph.js';
import { mat4 } from 'gl-matrix';
import { Vector3 } from 'three';
test('exported GLB loads with an independent glTF loader and preserves every part', async () => {
const parts = createModel();
const binary = exportGlb(parts);
const header = new DataView(binary);
assert.equal(header.getUint32(0, true), 0x46546c67);
assert.equal(header.getUint32(8, true), binary.byteLength);
const gltf = await new GLTFLoader().parseAsync(binary, '');
let meshCount = 0;
gltf.scene.traverse((node) => { if (node.isMesh) meshCount++; });
assert.equal(meshCount, parts.length);
assert.ok(binary.byteLength < 1024 * 1024);
});
test('GLB export writes alpha mode, cutoff, opacity and double-sided so the loader reads them back', async () => {
const part = createModel()[0];
const material = { ...part.material, alphaMode: 'mask', alphaCutoff: 0.3, opacity: 0.6, doubleSided: true };
const gltf = await new GLTFLoader().parseAsync(exportGlb([{ ...part, material }]), '');
let loaded;
gltf.scene.traverse((node) => { if (node.isMesh) loaded = node.material; });
assert.equal(loaded.alphaTest, 0.3);
assert.equal(loaded.side, 2);
assert.ok(Math.abs(loaded.opacity - 0.6) < 1e-6);
});
test('GLB export names the fix when textures have no UVs or exceed the size limit', () => {
const part = createModel()[0];
const image = { width: 4, height: 4, data: new Uint8ClampedArray(64).fill(255) };
const textured = { ...part, material: { ...part.material, map: { image } } };
assert.throws(() => exportGlb([textured]), /uv_unwrap/);
const withUvs = { ...textured, geometry: { ...part.geometry, uvs: new Float32Array(part.geometry.positions.length / 3 * 2) } };
assert.throws(() => exportGlb([withUvs], { maxTextureSize: 2 }), /maxTextureSize 2/);
assert.ok(exportGlb([withUvs]).byteLength > 0);
});
test('GLB export rejects a skin without joints and skin attributes without a skin', () => {
const part = createModel()[0];
assert.throws(() => exportGlb([{ ...part, geometry: { ...part.geometry, skinIndices: new Uint16Array(4) } }]), /[Ss]kin/);
assert.throws(() => exportGlb([{ ...part, skin: { jointMatrices: new Float32Array(16) } }]), /[Ss]kin/);
});
test('GLB export rejects malformed morph pairs rather than discarding expressions', () => {
const part = createModel()[0];
assert.throws(() => exportGlb([{ ...part, morph: { weights: new Float32Array(1) } }]), /target array/);
assert.throws(() => exportGlb([{ ...part, geometry: { ...part.geometry, morphTargets: [] } }]), /require a morph pose/);
});
test('GLB morph snapshots retain relative channels, shared meshes and independent signed node weights', async () => {
const geometry = box();
const positions = new Float32Array(geometry.positions.length);
const normals = new Float32Array(geometry.normals.length);
for (let offset = 0; offset < positions.length; offset += 3) {
positions[offset] = 0.25;
positions[offset + 1] = 0.125;
normals[offset + 2] = 0.1;
}
geometry.morphTargets = [{ positions }, { normals }];
const first = createMorphPose(2);
const second = createMorphPose(2);
first.weights.set([1.5, -0.5]);
second.weights.set([-0.25, 0.75]);
const material = { color: [0.4, 0.5, 0.6], metallic: 0, roughness: 0.7, emission: 0 };
const parts = [first, second].map((morph, index) => ({ name: `instance ${index}`, geometry, material, morph, matrix: mat4.create() }));
const binary = exportGlb(parts);
const view = new DataView(binary);
const document = JSON.parse(new TextDecoder().decode(new Uint8Array(binary, 20, view.getUint32(12, true))));
assert.equal(document.meshes.length, 1);
assert.deepEqual(document.nodes.map(node => node.weights), [[1.5, -0.5], [-0.25, 0.75]]);
const targets = document.meshes[0].primitives[0].targets;
assert.deepEqual(Object.keys(targets[0]), ['POSITION']);
assert.deepEqual(Object.keys(targets[1]), ['NORMAL']);
assert.deepEqual(document.accessors[targets[0].POSITION].min, [0.25, 0.125, 0]);
const loaded = await new GLTFLoader().parseAsync(binary, '');
const meshes = [];
loaded.scene.traverse(node => { if (node.isMesh) meshes.push(node); });
assert.equal(meshes.length, 2);
assert.equal(meshes[0].geometry, meshes[1].geometry);
assert.deepEqual(meshes.map(mesh => mesh.morphTargetInfluences), [[1.5, -0.5], [-0.25, 0.75]]);
for (let instance = 0; instance < meshes.length; instance++) {
// GLTFLoader fills an omitted position channel with the base attribute.
// Isolate the declared position target when using its CPU vertex helper.
meshes[instance].morphTargetInfluences[1] = 0;
const point = meshes[instance].getVertexPosition(0, new Vector3());
assert.equal(point.x, geometry.positions[0] + parts[instance].morph.weights[0] * positions[0]);
assert.equal(point.y, geometry.positions[1] + parts[instance].morph.weights[0] * positions[1]);
}
first.weights[0] = NaN;
assert.throws(() => exportGlb(parts), /finite Float32/);
});
function glbDocument(binary) {
const view = new DataView(binary);
const jsonLength = view.getUint32(12, true);
const document = JSON.parse(new TextDecoder().decode(new Uint8Array(binary, 20, jsonLength)));
function values(index) {
const accessor = document.accessors[index];
const bufferView = document.bufferViews[accessor.bufferView];
const components = { SCALAR: 1, VEC2: 2, VEC3: 3 }[accessor.type];
return Array.from(new Float32Array(binary, 28 + jsonLength + bufferView.byteOffset, accessor.count * components));
}
return { document, values };
}
function coloredPart() {
const geometry = box();
const colorStorage = new Float32Array(geometry.positions.length + 6).fill(99);
geometry.colors = colorStorage.subarray(3, colorStorage.length - 3);
for (let offset = 0; offset < geometry.colors.length; offset += 3) geometry.colors.set([0.125, 0.5, 0.875], offset);
const uvStorage = new Float32Array(geometry.positions.length / 3 * 2 + 4).fill(99);
geometry.uvs = uvStorage.subarray(2, uvStorage.length - 2);
for (let offset = 0; offset < geometry.uvs.length; offset += 2) geometry.uvs.set([-0.25, 2.5], offset);
return { name: 'editable channels', geometry, matrix: mat4.create(), material: {
color: [0.25, 0.5, 0.75], metallic: 0.25, roughness: 0.625,
emissiveColor: new Float32Array([0.875, 0.125, 0.25]), emission: 12.5,
} };
}
test('GLB keeps editable offset RGB/UV accessors and separate HDR emission with shared meshes', async () => {
const part = coloredPart();
const binary = exportGlb([part, { ...part, name: 'shared instance' }]);
const { document, values } = glbDocument(binary);
assert.equal(document.meshes.length, 1);
const attributes = document.meshes[0].primitives[0].attributes;
assert.equal(document.accessors[attributes.COLOR_0].type, 'VEC3');
assert.equal(document.accessors[attributes.TEXCOORD_0].type, 'VEC2');
assert.equal(document.accessors[attributes.TEXCOORD_0].count, part.geometry.positions.length / 3);
assert.deepEqual(values(attributes.COLOR_0), Array.from(part.geometry.colors));
assert.deepEqual(values(attributes.TEXCOORD_0), Array.from(part.geometry.uvs));
assert.deepEqual(document.materials[0].pbrMetallicRoughness.baseColorFactor, [0.25, 0.5, 0.75, 1]);
assert.deepEqual(document.materials[0].emissiveFactor, [0.875, 0.125, 0.25]);
assert.equal(document.materials[0].extensions.KHR_materials_emissive_strength.emissiveStrength, 12.5);
assert.deepEqual(document.extensionsRequired, ['KHR_materials_emissive_strength']);
const loaded = await new GLTFLoader().parseAsync(binary, '');
const meshes = [];
loaded.scene.traverse(node => { if (node.isMesh) meshes.push(node); });
assert.equal(meshes[0].geometry, meshes[1].geometry);
assert.deepEqual(Array.from(meshes[0].geometry.attributes.color.array), Array.from(part.geometry.colors));
assert.deepEqual(Array.from(meshes[0].geometry.attributes.uv.array), Array.from(part.geometry.uvs));
assert.deepEqual(meshes[0].material.emissive.toArray(), [0.875, 0.125, 0.25]);
assert.equal(meshes[0].material.emissiveIntensity, 12.5);
const { parseGltf } = await import('../src/gltf.js');
const imported = await parseGltf(binary);
try {
assert.equal(imported.parts[0].geometry, imported.parts[1].geometry);
assert.deepEqual(Array.from(imported.parts[0].geometry.colors), Array.from(part.geometry.colors));
assert.deepEqual(Array.from(imported.parts[0].geometry.uvs), Array.from(part.geometry.uvs));
assert.deepEqual(imported.parts[0].material.emissiveColor, [0.875, 0.125, 0.25]);
assert.equal(imported.parts[0].material.emission, 12.5);
} finally {
imported.dispose();
}
});
test('GLB defaults remain dark without extensions and active emission preserves color and scalar', async () => {
for (const emission of [undefined, 0, 1, 0.25, 1000]) {
const part = coloredPart();
delete part.material.emissiveColor;
part.material.emission = emission;
const binary = exportGlb([part]);
const { document } = glbDocument(binary);
// Below 1 the strength is folded into the factor, because emissiveStrength may not be under 1.
const factorScale = emission < 1 ? emission : 1;
const expectedFactor = emission ? part.material.color.map(channel => channel * factorScale) : [0, 0, 0];
document.materials[0].emissiveFactor.forEach((channel, index) => assert.ok(Math.abs(channel - expectedFactor[index]) < 1e-6));
assert.equal(Boolean(document.extensionsUsed), emission > 1);
const loaded = await new GLTFLoader().parseAsync(binary, '');
const material = loaded.scene.children[0].material;
assert.equal(material.emissive.r * material.emissiveIntensity, part.material.color[0] * (emission ?? 0));
}
});
test('GLB validates every channel and material before binary allocation without clamping', () => {
for (const [field, value] of [
['colors', new Float32Array(3)], ['colors', new Float64Array(72)],
['uvs', new Float32Array(3)], ['uvs', new Float64Array(48)],
['positions', new Float64Array(72)], ['normals', new Float32Array(72)],
['indices', new Uint16Array([0, 1, 2])], ['indices', new Uint32Array([0, 1, 4294967295])],
]) {
const part = coloredPart();
part.geometry[field] = value;
assert.throws(() => exportGlb([part]), /GLB/);
}
for (const [field, invalid] of [['colors', NaN], ['colors', -0.01], ['colors', 1.001], ['uvs', Infinity]]) {
const part = coloredPart();
part.geometry[field][0] = invalid;
assert.throws(() => exportGlb([part]), /finite values/);
}
for (const [field, invalid] of [
['color', [1.001, 0, 0]], ['color', [0, 0]], ['emissiveColor', [0, NaN, 0]],
['emissiveColor', [-1, 0, 0]], ['metallic', 1.01], ['roughness', -0.01],
['emission', -1], ['emission', Infinity], ['emission', 1e40],
]) {
const part = coloredPart();
part.material[field] = invalid;
assert.throws(() => exportGlb([part]), /GLB/);
}
const part = coloredPart();
part.matrix[3] = 1;
assert.throws(() => exportGlb([part]), /affine/);
assert.throws(() => exportGlb([]), /nonempty/);
});
test('GLB rejects an invalid later part before allocating its output buffer', () => {
const valid = coloredPart();
const invalid = coloredPart();
invalid.material.emission = Infinity;
const NativeArrayBuffer = globalThis.ArrayBuffer;
let allocations = 0;
globalThis.ArrayBuffer = class extends NativeArrayBuffer {
constructor(...argumentsList) {
super(...argumentsList);
allocations++;
}
};
try {
assert.throws(() => exportGlb([valid, invalid]), /GLB emission/);
assert.equal(allocations, 0);
} finally {
globalThis.ArrayBuffer = NativeArrayBuffer;
}
});
test('GLB scans shared static geometry once while preserving different instance materials', () => {
const part = coloredPart();
const positions = part.geometry.positions;
let reads = 0;
Object.defineProperty(part.geometry, 'positions', { get() { reads++; return positions; } });
exportGlb([part]);
const singleReads = reads;
reads = 0;
const second = { ...part, material: { ...part.material, emissiveColor: [0.125, 0.875, 0.25] } };
const { document } = glbDocument(exportGlb([part, second]));
assert.equal(reads, singleReads);
assert.equal(document.meshes.length, 2);
assert.equal(document.meshes[0].primitives[0].attributes.COLOR_0, document.meshes[1].primitives[0].attributes.COLOR_0);
assert.deepEqual(document.materials.map(material => material.emissiveFactor), [[0.875, 0.125, 0.25], [0.125, 0.875, 0.25]]);
});
test('GLB rejects shear and zero scales before output allocation', () => {
for (const [offset, value, message] of [[4, 0.5, /shear/], [0, 0, /nonzero scales/], [0, 1e-50, /nonzero scales/]]) {
const part = coloredPart();
part.matrix = Array.from(part.matrix);
part.matrix[offset] = value;
const NativeArrayBuffer = globalThis.ArrayBuffer;
let allocations = 0;
globalThis.ArrayBuffer = class extends NativeArrayBuffer {
constructor(...argumentsList) {
super(...argumentsList);
allocations++;
}
};
try {
assert.throws(() => exportGlb([part]), message);
assert.equal(allocations, 0);
} finally {
globalThis.ArrayBuffer = NativeArrayBuffer;
}
}
const scaledShear = coloredPart();
mat4.scale(scaledShear.matrix, scaledShear.matrix, [1e-25, 2e-25, 3e-25]);
scaledShear.matrix[4] = 1e-25;
assert.throws(() => exportGlb([scaledShear]), /shear/);
});
test('GLB Float32 rotated nonuniform, reflected and tiny TRS transforms roundtrip through Three', async () => {
for (const scale of [[0.125, 7, 2.5], [-0.125, 7, 2.5], [0.125, -7, -2.5], [1e-30, 2e-25, -3e-20]]) {
const part = coloredPart();
mat4.translate(part.matrix, part.matrix, [0.25, -1.5, 3]);
mat4.rotateX(part.matrix, part.matrix, 0.47);
mat4.rotateY(part.matrix, part.matrix, -0.71);
mat4.rotateZ(part.matrix, part.matrix, 1.13);
mat4.scale(part.matrix, part.matrix, scale);
const binary = exportGlb([part]);
assert.deepEqual(glbDocument(binary).document.nodes[0].matrix, Array.from(part.matrix, value => value === 0 ? 0 : value));
const loaded = await new GLTFLoader().parseAsync(binary, '');
loaded.scene.updateMatrixWorld(true);
const actual = loaded.scene.children[0].matrix.elements;
for (let column = 0; column < 4; column++) {
const magnitude = Math.max(...Array.from(part.matrix.slice(column * 4, column * 4 + 4), Math.abs));
for (let row = 0; row < 4; row++) {
const offset = column * 4 + row;
assert.ok(Number.isFinite(actual[offset]));
assert.ok(Math.abs(actual[offset] - part.matrix[offset]) <= magnitude * 1e-6, `scale ${scale}, component ${offset}`);
}
}
}
});
test('GLB export writes an additive material as BLEND because glTF has no additive mode', async () => {
const part = createModel()[0];
const material = { ...part.material, alphaMode: 'add', opacity: 0.5 };
const gltf = await new GLTFLoader().parseAsync(exportGlb([{ ...part, material }]), '');
let loaded;
gltf.scene.traverse((node) => { if (node.isMesh) loaded = node.material; });
assert.equal(loaded.transparent, true);
assert.ok(Math.abs(loaded.opacity - 0.5) < 1e-6);
});
test('GLB errors name the part and the material and say what to pass', () => {
const part = { name: 'lamp', geometry: box(), matrix: mat4.create(), material: { id: 'hot', color: [1, 1, 1], metallic: 0, roughness: 1, emission: 1, emissiveColor: [-1, 0, 0] } };
assert.throws(() => exportGlb([part]), /material "hot" of lamp needs emissiveColor as three finite numbers of 0 or more/);
const stretched = { ...part, name: 'kid', material: { ...part.material, emissiveColor: [1, 1, 1] }, matrix: mat4.fromValues(3, 0, 0, 0, 1.5, 1.5, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1) };
assert.throws(() => exportGlb([stretched], { nodePaths: { kid: 'p > kid' } }), /part "kid" \(p > kid\) cannot preserve shear.*uniform scale/);
assert.throws(() => exportGlb([stretched]), /part "kid" cannot preserve shear/);
});
test('GLB moves an emissive color above 1 into the emissive strength', () => {
const part = { name: 'lamp', geometry: box(), matrix: mat4.create(), material: { color: [1, 1, 1], metallic: 0, roughness: 1, emission: 0.5, emissiveColor: [4, 2, 1] } };
const binary = exportGlb([part]);
const [material] = JSON.parse(new TextDecoder().decode(new Uint8Array(binary, 20, new DataView(binary).getUint32(12, true)))).materials;
assert.deepEqual(material.emissiveFactor, [1, 0.5, 0.25]);
assert.equal(material.extensions.KHR_materials_emissive_strength.emissiveStrength, 2);
});