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
docs: give every hero its own render instead of one collage
Matt Kissingerc92fca444cf3
diff --git a/README.md b/README.mdindex a5a67fe7..c9a42f74 100644--- a/README.md+++ b/README.md@@ -6,22 +6,35 @@ Kiln turns a sentence into a game-ready GLB by having a model *write a program*,rendered, and fix it — not by sampling a mesh. The output is a small program with named parts, notan opaque blob: editable, diffable, parametric, and readable by the next agent that touches it.---Every asset above is a checked-in program in [`examples/`](examples/). No mesh was sampled, no-geometry was hand-authored, and none of it was touched in a DCC tool. A model wrote each one,-rendered it, looked at the result, and revised — which is also why each file's header comment reads-like a post-mortem.--| Asset | Tris | Authored by | What it exists to show |-|---|---|---|---|-| [`field-gun`](examples/field-gun.kiln.js) | 15,544 | Claude Opus 5 | booleans and arrays |-| [`street-lamp`](examples/street-lamp.kiln.js) | 13,036 | Claude Opus 5 | revolved profiles, emissive + glass |-| [`diving-helmet`](examples/diving-helmet.kiln.js) | 16,416 | Claude Opus 5 | material contrast |-| [`penny-farthing`](examples/penny-farthing.kiln.js) | 12,450 | Claude Opus 5 | curves and radial arrays |-| [`mech`](examples/mech.kiln.js) | 18,398 | Claude Opus 5 | armour oriented along a bone |-| [`arcade-cabinet`](examples/arcade-cabinet.kiln.js) | 19,916 | **Gemini 3.8 Flash** | silhouette from a swept profile |-| [`sushi-yatai`](examples/sushi-yatai.kiln.js) | 27,538 | Claude Opus 5 | repetition without looking generated |+Ten hero assets, each one a checked-in program in [`examples/`](examples/). Click any image for+the full-size render. No mesh was sampled, no geometry was hand-authored, and none of it was+touched in a DCC tool. A model wrote each program, rendered it, looked at the result, and revised+— which is also why each file's header comment reads like a post-mortem.++<table>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/field-gun.png"><img src="examples/renders/field-gun.png" alt="a Napoleonic field gun on a wooden carriage, generated by Kiln"></a><br><b><a href="examples/field-gun.kiln.js">field-gun</a></b><br>15,544 tris · Claude Opus 5<br><sub>booleans and arrays</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/street-lamp.png"><img src="examples/renders/street-lamp.png" alt="a cast-iron gas street lamp, generated by Kiln"></a><br><b><a href="examples/street-lamp.kiln.js">street-lamp</a></b><br>13,036 tris · Claude Opus 5<br><sub>revolved profiles, emissive + glass</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/diving-helmet.png"><img src="examples/renders/diving-helmet.png" alt="a brass standard diving helmet, generated by Kiln"></a><br><b><a href="examples/diving-helmet.kiln.js">diving-helmet</a></b><br>16,416 tris · Claude Opus 5<br><sub>material contrast</sub></td>+</tr>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/penny-farthing.png"><img src="examples/renders/penny-farthing.png" alt="a penny-farthing bicycle, generated by Kiln"></a><br><b><a href="examples/penny-farthing.kiln.js">penny-farthing</a></b><br>12,450 tris · Claude Opus 5<br><sub>curves and radial arrays</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/mech.png"><img src="examples/renders/mech.png" alt="a walking mech with plated limbs, generated by Kiln"></a><br><b><a href="examples/mech.kiln.js">mech</a></b><br>18,398 tris · Claude Opus 5<br><sub>armour oriented along a bone</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/arcade-cabinet.png"><img src="examples/renders/arcade-cabinet.png" alt="an upright arcade cabinet, generated by Kiln"></a><br><b><a href="examples/arcade-cabinet.kiln.js">arcade-cabinet</a></b><br>19,916 tris · <b>Gemini 3.8 Flash</b><br><sub>silhouette from a swept profile</sub></td>+</tr>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/sushi-store.png"><img src="examples/renders/sushi-store.png" alt="a two-storey Japanese sushi shopfront with a tiled roof, generated by Kiln"></a><br><b><a href="examples/sushi-store.kiln.js">sushi-store</a></b><br>24,082 tris · Claude Opus 5<br><sub>a facade as layered depth</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/cafe-racer.png"><img src="examples/renders/cafe-racer.png" alt="a cafe racer motorcycle, generated by Kiln"></a><br><b><a href="examples/cafe-racer.kiln.js">cafe-racer</a></b><br>16,410 tris · Claude Opus 5<br><sub>a tapered sweep along a curve</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/beam-engine.png"><img src="examples/renders/beam-engine.png" alt="a rotative beam engine, generated by Kiln"></a><br><b><a href="examples/beam-engine.kiln.js">beam-engine</a></b><br>15,396 tris · Claude Opus 5<br><sub>an animated four-bar linkage</sub></td>+</tr>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/lunar-lander.png"><img src="examples/renders/lunar-lander.png" alt="a lunar module on four legs, generated by Kiln"></a><br><b><a href="examples/lunar-lander.kiln.js">lunar-lander</a></b><br>13,208 tris · Claude Opus 5<br><sub>crumpled foil, and asymmetry on purpose</sub></td>+</tr>+</table>++Every shot above is regenerated by `bun scripts/hero-shots.ts`, straight from the checked-in+programs through the same PBR render port the agent loop uses. Nothing in this README was+retouched.The arcade cabinet is the one that matters most here. It was authored end to end by a **differentvendor's model in a different harness** — Gemini 3.8 Flash driving the same plugin through thediff --git a/examples/gallery.png b/examples/gallery.pngdeleted file mode 100644index 4b4a3a39..00000000Binary files a/examples/gallery.png and /dev/null differdiff --git a/scripts/hero-shots.ts b/scripts/hero-shots.tsnew file mode 100644index 00000000..2bf73e34--- /dev/null+++ b/scripts/hero-shots.ts@@ -0,0 +1,140 @@+/**+ * Render one beauty shot per hero example into `examples/renders/`.+ *+ * The README used to carry a single stitched contact-sheet collage. That was+ * the wrong artifact for two reasons: every asset got the same 380 px cell no+ * matter how much detail it had, and a reader who wanted to look closely at one+ * of them had no way to. So each hero now gets its own full-size PNG.+ *+ * This goes through the same PBR render port the `kiln render --views` path+ * uses, at a larger per-view size and with no cell label or axis gnomon, so the+ * output is a picture of the asset rather than a diagnostic sheet.+ *+ * bun scripts/hero-shots.ts # every hero+ * bun scripts/hero-shots.ts mech lunar-lander+ * bun scripts/hero-shots.ts --size 1400 --cpu+ *+ * Renders come off the port as raw RGB PNGs -- 8 MB each at 1200 px, which is+ * not something to put ten of in a git history for a README to load. They are+ * downscaled once and re-encoded at full compression on the way out, which is+ * also a free supersample: a 1200 px render shown at 1000 px is antialiased.+ */+import { mkdir, readFile, writeFile } from 'node:fs/promises';+import { basename, dirname, join, resolve } from 'node:path';+import { fileURLToPath } from 'node:url';++import sharp from 'sharp';++import { captureViewPngsViaPort } from '../src/agent/generate';+import { buildRenderPort } from '../src/cli-render-mode';+import { resolveEvaluatorPortV1 } from '../src/evaluator/protocol';++const HERE = dirname(fileURLToPath(import.meta.url));+const REPO = resolve(HERE, '..');+const EXAMPLES = join(REPO, 'examples');+const OUT_DIR = join(EXAMPLES, 'renders');++/**+ * The hero set, in the order the README presents them.+ *+ * Kept as an explicit list rather than a glob of `examples/*.kiln.js`, because+ * the examples directory also holds the small teaching programs (crate, well)+ * that are deliberately NOT heroes and should not appear in the gallery.+ */+const HEROES = [+ 'field-gun',+ 'diving-helmet',+ 'penny-farthing',+ 'street-lamp',+ 'mech',+ 'arcade-cabinet',+ 'sushi-store',+ 'cafe-racer',+ 'beam-engine',+ 'lunar-lander',+] as const;++/**+ * Slightly higher and further round than the contact sheet's 3/4 cell.+ *+ * The diagnostic 3/4 sits at [0.7, 0.5, 0.7] because it has to keep the front+ * readable next to five other cells. A single hero shot has no such duty, so it+ * can take the angle that actually flatters a silhouette: a touch more azimuth+ * to open up the side, a touch less elevation so the asset is not looked down+ * on. `zoom` is the frame padding — 1.06 leaves a hair of air at the edges.+ */+const HERO_DIR: [number, number, number] = [0.82, 0.44, 0.58];+const HERO_ZOOM = 1.06;++/** Width the shot is published at. Render size stays higher, for the downsample. */+const DISPLAY_PX = 1000;++function parseArgs(argv: string[]): { names: string[]; size: number; cpu: boolean } {+ const names: string[] = [];+ let size = 1200;+ let cpu = false;+ for (let i = 0; i < argv.length; i++) {+ const a = argv[i]!;+ if (a === '--size') size = Number(argv[++i]);+ else if (a === '--cpu') cpu = true;+ else if (a.startsWith('-')) throw new Error(`unknown flag ${a}`);+ else names.push(a.replace(/\.kiln\.js$/, ''));+ }+ if (!Number.isFinite(size) || size < 64 || size > 4096) {+ throw new Error(`--size must be between 64 and 4096, got ${size}`);+ }+ return { names: names.length ? names : [...HEROES], size, cpu };+}++async function main(): Promise<void> {+ const { names, size, cpu } = parseArgs(process.argv.slice(2));+ await mkdir(OUT_DIR, { recursive: true });++ const context = await buildRenderPort(cpu ? 'cpu' : 'auto', undefined);+ if (!context.viewRenderPort) {+ // The CPU rasterizer is geometry-flat: it draws shape, not materials. That+ // is the right fallback for an in-loop diagnostic and the wrong one for a+ // gallery image, so say so rather than quietly shipping grey renders.+ console.warn('no GPU render port — shots will be geometry-flat, not material-faithful');+ }+ const evaluator = resolveEvaluatorPortV1(undefined, 'trusted-local');++ for (const name of names) {+ const src = join(EXAMPLES, `${name}.kiln.js`);+ const code = await readFile(src, 'utf8');+ const rendered = await evaluator.render(code);++ let png: Uint8Array | undefined;+ if (context.viewRenderPort) {+ const ported = await captureViewPngsViaPort(+ context.viewRenderPort,+ rendered.glb,+ context.viewRenderTimeoutMs ?? 120_000,+ [HERO_DIR],+ size,+ );+ if (ported.ok) png = ported.pngs[0];+ else console.warn(` ${name}: port declined (${ported.reason}), falling back to CPU`);+ }+ if (!png) {+ const { renderGlbViewGrid } = await import('../src/views');+ const grid = await renderGlbViewGrid(rendered.glb, {+ capture: { preset: '1x1', cells: [{ azimuthDeg: 35, elevationDeg: 26, zoom: HERO_ZOOM }] },+ });+ png = grid.png;+ }++ const encoded = await sharp(Buffer.from(png))+ .resize(DISPLAY_PX)+ .png({ compressionLevel: 9, effort: 10 })+ .toBuffer();+ const out = join(OUT_DIR, `${name}.png`);+ await writeFile(out, encoded);+ console.log(+ ` ${basename(out)} ${DISPLAY_PX}px ${(encoded.byteLength / 1024).toFixed(0)} KB` ++ ` (from ${(png.byteLength / 1024 / 1024).toFixed(1)} MB raw)`,+ );+ }+}++await main();