# Civilization — Sprite / Art Spec

Everything in Civilization renders procedurally out of the box, so the game is
fully playable with **no** art: terrain is flat-shaded isometric diamonds with
glyphs, units are colored roundels with two-letter labels, cities are little
box clusters. This document lists the optional sprite sheets you can drop in
to replace those placeholders, with exact dimensions, layouts, and
frame-by-frame maps.

All art is wired through **`public/data/civilization-artwork.json`**. The scene
checks whether each sheet's texture is loaded; if it is, it uses your frames,
otherwise it falls back to procedural drawing. You never need to touch code —
just add a PNG under `public/assets/images/civilization/` and set its `path`
in that JSON.

Frame numbering everywhere is **row-major, 0-based**: frame 0 is top-left,
count left-to-right then down to the next row.

**The isometric diamond**: map tiles occupy a 128 × 64 px diamond. Terrain and
city frames are 128 × 96 px — the bottom 64 px is the diamond footprint, the
top 32 px is headroom for tall features (peaks, trees, towers). The diamond's
four corners touch the frame edges at (64, 32), (128, 64+32), (64, 96), and
(0, 64+32) — i.e. left/right corners at frame-y 64, top corner at frame-y 32,
bottom corner at frame-y 96. Fill the whole diamond opaquely; leave the
headroom transparent except where the feature rises into it. Tiles butt
against each other with no blending in v1 (hard Civ I-style edges).

> **Future work (not in v1):** terrain blend transitions between neighboring
> tile types, river overlays, and coastline foam. Roads, railroads and
> irrigation are currently vector-drawn; the improvements sheet below covers
> the badge-style overlays only.

---

## 1. Terrain base sheet — `civilization-terrain.png`

| | |
|---|---|
| **Path** | `public/assets/images/civilization/civilization-terrain.png` |
| **Sheet size** | **768 × 192 px** |
| **Frame size** | **128 × 96 px** |
| **Layout** | 6 columns × 2 rows = 12 frames |
| **Status** | ❌ not created — procedural diamonds render meanwhile |
| **JSON** | `terrainSheet` |

### Frame map

| Frame | id | Name | Notes |
|---:|---|---|---|
| 0 | `grassland` | Grassland | plain green |
| 1 | — | Grassland (shield) | grassland variant with the little shield mark |
| 2 | `plains` | Plains | dry golden grass |
| 3 | `forest` | Forest | trees rise into the 32px headroom |
| 4 | `hills` | Hills | rolling mounds |
| 5 | `mountains` | Mountains | peaks use full headroom, snow caps |
| 6 | `desert` | Desert | sand, maybe a dune |
| 7 | `tundra` | Tundra | patchy frozen grass |
| 8 | `glacier` | Glacier | ice sheet |
| 9 | `swamp` | Swamp | murky pools, reeds |
| 10 | `jungle` | Jungle | dense canopy, brighter green than forest |
| 11 | `ocean` | Ocean | deep blue, light wave marks |

Frame indexes are pinned in `data/civilization-rules.json` (`terrains[].frame`,
`grasslandShieldFrame`) — append-only, never renumber.

---

## 2. Special resources sheet — `civilization-resources.png`

Drawn centered on top of the base terrain tile (badge layer, 64 × 64 centered
on the diamond).

| | |
|---|---|
| **Path** | `public/assets/images/civilization/civilization-resources.png` |
| **Sheet size** | **320 × 256 px** |
| **Frame size** | **64 × 64 px** |
| **Layout** | 5 columns × 4 rows = 20 frames |
| **Status** | ❌ not created — colored dot badges render meanwhile |
| **JSON** | `resourceSheet` |

### Frame map

| Frame | id | Name | On terrain |
|---:|---|---|---|
| 0 | `buffalo` | Buffalo | Plains |
| 1 | `wheat` | Wheat | Plains |
| 2 | `pheasant` | Pheasant | Forest |
| 3 | `silk` | Silk | Forest |
| 4 | `coal` | Coal | Hills |
| 5 | `wine` | Wine | Hills |
| 6 | `gold` | Gold | Mountains |
| 7 | `iron` | Iron | Mountains |
| 8 | `oasis` | Oasis | Desert |
| 9 | `oil` | Oil | Desert |
| 10 | `game` | Game | Tundra |
| 11 | `furs` | Furs | Tundra |
| 12 | `ivory` | Ivory | Glacier |
| 13 | `glacieroil` | Oil (arctic) | Glacier |
| 14 | `peat` | Peat | Swamp |
| 15 | `spice` | Spice | Swamp |
| 16 | `gems` | Gems | Jungle |
| 17 | `fruit` | Fruit | Jungle |
| 18 | `fish` | Fish | Ocean |
| 19 | `whales` | Whales | Ocean |

---

## 3. Tile improvements sheet — `civilization-improvements.png`

Badge overlays drawn centered on the tile. Roads and railroads stay
vector-drawn (they connect dynamically between tiles), so they are NOT here.

| | |
|---|---|
| **Path** | `public/assets/images/civilization/civilization-improvements.png` |
| **Sheet size** | **384 × 64 px** |
| **Frame size** | **64 × 64 px** |
| **Layout** | 6 columns × 1 row = 6 frames |
| **Status** | ❌ not created — vector glyphs render meanwhile |
| **JSON** | `improvementSheet` |

### Frame map

| Frame | id | Name | Notes |
|---:|---|---|---|
| 0 | `irrigation` | Irrigation | furrow lines |
| 1 | `farmland` | Farmland | denser irrigation (Refrigeration upgrade) |
| 2 | `mine` | Mine | pit head / spoil heap |
| 3 | `fortress` | Fortress | square rampart outline |
| 4 | `hut` | Goody hut | little thatched hut |
| 5 | `fortify` | Fortify shield | reserved for a unit "fortified" badge |

---

## 4. Units sheet — `civilization-units.png`

Unit art is **neutral** (no civ color baked in): the game draws a player-color
ring/roundel underneath your frame. Center the unit in the frame with its feet
around y = 52 so it sits on the tile.

| | |
|---|---|
| **Path** | `public/assets/images/civilization/civilization-units.png` |
| **Sheet size** | **512 × 448 px** |
| **Frame size** | **64 × 64 px** |
| **Layout** | 8 columns × 7 rows = 56 frames (51 used, 52–55 reserved) |
| **Status** | ❌ not created — roundel + 2-letter label renders meanwhile |
| **JSON** | `unitSheet` |

### Frame map

| Frame | id | Name | | Frame | id | Name |
|---:|---|---|---|---:|---|---|
| 0 | `settlers` | Settlers | | 26 | `cannon` | Cannon |
| 1 | `engineers` | Engineers | | 27 | `artillery` | Artillery |
| 2 | `explorer` | Explorer | | 28 | `howitzer` | Howitzer |
| 3 | `caravan` | Caravan | | 29 | `fighter` | Fighter |
| 4 | `freight` | Freight | | 30 | `bomber` | Bomber |
| 5 | `warriors` | Warriors | | 31 | `helicopter` | Helicopter |
| 6 | `phalanx` | Phalanx | | 32 | `stealthfighter` | Stealth Ftr. |
| 7 | `archers` | Archers | | 33 | `stealthbomber` | Stealth Bmb. |
| 8 | `legion` | Legion | | 34 | `cruisemsl` | Cruise Msl. |
| 9 | `pikemen` | Pikemen | | 35 | `nuclearmsl` | Nuclear Msl. |
| 10 | `musketeers` | Musketeers | | 36 | `trireme` | Trireme |
| 11 | `riflemen` | Riflemen | | 37 | `caravel` | Caravel |
| 12 | `alpinetroops` | Alpine Troops | | 38 | `galleon` | Galleon |
| 13 | `partisans` | Partisans | | 39 | `frigate` | Frigate |
| 14 | `marines` | Marines | | 40 | `ironclad` | Ironclad |
| 15 | `paratroopers` | Paratroopers | | 41 | `destroyer` | Destroyer |
| 16 | `mechinf` | Mech. Inf. | | 42 | `cruiser` | Cruiser |
| 17 | `horsemen` | Horsemen | | 43 | `aegiscruiser` | AEGIS Cruiser |
| 18 | `chariot` | Chariot | | 44 | `battleship` | Battleship |
| 19 | `elephant` | Elephant | | 45 | `submarine` | Submarine |
| 20 | `knights` | Knights | | 46 | `carrier` | Carrier |
| 21 | `crusaders` | Crusaders | | 47 | `transport` | Transport |
| 22 | `dragoons` | Dragoons | | 48 | `ssstructural` | SS Structural |
| 23 | `cavalry` | Cavalry | | 49 | `sscomponent` | SS Component |
| 24 | `armor` | Armor | | 50 | `ssmodule` | SS Module |
| 25 | `catapult` | Catapult | | 51–55 | — | reserved |

Frame indexes are pinned in `data/civilization-rules.json` (`units[].frame`).

---

## 5. City sheet (classic theme) — `civilization-cities-classic.png`

Cities scale with population and show walls when City Walls are built. This is
the **classic/western** theme; more themes (e.g. `asian`) drop in later by
adding an entry to `citySheets` in the artwork JSON — the format already
supports it and no code changes are needed.

| | |
|---|---|
| **Path** | `public/assets/images/civilization/civilization-cities-classic.png` |
| **Sheet size** | **512 × 192 px** |
| **Frame size** | **128 × 96 px** (same diamond+headroom as terrain) |
| **Status** | ❌ not created — box-cluster fallback renders meanwhile |
| **Layout** | 4 columns × 2 rows = 8 frames |
| **JSON** | `citySheets.classic` |

### Frame map

| Frame | Size tier | Walls | Notes |
|---:|---|---|---|
| 0 | 1–3 (village) | no | a few small buildings |
| 1 | 4–7 (town) | no | denser, a landmark roof |
| 2 | 8–12 (city) | no | multi-story buildings |
| 3 | 13+ (metropolis) | no | grand skyline into the headroom |
| 4 | 1–3 | **yes** | tier 0 ringed by walls |
| 5 | 4–7 | **yes** | |
| 6 | 8–12 | **yes** | |
| 7 | 13+ | **yes** | |

The player-color banner and name plate are drawn by the game below the tile —
keep the bottom ~6 px of the diamond clear of critical detail.

---

## 6. HUD icons sheet — `civilization-icons.png`

Small interface icons (yields, governments, spaceship parts, moods).

| | |
|---|---|
| **Path** | `public/assets/images/civilization/civilization-icons.png` |
| **Sheet size** | **480 × 96 px** |
| **Frame size** | **48 × 48 px** |
| **Layout** | 10 columns × 2 rows = 20 frames |
| **Status** | ❌ not created — text labels render meanwhile |
| **JSON** | `iconSheet` |

### Frame map

| Frame | id | Notes | | Frame | id | Notes |
|---:|---|---|---|---:|---|---|
| 0 | `food` | wheat sheaf | | 10 | `gov-despotism` | |
| 1 | `shield` | production shield | | 11 | `gov-anarchy` | |
| 2 | `trade` | trade arrow | | 12 | `gov-monarchy` | |
| 3 | `gold` | coin | | 13 | `gov-communism` | |
| 4 | `beaker` | science flask | | 14 | `gov-republic` | |
| 5 | `pop` | citizen head | | 15 | `gov-democracy` | |
| 6 | `ss-structural` | | | 16 | `mood-happy` | diplomacy list dot |
| 7 | `ss-component` | | | 17 | `mood-idle` | |
| 8 | `ss-module` | | | 18 | `mood-upset` | |
| 9 | `vet` | veteran chevron | | 19 | — | reserved |

Government frames match `governments[].frame` in the rules JSON (10–15).

---

## 7. Menu icon — `game-icons.png` frame 83

| | |
|---|---|
| **Path** | `public/assets/images/game-icons.png` (shared sheet) |
| **Sheet size** | 660 × 660 px (15 × 15 grid of 44 × 44 frames) |
| **Frame** | **83** (row 5, col 8) |
| **Status** | ❌ needs painting |

Suggested motif: a tiny isometric globe/hex of terrain, or a laurel-wreathed
city. The menu shows a generic fallback until painted.

---

## Quick checklist

| # | File | Size | Priority |
|---|---|---|---|
| 1 | `civilization-terrain.png` | 768×192 | **High** — biggest visual upgrade |
| 2 | `civilization-cities-classic.png` | 512×192 | **High** |
| 3 | `civilization-units.png` | 512×448 | **High** (51 frames — biggest lift) |
| 4 | `civilization-resources.png` | 320×256 | Medium |
| 5 | `civilization-improvements.png` | 384×64 | Medium |
| 6 | `civilization-icons.png` | 480×96 | Low |
| 7 | `game-icons.png` frame 83 | 44×44 | Medium (menu presence) |

After painting a sheet, set its `path` in `public/data/civilization-artwork.json`,
e.g. `"path": "assets/images/civilization/civilization-terrain.png"`, and
reload — no code changes.