# Advance Wars — spritesheet spec

Art is split into **five independent sheets**, one per category, so each can
be painted and dropped in separately. Until a sheet is painted, the game
renders a procedural stand-in with the exact same frame map — everything is
fully playable art-free, and you can drop in one sheet at a time.

**Rivers and roads need NO art on the map itself**: they are drawn in code
(Graphics) from tile connection masks, so there are no variant frames to
paint for the *terrain sheet*. Shoreline foam where sea meets land is also
drawn in code. This exemption does **not** extend to the battle background
sheet (§5) — that one needs a full backdrop scene for every occupiable
terrain, river/road/bridge included, since it's a standalone illustration
rather than a tileable ground texture.

## Drop-in procedure (no code changes)

1. Paint a sheet per the specs below.
2. Save it under `assets/images/advancewars/` (suggested names below).
3. In `data/advancewars-artwork.json`, set that sheet's `path`.
4. Reload. Sheets left `path: null` keep their procedural stand-in.

Keep source PSDs next to the PNGs. **Frames are append-only — never
renumber.** Frame indices are pinned in `data/advancewars-rules.json`
(`terrains[].frame`, `units[].frame`) and in `UI_FRAMES` in
`AdvanceWarsMapView.js`.

## Tinting rules (important!)

The **building sheet** and the **unit sheet** are painted **neutral and
tintable**: light gray / near-white bodies (#e0e0e0-ish) with dark outlines.
The engine applies each army's color with a multiply tint at runtime
(orange / blue / yellow / green + gray for neutral buildings), and **flips
unit art horizontally** for enemy armies — so paint every unit **facing
RIGHT**. Avoid saturated colors on anything tinted; details that must stay
colored (glass, smoke, tires) should be dark.

The terrain and UI sheets are painted in full color — no tinting.

---

## 1. Terrain sheet — `advancewars-terrain.png`

**48×48 cells, 8 columns × 1 row = 384×48 px.** Full color, opaque tiles.

| frame | content |
|-------|---------|
| 0 | Plain (grass) |
| 1 | Wood (trees — hides units in fog) |
| 2 | Mountain |
| 3 | Sea |
| 4 | Reef (rocky shallows on sea) |
| 5 | Shoal (beach/sand transition) |
| 6 | Bridge, horizontal (paint the water background into the tile) |
| 7 | Bridge, vertical (ditto) |

Everything is a flat 48×48 tile — no headroom on this sheet. Rivers, roads
and coastlines are code-drawn; do not paint them.

## 2. Building sheet — `advancewars-buildings.png`

**48×64 cells, 5 frames in 1 row (suggest 6 columns = 288×64 px, last cell
spare).** Bottom 48×48 is the tile footprint; the top 16 px is headroom for
roofs and flags. Bottom-aligned, transparent background (the ground tile
shows through), **neutral + tintable**.

| frame | content |
|-------|---------|
| 0 | City |
| 1 | Base (land factory) |
| 2 | Airport |
| 3 | Port |
| 4 | HQ (make it grand — flag, use the headroom) |

## 3. Unit sheet — `advancewars-units.png`

**48×64 cells, 12 columns × 3 rows = 576×192 px.** Bottom-aligned in the
48×48 footprint with 16 px headroom for heads/rotors/masts. Transparent
background, **neutral + tintable, facing RIGHT**.

Each unit gets exactly **two frames**: `[idle A, idle B]` — a subtle
2-frame cycle (bob, tread shift, rotor spin). Frames are `base` and
`base+1`, laid out row-major:

| base | unit | | base | unit |
|------|------|-|------|------|
| 0 | Infantry | | 18 | Missiles |
| 2 | Mech | | 20 | Fighter |
| 4 | Recon | | 22 | Bomber |
| 6 | Tank | | 24 | B-Copter |
| 8 | Md Tank | | 26 | T-Copter |
| 10 | APC | | 28 | Battleship |
| 12 | Artillery | | 30 | Cruiser |
| 14 | Rockets | | 32 | Lander |
| 16 | Anti-Air | | 34 | Sub |

## 4. UI sheet — `advancewars-ui.png`

**48×48 cells, 7 frames in 1 row (suggest 8 columns = 384×48 px, last cell
spare).** Full color, transparent background.

| frame | content |
|-------|---------|
| 0 | tile cursor (corner brackets, white) |
| 1 | explosion, small |
| 2 | explosion, big |
| 3 | capture flag icon |
| 4 | low-fuel icon (lightning bolt) |
| 5 | low-ammo icon (bullet) |
| 6 | CO power star |

Icons 3–6 render at roughly 40% tile size as unit badges; keep them bold
and readable when small.

## 5. Battle background sheet — `advancewars-battlebg.png`

**256×256 cells, 5 columns × 3 rows = 1280×768 px (14 frames used, last cell
spare).** Full color, full-bleed illustration — no transparency needed,
these fill the entire backdrop behind each fighter in the battle cut-in
window (`AdvanceWarsBattleAnim.js`). Landscape/scene paintings, not tile
icons: think "diorama behind the two combatants," not "48×48 ground swatch."

One frame per terrain type a unit can actually stand on, **plus** one per
building type. A property tile's own terrain id (city/base/airport/port/hq)
*is* its building type — there's no separate "terrain underneath the
building" to paint over, since a tile only ever has one terrain value at a
time. So each frame below is a straight lookup, not a layered composite.

| frame | content |
|-------|---------|
| 0 | Plain (grass field) |
| 1 | Wood (forest clearing) |
| 2 | Mountain |
| 3 | Sea (open water) |
| 4 | Reef (rocky shallows) |
| 5 | Shoal (beach) |
| 6 | River |
| 7 | Bridge — used for **both** horizontal and vertical bridge tiles; orientation doesn't matter for a static backdrop, so this one frame covers both `bridgeh` and `bridgev` |
| 8 | Road |
| 9 | City |
| 10 | Base (land factory) |
| 11 | Airport |
| 12 | Port |
| 13 | HQ |

Each fighter's backdrop is picked by looking up the terrain tile they're
actually standing on when the battle happens (from the engine's `battle`
event coordinates) — so, e.g., a tank parked on a captured city shows the
City background, not Plain, even though a tank could also be fought on open
grass elsewhere. The defender's backdrop is horizontally mirrored (matching
the mirrored defender unit sprite) — avoid art with strong left/right
asymmetry (e.g. a building silhouette that visibly leans one way) unless
you're fine with it flipping on the right-hand side.

Unlike the other four sheets, this one is painted in full color and is
**not tinted** — buildings here don't need to react to owner army color
the way the small map-icon building sheet does.

Also paint **frame 86 of `assets/images/game-icons.png`** (44×44, row 5
col 11 of that 15-per-row sheet). Suggested motif: a small orange tank on a
green tile, AW box-art style.