# sprite_gen

Procedural 96x96 creature sprites for businesses. You give it a business name and logo. It picks a type, builds a creature from parts and recolors it with the logo's brand colors.

## Setup

```bash
pip install -r requirements.txt
```

You only need an [OpenRouter](https://openrouter.ai) API key if you want the type picked automatically. Skip the key by passing `--type`.

## Generate a sprite

```bash
# Type picked from the business name
OPENROUTER_API_KEY=<API_KEY> python generate_sprite.py "Rosas Landscaping" logos/rosas.png

# Add a description to help pick the type
OPENROUTER_API_KEY=<API_KEY> python generate_sprite.py "Rosas Landscaping" logos/rosas.png --desc "Lawn care and garden design"

# Set the type yourself (no API key needed)
python generate_sprite.py "Rosas Landscaping" logos/rosas.png --type grass

# Set the colors yourself instead of using a logo (main color first)
python generate_sprite.py "Rosas Landscaping" --type grass --colors "#2E7D32,#FBC02D"

# A different creature for the same business
python generate_sprite.py "Rosas Landscaping" logos/rosas.png --type grass --reroll 1
```

Each run writes `sprites/<slug>.png` (96x96), `sprites/<slug>@4x.png` and `sprites/<slug>.json` (type, parts, colors). With `--reroll N`, the file names end in `-rN`.

| Option | Meaning |
|---|---|
| `--type T` | Skip the classifier. One of: normal fire water grass electric ice fighting poison ground flying psychic bug rock ghost dragon |
| `--desc TEXT` | Description sent to the classifier (default: the name) |
| `--colors "#main,#accent"` | Manual colors; overrides the logo |
| `--reroll N` | Alternate creature; the name alone always gives the same sprite |
| `--out DIR` | Output folder (default `sprites`) |
| `--scale N` | Size of the upscaled copy (default 4, `1` disables it) |

Logo colors: transparent pixels, soft edge pixels and a solid white/black/gray background are ignored, and colored brand colors are used before white, black or gray. A logo with only white, black or gray in it still uses those colors.

## Batch

Use a CSV with the columns `name,logo,type,description`. Only `name` is required, and rows with no `type` use the classifier.

```bash
OPENROUTER_API_KEY=<API_KEY> python generate_sprite.py --batch businesses.csv --out sprites
```

## Editing the art

The parts are text grids in `parts_src/<slot>/<name>.txt`, compiled to `parts/<slot>/<name>.png`. Weights, compatibility and deny lists live in `sprite_parts.py`. See `AI_PIXEL_ART_GUIDE.md` for the palette and anchor rules.

```bash
python build_parts.py                     # compile all grids (or pass part names)
python validate_parts.py --sample 3000    # check colors, anchors, canvas fit on random composites
python preview.py bases                   # contact sheets in preview/
python preview.py part back plant_bulb    # one part on every base it fits
python preview.py zoom body=base_fox tail=tail_leaf
python generate_sprite.py --sprite-list SPRITES.md   # regenerate the part list and weight report
```

Do not run `--make-placeholders --overwrite`, because it replaces the real art with test placeholders.