fertig-classic-games/src/games/advancewars/sprites.md

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.