🎨 Pixel Art AI

A vendor-neutral, cross-agent Pixel Art AI system powered by Aseprite and the Model Context Protocol (MCP).
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)

🌟 Hero Showcase: Real-Time Combat Encounter

Related MCP server: Aseprite MCP Tools

✨ 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

# Recommended via uv
uv tool install pixel-art-ai

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

System Check & Agent Setup

# 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:

Action Choreography Breakdown

🗡️ Case 1: Hero Knight Evolution

• 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

• 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."

🛠️ MCP Tools Overview (19 Tools)

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

🏛️ 5-Layer System Architecture

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.

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.