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.

feat(asset-rails): add hardened overnight pipelines and agent context

Matt Kissinger2eca055265ef
diff --git a/generate.ts b/generate.ts
index dd852822..56aa7e23 100644
--- a/generate.ts
+++ b/generate.ts
@@ -80,7 +80,18 @@ const KILN_OUTPUT_SCHEMA = {
const DEFAULT_QUERY_TIMEOUT_MS = 720_000;
/** The pinned Opus generation model. Bump in one place. */
-const DEFAULT_OPUS_MODEL = 'claude-opus-4-7';
+// History:
+// - 2026-04-23 (early): temporarily downgraded to 'claude-sonnet-4-6' because
+// claude-agent-sdk 0.2.50 sent `thinking.type=enabled` which Opus 4.7
+// rejects ("use thinking.type=adaptive + effort").
+// - 2026-04-23 (late): SDK bumped to ^0.2.118 which accepts the new thinking
+// API. Restored to 'claude-opus-4-7'. If a future SDK release regresses,
+// set `KILN_MODEL=claude-sonnet-4-6` in the environment to bypass without
+// touching code.
+const DEFAULT_OPUS_MODEL =
+ process.env['KILN_MODEL'] ??
+ process.env['PIXEL_FORGE_MODEL'] ??
+ 'claude-opus-4-7';
/** The pinned Haiku compaction model. */
const DEFAULT_HAIKU_MODEL = 'claude-haiku-4-5-20251001';
diff --git a/inspect.ts b/inspect.ts
index 8ff098ed..a3c1cb79 100644
--- a/inspect.ts
+++ b/inspect.ts
@@ -85,12 +85,26 @@ const KNOWN_PRIMITIVE_NAMES = [
'createPivot',
'createPart',
'capsuleGeo',
+ 'capsuleXGeo',
+ 'capsuleYGeo',
+ 'capsuleZGeo',
'cylinderGeo',
+ 'cylinderXGeo',
+ 'cylinderYGeo',
+ 'cylinderZGeo',
'boxGeo',
'sphereGeo',
'coneGeo',
+ 'coneXGeo',
+ 'coneYGeo',
+ 'coneZGeo',
'torusGeo',
'planeGeo',
+ 'decalBox',
+ 'wingGeo',
+ 'createWingPair',
+ 'beamBetween',
+ 'createLadder',
'gameMaterial',
'basicMaterial',
'glassMaterial',
diff --git a/list-primitives.ts b/list-primitives.ts
index b2ed8e75..414c1cdb 100644
--- a/list-primitives.ts
+++ b/list-primitives.ts
@@ -135,6 +135,16 @@ const PRIMITIVES: PrimitiveSpec[] = [
'Y-axis cylinder. Use radiusTop != radiusBottom for cones / tapered pieces.',
example: 'const geo = cylinderGeo(0.25, 0.25, 1, 12);',
},
+ {
+ name: 'cylinderYGeo',
+ signature:
+ 'cylinderYGeo(radiusTop: number, radiusBottom: number, height: number, segments?: 8)',
+ returns: 'THREE.CylinderGeometry',
+ category: 'geometry',
+ description:
+ 'Alias for cylinderGeo — a Y-axis cylinder. Provided because the sandbox exposes cylinderXGeo / cylinderZGeo and the symmetric Y form is commonly reached for.',
+ example: 'const geo = cylinderYGeo(0.25, 0.25, 1, 12);',
+ },
{
name: 'cylinderXGeo',
signature:
@@ -163,6 +173,14 @@ const PRIMITIVES: PrimitiveSpec[] = [
description: 'Stadium shape (cylinder with hemispherical caps). Good for limbs.',
example: 'const geo = capsuleGeo(0.1, 0.5, 6);',
},
+ {
+ name: 'capsuleYGeo',
+ signature: 'capsuleYGeo(radius: number, height: number, segments?: 6)',
+ returns: 'THREE.CapsuleGeometry',
+ category: 'geometry',
+ description: 'Alias for capsuleGeo — a Y-axis capsule. Provided for symmetry with capsuleXGeo / capsuleZGeo.',
+ example: 'const geo = capsuleYGeo(0.1, 0.5, 6);',
+ },
{
name: 'capsuleXGeo',
signature: 'capsuleXGeo(radius: number, length: number, segments?: 6)',
@@ -189,6 +207,14 @@ const PRIMITIVES: PrimitiveSpec[] = [
description: 'Y-axis cone (pointed up). Use for spikes, roofs, projectiles.',
example: 'const geo = coneGeo(0.3, 0.8, 8);',
},
+ {
+ name: 'coneYGeo',
+ signature: 'coneYGeo(radius: number, height: number, segments?: 8)',
+ returns: 'THREE.ConeGeometry',
+ category: 'geometry',
+ description: 'Alias for coneGeo — a Y-axis cone (point +Y). Provided for symmetry with coneXGeo / coneZGeo.',
+ example: 'const geo = coneYGeo(0.3, 0.8, 8);',
+ },
{
name: 'coneXGeo',
signature: 'coneXGeo(radius: number, length: number, segments?: 8)',
@@ -222,9 +248,20 @@ const PRIMITIVES: PrimitiveSpec[] = [
'planeGeo(width: number, height: number, widthSegments?: 1, heightSegments?: 1)',
returns: 'THREE.PlaneGeometry',
category: 'geometry',
- description: 'Flat quad. Faces +Z by default. Rotate to use as ground / decal.',
+ description:
+ 'Flat quad for TEXTURED surfaces (ground, signs, walls with albedo maps). For solid-color decals like red stars, hull numbers, stamps, or window cutouts on no-texture assets use decalBox — a bare planeGeo without a texture will render as a disconnected 2-tri square and get flagged as a stray plane.',
example: 'const geo = planeGeo(4, 4);',
},
+ {
+ name: 'decalBox',
+ signature: 'decalBox(width: number, height: number, depth?: 0.01)',
+ returns: 'THREE.BoxGeometry',
+ category: 'geometry',
+ description:
+ 'Thin box for solid-color surface decals: red stars, hull numbers, stamps, no-texture windows. Unlike planeGeo, has real depth so it visibly attaches to its host surface. Must be placed on a surface with position + rotation.',
+ example:
+ "const star = decalBox(0.18, 0.18, 0.01);\ncreatePart('Mesh_StarPort', star, gameMaterial(0xc61f2a), { position: [0.4, 0.6, 0.41], parent: fuselage });",
+ },
{
name: 'wingGeo',
signature:
diff --git a/primitives.ts b/primitives.ts
index 4967c4f3..ccb4d312 100644
--- a/primitives.ts
+++ b/primitives.ts
@@ -197,6 +197,15 @@ export function coneZGeo(
return geo;
}
+// Y-axis aliases. The base geometries (`cylinderGeo`, `capsuleGeo`, `coneGeo`)
+// are already Y-axis by default, but LLMs see `*XGeo` / `*ZGeo` and infer a
+// matching `*YGeo` sibling. Rather than argue the naming, we accept the
+// symmetric form and route it to the base implementation. No behavior change
+// for existing code.
+export const cylinderYGeo = cylinderGeo;
+export const capsuleYGeo = capsuleGeo;
+export const coneYGeo = coneGeo;
+
export function torusGeo(
radius: number,
tube: number,
@@ -215,6 +224,36 @@ export function planeGeo(
return new THREE.PlaneGeometry(width, height, widthSegments, heightSegments);
}
+/**
+ * Flat box sized for surface-attached decals: red stars on fuselages, hull
+ * numbers, stamps, dome windows on no-texture vehicles. Returns a very thin
+ * {@link THREE.BoxGeometry} so the decal has depth and is visibly attached
+ * to its host surface — unlike a bare {@link planeGeo} which renders as a
+ * disconnected 2-tri quad when it drifts away from a parent mesh.
+ *
+ * Always place the returned geometry with `position` + `rotation` on the
+ * host surface via `createPart`. Keep `depth` as small as 0.005 for
+ * paper-thin decals, or bump to 0.05 for raised plates / badges.
+ *
+ * ```ts
+ * // Red star on the fuselage side.
+ * const star = decalBox(0.18, 0.18, 0.01);
+ * createPart('Mesh_StarPort', star, gameMaterial(0xc61f2a), {
+ * position: [0.4, 0.6, 0.41], // on +Z fuselage surface
+ * rotation: [0, 0, 0],
+ * parent: fuselage,
+ * });
+ * ```
+ */
+export function decalBox(
+ width: number,
+ height: number,
+ depth: number = 0.01,
+): THREE.BoxGeometry {
+ const d = Math.max(depth, 0.002);
+ return new THREE.BoxGeometry(width, height, d);
+}
+
export interface WingGeometryOptions {
span?: number;
rootChord?: number;
@@ -321,8 +360,10 @@ export function beamBetween(
const direction = b.clone().sub(a);
const length = direction.length();
- if (length <= 0) {
- throw new Error(`beamBetween("${name}"): start and end must be different points`);
+ if (length <= 1e-4) {
+ throw new Error(
+ `beamBetween("${name}"): start and end must be different points (got start=[${start.join(',')}], end=[${end.join(',')}], delta=${length.toExponential(2)}). Pick two distinct endpoints or switch to cylinderGeo with an explicit length + position.`,
+ );
}
const mesh = new THREE.Mesh(
@@ -825,17 +866,21 @@ export function buildSandboxGlobals(
createPart: wrap('createPart', createPart),
capsuleGeo: wrap('capsuleGeo', capsuleGeo),
capsuleXGeo: wrap('capsuleXGeo', capsuleXGeo),
+ capsuleYGeo: wrap('capsuleYGeo', capsuleYGeo),
capsuleZGeo: wrap('capsuleZGeo', capsuleZGeo),
cylinderGeo: wrap('cylinderGeo', cylinderGeo),
cylinderXGeo: wrap('cylinderXGeo', cylinderXGeo),
+ cylinderYGeo: wrap('cylinderYGeo', cylinderYGeo),
cylinderZGeo: wrap('cylinderZGeo', cylinderZGeo),
boxGeo: wrap('boxGeo', boxGeo),
sphereGeo: wrap('sphereGeo', sphereGeo),
coneGeo: wrap('coneGeo', coneGeo),
coneXGeo: wrap('coneXGeo', coneXGeo),
+ coneYGeo: wrap('coneYGeo', coneYGeo),
coneZGeo: wrap('coneZGeo', coneZGeo),
torusGeo: wrap('torusGeo', torusGeo),
planeGeo: wrap('planeGeo', planeGeo),
+ decalBox: wrap('decalBox', decalBox),
wingGeo: wrap('wingGeo', wingGeo),
createWingPair: wrap('createWingPair', createWingPair),
beamBetween: wrap('beamBetween', beamBetween),
diff --git a/prompt.ts b/prompt.ts
index f46d014d..b167905b 100644
--- a/prompt.ts
+++ b/prompt.ts
@@ -121,17 +121,21 @@ createPart("Name", geometry, material, { position: [x,y,z], parent: parentObj })
// Geometry (returns BufferGeometry)
boxGeo(width, height, depth)
sphereGeo(radius, widthSegs=8, heightSegs=6)
-cylinderGeo(radiusTop, radiusBot, height, segments=8) // Y-axis
+cylinderGeo(radiusTop, radiusBot, height, segments=8) // Y-axis (preferred)
cylinderXGeo(radiusTop, radiusBot, length, segments=8) // X-axis
+cylinderYGeo(radiusTop, radiusBot, length, segments=8) // alias for cylinderGeo (Y-axis)
cylinderZGeo(radiusTop, radiusBot, length, segments=8) // Z-axis
-coneGeo(radius, height, segments=8) // Y-axis, point +Y
+coneGeo(radius, height, segments=8) // Y-axis, point +Y (preferred)
coneXGeo(radius, length, segments=8) // point +X
+coneYGeo(radius, length, segments=8) // alias for coneGeo (point +Y)
coneZGeo(radius, length, segments=8) // point +Z
-capsuleGeo(radius, height, segments=6) // Y-axis
+capsuleGeo(radius, height, segments=6) // Y-axis (preferred)
capsuleXGeo(radius, length, segments=6) // X-axis
+capsuleYGeo(radius, length, segments=6) // alias for capsuleGeo (Y-axis)
capsuleZGeo(radius, length, segments=6) // Z-axis
torusGeo(radius, tube, radialSegs=8, tubularSegs=12)
-planeGeo(width, height, widthSegs=1, heightSegs=1)
+planeGeo(width, height, widthSegs=1, heightSegs=1) // texture-only; for solid-color decals use decalBox
+decalBox(width, height, depth=0.01) // flat box for solid-color decals: red stars, hull numbers, stamps, windows on no-texture assets. MUST be placed on a surface via position + rotation.
wingGeo({ span, rootChord, tipChord, sweep, thickness, dihedral }) // root at Z=0, span extends +Z
gearGeo({ teeth=12, rootRadius=0.8, tipRadius=1.0, boreRadius=0.2, height=0.3, toothWidthFrac=0.5 }) // parametric gear, flat-shaded
bladeGeo({ length=1.5, baseWidth=0.1, thickness=0.015, tipLength=0.25, edgeBevel=0 }) // tapered sword blade with pointed tip
diff --git a/render.ts b/render.ts
index f4f78450..751fd30d 100644
--- a/render.ts
+++ b/render.ts
@@ -456,6 +456,7 @@ export async function renderSceneToGLB(
// pivot" hint is first; the bridge also emits a briefer "target not
// found - skipped" for each unresolved track (kept for compatibility).
for (const w of inspectGeneratedAnimation(root, clips)) warnings.push(w);
+ for (const w of inspectSceneStructure(root)) warnings.push(w);
const doc = new Document();
const buf = doc.createBuffer();
@@ -563,3 +564,110 @@ export function inspectGeneratedAnimation(
return warnings;
}
+
+// =============================================================================
+// Runtime structural validators (stray planes, floating parts)
+// =============================================================================
+
+interface MeshStats {
+ name: string;
+ triCount: number;
+ isPlaneGeo: boolean;
+ center: THREE.Vector3;
+ size: THREE.Vector3;
+ box: THREE.Box3;
+}
+
+function collectMeshStats(root: THREE.Object3D): MeshStats[] {
+ root.updateMatrixWorld(true);
+ const out: MeshStats[] = [];
+ root.traverse((obj) => {
+ if (!(obj instanceof THREE.Mesh)) return;
+ const geo = obj.geometry;
+ if (!geo) return;
+
+ const idx = geo.getIndex();
+ const tri = idx ? idx.count / 3 : (geo.getAttribute('position')?.count ?? 0) / 3;
+
+ const box = new THREE.Box3().setFromObject(obj);
+ if (!isFinite(box.min.x) || !isFinite(box.max.x)) {
+ return;
+ }
+ const center = new THREE.Vector3();
+ const size = new THREE.Vector3();
+ box.getCenter(center);
+ box.getSize(size);
+
+ out.push({
+ name: obj.name || '(unnamed)',
+ triCount: Math.floor(tri),
+ isPlaneGeo: geo instanceof THREE.PlaneGeometry,
+ center,
+ size,
+ box,
+ });
+ });
+ return out;
+}
+
+/**
+ * Detects two structural failure modes observed in real overnight runs:
+ *
+ * 1. **Stray plane at origin** — a 2-triangle `PlaneGeometry` mesh whose
+ * world-space bbox centroid sits within 2cm of world origin. This is
+ * what happens when the model reaches for `planeGeo` as a decal (red
+ * star, stamp, hull number) and forgets to position it on the host
+ * surface. Fix: move the decal into place, or switch to `decalBox`.
+ * 2. **Floating part** — a mesh whose world-space bbox has no overlap
+ * (with a 2cm tolerance) with any other mesh in the scene. Fix: move
+ * the mesh so it contacts its intended parent surface.
+ *
+ * Emits strings compatible with the existing `warnings` channel on
+ * `RenderResult`. `_direct-generate.ts` threshold-checks these to trigger
+ * a single corrective retry.
+ */
+export function inspectSceneStructure(root: THREE.Object3D): string[] {
+ const warnings: string[] = [];
+ const meshes = collectMeshStats(root);
+ if (meshes.length === 0) return warnings;
+
+ const STRAY_CENTROID_TOL = 0.02;
+ const FLOATING_EXPAND = 0.02;
+ const DECAL_EXTENT_MAX = 0.5; // anything smaller than 50cm fits decal profile
+
+ for (const m of meshes) {
+ if (!m.isPlaneGeo) continue;
+ if (m.triCount > 2) continue;
+ if (m.size.length() > DECAL_EXTENT_MAX) continue;
+ if (m.center.length() < STRAY_CENTROID_TOL) {
+ warnings.push(
+ `Stray plane "${m.name}" at world origin (centroid ≈ [0,0,0]). Replace planeGeo with decalBox and position on a host surface, or move this mesh into place.`,
+ );
+ }
+ }
+
+ if (meshes.length > 1) {
+ const floaters: string[] = [];
+ for (let i = 0; i < meshes.length; i++) {
+ const a = meshes[i]!;
+ const ax = a.box.clone().expandByScalar(FLOATING_EXPAND);
+ let overlapsAny = false;
+ for (let j = 0; j < meshes.length; j++) {
+ if (i === j) continue;
+ const b = meshes[j]!;
+ if (ax.intersectsBox(b.box)) {
+ overlapsAny = true;
+ break;
+ }
+ }
+ if (!overlapsAny) floaters.push(a.name);
+ }
+ if (floaters.length > 0) {
+ warnings.push(
+ `Floating parts (no mesh overlap with any sibling, 2cm tol): ${floaters.join(', ')}. Move these so their bbox contacts a parent/surface mesh.`,
+ );
+ }
+ }
+
+ return warnings;
+}