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(kiln): unified-surface prompt — folded examples + finalize/render verbs
Matt Kissingerc8eeb729f49c
diff --git a/__tests__/__snapshots__/prompt-api.test.ts.snap b/__tests__/__snapshots__/prompt-api.test.ts.snapindex 0114bcbc..1de4a467 100644--- a/__tests__/__snapshots__/prompt-api.test.ts.snap+++ b/__tests__/__snapshots__/prompt-api.test.ts.snap@@ -233,3 +233,345 @@ getJointNames(root: Object3D) // All node names beginning with \`Joint_\`. UsevalidateAsset(root: Object3D, category: 'character' | 'prop' | 'vfx' | 'environment')// Warns on category-appropriate triangle / material budgets."`;++exports[`unified api surface (examples folded in) unified api snapshot (review folded examples in this diff) 1`] = `+"// Scene & structure (globals — no imports needed)+createRoot(name: string) // Creates the root Object3D for an asset. Call first in build().+ // e.g. const root = createRoot('FuelDrum');+createPivot(name: string, position?: [x, y, z], parent?: Object3D)+ // Creates an empty pivot node for skeletal animation. Name is auto-prefixed with \`Joint_\`.+ // e.g. const hip = createPivot('Hip', [0, 1, 0], root);+createPart(name, geometry, material, opts?: { position, rotation: [xDeg, yDeg, zDeg], scale, pivot, parent })+ // Creates a mesh, optionally wrapped in a pivot, and attaches it to \`opts.parent\`. \`rotation\`+ // is in DEGREES (like rotationTrack), NOT radians: [0, 0, 90] is a quarter turn; [0, 0, 1.57]+ // is a no-op.+ // NOTE: AUTO-ADDS to opts.parent. NEVER call parent.add(createPart(...)) — pass { parent }+ // instead. rotation is DEGREES — writing radians (e.g. 0.785 or Math.PI/4) silently produces+ // ~zero rotation.+ // e.g. createPart('Barrel', cylinderGeo(0.1, 0.1, 1), gameMaterial(0x556b2f), { position: [0,+ // 0.5, 0], rotation: [0, 0, 90], parent: root });+beamBetween(name, start: [x,y,z], end: [x,y,z], radius, material, opts?: { segments, parent })+ // Creates a cylindrical rail/strut exactly between two endpoints. Use for braces, gun+ // barrels, skid struts, cables, and scaffolding.+ // e.g. beamBetween('SkidBraceA', [0.8, 0.3, 0.7], [0.8, 1.0, 0.45], 0.025, black, { parent:+ // root });+snapTo(part: Object3D, host: Object3D, opts?: { axis?: 'x'|'y'|'z', overlap?: 0.02 })+ // Translates \`part\` by the minimal vector that brings its bounding box into contact with+ // \`host\` (plus a small overlap). The direct cure for a "Floating parts" warning — attach the+ // part instead of eyeballing a corrective offset. No-op if they already touch.+ // e.g. const scope = createPart('Scope', cylinderXGeo(0.04, 0.04, 0.3), steel, { parent:+ // root, position: [0.1, 0.32, 0] }); snapTo(scope, receiver);+createLadder(name, { bottom, top, material, width?, rungCount?, railRadius?, rungRadius?, widthAxis?, parent? })+ // Builds two continuous rails plus evenly-spaced rungs. Use this instead of loose boxes for+ // ladders.+ // e.g. createLadder('TowerLadder', { bottom: [0,0,0], top: [0,2.2,0], width: 0.45, rungCount:+ // 7, material: steel, parent: root });+createWingPair(name, material, { rootZ, span, rootChord, tipChord, sweep?, thickness?, dihedral?, rootX?, rootY?, parent? })+ // Creates mirrored trapezoid aircraft wings with roots attached at +/-rootZ. Use for aircraft+ // wings and helicopter stub wings.+ // e.g. createWingPair('MainWing', olive, { rootX: 0, rootY: 1.0, rootZ: 0.42, span: 2.4,+ // rootChord: 0.9, tipChord: 0.35, sweep: 0.25, dihedral: 0.08, parent: root });++// Geometry (returns BufferGeometry)+boxGeo(width: number, height: number, depth: number) // 6-face box. 12 tris regardless of size. Cheapest geometry.+ // e.g. const geo = boxGeo(1, 0.5, 2);+sphereGeo(radius: number, widthSegments?: 8, heightSegments?: 6)+ // UV sphere. Default 8x6 segments = 84 tris. Bump segments for smoother curves.+ // e.g. const geo = sphereGeo(0.5, 12, 8);+cylinderGeo(radiusTop: number, radiusBottom: number, height: number, segments?: 8)+ // Y-axis cylinder. Use radiusTop != radiusBottom for cones / tapered pieces.+ // e.g. const geo = cylinderGeo(0.25, 0.25, 1, 12);+cylinderYGeo(radiusTop: number, radiusBottom: number, height: number, segments?: 8)+ // Alias for cylinderGeo — a Y-axis cylinder. Provided because the sandbox exposes+ // cylinderXGeo / cylinderZGeo and the symmetric Y form is commonly reached for.+ // e.g. const geo = cylinderYGeo(0.25, 0.25, 1, 12);+cylinderXGeo(radiusTop: number, radiusBottom: number, length: number, segments?: 8)+ // Cylinder pre-rotated to run along +X/-X. Use for fuselages, cannons, barrels, axles, and+ // forward-facing tubes.+ // e.g. const geo = cylinderXGeo(0.1, 0.1, 1.2, 12);+cylinderZGeo(radiusTop: number, radiusBottom: number, length: number, segments?: 8)+ // Cylinder pre-rotated to run along +Z/-Z. Use for side-mounted weapons, rails, crossbars,+ // and pipes.+ // e.g. const geo = cylinderZGeo(0.08, 0.08, 0.9, 10);+cylinderOnAxis(center: [x,y,z], normal: [x,y,z], radiusBottom: number, height: number, opts?: { radiusTop?, segments? })+ // Frame-first cylinder: position + axis specified directly, no post-hoc rotation. Use when+ // the cylinder needs to point along a non-cardinal direction (struts inside CSG operands,+ // antennas off a tilted surface). For cardinal axes prefer the terser cylinderXGeo /+ // cylinderYGeo / cylinderZGeo helpers.+ // e.g. const strut = cylinderOnAxis([0.5, 0.7, 0], [1, 1, 0.3], 0.05, 0.9);+capsuleGeo(radius: number, height: number, segments?: 6)+ // Stadium shape (cylinder with hemispherical caps). Good for limbs.+ // e.g. const geo = capsuleGeo(0.1, 0.5, 6);+capsuleYGeo(radius: number, height: number, segments?: 6)+ // Alias for capsuleGeo — a Y-axis capsule. Provided for symmetry with capsuleXGeo /+ // capsuleZGeo.+ // e.g. const geo = capsuleYGeo(0.1, 0.5, 6);+capsuleXGeo(radius: number, length: number, segments?: 6)+ // Capsule pre-rotated to run along +X/-X. Use for aircraft bodies, rounded vehicle hulls, and+ // missiles.+ // e.g. const geo = capsuleXGeo(0.35, 2.4, 10);+capsuleZGeo(radius: number, length: number, segments?: 6)+ // Capsule pre-rotated to run along +Z/-Z. Use for lateral pods, floats, and side tanks.+ // e.g. const geo = capsuleZGeo(0.18, 1.1, 8);+coneGeo(radius: number, height: number, segments?: 8)+ // Y-axis cone (pointed up). Use for spikes, roofs, projectiles.+ // e.g. const geo = coneGeo(0.3, 0.8, 8);+coneYGeo(radius: number, height: number, segments?: 8)+ // Alias for coneGeo — a Y-axis cone (point +Y). Provided for symmetry with coneXGeo /+ // coneZGeo.+ // e.g. const geo = coneYGeo(0.3, 0.8, 8);+coneXGeo(radius: number, length: number, segments?: 8)+ // Cone pre-rotated so its point faces +X. Use for noses, rockets, shells, and forward-facing+ // tips.+ // e.g. const geo = coneXGeo(0.18, 0.45, 12);+coneZGeo(radius: number, length: number, segments?: 8)+ // Cone pre-rotated so its point faces +Z. Use for side-facing projectiles and tips.+ // e.g. const geo = coneZGeo(0.12, 0.35, 10);+taperConeGeo(radiusBottom: number, radiusTop: number, height: number, axis?: 'x'|'y'|'z', segments?: 8)+ // Truncated cone (frustum) — exposes both bottom and top radius. radiusTop=0 matches coneGeo,+ // radiusTop=radiusBottom matches cylinderGeo. Use for pylon caps, soda cans, lampshades,+ // anything tapered that does not come to a point. axis selects orientation (default Y).+ // e.g. const cap = taperConeGeo(0.3, 0.18, 0.4); // frustum+torusGeo(radius: number, tube: number, radialSegments?: 8, tubularSegments?: 12)+ // Donut shape. For rings, tyres, barrel ribs.+ // e.g. const geo = torusGeo(0.4, 0.04, 8, 16);+planeGeo(width: number, height: number, widthSegments?: 1, heightSegments?: 1)+ // 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.+ // e.g. const geo = planeGeo(4, 4);+decalBox(width: number, height: number, depth?: 0.01)+ // 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.+ // NOTE: Offset at least 0.01 outside the host surface to avoid z-fighting (a 0.8-wide hull+ // has faces at z=±0.4, so place the decal at z=±0.41).+ // e.g. const star = decalBox(0.18, 0.18, 0.01); createPart('Mesh_StarPort', star,+ // gameMaterial(0xc61f2a), { position: [0.4, 0.6, 0.41], parent: fuselage });+foliageCardGeo(opts?: { width?, height?, yPivot?: 0..1 })+ // Single-quad foliage card with a configurable Y pivot. yPivot=0 plants the quad on the+ // ground. Pair with an alpha-tested material and a leaf/plant sprite.+ // e.g. const quad = foliageCardGeo({ width: 4, height: 6, yPivot: 0 });+ // createPart('Mesh_Fern', quad, gameMaterial(0x3a6b2e), { parent: root });+crossedQuadsGeo(opts?: { width?, height?, planes?: 2 | 3, yPivot? })+ // Cross-billboard bush primitive: 2 or 3 planes intersecting along the Y axis. Reads as a+ // dense plant from any angle, cheaper than real geometry.+ // e.g. const bush = crossedQuadsGeo({ width: 2, height: 2, planes: 3 });+ // createPart('Mesh_Bush', bush, gameMaterial(0x2f4a1a), { parent: root });+octaGridPlane({ tilesX, tilesY, width?, height?, yPivot? })+ // Atlas-ready billboard quad. UVs are pre-scaled to cover one tile of a tilesX×tilesY atlas;+ // the consumer shader adds per-instance tile offsets at draw time.+ // e.g. const card = octaGridPlane({ tilesX: 4, tilesY: 4, width: 6, height: 6 });+wingGeo(opts?: { span, rootChord, tipChord, sweep, thickness, dihedral })+ // Trapezoid wing panel. Local root edge is at Z=0, span extends toward +Z, positive sweep+ // moves the tip aft along -X.+ // e.g. const geo = wingGeo({ span: 2.2, rootChord: 0.8, tipChord: 0.3, sweep: 0.25, dihedral:+ // 0.08 });+gearGeo(opts?: { teeth?: 12, rootRadius?: 0.8, tipRadius?: 1.0, boreRadius?: 0.2, height?: 0.3, toothWidthFrac?: 0.5 })+ // Parametric gear: disc with N additive teeth around the rim and a center bore. Flat-shaded+ // hard edges. Built directly (no CSG), so cheap.+ // e.g. const g = gearGeo({ teeth: 16, tipRadius: 1.0, boreRadius: 0.15, height: 0.25 });+ // createPart('Gear', g, gameMaterial(0x909090, { metalness: 0.8 }), { parent: root });+bladeGeo(opts?: { length?: 1.5, baseWidth?: 0.1, thickness?: 0.015, tipLength?: 0.25, edgeBevel?: 0 })+ // Parametric sword blade: rectangular base tapering to a point over tipLength. edgeBevel > 0+ // pinches the cross-section toward a diamond ridge.+ // e.g. const b = bladeGeo({ length: 1.6, baseWidth: 0.09, tipLength: 0.3, edgeBevel: 0.5 });+ // createPart('Blade', b, steel, { position: [0, 0, 0], parent: root });++// Materials+gameMaterial(color, opts?: { metalness, roughness, emissive, emissiveIntensity, flatShading })+ // Flat-shaded PBR material. Default for game-ready low-poly. Use for 95% of parts.+ // e.g. const mat = gameMaterial(0x8b7355, { roughness: 0.9 });+basicMaterial(color, opts?: { transparent, opacity })+ // Unlit flat material. For UI / effects where lighting is baked in.+ // e.g. const mat = basicMaterial(0xffffff, { transparent: true, opacity: 0.5 });+glassMaterial(color, opts?: { opacity, roughness, metalness })+ // Semi-transparent double-sided material. Panels need ~0.05 offset to avoid z-fighting.+ // e.g. const mat = glassMaterial(0x66ccff, { opacity: 0.3 });+lambertMaterial(color, opts?: { flatShading, emissive })+ // Cheaper than gameMaterial. No metalness/roughness. Use when PBR is overkill.+ // e.g. const mat = lambertMaterial(0x2a4d14, { flatShading: true });+pbrMaterial({ albedo?, normal?, roughness?, metalness?, emissive?, aoMap? })+ // Full PBR material. Each slot can be a hex color/scalar or a Texture loaded via loadTexture.+ // Exports as glTF pbrMetallicRoughness.+ // e.g. const wood = await loadTexture('./oak.png'); const crate = pbrMaterial({ albedo: wood,+ // roughness: 0.85, metalness: 0 });++// Instancing (share geometry+material; smaller GLBs)+cloneGeometry(geo: BufferGeometry)+ // Returns the same geometry reference. Use it as a signal that you are intentionally sharing+ // geometry across multiple parts; gltf-transform dedupes on export.+ // e.g. const wheelGeo = cylinderGeo(0.4, 0.4, 0.2, 12);+cloneMaterial(mat: Material) // Shared material reference. See cloneGeometry.+ // e.g. const rubberMat = gameMaterial(0x1a1a1a, { roughness: 0.95 });+createInstance(name, source, opts?: { position, rotation: [xDeg, yDeg, zDeg], scale, parent })+ // Creates a new mesh reusing an existing part's geometry + material at a new transform.+ // Cheapest way to replicate wheels / bolts / fence posts / windows. \`rotation\` is in DEGREES,+ // like createPart.+ // e.g. const wheelFL = createPart('WheelFL', wheelGeo, rubberMat, { position: [-0.8, 0.3,+ // 1.2], parent: root }); createInstance('WheelFR', wheelFL, { position: [0.8, 0.3, 1.2],+ // parent: root }); createInstance('WheelRL', wheelFL, { position: [-0.8, 0.3, -1.2], parent:+ // root }); createInstance('WheelRR', wheelFL, { position: [0.8, 0.3, -1.2], parent: root });++// Arrays (replicate a source part)+arrayLinear(namePrefix, source, count, offset: [x,y,z], parent?)+ // Places N copies of \`source\` along a constant offset vector. Copies share geometry ++ // material via createInstance.+ // e.g. const post = createPart('Post0', cylinderGeo(0.05,0.05,1.5,6), wood, { position:+ // [0,0.75,0], parent: root }); arrayLinear('Post', post, 10, [0.5, 0, 0], root);+arrayRadial(namePrefix, source, count, axis?: 'x'|'y'|'z', parent?)+ // Places N copies of \`source\` around the given axis. Source's local rotation is oriented+ // outward. Perfect for gear teeth, radial bolts, circle of columns.+ // e.g. const bolt = createPart('Bolt0', cylinderGeo(0.02,0.02,0.1,6), steel, { position:+ // [1,0,0], parent: root }); arrayRadial('Bolt', bolt, 8, 'y', root);+mirror(name, source, axis: 'x'|'y'|'z', parent?)+ // Reflects source across the plane whose normal is \`axis\`. Uses negative scale (winding flip+ // handled by viewers).+ // e.g. mirror('WingR', wingL, 'x', root);++// CSG / Boolean (async — using any of these requires \`async function build()\`)+await boolUnion(name: string, ...parts: Object3D[], opts?: { smooth?: false })+ // Merges two or more parts into one watertight manifold mesh. Default flat shading (hard+ // edges) — pass { smooth: true } as last arg for averaged normals on organic merges.+ // e.g. const body = new THREE.Mesh(boxGeo(2, 1, 1), steel); const turret = new+ // THREE.Mesh(cylinderGeo(0.3, 0.3, 0.4, 16), steel); turret.position.y = 0.5; const hull =+ // await boolUnion('Hull', body, turret);+await boolDiff(name: string, body: Object3D, ...cutters: Object3D[], opts?: { smooth?: false })+ // Subtracts cutters from a body (holes, button recesses, window slots). Default flat shading+ // for sharp mechanical edges.+ // e.g. const body = new THREE.Mesh(cylinderGeo(1, 1, 0.3, 32), steel); const teeth = [...];+ // // 8 radially-arrayed box meshes const gear = await boolDiff('Gear', body, ...teeth); //+ // hard-edged+await boolIntersect(name: string, a: Object3D, b: Object3D, opts?: { smooth?: false })+ // Keeps only the volume where both operands overlap. Default flat shading.+ // e.g. const lens = await boolIntersect('Lens', boxMesh, sphereMesh);+await hull(name: string, ...parts: Object3D[], opts?: { smooth?: true })+ // Tightest convex mesh enclosing all input points. Default smooth shading (rocks, collision+ // volumes). Pass { smooth: false } for a faceted look.+ // e.g. const rockChunks = [...]; // scattered box meshes const rock = await hull('Rock',+ // ...rockChunks);++// Mesh ops+subdivide(geometry: BufferGeometry, iterations?: 1, opts?: { split, uvSmooth, preserveEdges, flatOnly, weld })+ // Loop subdivision. Each iteration ~4x the triangle count and smooths the surface.+ // Non-indexed input is auto-welded via mergeVertices (weld: false to skip). Use 1 for mild+ // smoothing, 2 for organic shapes.+ // e.g. const smoothRock = subdivide(boxGeo(1, 1, 1), 2);+mergeVertices(geometry: BufferGeometry, tolerance?: 1e-4)+ // Welds coincident vertices into shared, indexed ones. Three's primitives emit disconnected+ // per-face strips — call this before subdividing, deforming, or smooth-shading so shared+ // corners move once.+ // e.g. // Weld before random deformation so corners drift together: const base =+ // mergeVertices(boxGeo(1, 1, 1)); const pos = base.getAttribute('position'); for (let i = 0;+ // i < pos.count; i++) pos.setXYZ(i, pos.getX(i) + jitter(), pos.getY(i) + jitter(),+ // pos.getZ(i) + jitter()); const rock = subdivide(base, 2);++// Curves+curveToMesh(points: [x,y,z][], radius, tubularSegs?: 32, radialSegs?: 8, closed?: false)+ // Sweeps a circular profile along a path. Equivalent to Blender's Curve to Mesh node with a+ // circle profile. Use for pipes, cables, tubular frames.+ // e.g. const pipe = curveToMesh([[0,0,0],[0,1,0],[1,1,0],[1,2,0]], 0.1);+pipeAlongPath(points: [x,y,z][], radius: number, opts?: { bendRadius?: 0, closed?: false, tubularSegments?: 32, radialSegments?: 8 })+ // Path-driven swept circle with optional bend smoothing. Generalises beamBetween+ // (point-to-point) and curveToMesh (raw spline) into one helper. bendRadius>0 inserts+ // interpolated waypoints near interior corners so the spline reads as a rounded turn instead+ // of pinching to the control point.+ // e.g. const cable = pipeAlongPath([[0, 0.5, 0], [1, 0.5, 0], [1, 0.5, 2]], 0.02, {+ // bendRadius: 0.1 });+lathe(profile: [x,y][], segments?: 12)+ // Surface of revolution. Spins a 2D profile around the Y axis. For bottles, vases, wheels,+ // turned wood parts.+ // e.g. const vase = lathe([[0.1,0],[0.3,0.5],[0.2,1],[0.1,1.2]], 16);+revolveGeo(profile: [x,y][], opts?: { angle?: 2π, axis?: [x,y,z]=[0,1,0], segments?: 12 })+ // Surface of revolution with explicit axis + sweep angle. Generalises lathe — use it when you+ // need a partial sweep (half-dome, 90° wedge) or revolution around a non-Y axis. Profile+ // convention is identical to lathe: x = radial distance, y = position along the axis.+ // e.g. // Half-dome (180° sweep around +Y): const quarter = [...Array(8)].map((_, i) => {+ // const t = (i/7)*Math.PI/2; return [Math.cos(t), Math.sin(t)] as [number, number]; }); const+ // dome = revolveGeo(quarter, { angle: Math.PI });+bezierCurve(controlPoints: [x,y,z][], samples?: 32)+ // Samples a quadratic (3 ctrl pts) or cubic (4 ctrl pts) Bézier into a point list you can+ // feed into curveToMesh.+ // e.g. const path = bezierCurve([[0,0,0],[1,2,0],[3,2,0],[4,0,0]], 24); const geo =+ // curveToMesh(path, 0.1);++// UV unwrapping+await autoUnwrap(geometry: BufferGeometry, opts?: { resolution?: 1024, padding?: 2, useNormals?: false })+ // xatlas-based UV atlas for ANY geometry (CSG output, subdivided, deformed). Output is a+ // packed atlas with arbitrary per-chart rotation — use for non-tileable baked textures. For+ // directional tileable textures on box/cylinder/plane primitives, prefer the shape-aware+ // unwraps below.+ // e.g. const unwrapped = await autoUnwrap(someCsgResult, { resolution: 1024 }); const mesh =+ // new THREE.Mesh(unwrapped, bakedPbr);+boxUnwrap(geometry: BufferGeometry)+ // Preserves BoxGeometry's built-in per-face UVs — every face maps [0,1] with consistent+ // orientation. Use for crates/blocks with a tileable texture. Sync; no WASM cost.+ // e.g. const crate = boxUnwrap(boxGeo(1, 1, 1)); const mesh = new THREE.Mesh(crate,+ // pbrMaterial({ albedo: planksTex }));+cylinderUnwrap(geometry: BufferGeometry)+ // Preserves CylinderGeometry's built-in UVs: u wraps around the axis (horizontal texture+ // features ring the cylinder), v runs up the height. Caps use circle-in-square. Sync; no WASM+ // cost.+ // e.g. const barrel = cylinderUnwrap(cylinderGeo(0.5, 0.5, 1.2, 24)); const mesh = new+ // THREE.Mesh(barrel, pbrMaterial({ albedo: bandsTex }));+planeUnwrap(geometry: BufferGeometry)+ // Projects xy-extent of the bbox to [0,1]. Use for signs/decals/posters where you want ONE+ // readable texture and no edge-face bleeding. Sync.+ // e.g. const sign = planeUnwrap(planeGeo(1, 0.6)); const mesh = new THREE.Mesh(sign,+ // pbrMaterial({ albedo: kilnTextTex }));+panelRemapV(geo, vScale=0.30, vOffset=0, uScale=1, uOffset=0)+ // Scales an existing UV attribute so a small mesh samples a sub-region of a SHARED texture.+ // Replaces the broken texture.clone() pattern (Three.js Texture.clone() runs JSON.stringify+ // on userData, mangling encoded PNG bytes — panelRemapV avoids that by remapping UVs on the+ // geometry instead). Typical use: multi-zone albedo where v=0..0.30 is plain panel and+ // v=0.30..1 has windows/markings — small parts call panelRemapV(unwrap(geo), 0.30) to sample+ // only the clean strip.+ // e.g. const cowlGeo = panelRemapV(cylinderUnwrap(capsuleXGeo(0.45, 1.0)), 0.30); const cowl+ // = new THREE.Mesh(cowlGeo, bodyMat); // SAME bodyMat as fuselage, no clone needed++// Textures (loadTexture is async)+await loadTexture(source: string | Buffer | Uint8Array)+ // Loads a PNG/JPG/WebP image into a Three.js Texture. Stashes the encoded bytes on+ // userData.encoded so GLB export is lossless.+ // NOTE: NEVER texture.clone() a loaded texture (clone() corrupts the encoded bytes and breaks+ // GLB export). Share the same Texture object and remap UVs with panelRemapV on the smaller+ // mesh instead.+ // e.g. const wood = await loadTexture('./textures/oak-albedo.png');++// Animation — keyframes use "rotation"/"position"/"scale" keys, NOT "value"+rotationTrack(jointName: string, keyframes: Array<{ time, rotation: [xDeg, yDeg, zDeg] }>, interp?: 'LINEAR' | 'STEP')+ // Rotation track in degrees, auto-converted to quaternions. Joint name must include \`Joint_\`+ // prefix.+ // e.g. rotationTrack('Joint_Lid', [{ time: 0, rotation: [0, 0, 0] }, { time: 1, rotation:+ // [90, 0, 0] }]);+positionTrack(jointName: string, keyframes: Array<{ time, position: [x, y, z] }>, interp?: 'LINEAR' | 'STEP')+ // Position track in world units. Always use \`position:\` not \`value:\` in keyframes.+ // e.g. positionTrack('Joint_Body', [{ time: 0, position: [0, 0, 0] }, { time: 1, position:+ // [0, 0.1, 0] }]);+scaleTrack(jointName: string, keyframes: Array<{ time, scale: [x, y, z] }>, interp?: 'LINEAR' | 'STEP')+ // Uniform or per-axis scale track.+ // e.g. scaleTrack('Joint_Chest', [{ time: 0, scale: [1, 1, 1] }, { time: 1, scale: [1.1, 1.1,+ // 1.1] }]);+createClip(name: string, duration: number, tracks: KeyframeTrack[])+ // Collects tracks into a named clip. Returned from animate().+ // e.g. return [createClip('Open', 1, [rotationTrack('Joint_Lid', [...])])];+idleBreathing(bodyJoint: string, duration?: 2, amount?: 0.02) // Gentle Y-axis bob. For NPC idle states.+ // e.g. return [idleBreathing('Joint_Body')];+bobbingAnimation(rootName: string, duration?: 2, height?: 0.1) // Floating / bobbing loop for pickups and effects.+ // e.g. return [bobbingAnimation('Joint_Root', 1.5, 0.08)];+spinAnimation(jointName: string, duration?: 2, axis?: 'x' | 'y' | 'z')+ // 360° rotation over \`duration\` around \`axis\`.+ // e.g. return [spinAnimation('Joint_Rotor', 0.5, 'y')];++// Inspection utilities+countTriangles(root: Object3D) // Sums triangle count across every mesh in the subtree.+ // e.g. meta.tris = countTriangles(root);+countMaterials(root: Object3D) // Unique material count (by reference) across the subtree.+ // e.g. const mats = countMaterials(root);+getJointNames(root: Object3D) // All node names beginning with \`Joint_\`. Use to sanity-check animation targets.+ // e.g. const joints = getJointNames(root);+validateAsset(root: Object3D, category: 'character' | 'prop' | 'vfx' | 'environment')+ // Warns on category-appropriate triangle / material budgets.+ // e.g. const v = validateAsset(root, 'prop');"+`;diff --git a/__tests__/prompt-api.test.ts b/__tests__/prompt-api.test.tsindex 791b25b3..311c6a62 100644--- a/__tests__/prompt-api.test.ts+++ b/__tests__/prompt-api.test.ts@@ -126,6 +126,35 @@ describe('system prompt embeds the generated catalog', () => {});});+describe('unified api surface (examples folded in)', () => {+ const primitives = listPrimitives();+ const def = renderApiSection(primitives);+ const withExamples = renderApiSection(primitives, { includeExamples: true });++ test('includeExamples:false is byte-identical to the default rendering', () => {+ expect(renderApiSection(primitives, { includeExamples: false })).toBe(def);+ });++ test('includeExamples:true folds an `e.g.` line per primitive (longer than default)', () => {+ const count = (s: string) => (s.match(/\/\/ e\.g\./g) ?? []).length;+ expect(withExamples.length).toBeGreaterThan(def.length);+ // Every primitive carries an example, so the folded render adds many `e.g.` lines.+ expect(count(withExamples)).toBeGreaterThan(count(def) + 40);+ });++ test('multi-line examples are collapsed to a single logical comment (no raw newline-in-example)', () => {+ // snapTo / createPart have multi-line examples; folded output must not leave a+ // bare un-commented continuation line (every wrapped line is `//`-prefixed).+ for (const line of withExamples.split('\n')) {+ expect(line === '' || line.trimStart().startsWith('//') || line.includes('(')).toBe(true);+ }+ });++ test('unified api snapshot (review folded examples in this diff)', () => {+ expect(withExamples).toMatchSnapshot();+ });+});+// =============================================================================// (3) Skill drift gate// =============================================================================diff --git a/__tests__/prompt.test.ts b/__tests__/prompt.test.tsindex ed15c9ee..46ba6a5c 100644--- a/__tests__/prompt.test.ts+++ b/__tests__/prompt.test.ts@@ -17,6 +17,11 @@ import {KILN_TSL_SYSTEM_PROMPT,KILN_BOTH_SYSTEM_PROMPT,KILN_REFINE_DIRECTIVE,+ KILN_API_SECTION,+ KILN_API_SECTION_UNIFIED,+ KILN_VISUAL_QA_UNIFIED,+ KILN_REFINE_DIRECTIVE_UNIFIED,+ KILN_EDIT_DIRECTIVE_UNIFIED,} from '../prompt';describe('getSystemPrompt', () => {@@ -186,3 +191,39 @@ describe('KILN_REFINE_DIRECTIVE', () => {expect(KILN_REFINE_DIRECTIVE).toContain('kiln_submit');});});++describe('unified tool surface prompt', () => {+ test('toolSurface:unified swaps in the examples-folded api and the unified visual-qa', () => {+ const unified = getSystemPrompt('glb', { toolSurface: 'unified' });+ expect(unified).not.toBe(KILN_SYSTEM_PROMPT);+ expect(unified).toContain(KILN_API_SECTION_UNIFIED);+ expect(unified).toContain(KILN_VISUAL_QA_UNIFIED);+ // The non-examples api block and the legacy verb sentence are gone.+ expect(unified).not.toContain(KILN_API_SECTION);+ expect(unified).not.toContain('Before kiln_submit, call kiln_screenshot');+ });++ test('unified takes precedence over apiSurface:trimmed (which points at the removed list tool)', () => {+ expect(getSystemPrompt('glb', { toolSurface: 'unified', apiSurface: 'trimmed' })).toBe(+ getSystemPrompt('glb', { toolSurface: 'unified' }),+ );+ });++ test('default (current) surface is unchanged', () => {+ expect(getSystemPrompt('glb')).toBe(KILN_SYSTEM_PROMPT);+ expect(getSystemPrompt('glb', { toolSurface: 'current' })).toBe(KILN_SYSTEM_PROMPT);+ });++ test('unified directives use kiln_finalize / kiln_render, never kiln_submit / kiln_screenshot', () => {+ expect(KILN_REFINE_DIRECTIVE_UNIFIED).toContain('kiln_finalize');+ expect(KILN_REFINE_DIRECTIVE_UNIFIED).toContain('MODIFYING');+ expect(KILN_REFINE_DIRECTIVE_UNIFIED).not.toContain('kiln_submit');+ expect(KILN_REFINE_DIRECTIVE_UNIFIED).not.toContain('kiln_screenshot');++ expect(KILN_EDIT_DIRECTIVE_UNIFIED).toContain('kiln_finalize');+ expect(KILN_EDIT_DIRECTIVE_UNIFIED).toContain('kiln_edit');+ expect(KILN_EDIT_DIRECTIVE_UNIFIED).toContain('kiln_draft');+ expect(KILN_EDIT_DIRECTIVE_UNIFIED).not.toContain('kiln_submit');+ expect(KILN_EDIT_DIRECTIVE_UNIFIED).not.toContain('kiln_screenshot');+ });+});diff --git a/prompt-api.ts b/prompt-api.tsindex 2a2c8031..7362964a 100644--- a/prompt-api.ts+++ b/prompt-api.ts@@ -53,7 +53,7 @@ function wrapComment(text: string, indent: string): string[] {return lines;}-function renderPrimitiveLines(p: PrimitiveSpec): string[] {+function renderPrimitiveLines(p: PrimitiveSpec, includeExamples = false): string[] {const oneLiner = `${p.signature} // ${p.description}`;const lines: string[] = [];if (oneLiner.length <= WRAP + 20 && !p.description.includes('\n')) {@@ -65,6 +65,14 @@ function renderPrimitiveLines(p: PrimitiveSpec): string[] {if (p.promptNotes) {lines.push(...wrapComment(`NOTE: ${p.promptNotes}`, ' '));}+ if (includeExamples && p.example) {+ // Fold the per-primitive example into the <api> (replaces the dropped+ // kiln_list_primitives tool's only extra signal). Collapse internal newlines+ // in multi-line examples (snapTo/createPart) to one logical line so the+ // section stays scannable; wrapComment re-wraps long ones at WRAP columns.+ const collapsed = p.example.replace(/\s*\n\s*/g, ' ').replace(/\s{2,}/g, ' ').trim();+ lines.push(...wrapComment(`e.g. ${collapsed}`, ' '));+ }return lines;}@@ -73,8 +81,16 @@ function renderPrimitiveLines(p: PrimitiveSpec): string[] {* category comment headers followed by one entry per primitive (signature plus* a wrapped description comment and any promptNotes). Order is the canonical* category order, primitives in catalog order within each category.+ *+ * `includeExamples` (default false → byte-identical to today) appends each+ * primitive's collapsed example, used by the unified tool surface to fold in the+ * signal the dropped kiln_list_primitives tool used to carry.*/-export function renderApiSection(primitives: PrimitiveSpec[]): string {+export function renderApiSection(+ primitives: PrimitiveSpec[],+ opts: { includeExamples?: boolean } = {},+): string {+ const includeExamples = opts.includeExamples ?? false;const byCategory = new Map<string, PrimitiveSpec[]>();for (const p of primitives) {const list = byCategory.get(p.category) ?? [];@@ -87,7 +103,7 @@ export function renderApiSection(primitives: PrimitiveSpec[]): string {const list = byCategory.get(category);if (!list || list.length === 0) continue;const lines = [header];- for (const p of list) lines.push(...renderPrimitiveLines(p));+ for (const p of list) lines.push(...renderPrimitiveLines(p, includeExamples));blocks.push(lines.join('\n'));}@@ -96,7 +112,7 @@ export function renderApiSection(primitives: PrimitiveSpec[]): string {for (const [category, list] of byCategory) {if (known.has(category as PrimitiveSpec['category'])) continue;const lines = [`// ${category}`];- for (const p of list) lines.push(...renderPrimitiveLines(p));+ for (const p of list) lines.push(...renderPrimitiveLines(p, includeExamples));blocks.push(lines.join('\n'));}diff --git a/prompt.ts b/prompt.tsindex 83d35ccc..8bbdfc67 100644--- a/prompt.ts+++ b/prompt.ts@@ -151,6 +151,18 @@ ${renderApiSection(listPrimitives())}${KILN_API_IDIOMS}</api>`;+/**+ * The <api> section for the unified tool surface: identical to {@link KILN_API_SECTION}+ * but with each primitive's example folded in (`includeExamples`). This replaces the+ * dropped kiln_list_primitives tool — the per-primitive examples now ride in the (cached)+ * prompt instead of a round-trip. Used only when toolSurface:'unified'.+ */+export const KILN_API_SECTION_UNIFIED = `<api>+${renderApiSection(listPrimitives(), { includeExamples: true })}++${KILN_API_IDIOMS}+</api>`;+export const KILN_ARCHITECTURE = `<architecture>Use Pivot+Mesh pattern for animated parts:- Joint_* = pivot node (animate this) - created by createPivot or createPart with pivot:true@@ -250,6 +262,34 @@ Before kiln_submit, call kiln_screenshot and check each view deliberately:If any view looks wrong, fix the code and re-screenshot before submitting.</visual-qa>`;+/**+ * The visual-qa section for the unified tool surface: same per-view checks as+ * {@link KILN_VISUAL_QA}, but phrased for the collapsed kiln_render (which SHOWS+ * the six views) and the kiln_finalize terminal verb instead of+ * kiln_screenshot + kiln_submit.+ */+export const KILN_VISUAL_QA_UNIFIED = `<visual-qa>+After kiln_render you SEE the six views (metrics ride alongside the image). Before kiln_finalize, check each view deliberately:+- Front (camera on +X): the nose/muzzle/face should point AT you. If you see+ a side profile here, the asset is built sideways — rebuild along +X.+ Wheels/discs read edge-on here and as circles from the side — a circle seen+ from the front means the disc faces the wrong axis.+- Right (+Z): the long profile. Check silhouette: proportions, ground contact+ at the bottom edge, nothing important missing. Roof slopes must DRAPE — the+ eave line drops below the wall top with visible overhang; a roofline flush+ with the walls reads as a flap propped open. Nothing functional should hang+ below the ground line (cross-check the kiln_render bbox.min[1]: below -0.05 is+ only OK for intentional earthworks, piles, or keels).+- Back / Left: symmetry with their opposites; no missing or one-sided parts.+- Top (+Y): left/right symmetry; wings/axles/rails centered on the body.+- 3/4: part CONTACT. Look for gaps where parts should touch (struts, ladder+ rails, wing roots, attachments). A visible gap means a floating part — fix+ the position or call snapTo(part, host), then render again. Cylindrical+ stave assemblies (barrels, drums) must look CLOSED — daylight through the+ wall means staves are rotated radial instead of tangent.+If any view looks wrong, fix the code (kiln_edit or kiln_draft) and re-render before finalizing.+</visual-qa>`;+export const KILN_EXAMPLES = `<example name="animated-chest">const meta = { name: "Chest", category: "prop" };@@ -637,11 +677,30 @@ export interface GetSystemPromptOptions {* tool for discovery. Bench-measured via the prompt axis.*/apiSurface?: 'full' | 'trimmed';+ /**+ * Which agent tool surface the prompt is written for: 'current' (default)+ * matches the kiln_screenshot + kiln_submit verbs; 'unified' folds the+ * per-primitive examples into <api> (the dropped kiln_list_primitives tool's+ * signal) and swaps the visual-qa verbs to kiln_render + kiln_finalize.+ * INCOMPATIBLE with apiSurface:'trimmed' (the trimmed stub points at the+ * removed kiln_list_primitives tool) — 'unified' takes precedence.+ */+ toolSurface?: 'current' | 'unified';}export function getSystemPrompt(mode: RenderMode, opts: GetSystemPromptOptions = {}): string {if (mode === 'tsl') return KILN_TSL_SYSTEM_PROMPT;if (mode === 'both') return KILN_BOTH_SYSTEM_PROMPT;+ // Unified tool surface: fold per-primitive examples into <api> and swap the+ // verb-bearing visual-qa section. Takes precedence over apiSurface:'trimmed'+ // (the trimmed stub references the removed kiln_list_primitives tool).+ if (opts.toolSurface === 'unified') {+ return KILN_SYSTEM_PROMPT_SECTIONS.map(([name, s]) => {+ if (name === 'api') return KILN_API_SECTION_UNIFIED;+ if (name === 'visual-qa') return KILN_VISUAL_QA_UNIFIED;+ return s;+ }).join('\n\n');+ }if (opts.apiSurface === 'trimmed') {return KILN_SYSTEM_PROMPT_SECTIONS.map(([name, s]) =>name === 'api' ? KILN_API_SECTION_TRIMMED : s,@@ -669,6 +728,17 @@ export const KILN_REFINE_DIRECTIVE = `You are MODIFYING an existing Kiln asset,*/export const KILN_EDIT_DIRECTIVE = `You are EDITING an existing Kiln asset in place, not rebuilding it. A working buffer holds the Current Code shown in the user message. Use the kiln_edit tool to make the SMALLEST set of changes that satisfy the Edit Request: replace an exact span (oldString) with newString. Each oldString must match the current buffer verbatim - call kiln_view to read it (the text is raw, with no line-number prefixes). Keep everything the Edit Request does not mention byte-for-byte unchanged. After your edits, re-validate and re-render the buffer with the kiln tools, then call kiln_submit (omit its code argument to submit the working buffer). If an edit cannot be anchored after a couple of tries, you may submit a complete corrected program instead.`;+/**+ * The unified-surface counterparts of {@link KILN_REFINE_DIRECTIVE} and+ * {@link KILN_EDIT_DIRECTIVE}. Same modify-not-rebuild framing, but the working+ * buffer IS the unified surface (already seeded with the Current Code) and the+ * terminal verb is kiln_finalize, not kiln_submit. Used only when+ * toolSurface:'unified'.+ */+export const KILN_REFINE_DIRECTIVE_UNIFIED = `You are MODIFYING an existing Kiln asset, not building a new one from scratch. The user message gives you the Original Request that created the asset, its Current Code, and an Edit Request. Your working buffer is already seeded with the Current Code. Keep the asset's established character, proportions, and structure; change ONLY what the Edit Request asks for — use kiln_edit for small changes, or kiln_draft to rewrite the whole program. Re-validate and re-render the buffer with the kiln tools, then call kiln_finalize.`;++export const KILN_EDIT_DIRECTIVE_UNIFIED = `You are EDITING an existing Kiln asset in place, not rebuilding it. Your working buffer is already seeded with the Current Code shown in the user message. Use the kiln_edit tool to make the SMALLEST set of changes that satisfy the Edit Request: replace an exact span (oldString) with newString. Each oldString must match the current buffer verbatim - call kiln_view to read it (the text is raw, with no line-number prefixes). Keep everything the Edit Request does not mention byte-for-byte unchanged. After your edits, re-validate and re-render the buffer with the kiln tools, then call kiln_finalize. If an edit cannot be anchored after a couple of tries, call kiln_draft to rewrite the whole program instead.`;+export interface AssetBudget {maxTriangles?: number;maxMaterials?: number;