Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
import { expect, test } from 'bun:test';
import { Document } from '@gltf-transform/core';
import { createGltfIO } from './gltf-io';
import { EXTMeshGPUInstancing, KHRNodeVisibility } from '@gltf-transform/extensions';
import { compareRevisionGlbs, compareRevisionTotals } from './revision-comparison';
import { loadGlbReviewScene } from './views/glb';
import { listCameraSubjects } from './views/camera';
import { renderGLBInProcess as render } from './render';
import { TIERED_CAR, TIERED_CAR_CHAINS } from './__tests__/helpers/lod-fixture';
test('animation-only edits cannot hide behind unchanged static geometry', async () => {
const code = `function build(){const r=createRoot('Root');const j=createPivot('Joint',[0,0,0],r);createPart('Body',boxGeo(1,1,1),gameMaterial('#888888'),{parent:j});return r;}
function animate(){return [createClip('Idle',1,[rotationTrack('Joint_Joint',[{time:0,rotation:[0,0,0]},{time:1,rotation:[0,0,45]}])])];}`;
const original = await render(code);
const changed = await render(code.replace('0,0,45', '0,0,90'));
const comparison = await compareRevisionGlbs(original.glb, changed.glb);
expect(comparison.summary.changed).toBe(0);
expect(comparison.animation.summary.changed).toBe(1);
expect(comparison.animation.changes[0]?.property).toBe('rotation');
const same = await compareRevisionGlbs(original.glb, original.glb);
expect(same.animation.summary.unchanged).toBe(1);
});
async function fixture(
change:
| 'none'
| 'geometry'
| 'move'
| 'material'
| 'texture'
| 'rename'
| 'duplicate'
| 'morph'
| 'scene-title'
| 'reorder' = 'none',
) {
const doc = new Document();
const buffer = doc.createBuffer();
const material = doc.createMaterial('paint').setBaseColorFactor([0.2, 0.4, 0.8, 1]);
material.setBaseColorTexture(
doc
.createTexture()
.setMimeType('image/png')
.setImage(new Uint8Array([1, 2, change === 'texture' ? 4 : 3])),
);
if (change === 'material') material.setMetallicFactor(0.7);
const pos = doc
.createAccessor()
.setType('VEC3')
.setArray(new Float32Array([0, 0, 0, change === 'geometry' ? 2 : 1, 0, 0, 0, 1, 0]))
.setBuffer(buffer);
const primitive = doc.createPrimitive().setAttribute('POSITION', pos).setMaterial(material);
if (change === 'morph')
primitive.addTarget(doc.createPrimitiveTarget().setAttribute('POSITION', pos));
const part = doc
.createNode(change === 'rename' ? 'Replacement' : 'Part')
.setMesh(doc.createMesh().addPrimitive(primitive));
const root = doc
.createNode('Root')
.setScale([2, 3, 1])
.setTranslation([change === 'move' ? 4 : 0, 1, 0])
.addChild(part);
if (change === 'duplicate') root.addChild(doc.createNode('Part'));
const fixed = doc
.createNode('Fixed')
.setMesh(doc.createMesh().addPrimitive(doc.createPrimitive().setAttribute('POSITION', pos)));
if (change === 'reorder') root.removeChild(part).addChild(fixed).addChild(part);
else root.addChild(fixed);
doc.createScene(change === 'scene-title' ? 'Revised / title' : '').addChild(root);
return createGltfIO().writeBinary(doc);
}
test('revision comparison uses exported data, stable named paths and precise world bounds', async () => {
const before = await fixture();
const same = await compareRevisionGlbs(before, await fixture('reorder'));
expect(same.summary).toEqual({ added: 0, removed: 0, changed: 0, unchanged: 3 });
expect(same.changes).toEqual([]);
expect(same.before.bounds).toEqual({ min: [0, 1, 0], max: [2, 4, 0], size: [2, 3, 0] });
expect(same.before.glbSha256).toMatch(/^sha256:[a-f0-9]{64}$/);
const moved = await compareRevisionGlbs(before, await fixture('move'));
const part = moved.changes.find((c) => c.name === 'Part')!;
expect(part.fields).toEqual(['transform', 'bounds']);
expect(part.afterBounds!.min).toEqual([4, 1, 0]);
});
test('revision comparison distinguishes geometry, PBR material and texture-byte changes', async () => {
const before = await fixture();
for (const change of ['geometry', 'material', 'texture'] as const) {
const result = await compareRevisionGlbs(before, await fixture(change));
const part = result.changes.find((c) => c.name === 'Part')!;
expect(part.fields).toContain(change === 'geometry' ? 'geometry' : 'material');
expect(part.fields).not.toContain('transform');
if (change !== 'geometry') expect(part.fields).not.toContain('geometry');
}
});
test('renames are add/remove, changes paginate without hiding total counts', async () => {
const result = await compareRevisionGlbs(await fixture(), await fixture('rename'), { limit: 1 });
expect(result.summary).toEqual({ added: 1, removed: 1, changed: 0, unchanged: 2 });
expect(result.changes).toHaveLength(1);
expect(result.nextOffset).toBe(1);
const end = await compareRevisionGlbs(await fixture(), await fixture('rename'), {
offset: 1,
limit: 1,
});
expect(end.changes[0]!.status).not.toBe(result.changes[0]!.status);
expect(end.nextOffset).toBeNull();
});
test('ambiguous identities and unsupported deformation fail explicitly', async () => {
const before = await fixture();
await expect(compareRevisionGlbs(before, await fixture('duplicate'))).rejects.toThrow(
'unique nonempty sibling names',
);
await expect(compareRevisionGlbs(before, await fixture('morph'))).rejects.toThrow('morph');
await expect(compareRevisionGlbs(before, before, { limit: 0 })).rejects.toThrow('page');
});
test('bounds follow referenced vertices, not unused accessor outliers', async () => {
const doc = new Document();
const buffer = doc.createBuffer();
const positions = doc
.createAccessor()
.setType('VEC3')
.setBuffer(buffer)
.setArray(new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0, 100, 100, 100]));
const indices = doc
.createAccessor()
.setType('SCALAR')
.setBuffer(buffer)
.setArray(new Uint16Array([0, 1, 2]));
doc
.createScene()
.addChild(
doc
.createNode('Triangle')
.setMesh(
doc
.createMesh()
.addPrimitive(
doc.createPrimitive().setAttribute('POSITION', positions).setIndices(indices),
),
),
);
const bytes = await createGltfIO().writeBinary(doc);
expect((await compareRevisionGlbs(bytes, bytes)).after.bounds!.size).toEqual([1, 1, 0]);
});
test('selected subtree reports are complete regardless of unrelated changes or pagination', async () => {
const before = await fixture();
const paths = ['/Scene[0]/Root[0]/Fixed[0]', '/Scene[0]/Root[0]/Part[0]'];
const compared = await compareRevisionGlbs(before, await fixture('material'), {
paths,
limit: 1,
offset: 100,
});
expect(compared.changes).toEqual([]);
expect(compared.subtrees).toMatchObject([
{
path: paths[0],
status: 'unchanged',
summary: { added: 0, removed: 0, changed: 0, unchanged: 1 },
},
{ path: paths[1], status: 'changed', summary: { changed: 1 } },
]);
const moved = await compareRevisionGlbs(before, await fixture('move'), { paths: [paths[1]!] });
expect(moved.subtrees![0]!.status).toBe('changed');
const renamed = await compareRevisionGlbs(before, await fixture('rename'), {
paths: ['/Scene[0]/Root[0]', paths[1]!],
});
expect(renamed.subtrees).toMatchObject([
{ status: 'changed', summary: { added: 1, removed: 1, unchanged: 2 } },
{ status: 'removed', summary: { removed: 1 } },
]);
for (const invalid of [
['/Root[0]/Part[0]'],
[paths[0]!, paths[0]!],
[],
Array(13).fill(paths[0]!),
]) {
await expect(compareRevisionGlbs(before, before, { paths: invalid })).rejects.toThrow();
}
});
test('comparison paths can be copied directly from exported-scene inspection subjects', async () => {
const before = await fixture();
const scene = await loadGlbReviewScene(before);
const path = listCameraSubjects(scene.root).find((s) => s.node.name === 'Part')!.path;
expect(path).toBe('/Scene[0]/Root[0]/Part[0]');
expect((await compareRevisionGlbs(before, before, { paths: [path] })).subtrees![0]!.status).toBe(
'unchanged',
);
});
test('scene title changes retain node identity and report both exact inspection paths', async () => {
const before = await fixture();
const path = '/Scene[0]/Root[0]/Part[0]';
const result = await compareRevisionGlbs(before, await fixture('scene-title'), { paths: [path] });
expect(result.summary).toEqual({ added: 0, removed: 0, changed: 0, unchanged: 3 });
expect(result.subtrees![0]).toMatchObject({
path,
status: 'unchanged',
beforePath: path,
afterPath: '/Revised%20%2F%20title[0]/Root[0]/Part[0]',
});
});
test('an MSFT_lod chain compares every level at the path it takes in LOD0 place', async () => {
const before = (await render(TIERED_CAR)).glb;
const same = await compareRevisionGlbs(before, before);
// Car; five LOD0 nodes with the body's two parts and four tyres; two lower body levels with
// a part each; four empty wheel levels.
expect(same.summary).toEqual({
added: 0,
removed: 0,
changed: 0,
unchanged: 1 + (5 + 2 + 4) + 2 * 2 + 4,
});
// Headline bounds are LOD0's: the 3 m far block is a level, not part of the drawn asset.
expect(same.before.bounds!.max[1]).toBeCloseTo(1.5, 6);
const narrower = TIERED_CAR.replace(
'boxGeo(4 - lod * 0.5,',
'boxGeo(lod === 1 ? 3.6 : 4 - lod * 0.5,',
);
const changed = await compareRevisionGlbs(before, (await render(narrower)).glb);
const level = `${TIERED_CAR_CHAINS[0]!.levels[1]!.path}`;
expect(changed.changes.map((change) => [change.path, change.fields])).toEqual([
[level, ['bounds']],
[`${level}/Mesh_Shell1[0]`, ['geometry', 'bounds']],
]);
expect(changed.changes[1]!.afterBounds!.size[0]).toBeCloseTo(3.6, 6);
// A level sits under LOD0's parent: moving the parent moves every level's bounds.
const moved = await compareRevisionGlbs(
before,
(
await render(
TIERED_CAR.replace("createRoot('Car');", "createRoot('Car'); root.position.x = 2;"),
)
).glb,
);
const far = moved.changes.find(
(change) => change.path === TIERED_CAR_CHAINS[0]!.levels[2]!.path,
)!;
expect(far.fields).toContain('bounds');
expect(far.afterBounds!.min[0]! - far.beforeBounds!.min[0]!).toBeCloseTo(2, 6);
expect(moved.after.bounds!.max[1]).toBeCloseTo(1.5, 6);
});
test('hiding a part is a visibility change, and bounds count what draws', async () => {
const program = (hide: boolean) => `function build(){
const r=createRoot('Root');const m=gameMaterial('#888888');
createPart('Body',boxGeo(1,1,1),m,{parent:r,position:[0,0.5,0]});
const cover=createPart('Cover',boxGeo(2,0.2,2),m,{parent:r,position:[0,3,0]});
${hide ? 'cover.visible=false;' : ''}return r;}`;
const result = await compareRevisionGlbs(
(await render(program(false))).glb,
(await render(program(true))).glb,
);
const change = (name: string) => result.changes.find((c) => c.name === name);
expect(change('Mesh_Cover')!.fields).toEqual(['visibility']);
// A part's own bounds are where it draws when shown; its ancestors count only what draws.
expect(change('Mesh_Cover')!.afterBounds).toEqual(change('Mesh_Cover')!.beforeBounds);
expect(change('Root')!.fields).toEqual(['bounds']);
expect(change('Mesh_Body')).toBeUndefined();
expect(result.before.bounds!.max[1]).toBeCloseTo(3.1, 6);
expect(result.after.bounds!.max[1]).toBeCloseTo(1, 6);
});
/** One unit quad drawn four ways: the drawn world-space triangles are what count. */
async function quads(
form: 'list' | 'strip' | 'flipped' | 'instanced' | 'hidden-extra',
): Promise<Uint8Array> {
const doc = new Document();
const buffer = doc.createBuffer();
const accessor = (
type: 'VEC3' | 'SCALAR',
array: Float32Array<ArrayBuffer> | Uint16Array<ArrayBuffer>,
) => doc.createAccessor().setType(type).setArray(array).setBuffer(buffer);
const scene = doc.createScene('Quads');
const corners = (x: number) => [x, 0, 0, x + 1, 0, 0, x, 1, 0, x + 1, 1, 0];
const listed = (x: number, order: number[]) =>
doc
.createPrimitive()
.setAttribute('POSITION', accessor('VEC3', new Float32Array(corners(x))))
.setIndices(accessor('SCALAR', new Uint16Array(order)));
if (form === 'strip') {
// Both quads baked into one strip each; strips alternate winding, as glTF defines.
const mesh = doc.createMesh();
for (const x of [1, 3])
mesh.addPrimitive(
doc
.createPrimitive()
.setMode(5)
.setAttribute('POSITION', accessor('VEC3', new Float32Array(corners(x)))),
);
scene.addChild(doc.createNode('Strip').setMesh(mesh));
} else if (form === 'instanced') {
const extension = doc.createExtension(EXTMeshGPUInstancing);
const mesh = doc.createMesh().addPrimitive(listed(0, [0, 1, 2, 2, 1, 3]));
scene.addChild(
doc
.createNode('Copies')
.setMesh(mesh)
.setExtension(
'EXT_mesh_gpu_instancing',
extension
.createInstancedMesh()
.setAttribute('TRANSLATION', accessor('VEC3', new Float32Array([1, 0, 0, 3, 0, 0]))),
),
);
} else {
// Two nodes, each a local quad at the origin moved into place by its translation.
for (const [index, x] of [3, 1].entries()) {
const order = form === 'flipped' && index === 0 ? [0, 2, 1, 2, 3, 1] : [1, 2, 0, 1, 3, 2];
scene.addChild(
doc
.createNode(`Quad${x}`)
.setTranslation([x, 0, 0])
.setMesh(doc.createMesh().addPrimitive(listed(0, order))),
);
}
if (form === 'hidden-extra') {
const extension = doc.createExtension(KHRNodeVisibility);
scene.addChild(
doc
.createNode('Hidden')
.setMesh(doc.createMesh().addPrimitive(listed(7, [0, 1, 2])))
.setExtension('KHR_node_visibility', extension.createVisibility().setVisible(false)),
);
}
}
return createGltfIO().writeBinary(doc);
}
test('geometry identity ignores node, primitive, mode, instancing and triangle order but not winding', async () => {
const list = await quads('list');
for (const form of ['strip', 'instanced', 'hidden-extra'] as const) {
const compared = await compareRevisionTotals(list, await quads(form));
expect(compared.geometryIdentical, form).toBe(true);
expect(compared.counts.triangles, form).toEqual({ before: 4, after: 4, delta: 0 });
expect(compared.boundsDelta, form).toEqual({ min: [0, 0, 0], max: [0, 0, 0], size: [0, 0, 0] });
}
const strip = await compareRevisionTotals(list, await quads('strip'));
expect(strip.counts.vertices).toEqual({ before: 8, after: 8, delta: 0 });
expect(strip.counts.drawCalls).toEqual({ before: 2, after: 2, delta: 0 });
// Neither revision has TEXCOORD_0, so their corners agree.
expect(strip.uvIdentical).toBe(true);
const flipped = await compareRevisionTotals(list, await quads('flipped'));
expect(flipped.geometryIdentical).toBe(false);
expect(flipped.uvIdentical).toBeUndefined();
const instanced = await compareRevisionTotals(list, await quads('instanced'));
expect(instanced.counts.drawCalls).toEqual({ before: 2, after: 1, delta: -1 });
});