Metadata-Version: 2.4
Name: kiln-gen
Version: 0.21.0
Summary: KILN (Keyed Implicit Language & Notation): write smooth stylised 3D models as text, build them into game-ready glTF.
Author: Lukas Golino
License-Expression: Apache-2.0
Project-URL: Homepage, https://kiln3d.dev/
Project-URL: Source, https://github.com/lukasgolino/kiln
Project-URL: Issues, https://github.com/lukasgolino/kiln/issues
Project-URL: Changelog, https://github.com/lukasgolino/kiln/blob/main/CHANGELOG.md
Keywords: 3d,gltf,godot,sdf,game-assets,mcp,procedural
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: Pillow>=10.1
Requires-Dist: PyYAML>=6
Requires-Dist: numpy>=1.26
Requires-Dist: fast-simplification>=0.2.0
Requires-Dist: fonttools>=4.40
Requires-Dist: mcp<3,>=2.3
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.15; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Requires-Dist: numba>=0.60; extra == "dev"
Requires-Dist: xatlas>=0.0.9; extra == "dev"
Provides-Extra: mcp
Provides-Extra: bake
Requires-Dist: xatlas>=0.0.9; extra == "bake"
Provides-Extra: fast
Requires-Dist: numba>=0.60; extra == "fast"
Dynamic: license-file

# KILN — Keyed Implicit Language & Notation

KILN turns text into smooth stylised 3D game models. An AI agent (or you) writes a model as a list of simple
shapes that blend into each other like clay; KILN meshes them, paints them from a palette, rigs and animates
them, and builds `.glb` files and Godot scenes. It's the 3D sibling of [PAGAN](https://github.com/lukasgolino/pagan)
(pixel art as text): Claude can't draw, but it can write, and KILN makes the writing into art. No paid
generators, no GPU, no Blender.

**Website:** https://kiln3d.dev/ (live 3D demo, docs). Sister libraries: [PAGAN](https://pagan.top/)
(pixel art) and [SEGAN](https://segan.top/) (audio).

![The demo models in Godot](https://raw.githubusercontent.com/lukasgolino/kiln/main/docs/showcase.png)

```yaml
name: pilot
class: character
parts:
  - capsule: { from: [0, 0.32, 0], to: [0, 0.74, 0], radius: 0.3 }    # the bean body
    color: red
    material: plastic
  - capsule: { from: [0.3, 0.6, 0], to: [0.42, 0.38, 0.08], radius: 0.08 }
    id: arm_l
    mirror: x
    mirror_id: arm_r
    blend: 0.04                                                    # melts into the body
    color: red
    material: plastic
  - sphere: { at: [0.1, 0.84, 0.23], radius: 0.1 }                  # big googly eyes
    mirror: x
    color: white
    material: plastic
rig:
  arm_l: { pivot: [0.3, 0.6, 0] }
skin: soft
animations:
  walk: { fps: 12, cycle: { type: waddle } }
```

> **Status:** 0.9, pre-1.0: notation, smooth and hard-surface meshing, painting (patterns, decals, palette atlas),
> rigs, soft and rigid skins, clip retargeting (humanoids, or any skeleton with a joint map), animations, effects, terrains (heightfields with splat layers), foliage scattering, five styles,
> previews, Godot export, lint, CC0 imports, a template library, a Claude skill and an MCP server.
> Bugs and requests: [GitHub issues](https://github.com/lukasgolino/kiln/issues).

## One model, any style

A project picks a **style**: how shapes become meshes (smooth or faceted), triangle budgets, material presets and
the look kit (lighting, tonemapping, outlines). The same model text below is soft toy (Dear Passengers, Fall Guys),
low poly and toon. Make your own from inspiration images.

![The same models in soft_toy, low_poly and toon](https://raw.githubusercontent.com/lukasgolino/kiln/main/docs/styles.png)

## Terrains

A model with `terrain:` is ground for a level: hills, ridges, plateaus, noise and paths combined in order, painted
with up to four palette colours by slope, height, nearness to paths and noise. It builds into chunked LOD meshes, a
splat map and a Godot scene with collision (`examples/terrain`).

![A 256 m terrain from above and from four sides](https://raw.githubusercontent.com/lukasgolino/kiln/main/docs/terrain.png)

## Foliage

A model with `scatter:` places other models many times over a terrain, another model's top or a flat area: density,
spacing, slope / height / noise / splat-layer / path rules, random turn, scale, lean and tint. KILN rolls every
instance at build time into a JSON file and a Godot scene of MultiMeshes with LODs (`examples/terrain`: `meadow`, `moss`).

![Trees, bushes, boulders, flowers and grass over the valley, and grass on a boulder](https://raw.githubusercontent.com/lukasgolino/kiln/main/docs/foliage.png)

## Install

Requires Python 3.11+.

```sh
pip install kiln-gen      # the package is kiln-gen on PyPI; the command and the import are `kiln`
kiln --version
```

Faster builds of big models: `kiln-gen[fast]` (numba). Its output differs from the plain install in the last float digits,
so a game pins one or the other in its requirements.

Development: `python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"`, then `pytest` and `mypy`.

## Quick start

```sh
kiln init my-game-art --style soft_toy    # kiln.toml, palette, BRIEF.md, STYLE.md, models/, styles/
cd my-game-art
kiln new model pilot --template bean      # a rigged bean character to edit
kiln lint                                 # errors and warnings with line numbers
kiln preview pilot                        # previews/pilot/turntable.png: 8 sides x 3 heights
kiln preview pilot --pose walk --closeup arm_l
kiln lineup                               # every model at one scale, with a 1 m bar
kiln build                                # build/models/pilot.glb + manifest.json
```

Every command takes `--json` and exits non-zero on errors. Previews render with KILN's own software renderer (no
GPU, no display); `kiln preview <model> --engine` renders through Godot.

## In Godot

`kiln init` inside a Godot project sets `export = ["glb", "godot"]` and `output_dir` to its `assets/kiln`; elsewhere set both by hand. Each model gets `models/<name>.tscn`
(the glb with the style's materials: toon bands, outlines, rim light) and each style a look kit
`looks/<style>.tscn` (sky, sun, tonemapper, SSAO, glow, colour grading).

```gdscript
add_child(load("res://assets/kiln/looks/soft_toy.tscn").instantiate())   # once per scene
var pilot: Node3D = load("res://assets/kiln/models/pilot.tscn").instantiate()
add_child(pilot)
pilot.get_node("AnimationPlayer").play("walk")
```

Humanoids can opt in to Godot's retargeting: `godot_bonemap = true` in kiln.toml writes a `BoneMap` on
`SkeletonProfileHumanoid` per humanoid and sets it in the glb's `.import`, so clips made for the profile play on them.
Godot then renames the skeleton's bones (`hips` -> `Hips`, `upperleg_l` -> `LeftUpperLeg`) and the skeleton node
(`%GeneralSkeleton`): game code that names KILN's bones must change, so it's off by default and reversible.

`kiln build --verify-godot` loads everything in headless Godot and checks parts, animations and materials.
`manifest.json` is the contract for any engine: files, sizes and bounds in metres, triangles, parts (pivots,
parents, gameplay metadata), animations, variants, LODs and licences. `examples/godot` is a runnable Godot 4.7
project showing the demo models.

## Other engines

The `.glb` files are plain glTF 2.0: Unity, Unreal, Bevy, three.js and Defold import them. Set `export = ["glb"]`.
[docs/engines.md](https://github.com/lukasgolino/kiln/blob/main/docs/engines.md) has per-engine notes (axes, scale, vertex colours, palette textures, animations,
LODs) and what's Godot-only (look kits, toon, outlines, rim light) with how to approximate it.

## Using KILN with Claude

```sh
kiln skill install        # copies the skill to .claude/skills/kiln/
```

Then ask: "make a bean pilot for my airline game", "make the knight's helmet detachable", "add a siege tower",
"make everything look more like these screenshots". The skill teaches the workflow: plan in metres, write parts,
lint, LOOK at the previews, check the line-up, report.

## From any agent (MCP)

```sh
claude mcp add kiln -- uvx kiln-gen mcp --project /path/to/art     # no install needed (uv); or `kiln mcp` after pip install
```

Other clients take the same command in their config:

```json
{ "mcpServers": { "kiln": { "command": "uvx", "args": ["kiln-gen", "mcp", "--project", "/path/to/art"] } } }
```

KILN is listed in the [MCP Registry](https://registry.modelcontextprotocol.io/) as `io.github.lukasgolino/kiln`.

Tools return the CLI's JSON; previews come back as images. Add `--allow-godot` for Godot verification and engine
renders.

## Free asset packs

For things text does badly (dense foliage, realistic rocks), bring in CC0 models (Kenney, KayKit, Quaternius):
`kiln import tree.glb --licence CC0-1.0 --author Kenney --height 4`. The build snaps their colours to your palette
and applies your style, so they match; `CREDITS.md` lists authors. With Blender 4.x installed (`blender` on PATH
or `BLENDER=/path/to/blender`), `kiln import` also takes .fbx, .blend and .obj and turns them into a glb; KILN itself
never needs Blender.

KILN ships recipes for some CC0 packs (Kenney, KayKit, Quaternius): `kiln pack add kaykit-adventurers` mirrors one
into a per-user cache (the only command that downloads), `kiln pack search knight --lineup` finds models by name and
tags, and `kiln pack import kaykit-adventurers knight --height 1.8` brings one in and records its files (pack,
version, URL, sha256, licence) in `kiln.lock`, which `kiln build` checks.

<!-- mcp-name: io.github.lukasgolino/kiln -->

## License

Apache 2.0 — see [LICENSE](https://github.com/lukasgolino/kiln/blob/main/LICENSE).
