spritekiln 0.1.0__tar.gz

spritekiln-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+
+# Rendered output and render cache (regenerated by the toolkit, never versioned)
+out/
+.kilncache/
+.pxcache/
+
+# Output of `ref prep` (cutout, palette and metrics derived from a splash art)
+specs/**/*_ref/
+
+# Godot editor metadata when testing the addon in place
+.godot/
+
+# .NET build output (MonoGame example and tests)
+bin/
+obj/

spritekiln-0.1.0/LICENSE

@@ -0,0 +1,38 @@
+MIT License
+
+Copyright (c) 2026 Lucas Ramos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+Scope
+
+The MIT license above covers the source code, documentation and integrations in
+this repository. Two groups of files are licensed differently; REUSE.toml maps
+every path to its license and LICENSES/ holds the full texts:
+
+- Example assets (gargoyle, cacador, the crates, gas lamp and training dummy
+  props, the humanoid template and the gothic/props palettes) are dedicated to
+  the public domain under CC0 1.0 (LICENSES/CC0-1.0.txt).
+- Showcase assets (the Templar and Huntress characters from the game Hunt
+  Tower, with the Huntress's mine: specs, splash arts, palettes, renders and
+  game captures) are
+  Copyright (c) 2026 Lucas Ramos / PlayRPG, all rights reserved. They are
+  included for demonstration only and are NOT licensed for reuse
+  (LICENSES/LicenseRef-Showcase.txt).

spritekiln-0.1.0/LICENSES/CC0-1.0.txt

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

spritekiln-0.1.0/LICENSES/LicenseRef-Showcase.txt

@@ -0,0 +1,18 @@
+Showcase assets: all rights reserved
+
+Copyright (c) 2026 Lucas Ramos / PlayRPG. All rights reserved.
+
+This applies to the files that REUSE.toml marks as "LicenseRef-Showcase": the
+Templar and Huntress characters from the game Hunt Tower and the Huntress's
+mine prop, including their specs, splash arts, palettes, rendered sprites,
+animations and game captures, and anything derived from them.
+
+These files are included in this repository for demonstration only. They are
+not licensed for reuse. You may view them, and you may run the toolkit on them
+on your own machine to evaluate the toolkit. You may not copy, modify,
+redistribute, or use them or works derived from them in any other project,
+commercial or not, without prior written permission from the copyright
+holders.
+
+The MIT license of the code and the CC0 dedication of the example assets do
+not apply to these files.

spritekiln-0.1.0/LICENSES/MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Ramos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spritekiln-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.5
+Name: spritekiln
+Version: 0.1.0
+Summary: Animated 8-direction pixel-art sprites from procedural 3D models described in YAML, built to be driven by coding AIs
+Project-URL: Homepage, https://github.com/LucasJRamos/spritekiln
+Project-URL: Issues, https://github.com/LucasJRamos/spritekiln/issues
+Author: Lucas Ramos
+License-Expression: MIT
+License-File: LICENSE
+License-File: LICENSES/CC0-1.0.txt
+License-File: LICENSES/LicenseRef-Showcase.txt
+License-File: LICENSES/MIT.txt
+Keywords: ai,gamedev,godot,pixel-art,procedural,sdf,sprites,spritesheet,top-down
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=10.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomli>=1.1; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: cryptography<49; (sys_platform == 'darwin' and platform_machine == 'x86_64') and extra == 'dev'
+Requires-Dist: jsonschema>=4.18; extra == 'dev'
+Requires-Dist: mcp<3,>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: cryptography<49; (sys_platform == 'darwin' and platform_machine == 'x86_64') and extra == 'mcp'
+Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
+Provides-Extra: splash
+Requires-Dist: rembg[cpu]; extra == 'splash'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/LucasJRamos/spritekiln/main/showcase/huntress/from_this_to_this.png" alt="A splash art of a gunslinger next to her pixel-art sprite in 8 directions" width="100%">
+</p>
+
+# SpriteKiln
+
+**English** | [Português (BR)](https://github.com/LucasJRamos/spritekiln/blob/main/README.pt-BR.md) | [한국어](https://github.com/LucasJRamos/spritekiln/blob/main/README.ko.md) | [日本語](https://github.com/LucasJRamos/spritekiln/blob/main/README.ja.md) | [简体中文](https://github.com/LucasJRamos/spritekiln/blob/main/README.zh-CN.md)
+
+**Animated pixel-art sprites from procedural 3D models, made to be driven by coding AIs.**
+
+A character is a small YAML file: a skeleton, smooth 3D shapes, materials and animations. SpriteKiln renders
+it into pixel art in 8 directions (top-down 3/4) or in profile (side view), with exact frame timing,
+gameplay events, attachment points, a normal map for dynamic light and an emissive layer, ready for Godot,
+Unity, MonoGame or any engine that reads Aseprite sheets.
+
+You do not have to write the YAML. Your coding assistant (Claude Code, Codex, Gemini, Copilot, Cursor) does,
+from a description or a splash art: it edits the spec, renders, **looks at the images** and fixes what it
+sees. You direct.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/LucasJRamos/spritekiln/main/showcase/huntress/turnaround.gif" alt="The Huntress idling in 8 directions" height="220">
+  <img src="https://raw.githubusercontent.com/LucasJRamos/spritekiln/main/showcase/templar/turnaround.gif" alt="The Templar idling in 8 directions" height="220">
+  <img src="https://raw.githubusercontent.com/LucasJRamos/spritekiln/main/docs/images/tutorials/platformer-run.gif" alt="Wren, a side-view platformer character, running in both profiles" height="220">
+</p>
+
+## Why
+- **Consistent by construction.** One camera, one light and one palette for every asset, in every
+  direction and frame. No drift between the north-east walk and the south-west attack.
+- **Cheap to change.** "Make the hat bigger" or "slow down the windup" is a one-line edit, not a redraw of
+  300 frames.
+- **Game-ready.** Per-frame durations, events (`hit`, `step_l`, `windup`) on the right frame, sockets
+  (muzzles, hands, impact points), the pivot on the ground for y-sorting, normal and emissive maps.
+- **Made for AIs.** One set of instructions for every assistant, an MCP server whose tools return images,
+  a JSON Schema for the spec, errors with `file:line:column`, and an art-direction review in numbers for
+  assistants that cannot see.
+- **Pure Python, any OS.** numpy, Pillow and PyYAML; no GPU, no Blender. Tested on Windows, macOS and
+  Linux.
+
+## Install
+
+Python 3.10 or newer. Install the `spritekiln` command with [pipx](https://pipx.pypa.io), which keeps it
+isolated and on your PATH:
+
+**Windows** (PowerShell; no Python yet? `winget install Python.Python.3.13`, then open a new terminal)
+
+```powershell
+py -m pip install --user pipx
+py -m pipx ensurepath
+py -m pipx install "spritekiln[mcp]"
+```
+
+**macOS** (Terminal, with [Homebrew](https://brew.sh))
+
+```bash
+brew install pipx
+pipx ensurepath
+pipx install "spritekiln[mcp]"
+```
+
+**Linux** (Debian/Ubuntu shown; Fedora: `sudo dnf install pipx`, Arch: `sudo pacman -S python-pipx`)
+
+```bash
+sudo apt install pipx
+pipx ensurepath
+pipx install "spritekiln[mcp]"
+```
+
+Then open a new terminal and check with `spritekiln --version`. `[mcp]` adds the tools for AI assistants;
+`pipx install spritekiln` is enough for the command line alone. uv, a virtual environment, upgrading and
+troubleshooting: [Install SpriteKiln](https://github.com/LucasJRamos/spritekiln/blob/main/docs/tutorials/install.md).
+
+## Quick start
+
+The same on every system:
+
+```
+spritekiln new knight                                   # specs/characters/knight/knight.yaml, from the template
+spritekiln render specs/characters/knight/knight.yaml   # atlas, JSON, maps, GIFs -> specs/characters/knight/out/knight/
+```
+
+Then hand it to your assistant: *"Turn this knight into a hooded goblin scout with a short sword. Check
+all 8 directions before rendering."* To set up a game project, run
+`spritekiln init --engine godot --ai claude` in its folder; see
+[Use SpriteKiln with your AI](https://github.com/LucasJRamos/spritekiln/blob/main/docs/tutorials/use-with-your-ai.md).
+
+## How it works
+
+```
+spec.yaml ──► skeleton + IK ──► SDF shapes ──► raymarched render ──► pixelize ──► atlas + JSON
+ (bones,      (expressions per   (spheres,      (colour, normals,     (palette ramps,   + normal map
+  shapes,      frame: cycles,     capsules,      depth, materials;     outlines, clean   + emissive map
+  materials,   keys, events)      boxes, cones,  3x supersampled,      single pixels)    + GIFs, QA
+  animations)                     smooth unions) fixed world light)                      -> your engine
+```
+
+The light is fixed in the world and the model turns, so shading stays coherent across directions. Every
+render writes a QA report (clipping, palette, silhouette stability) and contact sheets to review.
+
+## Features
+- **Modeling:** bones with expressions (`"0.045*sin(p)"`), 2-bone IK, smooth SDF primitives, mirrored
+  `_L`/`_R` parts, materials with palette ramps, emissive and glow, two-sided membranes, conditional parts.
+- **Animation:** cycles from expressions or keyframes with per-frame timing, tweens and easing, smears,
+  per-direction cheats, events, timing targets checked by `validate` (e.g. "impact at 300 ms").
+- **Views:** top-down 3/4 in 8 (or 4, or 1) directions, or a side view for platformers (`view: side`, with
+  a template that has run, jump, rise, fall and land); `mirror: true` renders only the right-facing
+  directions (the engine flips the rest) for symmetric designs.
+- **From a splash art:** `ref prep` cuts the character out and extracts its palette; `ref compare` scores
+  the silhouette against the model (pitch-corrected IoU) and says what to change.
+- **Review:** `spritekiln review` measures value range, contrast, pixels per material and legibility, and
+  previews the sprite over your game's floor (`--bg`) under its light (`--tint`).
+- **Output:** atlas, normal and emissive maps, Aseprite-compatible JSON ([format](https://github.com/LucasJRamos/spritekiln/blob/main/docs/format.md)), sockets
+  per frame, GIFs and contact sheets.
+
+## Engines
+
+| Engine | What you get | Guide |
+|---|---|---|
+| **Godot 4** | `KilnSprite2D` node, SpriteFrames and a ready scene; an editor plugin builds them from a dropped JSON | [godot.md](https://github.com/LucasJRamos/spritekiln/blob/main/docs/engines/godot.md) · [example](https://github.com/LucasJRamos/spritekiln/blob/main/examples/godot) |
+| **Unity 2022.3+** | UPM package: `.kiln` importer (sprites, normal map, AnimationClips) and `KilnAnimator` | [unity.md](https://github.com/LucasJRamos/spritekiln/blob/main/docs/engines/unity.md) |
+| **MonoGame** | `KilnSprite.cs` runtime and the `KilnLit.fx` normal-mapped light shader | [monogame.md](https://github.com/LucasJRamos/spritekiln/blob/main/docs/engines/monogame.md) · [example](https://github.com/LucasJRamos/spritekiln/blob/main/examples/monogame) |
+| **Anything else** | Aseprite-compatible JSON: Phaser, LÖVE, Defold, GameMaker... | [generic.md](https://github.com/LucasJRamos/spritekiln/blob/main/docs/engines/generic.md) |
+
+All runtimes play the same way: exact durations, events on the frame they belong to, sockets, the direction
+nearest to a velocity, mirrored directions.
+
+## AI assistants
+
+| Assistant | Instructions | MCP tools |
+|---|---|---|
+| Claude Code | `CLAUDE.md`, skills, and modeler / animator / art-director agents | `.mcp.json` |
+| Codex | `AGENTS.md` | `~/.codex/config.toml` |
+| Gemini CLI | `GEMINI.md` | `.gemini/settings.json` |
+| GitHub Copilot | `.github/copilot-instructions.md` | `.vscode/mcp.json` |
+| Cursor | `.cursor/rules/spritekiln.mdc` | `.cursor/mcp.json` |
+
+`spritekiln init --ai claude,codex,...` writes them from one source ([`docs/agent/`](https://github.com/LucasJRamos/spritekiln/blob/main/docs/agent)). The
+recipe for a new character from a splash art: a modeler builds the shape, an art director reviews it
+against the art, the modeler fixes, an animator animates, the director reviews again
+([recipe.md](https://github.com/LucasJRamos/spritekiln/blob/main/docs/agent/recipe.md)).
+
+## Showcase
+The Templar and the Huntress were made with SpriteKiln for the game **Hunt Tower**, from their splash arts,
+by Claude Code following the recipe above. Their specs are in `specs/characters/`; more images, animations
+and in-game captures are in [`showcase/`](https://github.com/LucasJRamos/spritekiln/blob/main/showcase).
+
+## Learn more
+- [Install SpriteKiln](https://github.com/LucasJRamos/spritekiln/blob/main/docs/tutorials/install.md) (Windows, macOS, Linux; pipx, uv or a virtual environment)
+- [Your first character in 10 minutes](https://github.com/LucasJRamos/spritekiln/blob/main/docs/tutorials/first-character.md)
+- [From your splash art, with an AI](https://github.com/LucasJRamos/spritekiln/blob/main/docs/tutorials/splash-art.md)
+- [Animations and events](https://github.com/LucasJRamos/spritekiln/blob/main/docs/tutorials/animations.md)
+- [A platformer character (side view)](https://github.com/LucasJRamos/spritekiln/blob/main/docs/tutorials/platformer.md)
+- [Use SpriteKiln with your AI](https://github.com/LucasJRamos/spritekiln/blob/main/docs/tutorials/use-with-your-ai.md) (instructions files and MCP tools)
+- [Spec reference](https://github.com/LucasJRamos/spritekiln/blob/main/docs/agent/spec.md) · [Output format](https://github.com/LucasJRamos/spritekiln/blob/main/docs/format.md) · [Roadmap](https://github.com/LucasJRamos/spritekiln/blob/main/docs/ROADMAP.md)
+- [Contributing](https://github.com/LucasJRamos/spritekiln/blob/main/CONTRIBUTING.md) · [Changelog](https://github.com/LucasJRamos/spritekiln/blob/main/CHANGELOG.md) · Translations: [Português (BR)](https://github.com/LucasJRamos/spritekiln/blob/main/README.pt-BR.md), [한국어](https://github.com/LucasJRamos/spritekiln/blob/main/README.ko.md), [日本語](https://github.com/LucasJRamos/spritekiln/blob/main/README.ja.md),
+  [简体中文](https://github.com/LucasJRamos/spritekiln/blob/main/README.zh-CN.md)
+
+## License
+Code, docs and integrations: [MIT](https://github.com/LucasJRamos/spritekiln/blob/main/LICENSE). Example assets (the gargoyle, the hunter, Wren, the crates, gas lamp
+and training dummy props, the templates, the gothic and props palettes, the examples' sprites):
+[CC0 1.0](https://github.com/LucasJRamos/spritekiln/blob/main/LICENSES/CC0-1.0.txt). Showcase assets (Templar and Huntress from Hunt Tower, with the Huntress's
+mine: specs, splash arts, palettes, renders and game captures): © 2026 Lucas Ramos / PlayRPG, all rights
+reserved, included for demonstration only ([terms](https://github.com/LucasJRamos/spritekiln/blob/main/LICENSES/LicenseRef-Showcase.txt)).
+[`REUSE.toml`](https://github.com/LucasJRamos/spritekiln/blob/main/REUSE.toml) maps every path to its license.

spritekiln-0.1.0/README.md

@@ -0,0 +1,163 @@
+<p align="center">
+  <img src="showcase/huntress/from_this_to_this.png" alt="A splash art of a gunslinger next to her pixel-art sprite in 8 directions" width="100%">
+</p>
+
+# SpriteKiln
+
+**English** | [Português (BR)](README.pt-BR.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
+
+**Animated pixel-art sprites from procedural 3D models, made to be driven by coding AIs.**
+
+A character is a small YAML file: a skeleton, smooth 3D shapes, materials and animations. SpriteKiln renders
+it into pixel art in 8 directions (top-down 3/4) or in profile (side view), with exact frame timing,
+gameplay events, attachment points, a normal map for dynamic light and an emissive layer, ready for Godot,
+Unity, MonoGame or any engine that reads Aseprite sheets.
+
+You do not have to write the YAML. Your coding assistant (Claude Code, Codex, Gemini, Copilot, Cursor) does,
+from a description or a splash art: it edits the spec, renders, **looks at the images** and fixes what it
+sees. You direct.
+
+<p align="center">
+  <img src="showcase/huntress/turnaround.gif" alt="The Huntress idling in 8 directions" height="220">
+  <img src="showcase/templar/turnaround.gif" alt="The Templar idling in 8 directions" height="220">
+  <img src="docs/images/tutorials/platformer-run.gif" alt="Wren, a side-view platformer character, running in both profiles" height="220">
+</p>
+
+## Why
+- **Consistent by construction.** One camera, one light and one palette for every asset, in every
+  direction and frame. No drift between the north-east walk and the south-west attack.
+- **Cheap to change.** "Make the hat bigger" or "slow down the windup" is a one-line edit, not a redraw of
+  300 frames.
+- **Game-ready.** Per-frame durations, events (`hit`, `step_l`, `windup`) on the right frame, sockets
+  (muzzles, hands, impact points), the pivot on the ground for y-sorting, normal and emissive maps.
+- **Made for AIs.** One set of instructions for every assistant, an MCP server whose tools return images,
+  a JSON Schema for the spec, errors with `file:line:column`, and an art-direction review in numbers for
+  assistants that cannot see.
+- **Pure Python, any OS.** numpy, Pillow and PyYAML; no GPU, no Blender. Tested on Windows, macOS and
+  Linux.
+
+## Install
+
+Python 3.10 or newer. Install the `spritekiln` command with [pipx](https://pipx.pypa.io), which keeps it
+isolated and on your PATH:
+
+**Windows** (PowerShell; no Python yet? `winget install Python.Python.3.13`, then open a new terminal)
+
+```powershell
+py -m pip install --user pipx
+py -m pipx ensurepath
+py -m pipx install "spritekiln[mcp]"
+```
+
+**macOS** (Terminal, with [Homebrew](https://brew.sh))
+
+```bash
+brew install pipx
+pipx ensurepath
+pipx install "spritekiln[mcp]"
+```
+
+**Linux** (Debian/Ubuntu shown; Fedora: `sudo dnf install pipx`, Arch: `sudo pacman -S python-pipx`)
+
+```bash
+sudo apt install pipx
+pipx ensurepath
+pipx install "spritekiln[mcp]"
+```
+
+Then open a new terminal and check with `spritekiln --version`. `[mcp]` adds the tools for AI assistants;
+`pipx install spritekiln` is enough for the command line alone. uv, a virtual environment, upgrading and
+troubleshooting: [Install SpriteKiln](docs/tutorials/install.md).
+
+## Quick start
+
+The same on every system:
+
+```
+spritekiln new knight                                   # specs/characters/knight/knight.yaml, from the template
+spritekiln render specs/characters/knight/knight.yaml   # atlas, JSON, maps, GIFs -> specs/characters/knight/out/knight/
+```
+
+Then hand it to your assistant: *"Turn this knight into a hooded goblin scout with a short sword. Check
+all 8 directions before rendering."* To set up a game project, run
+`spritekiln init --engine godot --ai claude` in its folder; see
+[Use SpriteKiln with your AI](docs/tutorials/use-with-your-ai.md).
+
+## How it works
+
+```
+spec.yaml ──► skeleton + IK ──► SDF shapes ──► raymarched render ──► pixelize ──► atlas + JSON
+ (bones,      (expressions per   (spheres,      (colour, normals,     (palette ramps,   + normal map
+  shapes,      frame: cycles,     capsules,      depth, materials;     outlines, clean   + emissive map
+  materials,   keys, events)      boxes, cones,  3x supersampled,      single pixels)    + GIFs, QA
+  animations)                     smooth unions) fixed world light)                      -> your engine
+```
+
+The light is fixed in the world and the model turns, so shading stays coherent across directions. Every
+render writes a QA report (clipping, palette, silhouette stability) and contact sheets to review.
+
+## Features
+- **Modeling:** bones with expressions (`"0.045*sin(p)"`), 2-bone IK, smooth SDF primitives, mirrored
+  `_L`/`_R` parts, materials with palette ramps, emissive and glow, two-sided membranes, conditional parts.
+- **Animation:** cycles from expressions or keyframes with per-frame timing, tweens and easing, smears,
+  per-direction cheats, events, timing targets checked by `validate` (e.g. "impact at 300 ms").
+- **Views:** top-down 3/4 in 8 (or 4, or 1) directions, or a side view for platformers (`view: side`, with
+  a template that has run, jump, rise, fall and land); `mirror: true` renders only the right-facing
+  directions (the engine flips the rest) for symmetric designs.
+- **From a splash art:** `ref prep` cuts the character out and extracts its palette; `ref compare` scores
+  the silhouette against the model (pitch-corrected IoU) and says what to change.
+- **Review:** `spritekiln review` measures value range, contrast, pixels per material and legibility, and
+  previews the sprite over your game's floor (`--bg`) under its light (`--tint`).
+- **Output:** atlas, normal and emissive maps, Aseprite-compatible JSON ([format](docs/format.md)), sockets
+  per frame, GIFs and contact sheets.
+
+## Engines
+
+| Engine | What you get | Guide |
+|---|---|---|
+| **Godot 4** | `KilnSprite2D` node, SpriteFrames and a ready scene; an editor plugin builds them from a dropped JSON | [godot.md](docs/engines/godot.md) · [example](examples/godot) |
+| **Unity 2022.3+** | UPM package: `.kiln` importer (sprites, normal map, AnimationClips) and `KilnAnimator` | [unity.md](docs/engines/unity.md) |
+| **MonoGame** | `KilnSprite.cs` runtime and the `KilnLit.fx` normal-mapped light shader | [monogame.md](docs/engines/monogame.md) · [example](examples/monogame) |
+| **Anything else** | Aseprite-compatible JSON: Phaser, LÖVE, Defold, GameMaker... | [generic.md](docs/engines/generic.md) |
+
+All runtimes play the same way: exact durations, events on the frame they belong to, sockets, the direction
+nearest to a velocity, mirrored directions.
+
+## AI assistants
+
+| Assistant | Instructions | MCP tools |
+|---|---|---|
+| Claude Code | `CLAUDE.md`, skills, and modeler / animator / art-director agents | `.mcp.json` |
+| Codex | `AGENTS.md` | `~/.codex/config.toml` |
+| Gemini CLI | `GEMINI.md` | `.gemini/settings.json` |
+| GitHub Copilot | `.github/copilot-instructions.md` | `.vscode/mcp.json` |
+| Cursor | `.cursor/rules/spritekiln.mdc` | `.cursor/mcp.json` |
+
+`spritekiln init --ai claude,codex,...` writes them from one source ([`docs/agent/`](docs/agent)). The
+recipe for a new character from a splash art: a modeler builds the shape, an art director reviews it
+against the art, the modeler fixes, an animator animates, the director reviews again
+([recipe.md](docs/agent/recipe.md)).
+
+## Showcase
+The Templar and the Huntress were made with SpriteKiln for the game **Hunt Tower**, from their splash arts,
+by Claude Code following the recipe above. Their specs are in `specs/characters/`; more images, animations
+and in-game captures are in [`showcase/`](showcase).
+
+## Learn more
+- [Install SpriteKiln](docs/tutorials/install.md) (Windows, macOS, Linux; pipx, uv or a virtual environment)
+- [Your first character in 10 minutes](docs/tutorials/first-character.md)
+- [From your splash art, with an AI](docs/tutorials/splash-art.md)
+- [Animations and events](docs/tutorials/animations.md)
+- [A platformer character (side view)](docs/tutorials/platformer.md)
+- [Use SpriteKiln with your AI](docs/tutorials/use-with-your-ai.md) (instructions files and MCP tools)
+- [Spec reference](docs/agent/spec.md) · [Output format](docs/format.md) · [Roadmap](docs/ROADMAP.md)
+- [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · Translations: [Português (BR)](README.pt-BR.md), [한국어](README.ko.md), [日本語](README.ja.md),
+  [简体中文](README.zh-CN.md)
+
+## License
+Code, docs and integrations: [MIT](LICENSE). Example assets (the gargoyle, the hunter, Wren, the crates, gas lamp
+and training dummy props, the templates, the gothic and props palettes, the examples' sprites):
+[CC0 1.0](LICENSES/CC0-1.0.txt). Showcase assets (Templar and Huntress from Hunt Tower, with the Huntress's
+mine: specs, splash arts, palettes, renders and game captures): © 2026 Lucas Ramos / PlayRPG, all rights
+reserved, included for demonstration only ([terms](LICENSES/LicenseRef-Showcase.txt)).
+[`REUSE.toml`](REUSE.toml) maps every path to its license.