<p align="center">
  <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT License" />
  <img src="https://img.shields.io/badge/python-3.12+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.12+" />
  <img src="https://img.shields.io/badge/node-20+-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node 20+" />
  <img src="https://img.shields.io/badge/MCP-ready-000000?style=flat-square&logo=openai" alt="MCP ready" />
</p>

<h1 align="center">Pixel Art Factory</h1>

<p align="center">
  Local SDXL + pixel-art LoRA pipeline with a <strong>Cursor MCP server</strong> for agent-driven game asset generation.
</p>

<p align="center">
  Generate sprites, tiles, icons, and backgrounds → pixelize → batch from manifests → export Phaser atlases.
</p>

---

## Features

| Capability | Description |
|---|---|
| **Local generation** | SDXL base + `nerijs/pixel-art-xl` LoRA via Hugging Face Diffusers |
| **Pixel post-process** | Downscale, palette quantization, transparency trim |
| **Game presets** | `sprite`, `character`, `tile`, `icon`, `item`, `background` |
| **Batch manifests** | JSON-driven asset packs in `assets/manifests/` |
| **MCP tools** | Six tools for Cursor agents and other MCP clients |
| **Engine export** | Spritesheet packing + Phaser atlas JSON |

---

## Requirements

- **GPU:** NVIDIA with CUDA (8 GB+ VRAM recommended)
- **Python:** 3.12+
- **Node.js:** 20+
- **OS:** Windows or Linux (setup scripts provided for both)

---

## Quick start

### 1. Clone and install

**Windows (PowerShell)**

```powershell
git clone https://github.com/RosemyneH/pixel-art-factory.git
cd pixel-art-factory
.\scripts\setup.ps1
```

**Linux / macOS**

```bash
git clone https://github.com/RosemyneH/pixel-art-factory.git
cd pixel-art-factory
./scripts/setup.sh
```

> First run downloads PyTorch + SDXL models (~10–15 GB). Use `-SkipModelDownload` on Windows or `SKIP_MODEL_DOWNLOAD=1` on Linux to defer until first generate.

### 2. Verify the engine

```bash
# Windows
.\.venv\Scripts\python.exe -m engine.cli status

# Linux / macOS
./.venv/bin/python -m engine.cli status
```

### 3. Generate a test asset

```bash
python -m engine.cli generate "green slime enemy" --type sprite --name slime
```

Output lands in `assets/output/` with metadata in `assets/output/.meta/`.

---

## Agent / MCP setup

Pixel Art Factory exposes a **stdio MCP server** that keeps the Python engine warm for fast repeated generations.

### Step 1 — Build the MCP server

```bash
cd mcp-server
npm install
npm run build
```

### Step 2 — Add to Cursor

Copy `mcp.json.example` into your Cursor MCP config:

| Location | Scope |
|---|---|
| `~/.cursor/mcp.json` | Global (all projects) |
| `<project>/.cursor/mcp.json` | Single project |

Replace `<REPO_ROOT>` with the absolute path to your clone.

**Windows**

```json
{
  "mcpServers": {
    "pixel-art-factory": {
      "command": "node",
      "args": ["C:/path/to/pixel-art-factory/mcp-server/dist/index.js"],
      "env": {
        "PIXEL_FACTORY_PYTHON": "C:/path/to/pixel-art-factory/.venv/Scripts/python.exe"
      }
    }
  }
}
```

**Linux / macOS**

```json
{
  "mcpServers": {
    "pixel-art-factory": {
      "command": "node",
      "args": ["/path/to/pixel-art-factory/mcp-server/dist/index.js"],
      "env": {
        "PIXEL_FACTORY_PYTHON": "/path/to/pixel-art-factory/.venv/bin/python"
      }
    }
  }
}
```

### Step 3 — Restart Cursor

Open **Settings → MCP** and confirm `pixel-art-factory` shows as connected.

### Step 4 — Smoke test (agent prompt)

Paste into any Cursor agent:

```
Call engine_status on pixel-art-factory, then generate_pixel_art with prompt "gold coin pickup" asset_type icon name coin_icon
```

---

## MCP tools reference

| Tool | Purpose |
|---|---|
| `engine_status` | GPU, CUDA, model, and output paths |
| `generate_pixel_art` | Single asset from a text prompt |
| `batch_generate_assets` | Run a manifest (e.g. `starter-pack.json`) |
| `list_generated_assets` | Browse recent outputs + metadata |
| `create_spritesheet` | Pack animation frames into one sheet |
| `export_game_asset` | Export Phaser atlas JSON for an asset |

### `generate_pixel_art` parameters

| Param | Type | Default | Notes |
|---|---|---|---|
| `prompt` | string | *required* | What to generate |
| `asset_type` | enum | `sprite` | `sprite` `character` `tile` `icon` `background` `item` |
| `width` | number | `64` | Final pixel width |
| `height` | number | `64` | Final pixel height |
| `palette_size` | number | `16` | Color count after quantization |
| `seed` | number | — | Reproducible output |
| `name` | string | — | Output filename slug |
| `tags` | string[] | — | Stored in metadata |

---

## Batch manifests

Save to `assets/manifests/<name>.json`:

```json
{
  "name": "starter-pack",
  "assets": [
    {
      "prompt": "wooden treasure chest closed",
      "asset_type": "item",
      "name": "chest_closed",
      "tags": ["loot"]
    },
    {
      "prompt": "grass ground tile top-down",
      "asset_type": "tile",
      "name": "grass_tile",
      "tags": ["terrain"]
    }
  ]
}
```

Run via CLI or MCP:

```bash
python -m engine.cli batch starter-pack.json
```

```
batch_generate_assets(manifest: "starter-pack.json")
```

---

## Agent workflow tips

1. **Always call `engine_status` first** — confirms GPU + model before a long batch.
2. **Use manifests for packs** — one MCP call generates many assets with consistent presets.
3. **Name your assets** — `name` becomes the filename; agents can reference it in `export_game_asset`.
4. **Tune presets** — edit `pipeline/presets.json` for per-type sizes, steps, and prompt prefixes.
5. **Keep the engine warm** — the MCP server holds the model loaded; avoid spawning separate CLI processes during agent sessions.

---

## Project layout

```
pixel-art-factory/
├── engine/              # Python SDXL + pixel pipeline + CLI
├── mcp-server/          # TypeScript MCP bridge (stdio)
├── pipeline/            # Asset-type presets
├── assets/
│   ├── manifests/       # Batch job definitions
│   └── output/          # Generated PNGs (gitignored)
├── scripts/             # setup.ps1, setup.sh
├── tests/               # Pipeline unit tests
└── mcp.json.example     # Cursor MCP config template
```

---

## Models

| Role | Model |
|---|---|
| Base | `stabilityai/stable-diffusion-xl-base-1.0` |
| LoRA | `nerijs/pixel-art-xl` |
| VAE | `stabilityai/sdxl-vae` |
| Fallback | `stabilityai/sdxl-turbo` |

Models download automatically on first run via `engine.cli prefetch`.

---

## Development

```bash
# Run tests
python -m unittest discover -s tests -v

# Rebuild MCP server after TS changes
cd mcp-server && npm run build
```

---

## License

[MIT](LICENSE) © 2026 RosemyneH