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
/** Bounded, advisory draw analysis. Never mutates geometry or supplies QA acceptance evidence. */
import { type Document, type Node, Primitive } from '@gltf-transform/core';
import { cloneDocument } from '@gltf-transform/functions';
import * as THREE from 'three';
import { createGltfIO } from './gltf-io';
import { isHiddenGltfNode } from './metrics';
import { findRigidBoundaries, mergeRigidGroups } from './rigid-merge';
const MAX_NODES = 2048;
const MAX_USES = 256;
const MAX_VERTICES = 262_144;
const MAX_BYTES = 32 * 1024 * 1024;
const MAX_ANCHORS = 16;
const MAX_SAMPLES = 256;
const MAX_FINDINGS = 4;
const SCOPE =
'Static single-pass primitive draws across document scenes, respecting node visibility. Excludes culling, alternate LOD selections, shadow, reflection and depth passes, and renderer-specific extra passes; GPU instances count once per primitive. IDs use scene/node indices; names are bounded labels.';
const METHOD =
'Current rigid-merge policy on a bounded clone with existing materials: includes layouts, boundaries, locks, shared-byte budget and vertex splits. Excludes palette consolidation and instancing; not a full-mode or GPU performance prediction.';
interface PartRef {
id: string;
name: string;
}
interface Anchor extends PartRef {
draws: number;
afterRigidMerge: number;
}
export interface DrawDiagnostics {
version: 'kiln.draw-diagnostics.v1';
status: 'assessed' | 'skipped';
scope: string;
reason?: 'input-limit' | 'unreadable-glb' | 'analysis-failed';
currentDraws?: number;
mergeEstimate?: {
method: string;
draws: number;
saved: number;
rejectedBuckets: number;
skipped?: string;
};
anchors?: { total: number; omitted: number; items: Anchor[] };
observations?: {
mirroredTangents: { count: number; omitted: number; parts: PartRef[]; evidence: string };
coplanarParts: {
sampledTriangles: number;
eligibleTriangles: number;
unexaminedPrimitiveUses: number;
candidatePairs: number;
omitted: number;
candidates: { parts: [PartRef, PartRef] }[];
evidence: string;
};
};
}
interface Use {
node: Node;
primitive: Primitive;
part: PartRef;
}
const nameOf = (name: string) => (name.length <= 80 ? name : `${name.slice(0, 79)}…`);
const skipped = (reason: DrawDiagnostics['reason']): DrawDiagnostics => ({
version: 'kiln.draw-diagnostics.v1',
status: 'skipped',
scope: SCOPE,
reason,
});
/** Bound clone/bake work by stored resources and placed uses, including invisible geometry. */
function withinLimits(doc: Document): boolean {
const root = doc.getRoot();
if (
root.listNodes().length > MAX_NODES ||
root.listAccessors().length > 4096 ||
root.listMaterials().length > 2048 ||
root.listTextures().length > 256 ||
root.listScenes().length > 32 ||
doc.getGraph().listEdges().length > 32768
)
return false;
let bytes =
root.listAccessors().reduce((n, a) => n + (a.getArray()?.byteLength ?? 0), 0) +
root.listTextures().reduce((n, t) => n + (t.getImage()?.byteLength ?? 0), 0);
let uses = 0;
let vertices = 0;
const walk = (node: Node, depth: number): boolean => {
if (depth > 128) return false;
for (const p of node.getMesh()?.listPrimitives() ?? []) {
uses++;
vertices += p.getAttribute('POSITION')?.getCount() ?? 0;
bytes +=
p.listAttributes().reduce((n, a) => n + (a.getArray()?.byteLength ?? 0), 0) +
(p.getIndices()?.getArray()?.byteLength ?? 0);
}
return (
uses <= MAX_USES &&
vertices <= MAX_VERTICES &&
bytes <= MAX_BYTES &&
node.listChildren().every((n) => walk(n, depth + 1))
);
};
return (
bytes <= MAX_BYTES && root.listScenes().every((s) => s.listChildren().every((n) => walk(n, 0)))
);
}
function collect(doc: Document, keep: readonly string[]) {
const root = doc.getRoot();
const boundaries = findRigidBoundaries(doc, new Set(keep));
const nodeIds = new Map(root.listNodes().map((n, i) => [n, i]));
const anchors = new Map<string, Anchor>();
const uses: Use[] = [];
for (const [sceneIndex, scene] of root.listScenes().entries()) {
const id = `scene:${sceneIndex}`;
const initial = { id, name: nameOf(scene.getName() || 'Scene'), draws: 0, afterRigidMerge: 0 };
anchors.set(id, initial);
const walk = (node: Node, anchor: Anchor): void => {
if (isHiddenGltfNode(node)) return;
const part = { id: `${id}/node:${nodeIds.get(node)}`, name: nameOf(node.getName()) };
if (boundaries.has(node)) {
anchor = { ...part, draws: 0, afterRigidMerge: 0 };
anchors.set(part.id, anchor);
}
for (const primitive of node.getMesh()?.listPrimitives() ?? []) {
anchor.draws++;
uses.push({ node, primitive, part });
}
for (const child of node.listChildren()) walk(child, anchor);
};
for (const child of scene.listChildren()) walk(child, initial);
}
return { anchors, uses };
}
interface Sample {
points: THREE.Vector3[];
normal: THREE.Vector3;
bounds: THREE.Box3;
part: PartRef;
}
type Point2 = [number, number];
const cross2 = (a: Point2, b: Point2, p: Point2) =>
(b[0] - a[0]) * (p[1] - a[1]) - (b[1] - a[1]) * (p[0] - a[0]);
/** Positive projected overlap excludes mere shared edges and vertices. */
function overlaps(a: Sample, b: Sample): boolean {
if (Math.abs(a.normal.dot(b.normal)) < 1 - 1e-8 || !a.bounds.intersectsBox(b.bounds))
return false;
const tolerance =
Math.max(
a.bounds.getSize(new THREE.Vector3()).length(),
b.bounds.getSize(new THREE.Vector3()).length(),
1e-12,
) * 1e-6;
if (b.points.some((p) => Math.abs(a.normal.dot(p.clone().sub(a.points[0]!))) > tolerance))
return false;
const normal = a.normal.toArray().map(Math.abs);
const drop = normal.indexOf(Math.max(...normal));
const project = (p: THREE.Vector3): Point2 => p.toArray().filter((_, i) => i !== drop) as Point2;
const clip = a.points.map(project);
if (cross2(clip[0]!, clip[1]!, clip[2]!) < 0) clip.reverse();
let polygon = b.points.map(project);
for (let i = 0; i < 3 && polygon.length; i++) {
const x = clip[i]!,
y = clip[(i + 1) % 3]!;
const output: Point2[] = [];
for (let j = 0; j < polygon.length; j++) {
const p = polygon[j]!,
q = polygon[(j + 1) % polygon.length]!;
const dp = cross2(x, y, p),
dq = cross2(x, y, q);
if (dp >= 0) output.push(p);
if (dp >= 0 !== dq >= 0) {
const t = dp / (dp - dq);
output.push([p[0] + t * (q[0] - p[0]), p[1] + t * (q[1] - p[1])]);
}
}
polygon = output;
}
let area = 0;
for (let i = 0; i < polygon.length; i++) {
const p = polygon[i]!,
q = polygon[(i + 1) % polygon.length]!;
area += p[0] * q[1] - p[1] * q[0];
}
return Math.abs(area) / 2 > tolerance * tolerance;
}
function observe(uses: Use[]): NonNullable<DrawDiagnostics['observations']> {
const mirrored = new Map<string, PartRef>();
const samples: Sample[] = [];
let eligibleTriangles = 0;
let unexaminedPrimitiveUses = 0;
for (const { node, primitive, part } of uses) {
if (
node.getSkin() ||
node.getExtension('EXT_mesh_gpu_instancing') ||
primitive.listTargets().length
) {
unexaminedPrimitiveUses++;
continue;
}
const matrix = new THREE.Matrix4().fromArray(node.getWorldMatrix());
if (primitive.getAttribute('TANGENT') && matrix.determinant() < 0) mirrored.set(part.id, part);
const position = primitive.getAttribute('POSITION');
if (!position || primitive.getMode() !== Primitive.Mode.TRIANGLES) {
unexaminedPrimitiveUses++;
continue;
}
const indices = primitive.getIndices();
const count = Math.floor((indices?.getCount() ?? position.getCount()) / 3);
eligibleTriangles += count;
const amount = Math.min(count, 8, MAX_SAMPLES - samples.length);
for (let i = 0; i < amount; i++) {
const start = Math.floor((i * count) / amount) * 3;
const points = [0, 1, 2].map((j) =>
new THREE.Vector3()
.fromArray(position.getElement(indices ? indices.getScalar(start + j) : start + j, []))
.applyMatrix4(matrix),
);
const normal = points[1]!.clone().sub(points[0]!).cross(points[2]!.clone().sub(points[0]!));
if (!Number.isFinite(normal.lengthSq()) || normal.lengthSq() === 0) continue;
samples.push({
points,
normal: normal.normalize(),
bounds: new THREE.Box3().setFromPoints(points),
part,
});
}
}
const pairs = new Map<string, { parts: [PartRef, PartRef] }>();
for (let i = 0; i < samples.length; i++)
for (let j = i + 1; j < samples.length; j++) {
const a = samples[i]!,
b = samples[j]!;
if (a.part.id === b.part.id || a.part.id.split('/')[0] !== b.part.id.split('/')[0]) continue;
const key = [a.part.id, b.part.id].sort().join('|');
if (!pairs.has(key) && overlaps(a, b)) pairs.set(key, { parts: [a.part, b.part] });
}
return {
mirroredTangents: {
count: mirrored.size,
omitted: Math.max(0, mirrored.size - MAX_FINDINGS),
parts: [...mirrored.values()].slice(0, MAX_FINDINGS),
evidence:
'Visible static nodes with tangent attributes and negative world determinant; not proof of a shading defect. Skinned, morphed and GPU-instanced uses are not assessed.',
},
coplanarParts: {
sampledTriangles: samples.length,
eligibleTriangles,
unexaminedPrimitiveUses,
candidatePairs: pairs.size,
omitted: Math.max(0, pairs.size - MAX_FINDINGS),
candidates: [...pairs.values()].slice(0, MAX_FINDINGS),
evidence:
'Sampled overlapping coplanar triangles in separate static nodes; not proof of visible z-fighting. At most 8 triangles per primitive and 256 total; unexamined faces may contain other candidates.',
},
};
}
/** Same-material merge estimate only; byte limits return an explicit skipped assessment. */
export function analyzeDrawDiagnostics(
doc: Document,
options: { keep?: readonly string[] } = {},
): DrawDiagnostics {
try {
if (!withinLimits(doc)) return skipped('input-limit');
const keep = options.keep ?? [];
const before = collect(doc, keep);
const copy = cloneDocument(doc);
const merge = mergeRigidGroups(copy, { keep });
const after = collect(copy, keep);
const all = [...before.anchors.values()].map((anchor) => ({
...anchor,
afterRigidMerge: after.anchors.get(anchor.id)?.draws ?? 0,
}));
const currentDraws = before.uses.length;
return {
version: 'kiln.draw-diagnostics.v1',
status: 'assessed',
scope: SCOPE,
currentDraws,
mergeEstimate: {
method: METHOD,
draws: after.uses.length,
saved: currentDraws - after.uses.length,
rejectedBuckets: merge.rejected.length,
...(merge.skipped ? { skipped: merge.skipped } : {}),
},
anchors: {
total: all.length,
omitted: Math.max(0, all.length - MAX_ANCHORS),
items: all.slice(0, MAX_ANCHORS),
},
observations: observe(before.uses),
};
} catch {
return skipped('analysis-failed');
}
}
/** Best-effort diagnostics for exact delivery bytes; unsupported GLBs still remain exportable. */
export async function inspectDrawDiagnostics(
bytes: Uint8Array,
options: { keep?: readonly string[] } = {},
): Promise<DrawDiagnostics> {
if (bytes.byteLength > MAX_BYTES) return skipped('input-limit');
try {
const io = createGltfIO();
const json = await io.binaryToJSON(bytes);
let expandedBytes = 0;
let compressed = false;
// The extension allocates count * byteStride before invoking its decoder. Bound
// that allocation before readJSON, rather than only inspecting the decoded document.
for (const view of json.json.bufferViews ?? []) {
const extension = view.extensions?.['EXT_meshopt_compression'] as
| { count?: number; byteStride?: number }
| undefined;
compressed ||= extension !== undefined;
const length = extension
? (extension.count ?? Number.NaN) * (extension.byteStride ?? Number.NaN)
: view.byteLength;
if (!Number.isSafeInteger(length) || length < 0) return skipped('unreadable-glb');
expandedBytes += length;
if (expandedBytes > MAX_BYTES) return skipped('input-limit');
}
if (compressed) {
// Decoder ownership stays with this host diagnostic, not every deterministic
// engine reader. No network, renderer or provider is involved.
const { MeshoptDecoder } = await import('meshoptimizer');
await MeshoptDecoder.ready;
io.registerDependencies({ 'meshopt.decoder': MeshoptDecoder });
}
return analyzeDrawDiagnostics(await io.readJSON(json), options);
} catch {
return skipped('unreadable-glb');
}
}