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
Check that a text-to-3D delivery file keeps what code and viewers rely on (#346)
Matthew Kissinger0dd5868ab5cc
diff --git a/site/scripts/generate-commons.mjs b/site/scripts/generate-commons.mjsindex 9acfe8c8..5a296d09 100644--- a/site/scripts/generate-commons.mjs+++ b/site/scripts/generate-commons.mjs@@ -40,6 +40,25 @@ const readJson = async (path) => JSON.parse(await readFile(path, 'utf8'));const writeJson = async (path, value) => { await mkdir(dirname(path), { recursive: true }); await writeFile(path, `${JSON.stringify(value, null, 2)}\n`); };const modelNames = { 'claude-opus-5-5': 'Claude Opus 5.5', 'gpt-6-astra': 'GPT-6 Astra', 'claude-sonnet-5-5': 'Claude Sonnet 5.5', 'gemini-3.8-flash-high': 'Gemini 3.8 Flash High' };+/** Each copy's place under a node with EXT_mesh_gpu_instancing, or the node's own place alone. Float attributes only. */+function instancePlaces(json, data, node) {+ const attributes = node.extensions?.EXT_mesh_gpu_instancing?.attributes;+ if (!attributes) return [new Matrix4()];+ const bin = data.subarray(20 + data.readUInt32LE(12) + 8);+ const read = (name, width) => {+ if (attributes[name] === undefined) return undefined;+ const accessor = json.accessors[attributes[name]];+ if (accessor.componentType !== 5126) throw new Error(`Instanced ${name} is not float data`);+ const view = json.bufferViews[accessor.bufferView];+ const stride = view.byteStride ?? width * 4;+ const start = (view.byteOffset ?? 0) + (accessor.byteOffset ?? 0);+ return Array.from({ length: accessor.count }, (_, i) => Array.from({ length: width }, (_, k) => bin.readFloatLE(start + i * stride + k * 4)));+ };+ const [moves, turns, sizes] = [read('TRANSLATION', 3), read('ROTATION', 4), read('SCALE', 3)];+ const count = (moves ?? turns ?? sizes ?? []).length;+ return Array.from({ length: count }, (_, i) => new Matrix4().compose(new Vector3(...(moves?.[i] ?? [0, 0, 0])), new Quaternion(...(turns?.[i] ?? [0, 0, 0, 1])), new Vector3(...(sizes?.[i] ?? [1, 1, 1]))));+}+export function inspectGlb(bytes) {const data = Buffer.from(bytes);if (data.toString('ascii', 0, 4) !== 'glTF' || data.readUInt32LE(4) !== 2 || data.readUInt32LE(8) !== data.length) throw new Error('Invalid GLB header');@@ -53,12 +72,14 @@ export function inspectGlb(bytes) {const path = [...parentPath, node.name ?? `node_${index}`];if (node.mesh !== undefined) {meshes++; parts.push(path.join('/'));+ // A GPU-instanced batch draws its mesh once per copy, each at its own place under the node.+ const copies = instancePlaces(json, data, node).map((place) => world.clone().multiply(place));for (const primitive of json.meshes[node.mesh].primitives) {const accessor = json.accessors[primitive.attributes.POSITION];const count = primitive.indices !== undefined ? json.accessors[primitive.indices].count : accessor.count;- triangles += (primitive.mode ?? 4) === 4 ? count / 3 : 0;+ triangles += (primitive.mode ?? 4) === 4 ? (count / 3) * copies.length : 0;if (!accessor.min || !accessor.max) throw new Error(`GLB position bounds missing: ${path.join('/')}`);- for (let corner = 0; corner < 8; corner++) bounds.expandByPoint(new Vector3(...[0, 1, 2].map((axis) => ((corner >> axis) & 1) ? accessor.max[axis] : accessor.min[axis])).applyMatrix4(world));+ for (const place of copies) for (let corner = 0; corner < 8; corner++) bounds.expandByPoint(new Vector3(...[0, 1, 2].map((axis) => ((corner >> axis) & 1) ? accessor.max[axis] : accessor.min[axis])).applyMatrix4(place));}}for (const child of node.children ?? []) visit(child, world, path);diff --git a/site/scripts/stage-text-to-3d.mjs b/site/scripts/stage-text-to-3d.mjsindex 98342922..2cbc8d2d 100644--- a/site/scripts/stage-text-to-3d.mjs+++ b/site/scripts/stage-text-to-3d.mjs@@ -18,8 +18,8 @@ import { ASSET_BASE } from './mirror-core.mjs';** <directory>/tools.json names the tools. <directory>/<subject>/ is a workspace holding `assets/`, `run/` with the prompts and* `steps.json`, which lists each step's prompt and saved revision, and `renders/manifest.json` from- * scripts/render-text-to-3d.mjs. A steps.json may name a `delivery` file, `{ file, madeFrom: "sha256:…" }`, to serve- * in place of the final revision's GLB (see `checkDelivery`); the page's claims are still checked on the revisions.+ * scripts/render-text-to-3d.mjs. A steps.json may name a `delivery` file, `{ file, madeFrom: "sha256:…", drops?: [names] }`,+ * to serve in place of the final revision's GLB (see `checkDelivery`); the page's claims are still checked on the revisions.** Images and programs are committed under public/text-to-3d/. The two GLBs go to the asset host, the way Golden Gate's do:* each is named by its own hash, pinned in the mirror manifest and copied to .localdata/asset-delivery with an upload list@@ -131,30 +131,113 @@ export function clipDigests(bytes) {/*** The file a subject is served as, when its steps.json names one in `delivery`: a form of the final revision made for- * playing, such as its parts merged into one skinned mesh. It is served only if it was made from that revision's exact- * bytes and keeps what code reaches for: every named node that is not a mesh part, with its notes, every clip's- * targets and keyframes, the material names and the triangle count. Returns the delivery file.+ * playing, such as its parts merged into one skinned mesh or into fewer draws. It is served only if it was made from+ * that revision's exact bytes and keeps what code reaches for:+ * - every named node that is not a mesh part, in order where a name repeats, with its notes, its parent and its place;+ * - parts that still follow every node a clip moves, as meshes beneath it or skinned to it;+ * - every clip's targets and keyframes, every material in full and the triangle count.+ * `drops` names grouping nodes the delivery may leave out, as a draw reduction does once their parts become batches;+ * each must be one the record states, with no notes, moved by no clip and binding no skin. Returns the delivery file.*/-export function checkDelivery(saved, delivered, madeFrom) {+export function checkDelivery(saved, delivered, madeFrom, { drops = [] } = {}) {if (madeFrom !== `sha256:${hash(saved)}`) throw Error(`the delivery file was made from ${madeFrom}, not the final revision; make it again`);const before = openGlb(saved).gltf;const after = openGlb(delivered).gltf;- const named = new Map(after.nodes.map((node) => [node.name, node]));- for (const node of before.nodes) {- if (node.mesh !== undefined) continue;- const kept = named.get(node.name);- if (!kept) throw Error(`the delivery file has no ${node.name}`);- if (JSON.stringify(kept.extras ?? null) !== JSON.stringify(node.extras ?? null)) throw Error(`the delivery file changes the notes on ${node.name}`);+ const named = byName(after);+ const moved = movedByClips(before);+ const joints = new Set((before.skins ?? []).flatMap((skin) => skin.joints.map((joint) => before.nodes[joint].name)));+ for (const [name, nodes] of byName(before)) {+ const kept = named.get(name) ?? [];+ if (kept.length === 0 && drops.includes(name)) {+ if (nodes.some(({ node }) => node.extras) || moved.has(name) || joints.has(name)) throw Error(`the delivery file may not drop ${name}: code can reach for it`);+ continue;+ }+ nodes.forEach((node, nth) => {+ const same = kept[nth];+ const which = nodes.length > 1 ? `${name} (number ${nth + 1} of that name)` : name;+ if (!same) throw Error(`the delivery file has no ${which}`);+ if (JSON.stringify(same.node.extras ?? null) !== JSON.stringify(node.node.extras ?? null)) throw Error(`the delivery file changes the notes on ${which}`);+ if (same.parent !== node.parent) throw Error(`the delivery file moves ${which} from ${node.parent} to ${same.parent}`);+ if (!samePlace(same.node, node.node)) throw Error(`the delivery file moves ${which}`);+ });+ }+ const carriers = carriersOf(after);+ for (const name of moved) {+ if (!carriesParts(before, name)) continue;+ if (!carriers.has(name)) throw Error(`the delivery file's ${name} no longer carries its parts: the clip would move nothing`);}const clips = clipDigests(delivered);for (const [name, digest] of clipDigests(saved)) if (clips.get(name) !== digest) throw Error(`the delivery file's ${name} clip differs`);- const materials = (gltf) => JSON.stringify((gltf.materials ?? []).map(({ name }) => name).sort());- if (materials(before) !== materials(after)) throw Error('the delivery file has other materials');- const [was, now] = [inspectGlb(saved).triangles, inspectGlb(delivered).triangles];- if (was !== now) throw Error(`the delivery file has ${now} triangles, not ${was}`);+ const [was, now] = [materialsOf(saved), materialsOf(delivered)];+ for (const [name, definition] of was) if (now.get(name) !== definition) throw Error(`the delivery file changes the material ${name}`);+ if (was.size !== now.size) throw Error('the delivery file has other materials');+ const [trianglesWere, trianglesNow] = [inspectGlb(saved).triangles, inspectGlb(delivered).triangles];+ if (trianglesWere !== trianglesNow) throw Error(`the delivery file has ${trianglesNow} triangles, not ${trianglesWere}`);return delivered;}+/** Each named node that is not a mesh part, by name, in file order, with its parent's name. */+function byName(gltf) {+ const parentOf = new Map();+ gltf.nodes.forEach((node, index) => (node.children ?? []).forEach((child) => parentOf.set(child, index)));+ const names = new Map();+ gltf.nodes.forEach((node, index) => {+ if (node.mesh !== undefined || !node.name) return;+ const up = parentOf.get(index);+ const parent = up === undefined ? '(the scene)' : (gltf.nodes[up].name ?? `node ${up}`);+ names.set(node.name, [...(names.get(node.name) ?? []), { node, parent }]);+ });+ return names;+}++/** Whether two nodes sit in the same place under their parents, to within float rounding. */+function samePlace(a, b) {+ const place = (node) =>+ node.matrix ?? [...(node.translation ?? [0, 0, 0]), ...(node.rotation ?? [0, 0, 0, 1]), ...(node.scale ?? [1, 1, 1])];+ const [p, q] = [place(a), place(b)];+ return p.length === q.length && p.every((value, i) => Math.abs(value - q[i]) <= 1e-6 * Math.max(1, Math.abs(value)));+}++/** The names of the nodes any clip moves. */+function movedByClips(gltf) {+ return new Set((gltf.animations ?? []).flatMap((clip) => clip.channels.map((channel) => gltf.nodes[channel.target.node]?.name)).filter(Boolean));+}++/** Whether a node of this name has mesh parts beneath it. */+function carriesParts(gltf, name) {+ const below = (index) => (gltf.nodes[index].children ?? []).some((child) => gltf.nodes[child].mesh !== undefined || below(child));+ return gltf.nodes.some((node, index) => node.name === name && below(index));+}++/** The names of the nodes that move parts: those with meshes beneath them, and the joints of a skin a mesh uses. */+function carriersOf(gltf) {+ const carriers = new Set(gltf.nodes.filter((node) => node.name && carriesParts(gltf, node.name)).map((node) => node.name));+ const used = new Set(gltf.nodes.filter((node) => node.mesh !== undefined && node.skin !== undefined).map((node) => node.skin));+ for (const skin of used) for (const joint of gltf.skins[skin].joints) if (gltf.nodes[joint].name) carriers.add(gltf.nodes[joint].name);+ return carriers;+}++/** Every material by name, in full, with each texture named by its image's bytes rather than its place in the file. */+function materialsOf(bytes) {+ const { gltf } = openGlb(bytes);+ const bin = bytes.subarray(20 + bytes.readUInt32LE(12) + 8);+ const image = (texture) => {+ const source = gltf.images?.[gltf.textures?.[texture]?.source];+ const view = source && gltf.bufferViews[source.bufferView];+ return view ? hash(bin.subarray(view.byteOffset ?? 0, (view.byteOffset ?? 0) + view.byteLength)) : (source?.uri ?? `texture ${texture}`);+ };+ const named = (value) => {+ if (Array.isArray(value)) return value.map(named);+ if (!value || typeof value !== 'object') return value;+ return Object.fromEntries(+ Object.entries(value)+ .sort(([a], [b]) => a.localeCompare(b))+ .map(([key, inner]) => [key, /Texture$/.test(key) && typeof inner?.index === 'number' ? named({ ...inner, index: image(inner.index) }) : named(inner)]),+ );+ };+ return new Map((gltf.materials ?? []).map((material) => [material.name, JSON.stringify(named(material))]));+}+/** Every mesh node in a GLB by name, with where it sits in the world and a digest of its vertex positions alone: baked colours may share the buffer. */function placedMeshes(bytes) {const { gltf } = openGlb(bytes);@@ -342,7 +425,7 @@ async function stageSubject(run, subject) {}const diffAt = plan.steps.findIndex((step) => step.id === plan.diffStep);const model = plan.delivery- ? checkDelivery(glbs.at(-1), await readFile(join(directory, plan.delivery.file)), plan.delivery.madeFrom)+ ? checkDelivery(glbs.at(-1), await readFile(join(directory, plan.delivery.file)), plan.delivery.madeFrom, { drops: plan.delivery.drops }): glbs.at(-1);const { triangles } = inspectGlb(model);return {diff --git a/site/scripts/text-to-3d-delivery.test.ts b/site/scripts/text-to-3d-delivery.test.tsindex 6808d41e..35b99b15 100644--- a/site/scripts/text-to-3d-delivery.test.ts+++ b/site/scripts/text-to-3d-delivery.test.ts@@ -1,5 +1,6 @@import { expect, test } from 'bun:test';import { createHash } from 'node:crypto';+import { inspectGlb } from './generate-commons.mjs';import { checkDelivery } from './stage-text-to-3d.mjs';/** A GLB from a glTF record and its one binary chunk. */@@ -20,8 +21,21 @@ function glb(gltf: object, bin: Buffer): Buffer {return Buffer.concat([header, chunk(json, 0x4e4f534a), chunk(body, 0x004e4942)]);}-/** One triangle under a joint that a clip turns: as saved, with a mesh node per part, or delivered skinned. */-function model({ skinned = false, joint = 'Joint_Knee', turn = 0.5, triangles = 1, aimAt = 'Joint_Hip' } = {}) {+/**+ * One triangle under a joint that a clip turns: as saved, with a mesh node per part, or delivered skinned. `skinJoint`+ * is the node the skin binds the triangle to; null leaves the merged mesh unskinned, so nothing carries it.+ */+function model({+ skinned = false,+ joint = 'Joint_Knee',+ turn = 0.5,+ triangles = 1,+ aimAt = 'Joint_Hip',+ skinJoint = 2 as number | null,+ kneeAt = [0, 0.5, 0],+ material = { name: 'Gunmetal' } as Record<string, unknown>,+ socketNote = 'muzzle',+} = {}) {const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]);const indices = new Uint16Array(Array.from({ length: triangles * 3 }, (_, i) => i % 3));const times = new Float32Array([0, 1]);@@ -34,18 +48,25 @@ function model({ skinned = false, joint = 'Joint_Knee', turn = 0.5, triangles =offset += part.length + ((4 - (part.length % 4)) % 4);}const bin = Buffer.concat(parts.map((part) => Buffer.concat([part, Buffer.alloc((4 - (part.length % 4)) % 4)])));+ // Two sockets share a name, as repeated parts do; three's getObjectByName answers with the first.+ const sockets = [+ { name: 'Socket', extras: { role: socketNote } },+ { name: 'Socket', extras: { role: 'exhaust' } },+ ];const nodes = skinned? [- { name: 'Walker', children: [1, 2, 3], extras: { rig: { clip: 'Walk' } } },+ { name: 'Walker', children: [1, 2, 3, 4, 5], extras: { rig: { clip: 'Walk' } } },{ name: 'Joint_Hip' },- { name: joint, extras: { aimAt } },- { name: 'Walker_Body', mesh: 0 },+ { name: joint, extras: { aimAt }, translation: kneeAt },+ { name: 'Walker_Body', mesh: 0, ...(skinJoint === null ? {} : { skin: 0 }) },+ ...sockets,]: [- { name: 'Walker', children: [1, 2], extras: { rig: { clip: 'Walk' } } },+ { name: 'Walker', children: [1, 2, 4, 5], extras: { rig: { clip: 'Walk' } } },{ name: 'Joint_Hip' },- { name: joint, extras: { aimAt }, children: [3] },+ { name: joint, extras: { aimAt }, translation: kneeAt, children: [3] },{ name: 'Mesh_Shin_steel', mesh: 0 },+ ...sockets,];return glb({@@ -53,8 +74,9 @@ function model({ skinned = false, joint = 'Joint_Knee', turn = 0.5, triangles =scene: 0,scenes: [{ nodes: [0] }],nodes,+ ...(skinned && skinJoint !== null ? { skins: [{ joints: [skinJoint] }] } : {}),meshes: [{ primitives: [{ attributes: { POSITION: 0 }, indices: 1, material: 0 }] }],- materials: [{ name: 'Gunmetal' }],+ materials: [material],buffers: [{ byteLength: bin.length }],bufferViews: views,accessors: [@@ -96,3 +118,78 @@ test('a delivery file whose clip moves differently is refused', () => {test('a delivery file with other triangles is refused', () => {expect(() => checkDelivery(saved, model({ skinned: true, triangles: 2 }), madeFrom)).toThrow(/triangles/);});++test('a delivery file whose parts no longer follow a joint the clip moves is refused', () => {+ // Merged but unskinned: the joint keeps its clip and name, and moves nothing.+ expect(() => checkDelivery(saved, model({ skinned: true, skinJoint: null }), madeFrom)).toThrow(/Joint_Knee.*parts/);+ // Skinned to the wrong joint: the knee's parts ride the hip.+ expect(() => checkDelivery(saved, model({ skinned: true, skinJoint: 1 }), madeFrom)).toThrow(/Joint_Knee.*parts/);+});++test('a delivery file that moves or reparents a named node is refused', () => {+ expect(() => checkDelivery(saved, model({ skinned: true, kneeAt: [0, 0.6, 0] }), madeFrom)).toThrow(/Joint_Knee/);+});++test('a delivery file whose materials differ beyond their names is refused', () => {+ const glowing = { name: 'Gunmetal', emissiveFactor: [1, 0.4, 0] };+ expect(() => checkDelivery(model({ material: glowing }), model({ skinned: true }), madeFromOf(model({ material: glowing })))).toThrow(/Gunmetal/);+});++test('a delivery file is compared on every node of a repeated name, in order', () => {+ expect(() => checkDelivery(saved, model({ skinned: true, socketNote: 'exhaust' }), madeFrom)).toThrow(/Socket/);+});++test('a grouping node the record lets the delivery drop may go, and one code can reach for may not', () => {+ // The knee carries notes and the clip moves it, so naming it in drops does not let it go.+ const renamed = model({ skinned: true, joint: 'Joint_Shin' });+ expect(() => checkDelivery(saved, renamed, madeFrom, { drops: ['Joint_Knee'] })).toThrow(/may not drop Joint_Knee/);+ expect(() => checkDelivery(saved, renamed, madeFrom, { drops: ['Joint_Hip'] })).toThrow(/Joint_Knee/);+});++test('a delivery file without a grouping node it names in drops is served', () => {+ const hipless = Buffer.from(model({ skinned: true }));+ const { gltf, bin } = splitGlb(hipless);+ gltf.nodes[1].name = 'Unnamed';+ const withoutHip = glb(gltf, bin);+ const base = Buffer.from(saved);+ expect(checkDelivery(base, withoutHip, madeFrom, { drops: ['Joint_Hip'] })).toBe(withoutHip);+ expect(() => checkDelivery(base, withoutHip, madeFrom)).toThrow(/Joint_Hip/);+});++test('an instanced batch counts a triangle and a place for every copy', () => {+ // One triangle drawn three times by EXT_mesh_gpu_instancing, the copies 10 m apart along x.+ const positions = Buffer.from(new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]).buffer);+ const offsets = Buffer.from(new Float32Array([0, 0, 0, 10, 0, 0, 20, 0, 0]).buffer);+ const batched = glb(+ {+ asset: { version: '2.0' },+ extensionsUsed: ['EXT_mesh_gpu_instancing'],+ scene: 0,+ scenes: [{ nodes: [0] }],+ nodes: [{ mesh: 0, extensions: { EXT_mesh_gpu_instancing: { attributes: { TRANSLATION: 1 } } } }],+ meshes: [{ primitives: [{ attributes: { POSITION: 0 } }] }],+ buffers: [{ byteLength: 72 }],+ bufferViews: [+ { buffer: 0, byteOffset: 0, byteLength: 36 },+ { buffer: 0, byteOffset: 36, byteLength: 36 },+ ],+ accessors: [+ { bufferView: 0, componentType: 5126, count: 3, type: 'VEC3', min: [0, 0, 0], max: [1, 1, 0] },+ { bufferView: 1, componentType: 5126, count: 3, type: 'VEC3' },+ ],+ },+ Buffer.concat([positions, offsets]),+ );+ const facts = inspectGlb(batched);+ expect(facts.triangles).toBe(3);+ expect(facts.boundsMax[0]).toBe(21);+});++function splitGlb(bytes: Buffer) {+ const length = bytes.readUInt32LE(12);+ return { gltf: JSON.parse(bytes.subarray(20, 20 + length).toString('utf8')), bin: bytes.subarray(20 + length + 8) };+}++function madeFromOf(bytes: Buffer) {+ return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;+}