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
/**
* Delivery facts read from a written GLB alone (delivery contract item 1).
*
* Walks the default scene once, depth first, and lists every collider proxy, anchor, kit
* module and port by its semantic role, with the inspection path `kiln_inspect` lists and the
* node transform relative to the asset root. Lower `MSFT_lod` levels sit outside the scene
* and are not reached. The diagnostics are advisory and never QA acceptance: a proxy that
* draws, leaves the drawn bounds or touches no drawn triangle; a port outside its module's
* footprint; an anchor with children.
*/
import type { Document, Node as GltfNode } from '@gltf-transform/core';
import type { InstancedMesh } from '@gltf-transform/extensions';
import * as THREE from 'three';
import { PropertyType } from '@gltf-transform/core';
import type {
DeliveryAnchorV1,
DeliveryColliderV1,
DeliveryDiagnosticV1,
DeliveryKitModuleV1,
DeliveryPortV1,
DeliveryTransformV1,
DeliveryVertexAttributeV1,
} from './contracts/integration';
import { type Lod, MSFT_LOD } from './gltf-io';
import { KILN_SEMANTIC_ROLES, readSemanticMetadataV1FromExtras } from './contracts/semantic';
import { KILN_KIT_KEY, kitModuleExtras } from './delivery';
import { isHiddenGltfNode } from './metrics';
import { drawnSceneBounds } from './node-visibility';
/** Upper bound on collider-triangle overlap tests before the check reports itself unmeasured. */
export const DELIVERY_OVERLAP_TEST_LIMIT = 50_000_000;
export interface DeliverySummary {
colliders: DeliveryColliderV1[];
anchors: DeliveryAnchorV1[];
kit?: DeliveryKitModuleV1;
ports: DeliveryPortV1[];
diagnostics: DeliveryDiagnosticV1[];
}
interface Visited {
node: GltfNode;
path: string;
roles: string[];
hidden: boolean;
/** Path of the nearest kit module at or above this node. */
module?: { node: GltfNode; path: string };
}
const segment = (name: string, occurrence: number) => `/${encodeURIComponent(name)}[${occurrence}]`;
const roleTail = (role: string, base: string): string | undefined =>
role.startsWith(`${base}.`) ? role.slice(base.length + 1) : undefined;
function decompose(matrix: THREE.Matrix4): DeliveryTransformV1 {
const translation = new THREE.Vector3();
const rotation = new THREE.Quaternion();
const scale = new THREE.Vector3();
matrix.decompose(translation, rotation, scale);
const clean = (value: number) => (Object.is(value, -0) ? 0 : value);
return {
translation: translation.toArray().map(clean) as [number, number, number],
rotation: rotation.toArray().map(clean) as [number, number, number, number],
scale: scale.toArray().map(clean) as [number, number, number],
};
}
const worldMatrix = (node: GltfNode) => new THREE.Matrix4().fromArray(node.getWorldMatrix());
/** World triangles of every drawn mesh outside collider proxies, instance copies included. */
function drawnTriangles(visited: readonly Visited[]): Float64Array {
const values: number[] = [];
const local = [0, 0, 0];
const point = new THREE.Vector3();
for (const { node, roles, hidden } of visited) {
const mesh = node.getMesh();
if (!mesh || hidden || roles.some((role) => role.startsWith('collider.'))) continue;
const base = worldMatrix(node);
const instances = node.getExtension<InstancedMesh>('EXT_mesh_gpu_instancing');
const translation = instances?.getAttribute('TRANSLATION');
const rotation = instances?.getAttribute('ROTATION');
const scale = instances?.getAttribute('SCALE');
const copies = translation?.getCount() ?? rotation?.getCount() ?? scale?.getCount() ?? 1;
const matrices: THREE.Matrix4[] = [];
for (let i = 0; i < copies; i++) {
const instance = new THREE.Matrix4().compose(
new THREE.Vector3().fromArray(translation?.getElement(i, []) ?? [0, 0, 0]),
new THREE.Quaternion().fromArray(rotation?.getElement(i, []) ?? [0, 0, 0, 1]),
new THREE.Vector3().fromArray(scale?.getElement(i, []) ?? [1, 1, 1]),
);
matrices.push(base.clone().multiply(instance));
}
for (const primitive of mesh.listPrimitives()) {
if (primitive.getMode() !== 4) continue;
const position = primitive.getAttribute('POSITION');
if (!position) continue;
const indices = primitive.getIndices();
const count = indices ? indices.getCount() : position.getCount();
for (const matrix of matrices)
for (let i = 0; i + 2 < count; i += 3)
for (let k = 0; k < 3; k++) {
position.getElement(indices ? indices.getScalar(i + k) : i + k, local);
point.fromArray(local).applyMatrix4(matrix);
values.push(point.x, point.y, point.z);
}
}
}
return Float64Array.from(values);
}
/** Separating-axis test of a triangle against the box [-h, h] centred at the origin. */
function triangleOverlapsBox(
a: THREE.Vector3,
b: THREE.Vector3,
c: THREE.Vector3,
h: THREE.Vector3,
tolerance: number,
): boolean {
const verts = [a, b, c];
const he = [h.x + tolerance, h.y + tolerance, h.z + tolerance];
for (let axis = 0; axis < 3; axis++) {
const values = verts.map((v) => v.getComponent(axis));
if (Math.min(...values) > he[axis]! || Math.max(...values) < -he[axis]!) return false;
}
const e = [
new THREE.Vector3().subVectors(b, a),
new THREE.Vector3().subVectors(c, b),
new THREE.Vector3().subVectors(a, c),
];
const normal = new THREE.Vector3().crossVectors(e[0]!, e[1]!);
const axes: THREE.Vector3[] = [normal];
const units = [
new THREE.Vector3(1, 0, 0),
new THREE.Vector3(0, 1, 0),
new THREE.Vector3(0, 0, 1),
];
for (const unit of units)
for (const edge of e) axes.push(new THREE.Vector3().crossVectors(unit, edge));
for (const axis of axes) {
if (axis.lengthSq() < 1e-24) continue;
const projections = verts.map((v) => v.dot(axis));
const radius =
he[0]! * Math.abs(axis.x) + he[1]! * Math.abs(axis.y) + he[2]! * Math.abs(axis.z);
if (Math.min(...projections) > radius || Math.max(...projections) < -radius) return false;
}
return true;
}
/** Closest point on triangle abc to p (Ericson, Real-Time Collision Detection 5.1.5). */
function closestPointOnTriangle(
p: THREE.Vector3,
a: THREE.Vector3,
b: THREE.Vector3,
c: THREE.Vector3,
): THREE.Vector3 {
const ab = new THREE.Vector3().subVectors(b, a);
const ac = new THREE.Vector3().subVectors(c, a);
const ap = new THREE.Vector3().subVectors(p, a);
const d1 = ab.dot(ap);
const d2 = ac.dot(ap);
if (d1 <= 0 && d2 <= 0) return a.clone();
const bp = new THREE.Vector3().subVectors(p, b);
const d3 = ab.dot(bp);
const d4 = ac.dot(bp);
if (d3 >= 0 && d4 <= d3) return b.clone();
const vc = d1 * d4 - d3 * d2;
if (vc <= 0 && d1 >= 0 && d3 <= 0) return a.clone().addScaledVector(ab, d1 / (d1 - d3));
const cp = new THREE.Vector3().subVectors(p, c);
const d5 = ab.dot(cp);
const d6 = ac.dot(cp);
if (d6 >= 0 && d5 <= d6) return c.clone();
const vb = d5 * d2 - d1 * d6;
if (vb <= 0 && d2 >= 0 && d6 <= 0) return a.clone().addScaledVector(ac, d2 / (d2 - d6));
const va = d3 * d6 - d5 * d4;
if (va <= 0 && d4 - d3 >= 0 && d5 - d6 >= 0)
return b
.clone()
.addScaledVector(new THREE.Vector3().subVectors(c, b), (d4 - d3) / (d4 - d3 + (d5 - d6)));
const denominator = 1 / (va + vb + vc);
return a
.clone()
.addScaledVector(ab, vb * denominator)
.addScaledVector(ac, vc * denominator);
}
/** Squared distance between segments p1q1 and p2q2 (Ericson 5.1.9). */
function segmentSegmentDistanceSq(
p1: THREE.Vector3,
q1: THREE.Vector3,
p2: THREE.Vector3,
q2: THREE.Vector3,
): number {
const d1 = new THREE.Vector3().subVectors(q1, p1);
const d2 = new THREE.Vector3().subVectors(q2, p2);
const r = new THREE.Vector3().subVectors(p1, p2);
const a = d1.dot(d1);
const e = d2.dot(d2);
const f = d2.dot(r);
let s = 0;
let t = 0;
if (a <= 1e-24 && e <= 1e-24) return r.lengthSq();
if (a <= 1e-24) t = THREE.MathUtils.clamp(f / e, 0, 1);
else {
const c = d1.dot(r);
if (e <= 1e-24) s = THREE.MathUtils.clamp(-c / a, 0, 1);
else {
const b = d1.dot(d2);
const denominator = a * e - b * b;
s = denominator !== 0 ? THREE.MathUtils.clamp((b * f - c * e) / denominator, 0, 1) : 0;
t = (b * s + f) / e;
if (t < 0) {
t = 0;
s = THREE.MathUtils.clamp(-c / a, 0, 1);
} else if (t > 1) {
t = 1;
s = THREE.MathUtils.clamp((b - c) / a, 0, 1);
}
}
}
const c1 = p1.clone().addScaledVector(d1, s);
const c2 = p2.clone().addScaledVector(d2, t);
return c1.distanceToSquared(c2);
}
/** Whether segment pq passes through triangle abc. */
function segmentCrossesTriangle(
p: THREE.Vector3,
q: THREE.Vector3,
a: THREE.Vector3,
b: THREE.Vector3,
c: THREE.Vector3,
): boolean {
const hit = new THREE.Vector3();
const ray = new THREE.Ray(p, new THREE.Vector3().subVectors(q, p));
const length = ray.direction.length();
if (length === 0) return false;
ray.direction.divideScalar(length);
return ray.intersectTriangle(a, b, c, false, hit) !== null && hit.distanceTo(p) <= length;
}
/** Whether triangle abc comes within `radius` of segment pq. */
function triangleTouchesCapsule(
a: THREE.Vector3,
b: THREE.Vector3,
c: THREE.Vector3,
p: THREE.Vector3,
q: THREE.Vector3,
radius: number,
): boolean {
const r2 = radius * radius;
if (closestPointOnTriangle(p, a, b, c).distanceToSquared(p) <= r2) return true;
if (closestPointOnTriangle(q, a, b, c).distanceToSquared(q) <= r2) return true;
for (const [s, e] of [
[a, b],
[b, c],
[c, a],
] as const)
if (segmentSegmentDistanceSq(p, q, s, e) <= r2) return true;
return segmentCrossesTriangle(p, q, a, b, c);
}
/**
* Custom (underscore) vertex attributes on every mesh reachable from the default scene,
* lower `MSFT_lod` levels included, grouped by attribute name and recorded bake parameters
* (mesh extras `kilnSurfaceBakeV1`). Paths are inspection paths; a lower level takes the
* path it has in its LOD0's place.
*/
/**
* Delivery path of every node in the default scene, the same paths the manifest uses:
* `/<scene>[0]/<name>[occurrence]/...` with each name URI-encoded.
*/
export function deliveryNodePaths(doc: Document): Map<GltfNode, string> {
const paths = new Map<GltfNode, string>();
const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0];
if (!scene) return paths;
const visit = (siblings: readonly GltfNode[], parentPath: string): void => {
const seen = new Map<string, number>();
for (const node of siblings) {
const name = node.getName();
const occurrence = seen.get(name) ?? 0;
seen.set(name, occurrence + 1);
const path = `${parentPath}${segment(name, occurrence)}`;
paths.set(node, path);
visit(node.listChildren(), path);
}
};
visit(scene.listChildren(), segment(scene.getName() || 'Scene', 0));
return paths;
}
export function summarizeVertexAttributes(doc: Document): DeliveryVertexAttributeV1[] {
const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0];
if (!scene) return [];
const groups = new Map<string, DeliveryVertexAttributeV1>();
const order: string[] = [];
const record = (node: GltfNode, path: string) => {
const mesh = node.getMesh();
if (!mesh) return;
const bake = (mesh.getExtras() as Record<string, unknown>).kilnSurfaceBakeV1 as
| Record<string, Record<string, number>>
| undefined;
const names = new Set<string>();
for (const primitive of mesh.listPrimitives())
for (const semantic of primitive.listSemantics())
if (semantic.startsWith('_')) names.add(semantic);
for (const name of names) {
const params = bake && typeof bake === 'object' ? bake[name] : undefined;
const key = `${name}\u0000${JSON.stringify(params ?? null)}`;
let group = groups.get(key);
if (!group) {
group = { name, meshes: [], ...(params ? { params: { ...params } } : {}) };
groups.set(key, group);
order.push(key);
}
if (!group.meshes.includes(path)) group.meshes.push(path);
}
};
const visit = (siblings: readonly GltfNode[], parentPath: string): void => {
siblings.forEach((node, index) => {
const at = (name: string) => {
let occurrence = 0;
for (let i = 0; i < index; i++) if (siblings[i]!.getName() === name) occurrence++;
return `${parentPath}${segment(name, occurrence)}`;
};
const path = at(node.getName());
record(node, path);
visit(node.listChildren(), path);
const lower = (node.getExtension<Lod>(MSFT_LOD)?.listLevels() ?? []).filter(
(level): level is GltfNode => level.propertyType === PropertyType.NODE,
);
for (const level of lower) {
const levelPath = at(level.getName());
record(level, levelPath);
visit(level.listChildren(), levelPath);
}
});
};
visit(scene.listChildren(), segment(scene.getName() || 'Scene', 0));
// Attribute name order is stable for consumers: _EDGE, _CAVITY, then others by name.
const rank = (name: string) => (name === '_EDGE' ? 0 : name === '_CAVITY' ? 1 : 2);
return order
.map((key, position) => ({ group: groups.get(key)!, position }))
.sort(
(a, b) =>
rank(a.group.name) - rank(b.group.name) ||
(rank(a.group.name) === 2 ? a.group.name.localeCompare(b.group.name) : 0) ||
a.position - b.position,
)
.map(({ group }) => group);
}
/** Every delivery record and advisory finding in the default scene of `doc`. */
export function inspectDelivery(doc: Document): DeliverySummary {
const summary: DeliverySummary = { colliders: [], anchors: [], ports: [], diagnostics: [] };
const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0];
if (!scene) return summary;
const visited: Visited[] = [];
const visit = (
siblings: readonly GltfNode[],
parentPath: string,
hidden: boolean,
module: Visited['module'],
): void => {
const seen = new Map<string, number>();
for (const node of siblings) {
const name = node.getName();
const occurrence = seen.get(name) ?? 0;
seen.set(name, occurrence + 1);
const path = `${parentPath}${segment(name, occurrence)}`;
const roles = readSemanticMetadataV1FromExtras(node.getExtras())?.roles ?? [];
const nodeHidden = hidden || isHiddenGltfNode(node);
const nodeModule = roles.includes(KILN_SEMANTIC_ROLES.kitModule) ? { node, path } : module;
visited.push({ node, path, roles, hidden: nodeHidden, module: nodeModule });
visit(node.listChildren(), path, nodeHidden, nodeModule);
}
};
visit(scene.listChildren(), segment(scene.getName() || 'Scene', 0), false, undefined);
const finding = (code: string, path: string, message: string) =>
summary.diagnostics.push({ code, path, message });
// Drawn bounds, the same measure the manifest headline uses.
const { min, max } = drawnSceneBounds(scene);
const bounds = new THREE.Box3(new THREE.Vector3(...min), new THREE.Vector3(...max));
const finiteBounds = [...min, ...max].every(Number.isFinite);
const diagonal = finiteBounds ? bounds.getSize(new THREE.Vector3()).length() : 0;
const tolerance = Math.max(1e-4, diagonal * 1e-4);
const colliderNodes: Array<{ visit: Visited; record: DeliveryColliderV1 }> = [];
for (const entry of visited) {
const { node, path, roles } = entry;
for (const role of roles) {
const matrix = worldMatrix(node);
const transform = decompose(matrix);
for (const shape of ['box', 'capsule', 'hull'] as const) {
const id = roleTail(role, `${KILN_SEMANTIC_ROLES.collider}.${shape}`);
if (id === undefined) continue;
const scale = transform.scale;
const record: DeliveryColliderV1 = {
role,
id,
path,
name: node.getName(),
transform,
shape:
shape === 'box'
? { kind: 'box', size: [...scale] }
: shape === 'capsule'
? { kind: 'capsule', radius: scale[0] / 2, height: scale[1] }
: {
kind: 'hull',
vertices:
node
.getMesh()
?.listPrimitives()
.reduce(
(sum, primitive) =>
sum + (primitive.getAttribute('POSITION')?.getCount() ?? 0),
0,
) ?? 0,
},
};
summary.colliders.push(record);
colliderNodes.push({ visit: entry, record });
}
const anchorTail = roleTail(role, KILN_SEMANTIC_ROLES.anchor);
if (anchorTail !== undefined) {
const [kind, ...rest] = anchorTail.split('.');
summary.anchors.push({
role,
kind: kind!,
id: rest.join('.'),
path,
name: node.getName(),
transform,
});
}
const portId = roleTail(role, KILN_SEMANTIC_ROLES.kitPort);
if (portId !== undefined)
summary.ports.push({
role,
id: portId,
path,
name: node.getName(),
...(entry.module && entry.module.node !== node ? { module: entry.module.path } : {}),
transform,
});
if (role === KILN_SEMANTIC_ROLES.kitModule) {
const extras = (node.getExtras() as Record<string, unknown>)[KILN_KIT_KEY];
let spec: ReturnType<typeof kitModuleExtras> | undefined;
try {
const { schemaVersion, ...rest } = (extras ?? {}) as Record<string, unknown>;
spec = schemaVersion === 1 ? kitModuleExtras(rest) : undefined;
} catch {
spec = undefined;
}
if (!spec)
finding(
'DELIVERY_KIT_INVALID',
path,
`kit module has no valid ${KILN_KIT_KEY} extras; mark it with defineModule.`,
);
else if (summary.kit)
finding(
'DELIVERY_KIT_MULTIPLE',
path,
`a GLB delivers one kit module; ${summary.kit.path} is listed and this one is not.`,
);
else
summary.kit = {
role,
path,
name: node.getName(),
footprint: spec.footprint,
height: spec.height,
snapAxis: spec.snapAxis,
origin: spec.origin,
transform,
};
}
}
}
// Collider findings, in scene order.
const triangles = colliderNodes.some(({ record }) => record.shape.kind !== 'hull')
? drawnTriangles(visited)
: new Float64Array();
const triangleCount = triangles.length / 9;
let overlapTests = 0;
const a = new THREE.Vector3();
const b = new THREE.Vector3();
const c = new THREE.Vector3();
for (const { visit: entry, record } of colliderNodes) {
if (!entry.hidden)
finding(
'DELIVERY_COLLIDER_NOT_HIDDEN',
record.path,
'collider proxy draws; hide it (the delivery helpers do) so importers that ignore roles draw only the asset.',
);
const matrix = worldMatrix(entry.node);
const proxyBounds = new THREE.Box3();
const mesh = entry.node.getMesh();
const local = [0, 0, 0];
for (const primitive of mesh?.listPrimitives() ?? []) {
const position = primitive.getAttribute('POSITION');
for (let i = 0; i < (position?.getCount() ?? 0); i++)
proxyBounds.expandByPoint(
new THREE.Vector3().fromArray(position!.getElement(i, local)).applyMatrix4(matrix),
);
}
if (proxyBounds.isEmpty())
proxyBounds.expandByPoint(new THREE.Vector3().setFromMatrixPosition(matrix));
const expanded = bounds.clone().expandByScalar(tolerance);
if (!finiteBounds || !expanded.containsBox(proxyBounds))
finding(
'DELIVERY_COLLIDER_OUTSIDE_BOUNDS',
record.path,
'collider proxy reaches outside the bounds of the drawn asset.',
);
if (record.shape.kind === 'hull') continue;
if (overlapTests + triangleCount > DELIVERY_OVERLAP_TEST_LIMIT) {
finding(
'DELIVERY_COLLIDER_OVERLAP_UNMEASURED',
record.path,
`overlap with drawn triangles was not measured: the check stops at ${DELIVERY_OVERLAP_TEST_LIMIT} collider-triangle tests.`,
);
continue;
}
overlapTests += triangleCount;
const toLocal = new THREE.Matrix4();
let touches = false;
if (record.shape.kind === 'box') {
// Unit box space: the inverse world matrix maps the box onto [-0.5, 0.5]^3.
toLocal.copy(matrix).invert();
const half = new THREE.Vector3(0.5, 0.5, 0.5);
const scale = Math.max(...record.transform.scale.map(Math.abs), 1e-9);
for (let t = 0; t < triangleCount && !touches; t++) {
a.fromArray(triangles, t * 9).applyMatrix4(toLocal);
b.fromArray(triangles, t * 9 + 3).applyMatrix4(toLocal);
c.fromArray(triangles, t * 9 + 6).applyMatrix4(toLocal);
touches = triangleOverlapsBox(a, b, c, half, tolerance / scale);
}
} else {
// Rigid capsule frame: translation and rotation only, so the radius stays metric.
const { translation, rotation } = record.transform;
toLocal
.compose(
new THREE.Vector3(...translation),
new THREE.Quaternion(...rotation),
new THREE.Vector3(1, 1, 1),
)
.invert();
const { radius, height } = record.shape;
const p = new THREE.Vector3(0, -height / 2 + radius, 0);
const q = new THREE.Vector3(0, height / 2 - radius, 0);
for (let t = 0; t < triangleCount && !touches; t++) {
a.fromArray(triangles, t * 9).applyMatrix4(toLocal);
b.fromArray(triangles, t * 9 + 3).applyMatrix4(toLocal);
c.fromArray(triangles, t * 9 + 6).applyMatrix4(toLocal);
touches = triangleTouchesCapsule(a, b, c, p, q, radius + tolerance);
}
}
if (!touches)
finding(
'DELIVERY_COLLIDER_NO_OVERLAP',
record.path,
'collider proxy overlaps no drawn triangle; a box or capsule normally wraps or crosses the surface it stands for.',
);
}
// Port findings: each port must lie in its module's footprint.
for (const record of summary.ports) {
const entry = visited.find((item) => item.path === record.path)!;
const moduleEntry = entry.module && entry.module.node !== entry.node ? entry.module : undefined;
const spec = moduleEntry && summary.kit?.path === moduleEntry.path ? summary.kit : undefined;
if (!spec) {
finding(
'DELIVERY_PORT_WITHOUT_MODULE',
record.path,
'port is not under a valid kit module; place ports under the root defineModule marked.',
);
continue;
}
const point = new THREE.Vector3(...record.transform.translation).applyMatrix4(
worldMatrix(moduleEntry!.node).invert(),
);
const [width, depth] = spec.footprint;
const [x0, x1, z0, z1] =
spec.origin === 'corner'
? [0, width, 0, depth]
: [-width / 2, width / 2, -depth / 2, depth / 2];
const slack = Math.max(1e-4, Math.max(width, depth, spec.height) * 1e-5);
if (
point.x < x0 - slack ||
point.x > x1 + slack ||
point.z < z0 - slack ||
point.z > z1 + slack ||
point.y < -slack ||
point.y > spec.height + slack
)
finding(
'DELIVERY_PORT_OUTSIDE_FOOTPRINT',
record.path,
`port lies outside its module footprint (${width} x ${depth} m from the ${spec.origin}, 0..${spec.height} m high).`,
);
}
// Anchor findings: an anchor is a point, so it has no children.
for (const record of summary.anchors) {
const entry = visited.find((item) => item.path === record.path)!;
if (entry.node.listChildren().length > 0)
finding(
'DELIVERY_ANCHOR_NOT_LEAF',
record.path,
'anchor has children; an anchor is an empty leaf node, so attach parts beside it instead.',
);
}
return summary;
}