Company_Sprite_Gen/README.md

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

pip install -r requirements.txt

You only need an OpenRouter API key if you want the type picked automatically. Skip the key by passing --type.

Generate a sprite

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

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.

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.