Skip to content

armgit / kiln

Public Imported from GitHub
0

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.

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.mjs
index 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.mjs
index 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.ts
index 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')}`;
+}