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
feat(asset-rails): add hardened overnight pipelines and agent context
Matt Kissinger2eca055265ef
diff --git a/generate.ts b/generate.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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-axistorusGeo(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 +ZgearGeo({ teeth=12, rootRadius=0.8, tipRadius=1.0, boreRadius=0.2, height=0.3, toothWidthFrac=0.5 }) // parametric gear, flat-shadedbladeGeo({ length=1.5, baseWidth=0.1, thickness=0.015, tipLength=0.25, edgeBevel=0 }) // tapered sword blade with pointed tipdiff --git a/render.ts b/render.tsindex 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;+}