8000 GitHub - CDM172/kiln: Text-to-3D as code: language models write JavaScript programs that build game-ready GLBs, look at their own renders, and revise. Ships as an MCP server plus skills for any harness. · GitHub
[go: up one dir, main page]

Skip to content
CDM172Public
forked from instruktlabs/kiln

About

Text-to-3D as code: language models write JavaScript programs that build game-ready GLBs, look at their own renders, and revise. Ships as an MCP server plus skills for any harness.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

 
 

Latest commit

 

History

186 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Kiln

CI License: MIT

Build and revise 3D assets with your coding agent.

The agent writes JavaScript using Kiln's geometry and material helpers. Kiln runs the program and returns rendered views and structural checks so the agent can review its work. Export the asset as a GLB and keep the source for later changes.

Kiln runs locally. It includes an MCP server, a CLI, a TypeScript library, and skills for authoring, editing, animation review, and scene composition. Your agent supplies the model; Kiln does not require a separate model API key for its tools.

kiln-launch.mp4

Kiln 27-asset collection

Click the gallery banner above or select an asset below to explore in interactive 3D:
Typewriter · Solar Sail Courier · Mechanical Peacock · Kestrel Rescue · Anglerfish · Kinetic Wave · Orrery · Orbital Station · Deco Radio · Cathedral · Steam Locomotive · Lighthouse · Alpine Cable Terminal · Research Vessel · Sushi Store · Windmill · Tram · Ribbon Tea Pavilion · Diesel Locomotive · Art Deco Conservatory · Floating Observatory · Deep Sea Station · Unfolding Dragonfly · Vintage Typewriter · Argent Carrier · Noctilus Submarine · Resolute Flagship

Mechanical peacock · Claude Opus 5 Unfolding dragonfly · GPT-6 Astra Solar sail courier · Gemini 3.8 Flash
Mechanical peacock with articulated jewel fan Clockwork dragonfly with unfolding wings and gears Solar sail courier deploying origami gold sails

Browse the interactive gallery · All examples and model credits

These are saved examples from different authoring runs, not a model ranking. Credits, review conditions and build records.

Start with the installation guide for a built package on macOS, Windows, or Linux. It uses Node.js and creates a project-local agent setup. Package checks pass on Windows, Linux, and hosted macOS runners for Apple Silicon and Intel. See the platform receipts; real-world setup reports and GPU checks remain welcome from contributors.

Run from a checkout

Install Bun, then:

git clone --filter=blob:none https://github.com/matthew-kissinger/kiln
cd kiln
bun install --frozen-lockfile
bun run kiln render examples/crate.kiln.js --out crate.glb --views sheet.png

--filter=blob:none checks out the current tree in full and leaves historical file contents on the server, fetching them only if you ask for an old revision. A plain git clone also works and gives you the whole history up front.

History was rewritten on 2026-09-10 to drop 288 MB of gallery renders and launch video that no tool reads, taking a clone from 440 MB and 79 seconds to 52 MB and 8 seconds, or 48 MB with --filter=blob:none. Every commit survived and the tree is unchanged apart from those files, but every commit hash changed, so a clone made before that date cannot fast-forward. Re-clone, or discard local history with git fetch origin && git reset --hard origin/main. The gallery images are served from assets.kilnstudio.tools; the 83 poster receipts that attest their bytes stayed in examples/renders/.

This writes a GLB and a six-view image of an existing program. It makes no model call. Rendering uses the CPU unless a compatible local GPU service is available. Use --render cpu to select the CPU explicitly.

Connect your agent

The agent reading guide links to setup, tool schemas and the source revision workflow in plain text.

Create a separate directory for your assets. The setup command writes project-local configuration and copies the Kiln skills; it does not change your global settings.

bun run build:runtime
node scripts/create-workspace.mjs ../my-assets --harness opencode
cd ../my-assets
# Follow START.md for your harness

Choose claude, codex, opencode, hermes, or agy for --harness, then open that harness in the new directory using its generated START.md instructions and accept its project and MCP trust prompts. Sign in to your harness first. The MCP server and local CLI are tested on Node.js 22.23.1.

Try: “Read AGENTS.md, then make a wooden workbench with a lower shelf. Render it, review the result, and save the source and GLB.”

Setup installs the core authoring, refinement and QA skills. Composition and batch workflows are opt-in.

The workspace contains your brief, assets, and skills. The engine source and example collection stay in the installation directory. See clean-room setup for the exact boundaries and headless use, or installation for other harnesses and the plugin path.

For Google models, see Antigravity and Gemini setup. Local coding agents use stdio directly; browser chat connections have different setup requirements.

Revise an asset

Save finished work into a collection with node kiln.mjs save workbench.kiln.js --name "Workbench". Run node kiln.mjs view to browse saved assets, inspect revisions, and download GLBs or editable ZIP bundles. Project collections and personal libraries use the same portable folders. See saved assets and the viewer.

Use Kiln in a chat client

Create and refine assets in ChatGPT through a private MCP connection, then ask to see a saved revision. kiln_present opens an interactive 3D card in supporting MCP App clients. Orbit the model and inspect its animation without leaving chat. ChatGPT viewing was verified with real saved assets.

  1. Build the runtime and connect its stdio MCP server through an OpenAI Secure MCP Tunnel scoped to your workspace.
  2. Install the authoring and refinement skills with their reference files using ChatGPT's native skill uploader.
  3. Ask: “Make a field recorder, review the renders, save it to my project collection, and show it with kiln_present.”

The ChatGPT setup guide covers connection, skill packaging, and host requirements. This currently needs developer setup; it is not a public one-click ChatGPT app. Local GLB and editable ZIP downloads work through kiln view. ChatGPT-native GLB/ZIP attachments remain unverified; download support depends on the client or a host-provided delivery link.

Restore source for another edit

Import an existing program from your asset workspace:

node kiln.mjs source workbench.kiln.js

The command prints a short programRef, such as p_7c94a132b8e0, identifying that exact source. Copy it exactly for later calls:

// programRef is the value returned by Kiln.
kiln_source({ programRef, query: "shelfHeight" })
kiln_edit({
  programRef,
  edits: [{ oldString: "shelfHeight = 0.2", newString: "shelfHeight = 0.35" }]
})

kiln_source reads a bounded portion of the source. kiln_edit applies the changes and renders the result, returning a new reference and a diff. The original revision remains available. Text outside the replacements stays unchanged, and a failed edit does not modify the base.

Save the new revision and export it without copying its source through the model:

node kiln.mjs source RETURNED_REF --out workbench-v2.kiln.js
node kiln.mjs render RETURNED_REF --out workbench-v2.glb --views workbench-v2.png

Replace RETURNED_REF with the new reference from the edit. Short references survive local server restarts while you keep the workspace's store. Full SHA-256 references are still accepted. Inline code still works for new drafts and existing integrations. Program storage and API details.

Shape geometry and choose views

Keep equations and custom modeling functions in the program. For example, this samples a curved sheet; the complete canopy example adds its material, posts and sockets.

const surface = parametricSurface(
  (u, v) => [u, 1.35 + 0.22 * Math.sin(u * 2) + 0.12 * v * v, v],
  { u: [-1.6, 1.6], v: [-0.8, 0.8],
    uSegments: 48, vSegments: 24, orientation: 'vu' }
);

Use meshGeo for explicit topology, or shape existing geometry with bends, twists, lofts and sweeps. Geometry contracts and limits.

To check an attachment, request a close-up beside a whole-asset view. Reuse the programRef and exact partPath from the render result:

kiln_render({ programRef, capture: {
  version: 'kiln.capture.v1', cols: 2,
  shots: [
    { name: 'Whole asset' },
    { name: 'Attachment', subject: { path: partPath },
      visibility: 'context', camera: { type: 'orbit', relativeTo: 'part',
        azimuthDeg: 65, elevationDeg: -18, padding: 3 } }
  ]
}});

The close-up follows the part's local axes while retaining surrounding geometry. You can also set explicit camera positions, return separate images, or sample animation frames. Camera controls.

Tool reference

Use kiln_list_primitives to discover signatures and examples. The generated tool reference covers source editing, validation, rendering, part inspection, animation and interior views. The shared factory is createKilnProgramToolRegistry in @kiln/engine/tools.

Uses and limitations

The examples cover props, machinery, vehicles, buildings and rigid-part animation. Programs are useful when you want named parts, adjustable dimensions and repeatable variants. Organic shapes and detailed character work are less well demonstrated. Kiln is not a reconstruction tool: a reference image does not establish unseen geometry.

Structural checks help find problems, but do not establish visual quality or suitability for a particular game. Review scale, performance, collision and appearance in your target scene. The CPU renderer shows geometry and base colours; inspect viewFidelity before judging textures or PBR materials. GPU setup and materials.

Development

bun run typecheck
bun run lint
bun run test
bun run test:coverage

Tests run without model calls and use CPU rendering. Coverage thresholds are checked in CI. Runtime changes to the MCP server or CLI must also rebuild their committed bundles:

bun run build:runtime

For bug reports, include the smallest program that reproduces the problem and the render or error you saw. CONTRIBUTING.md covers setup, checks and pull requests; AGENTS.md covers repository conventions.

Kiln began as the engine behind Kiln Studio. The hosted product has retired; this repository contains the open-source engine and local tools.

MIT licensed. Built by Matthew Kissinger.

About

Text-to-3D as code: language models write JavaScript programs that build game-ready GLBs, look at their own renders, and revise. Ships as an MCP server plus skills for any harness.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0