# 🎨 Pixel Art AI

[![Version](https://img.shields.io/badge/version-0.1.0-blue)](CHANGELOG.md)
[![Python Version](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP Protocol](https://img.shields.io/badge/MCP-2.0+-green)](https://modelcontextprotocol.io/)
[![Powered by Aseprite](https://img.shields.io/badge/Powered%20by-Aseprite%201.3+-orange)](https://www.aseprite.org/)

> A vendor-neutral, cross-agent **Pixel Art AI system** powered by [Aseprite](https://www.aseprite.org/) and the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).  
> Equips AI agents (**Claude Code**, **Codex**, **Google Antigravity**, **Cursor**) with deterministic drawing tools, multimodal visual feedback, objective pixel analyzers, and multi-layer game animation pipelines.

[📖 繁體中文說明文件 (Traditional Chinese Document)](README_zh.md)

---

## 🌟 Hero Showcase: Real-Time Combat Encounter

<p align="center">
  <img src="docs/assets/demo.gif" width="640" alt="Pixel Art AI Combat Encounter" />
  <br>
  <em>80x32 Multi-Layer Real-Time Battle: Walk ➔ Knight Slash vs Slime Dodge ➔ Acid Spit vs Hurt ➔ Holy Cleave vs Burst Death</em>
</p>

---

## ✨ Key Features

* 🖌️ **Native Aseprite Engine**: Headless, deterministic execution via audited Lua scripting for canvas, layers, frames, and timeline tags.
* 🛡️ **Multi-Layer Separation**: Native 4-layer architecture (`shadow`, `body`, `weapon`/`core`, `fx`) directly compatible with Godot and Unity.
* 🤖 **Cross-Agent MCP 2.0+**: One-click configuration for Claude Code, Codex, Antigravity, and Cursor via stdio or streamable HTTP.
* 🔍 **Multimodal Visual Feedback**: Nearest-neighbor scaled previews (`preview_generate`) and pixel-exact diff heatmaps (`preview_diff`).
* 🎨 **Declarative Style Engine**: Automated validation (`style_validate`) against strict YAML palette and clustering rules (Game Boy, PICO-8, SNES).

---

## 🚀 Quick Start (5 Minutes)

### Prerequisites
1. **Python**: `>= 3.11`
2. **Aseprite**: `>= 1.3.0` (Installed via Steam or official installer)

### Installation
```bash
# Recommended via uv
uv tool install pixel-art-ai

# Or via standard pip
pip install pixel-art-ai
```

### System Check & Agent Setup
```bash
# 1. Verify Aseprite installation and workspace paths
pixel-art-ai doctor

# 2. Automatically configure your AI coding agent
pixel-art-ai setup --agent claude-code
pixel-art-ai setup --agent antigravity

# 3. Start the MCP server (stdio transport)
pixel-art-ai serve
```

---

## ⚔️ Game Action Matrix & Spritesheets

`pixel-art-ai` generates complete multi-layer game action sequences tagged directly inside `.aseprite` documents:

| Entity | Complete Action GIF | Packed Spritesheet Strip | Aseprite Source Document |
| :--- | :---: | :---: | :---: |
| **Hero Knight** | <img src="docs/assets/character_actions.gif" width="160" alt="Knight Actions" style="image-rendering: pixelated;" /> | <img src="docs/assets/character_sheet.png" width="280" alt="Knight Sheet" style="image-rendering: pixelated;" /> | [`character_actions.aseprite`](docs/assets/character_actions.aseprite)<br>*(4 Layers / 7 Tags / 24 Frames)* |
| **Acid Slime** | <img src="docs/assets/monster_actions.gif" width="160" alt="Slime Actions" style="image-rendering: pixelated;" /> | <img src="docs/assets/monster_sheet.png" width="280" alt="Slime Sheet" style="image-rendering: pixelated;" /> | [`monster_actions.aseprite`](docs/assets/monster_actions.aseprite)<br>*(4 Layers / 7 Tags / 26 Frames)* |

### Action Choreography Breakdown

| Action Tag | Knight Frames | Slime Frames | Key Animation Notes |
| :--- | :---: | :---: | :--- |
| **`idle`** | 2 frames (350ms) | 4 frames (180ms) | Knight breathing bob & plume sway; Slime squishy dome breathing. |
| **`walk`** | 4 frames (140ms) | 4 frames (130ms) | Knight 4-beat contact stride; Slime inchworm hop & stretch. |
| **`attack`** | 4 frames (90ms) | 4 frames (100ms) | Knight sword slash with cyan FX arc; Slime coil & acid spike thrust. |
| **`dodge`** | 3 frames (110ms) | 3 frames (110ms) | Knight backward slide with dust trail; Slime flat puddle melt & retreat. |
| **`hurt`** | 2 frames (160ms) | 2 frames (150ms) | Knight impact recoil & sparks; Slime dented shockwave & core shake. |
| **`die`** | 4 frames (180ms) | 4 frames (160ms) | Knight collapse & sword drop; Slime burst ➔ puddle ➔ dissolve. |
| **`special`** | 5 frames (120ms) | 5 frames (130ms) | **Knight Holy Cleave**: Leaping slam with radiant ground wave.<br>**Slime Acid Nova**: 4-way acid explosion from white-hot core. |

<details>
<summary><b>🔍 View AI Iterative Refinement Case Studies (V1 Prototype ➔ V2 Refinement & Prompts)</b></summary>

<br>

#### 🗡️ Case 1: Hero Knight Evolution
| V1 Prototype (1 Frame) | V2 Refined (2-Frame Idle GIF) | Pixel Diff Heatmap |
| :---: | :---: | :---: |
| <img src="docs/assets/character_v1.png" width="160" style="image-rendering: pixelated;" /> | <img src="docs/assets/character_v2.gif" width="160" style="image-rendering: pixelated;" /> | <img src="docs/assets/character_diff.png" width="160" style="image-rendering: pixelated;" /> |
* **Prompt 1 (V1)**: `"Create a 32x32 retro pixel art knight with iron armor, blue tabard, a sword, and helmet facing front."`
* **Critique**: Single-tone shading, lack of specular metal glints, blocky silhouette, zero motion.
* **Prompt 2 (V2)**: `"Refine the knight character to 16-bit quality: add a 4-step metallic shading ramp with bright specular glints, golden pauldrons and helmet crest, a flowing red plume, high-contrast dark outline, leather belt with buckle, and a 2-frame idle breathing/bobbing animation."`

#### 🧪 Case 2: Acid Slime Evolution
| V1 Prototype (1 Frame) | V2 Refined (4-Frame Idle GIF) | Pixel Diff Heatmap |
| :---: | :---: | :---: |
| <img src="docs/assets/monster_v1.png" width="160" style="image-rendering: pixelated;" /> | <img src="docs/assets/monster_v2.gif" width="160" style="image-rendering: pixelated;" /> | <img src="docs/assets/monster_diff.png" width="160" style="image-rendering: pixelated;" /> |
* **Prompt 1 (V1)**: `"Create a 32x32 retro pixel art green slime monster with cute round eyes, a rounded dome shape, and a dark shadow on the floor."`
* **Critique**: Solid opaque rubber look, no inner core, missing translucent liquid reflections.
* **Prompt 2 (V2)**: `"Upgrade the green slime into a vibrant animated translucent acid slime: add a floating glowing magical core, dynamic specular liquid highlights on top, darker ambient occlusion base, floating bubbles, and a 4-frame squash-and-stretch idle bounce animation."`

</details>

---

## 🛠️ MCP Tools Overview (19 Tools)

The `pixel-art-ai` MCP server exposes exactly 19 tools organized into 5 functional groups:

| Group | Key Tools | Capabilities |
| :--- | :--- | :--- |
| **Canvas & Lifecycle** | `sprite_create`, `sprite_open`, `sprite_save`, `canvas_resize`, `canvas_crop` | Document creation, atomic disk writes, canvas dimension and anchoring adjustments. |
| **Drawing & Geometry** | `draw_pixels_batch`, `draw_shape` | Atomic batch painting of indexed/RGBA coordinates, lines, rectangles, and circles. |
| **Timeline & Layers** | `layer_manage`, `frame_manage`, `tag_manage`, `palette_manage` | Multi-layer hierarchy (`shadow`/`body`/`weapon`/`fx`), frame timing (`duration_ms`), and animation loop tags. |
| **Export & Vision** | `export_manage`, `preview_generate`, `preview_diff` | Spritesheet packing, animated GIF export, nearest-neighbor base64 visual feedback, and pixel diff heatmaps. |
| **Analysis & Validation** | `pixel_analyze`, `style_validate`, `asset_workflow` | Static palette/luminance inspection, declarative YAML compliance checking, and autonomous repair orchestration. |

---

## 🏛️ 5-Layer System Architecture

```mermaid
graph TD
    User([Game Developer / User Prompt]) --> Agents[AI Coding Agents
Claude Code / Codex / Antigravity / Cursor]

    subgraph Layer5 ["Layer 5: Workflow Orchestration"]
        Orchestrator[Reference Planner & State Machine]
        RepairPlanner[Declarative Repair Engine]
    end

    subgraph Layer4 ["Layer 4: Agent Adapters"]
        ClaudeAdapter[Claude Code]
        AntigravityAdapter[Google Antigravity]
        CursorAdapter[Cursor IDE]
    end

    subgraph Layer3 ["Layer 3: Style Compliance"]
        StyleDoc[YAML Specifications]
        StyleValidator[Rule Compliance Engine]
    end

    subgraph Layer2 ["Layer 2: Analyzers & Vision"]
        StaticAnalyzers[Palette / Edge / Luminance]
        VisualFeedback[ImageContent Preview & Diff]
    end

    subgraph Layer1 ["Layer 1: Aseprite MCP Server"]
        MCPServer[19 MCP Tools - Stdio / HTTP]
        LuaRunner[Sandboxed Lua Execution Engine]
    end

    HostApp[(Host Aseprite >= 1.3.0)]

    Agents --> Layer4
    Layer4 --> Layer5
    Layer5 --> Layer3
    Layer3 --> Layer2
    Layer2 --> Layer1
    Layer1 --> HostApp
```

---

## 🔒 Security & Sandbox Policy

* **Path Confinement**: All read/write operations strictly sandboxed to the project workspace root.
* **Symlink Traversal Prevention**: Symlink targets resolving outside the workspace are blocked.
* **Audited Lua Only**: Arbitrary script injection is disallowed; only pre-audited template routines execute.
* **Zero External Calls**: Fully offline-capable backend with zero telemetry and zero external LLM API dependencies.

---

## 📄 License & Legal Notice

Distributed under the [MIT License](LICENSE).

> **Aseprite Notice**: `pixel-art-ai` does not bundle, redistribute, or modify Aseprite. It communicates with a user-installed Aseprite instance through documented CLI and Lua scripting interfaces. Aseprite remains the property of its respective copyright holders.