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 { describe, expect, test } from 'bun:test';
import { mkdtemp, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { engineNoteErrors, factsOf, isAssetPageRoute, readGlbFacts } from './engine-note.mjs';
import { inspectHtml } from './static-validation-core.mjs';
const NOTE =
'For your engine. The download is a standard glTF 2.0 binary (GLB) with PBR metallic-roughness materials. glTF stores materials, not lighting or tone mapping, so your engine decides how they read. This 3D view tone-maps with Review Neutral, the Khronos PBR Neutral construction with a smaller glare offset (0.015 instead of 0.04), at exposure 0.9. Its Tone mapping control also shows ACES and Linear, for comparison.';
const VEHICLE_NOTE = NOTE.replace('materials.', 'materials, and the vehicle files also declare the optional MSFT_lod extension for their detail tiers.');
const plain = { container: 2, version: '2.0', extensionsUsed: [], extensionsRequired: [], materials: 3 };
const pages = (entries: Record<string, { engineNotes: string[] }>) => new Map(Object.entries(entries));
const run = (entries: Record<string, { engineNotes: string[] }>, facts: Record<string, unknown>) =>
engineNoteErrors({ pages: pages(entries) as never, facts: new Map(Object.entries(facts)) as never }).map((error: { page: string; message: string }) => `${error.page}: ${error.message}`);
describe('which pages carry a 3D view of a GLB', () => {
test('cabin and woodland items participate without treating the pack namespace as an asset', () => {
expect(isAssetPageRoute('/gallery/cabin-woods-psx-horror/stone-golem/')).toBe(true);
expect(isAssetPageRoute('/gallery/cabin-woods-psx-horror/')).toBe(false);
expect(isAssetPageRoute('/gallery/cabin-woods-psx-horror/stone-golem/extra/')).toBe(false);
});
test('Holodeck scene items participate without treating the Holodeck namespace as an asset', () => {
expect(isAssetPageRoute('/gallery/holodeck/plaza-fountain/')).toBe(true);
expect(isAssetPageRoute('/gallery/holodeck/')).toBe(false);
});
test('a reviewed asset page and an archive item, and nothing else', () => {
expect(isAssetPageRoute('/gallery/farmhouse/')).toBe(true);
expect(isAssetPageRoute('/gallery/archive/robot-arm/')).toBe(true);
expect(isAssetPageRoute('/gallery/foundry-floor/foup/')).toBe(true);
expect(isAssetPageRoute('/gallery/foundry-floor/')).toBe(false);
expect(isAssetPageRoute('/gallery/')).toBe(false);
expect(isAssetPageRoute('/gallery/archive/')).toBe(false);
expect(isAssetPageRoute('/packs/farm/')).toBe(false);
expect(isAssetPageRoute('/gallery/archive/robot-arm/extra/')).toBe(false);
});
});
describe('the page markup the note is read from', () => {
test('inspection returns the note text and the GLB the 3D view loads', () => {
const html = `<html lang="en"><head><title>x</title></head><body><asset-viewer data-name="Barn" data-model="/models/farm/barn.glb?revision=r_1"></asset-viewer><p data-engine-note><strong>For your engine.</strong> The download is
standard.</p></body></html>`;
const result = inspectHtml(html);
expect(result.engineNotes).toEqual(['For your engine. The download is standard.']);
expect(result.viewerModels).toEqual(['/models/farm/barn.glb?revision=r_1']);
expect(inspectHtml('<html lang="en"><head><title>x</title></head><body></body></html>')).toMatchObject({ engineNotes: [], viewerModels: [] });
});
});
describe('what a GLB says about itself', () => {
test('facts come from the JSON chunk: glTF version, declared extensions, material count', () => {
expect(factsOf({ asset: { version: '2.0' }, extensionsUsed: ['MSFT_lod', 'KHR_x'], materials: [{}, {}] }, 2)).toEqual({
container: 2,
version: '2.0',
extensionsUsed: ['KHR_x', 'MSFT_lod'],
extensionsRequired: [],
materials: 2,
});
expect(factsOf({}, 2)).toMatchObject({ version: undefined, extensionsUsed: [], materials: 0 });
});
test('a GLB is read from its header and first chunk only', async () => {
const directory = await mkdtemp(join(tmpdir(), 'glb-facts-'));
try {
const json = Buffer.from(JSON.stringify({ asset: { version: '2.0' }, extensionsUsed: ['MSFT_lod'], materials: [{ pbrMetallicRoughness: {} }] }));
const padded = Buffer.concat([json, Buffer.alloc((4 - (json.length % 4)) % 4, 0x20)]);
const header = Buffer.alloc(20);
header.write('glTF', 0, 'latin1');
header.writeUInt32LE(2, 4);
header.writeUInt32LE(20 + padded.length + 1000, 8);
header.writeUInt32LE(padded.length, 12);
header.write('JSON', 16, 'latin1');
const good = join(directory, 'good.glb');
await writeFile(good, Buffer.concat([header, padded, Buffer.alloc(1000)]));
expect(await readGlbFacts(good)).toEqual({ container: 2, version: '2.0', extensionsUsed: ['MSFT_lod'], extensionsRequired: [], materials: 1 });
const bad = join(directory, 'bad.glb');
await writeFile(bad, Buffer.from('not a glb, only text that is long enough to read a header from'));
await expect(readGlbFacts(bad)).rejects.toThrow('not a GLB');
} finally {
await rm(directory, { recursive: true, force: true });
}
});
});
describe('the engine note on asset pages', () => {
test('passes when every asset page has the note and the GLB it describes is plain glTF 2.0', () => {
expect(run({ '/gallery/farmhouse/': { engineNotes: [NOTE] }, '/gallery/': { engineNotes: [] } }, { '/gallery/farmhouse/': plain })).toEqual([]);
});
test('a page without the note, or with it twice, fails', () => {
expect(run({ '/gallery/farmhouse/': { engineNotes: [] } }, { '/gallery/farmhouse/': plain })).toEqual(['/gallery/farmhouse/: Asset page must carry exactly one engine note, found 0']);
expect(run({ '/gallery/farmhouse/': { engineNotes: [NOTE, NOTE] } }, { '/gallery/farmhouse/': plain })).toEqual(['/gallery/farmhouse/: Asset page must carry exactly one engine note, found 2']);
});
test('the note must say what it promises: glTF 2.0, PBR metallic-roughness, the preview tone mapping and the choices', () => {
const errors = run({ '/gallery/farmhouse/': { engineNotes: ['For your engine. Nothing useful here.'] } }, { '/gallery/farmhouse/': plain });
expect(errors.length).toBe(5);
for (const phrase of ['glTF 2.0', 'PBR metallic-roughness', 'Review Neutral', 'ACES', 'Linear']) expect(errors.join('\n')).toContain(`"${phrase}"`);
});
test('a page whose 3D view names no GLB cannot be checked, and a GLB that could not be read is reported', () => {
expect(run({ '/gallery/farmhouse/': { engineNotes: [NOTE] } }, {})).toEqual(['/gallery/farmhouse/: The 3D view names no GLB that the engine note can be checked against']);
expect(run({ '/gallery/farmhouse/': { engineNotes: [NOTE] } }, { '/gallery/farmhouse/': { error: 'ENOENT' } })).toEqual(['/gallery/farmhouse/: The GLB behind the 3D view could not be read: ENOENT']);
});
test('the note is true of the GLB: glTF 2.0, nothing required, no other shading model', () => {
expect(run({ '/gallery/a/': { engineNotes: [NOTE] } }, { '/gallery/a/': { ...plain, version: '1.0' } })).toEqual(['/gallery/a/: The engine note says glTF 2.0 but the GLB declares 1.0']);
expect(run({ '/gallery/a/': { engineNotes: [NOTE] } }, { '/gallery/a/': { ...plain, extensionsRequired: ['KHR_draco_mesh_compression'] } })).toEqual(['/gallery/a/: The GLB requires KHR_draco_mesh_compression, so it is not plain glTF 2.0 for every engine']);
expect(run({ '/gallery/a/': { engineNotes: [NOTE] } }, { '/gallery/a/': { ...plain, extensionsUsed: ['KHR_materials_unlit'] } })[0]).toContain('KHR_materials_unlit');
expect(run({ '/gallery/a/': { engineNotes: [NOTE] } }, { '/gallery/a/': { ...plain, extensionsUsed: ['KHR_materials_pbrSpecularGlossiness'] } })[0]).toContain('KHR_materials_pbrSpecularGlossiness');
});
test('MSFT_lod is named in the note exactly when the GLB declares it', () => {
const lod = { ...plain, extensionsUsed: ['MSFT_lod'] };
expect(run({ '/gallery/sedan/': { engineNotes: [VEHICLE_NOTE] } }, { '/gallery/sedan/': lod })).toEqual([]);
expect(run({ '/gallery/sedan/': { engineNotes: [NOTE] } }, { '/gallery/sedan/': lod })).toEqual(['/gallery/sedan/: The GLB declares MSFT_lod but the engine note does not mention it']);
expect(run({ '/gallery/barn/': { engineNotes: [VEHICLE_NOTE] } }, { '/gallery/barn/': plain })).toEqual(['/gallery/barn/: The engine note mentions MSFT_lod but the GLB does not declare it']);
});
test('any other declared extension is one the note has not told the reader about', () => {
expect(run({ '/gallery/a/': { engineNotes: [NOTE] } }, { '/gallery/a/': { ...plain, extensionsUsed: ['KHR_texture_transform'] } })).toEqual(['/gallery/a/: The GLB declares KHR_texture_transform, which the engine note does not mention']);
});
});