Heroquarium ArtGen

Pixel-art asset pipeline for the game Heroquarium: procedural generation (procgen), external-art normalization (pixelize), and an MCP server that exposes both to Claude. See ARTGEN_BLUEPRINT.md for the full design.

Canon: generate at TILE=32, export downscaled to 16 for the current renderer. All output snaps to the 53-colour palette in palette.json (single source of truth). RGBA, binary alpha, light from top-left.

Layout

palette.json          canonical palette (53 colours) — do not diverge
artgen/
  palette.py          load, redmean nearest-match, quantize, ramps
  canvas.py           pixel-map DSL, value noise, dither, shadow, outline, mirror
  pixelize.py         normalize any image/atlas -> palette + tile size
  procgen/            procedural generators (M2+)
mcp/                  MCP server (M5)
tools/                original game sources, kept for reference
tests/                palette + canvas acceptance tests
references/           style refs + Recraft prompts (for nngen / M7-M8)
out/                  generated art (gitignored)

Related MCP server: pixel-mcp

Setup

pip install -e '.[dev]'   # runtime + pytest
pytest -q                 # 14 tests

pixelize

# single sprite -> 16x16 in palette
python -m artgen.pixelize in.png -o out/tree.png

# atlas: 4x4 grid, or 32px source tiles -> separate files
python -m artgen.pixelize sheet.png --grid 4 4 -o out/
python -m artgen.pixelize sheet.png --src-tile 32 -o out/

--method box|lanczos for "fat" (AI/painted) art, nearest for already-pixel art.

procgen

python -m artgen.procgen terrain  --tile 32 --seed 42 --variety 3 -o out/terrain/
python -m artgen.procgen nature   --tile 32 --seed 42 -o out/nature/
python -m artgen.procgen autotile --from grass --to water -o out/edges/
python -m artgen.procgen building --size L --roof red --walls stone -o out/
python -m artgen.procgen village -o out/village/
python -m artgen.procgen all -o out/

Buildings: parametric houses (size S/M/L x roof slate/red/thatch x walls stone/ timber/frame) plus a prop kit — fence, gate, well, barrel, crate, signpost, lantern, market stall, woodpile, haystack. village writes the whole catalog + a gallery sheet.

Terrain biomes: grass (+flowers), forest_floor, dirt, sand, stone, snow, swamp, plus animated water frames — all tileable (seamless when repeated). Nature props: round/pine/palm trees, bush, stump, boulder, small rock, flowers, mushroom, grass tuft, reeds, skull. Each run writes PNGs + a _*_sheet.png contact sheet.

Status

• M1 — done: scaffold, palette, canvas primitives, pixelize ported.

• M2 — done: tileable terrain (7 biomes + water), 12 nature props, preview (contact sheets, 3x3 tiling check), procgen CLI.

• M3 — done: corner-based 16-tile autotile transitions between any two biomes, organic edges, dark rim, animated water foam. Seams exact by construction (bilinear corner field + edge-vanishing noise). Emits a bitmask manifest for the game renderer. 28 tests green.

• M4 — done: parametric buildings (3x3x3 house combos: size x roof x walls)

  • 10-piece prop kit (fence/gate/well/barrel/crate/signpost/lantern/stall/ woodpile/haystack), gallery preview, village catalog. 35 tests green.

• M1-M4 polish pass — done: warm low-contrast terrain with soft details (sprigs/pebbles/rare pale flowers) + new biomes (pine_floor, gravel, cobble, dirt, path) and 6+ variants each to kill repetition; roads/paths as a linear autotile feature (roads.py, layouts cross/curve/plaza…) with grassy fringe; reference-level detailed houses (varied shingles, ridge cap, moss, 4-pane windows w/ muntins+shutters+glow, timber framing, stone base, framed door, capped chimney) + decor kit (bucket, sack, potted plant, flower box, lantern, axe-stump, …). Demo: python scripts/demo_scene.py. 40 tests green.

• Anti-repetition pass — done: autotile tiles take a position-hashed variant that reseeds interior noise + fill (seams stay exact because noise vanishes at edges), so roads/maps no longer show a repeating pattern; terrain.ground_rect() bakes a large continuous ground field (soft patches flow across the whole area, no per-tile rhythm) for scene/chunk backgrounds; softer terrain details + more nature (flat rock, fallen branch, mushroom cluster).

• M5+ — MCP server, export/integration, nngen (GPU). §11.

Autotile scheme

Corner 4-bit Wang / dual-grid: each tile's four corners (NW=1, NE=2, SE=4, SW=8) mark upper vs lower terrain, giving 16 tiles. The boundary along any edge is a pure function of that edge's two shared corners, so tiles that abut on the dual grid are exactly seamless (0-mismatch, verified in tests). The renderer picks a tile per world corner-cell from its 2x2 terrain values; the mapping is written to <from>_<to>.manifest.json.