# Star Wars Deckbuilder — Sprite / Art Spec

Everything in SWDBG renders procedurally out of the box (faction-colored frame,
cost badge, stats, name plate, rules text), so the game is fully playable with
**no** art. This document lists the sprite sheets that replace the placeholder
art windows, with exact dimensions, layout, and frame-by-frame maps.

All art is wired through **`public/data/swdbg-artwork.json`**. The scene checks
whether each sheet's texture is loaded **and whether the mapped frame actually
exists in the PNG** — a card mapped to a frame beyond the sheet's last row
simply stays procedural until you extend the image, so you can paint the new
frames at your own pace.

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

Only paint the illustration — the card frame, border, faction edge color,
Hero-card gold inset, cost/stat badges, name plate, and rules text are all
drawn procedurally on top of your art. Art is scaled to **fit** the art window
(no cropping), so match the aspect ratio below for edge-to-edge fill; other
aspects letterbox inside the window.

---

## ⚠ 2026-07 card overhaul — what changed for the art

The card list was regenerated from the owner-transcribed CSV
(`assets/info/sw-force-cards.csv`). **Every previously painted frame keeps its
position** (append-only policy). What you need to know:

1. **The sheet grows one row group: 2400 × 1085 → 2400 × 1395** (8 columns ×
   9 rows, 155 px per row). Extend the canvas downward; nothing above moves.
2. **11 new cards need art in frames 55–65** (frame 55 is the old spare
   top-sheet cell; 56–65 live in the two new rows; 66–71 stay spare).
3. **4 frames are orphaned but preserved** — their cards left the game, the
   art stays in place in case they return: 18 (Emperor Palpatine),
   22 (Rebel Pathfinder), 29 (K-2SO), 38 (Medical Frigate). Nothing reads them.
4. **Frame 54 (Khetanna / Jabba's Sail Barge) is reused as-is** by the new
   `jabbassailbarge` card — the barge is now a neutral 7-cost *unit* instead
   of a capital ship. Same art, new stats; no repaint needed.
5. **Faction/type changes on existing frames** (procedural frame recolors
   automatically — repaint only if the art itself feels off-faction):
   - Boba Fett (51): neutral → **Empire**
   - Blockade Runner (36): Rebel → **neutral**
   - Millennium Falcon (40): capital ship → **unit** (same art window)

---

## 1. Card art sheet — `swdbg-cards-art.png`

| | |
|---|---|
| **Path** | `public/assets/images/swdbg-cards-art.png` |
| **Frame size** | **300 × 155 px** (aspect ≈ 1.9 : 1, landscape — matches the card art window) |
| **Sheet size** | **8 columns × 9 rows = 2400 × 1395 px** — 66 frames used (0–65), 66–71 spare |
| **Status** | ✅ frames 0–54 painted (existing sheet) · ⛔ frames 55–65 needed |
| **JSON** | `cardSheet` (path set) + `cards` map (already updated for all 66 ids) |

The art window sits just below the name plate on every unit/ship/character
card. **The overall card is roughly a standard trading-card shape, but the
art window itself is a wide, short band** — rules text and stats take up the
lower two-thirds of the card, so the window works out to about 1.9 : 1, not
portrait. It's shown at roughly 134×70 px on a resting hand card (which
always shows its rules text) and up to ~326×160 px in the inspect/hover zoom
— design for readability at the smaller size, and lean into a horizontal
composition (a ship in profile, a trooper mid-stride) rather than a portrait
bust, since a portrait-oriented image will letterbox heavily in this window.

### Frame map

Faction legend: **E** = Empire, **R** = Rebel, **N** = neutral/outer rim.
**Hero** cards get the procedural gold inset.

| Frame | id | Name | Faction | Notes |
|---:|---|---|---|---|
| 0 | `allianceshuttle` | Alliance Shuttle | R | starter |
| 1 | `rebeltrooper` | Rebel Trooper | R | starter |
| 2 | `templeguardian` | Temple Guardian | R | starter |
| 3 | `imperialshuttle` | Imperial Shuttle | E | starter |
| 4 | `stormtrooper` | Stormtrooper | E | starter |
| 5 | `inquisitor` | Inquisitor | E | starter |
| 6 | `outerrimpilot` | Outer Rim Pilot | N | shared neutral card |
| 7 | `tiefighter` | TIE Fighter | E | |
| 8 | `scouttrooper` | Scout Trooper | E | |
| 9 | `deathtrooper` | Death Trooper | E | |
| 10 | `tiebomber` | TIE Bomber | E | |
| 11 | `tieinterceptor` | TIE Interceptor | E | |
| 12 | `atst` | AT-ST | E | |
| 13 | `atat` | AT-AT | E | |
| 14 | `generalveers` | General Veers | E | Hero |
| 15 | `grandmofftarkin` | Grand Moff Tarkin | E | Hero |
| 16 | `directorkrennic` | Director Krennic | E | Hero |
| 17 | `darthvader` | Darth Vader | E | Hero |
| 18 | — | *(orphaned: Emperor Palpatine)* | | card removed; art preserved, unused |
| 19 | `gozanticruiser` | Gozanti Cruiser | E | capital |
| 20 | `imperialcarrier` | Imperial Carrier | E | capital |
| 21 | `stardestroyer` | Star Destroyer | E | capital |
| 22 | — | *(orphaned: Rebel Pathfinder)* | | card removed; art preserved, unused |
| 23 | `ywing` | Y-Wing | R | |
| 24 | `snowspeeder` | Snowspeeder | R | |
| 25 | `durosspy` | Duros Spy | R | |
| 26 | `xwing` | X-Wing | R | |
| 27 | `rebelcommando` | Rebel Commando | R | |
| 28 | `cassianandor` | Cassian Andor | R | Hero |
| 29 | — | *(orphaned: K-2SO)* | | card removed; art preserved, unused |
| 30 | `chirrutimwe` | Chirrut Îmwe | R | no longer a Hero (still 1-of) |
| 31 | `jynerso` | Jyn Erso | R | Hero |
| 32 | `chewbacca` | Chewbacca | R | Hero |
| 33 | `hansolo` | Han Solo | R | Hero |
| 34 | `princessleia` | Princess Leia | R | Hero |
| 35 | `lukeskywalker` | Luke Skywalker | R | Hero |
| 36 | `blockaderunner` | Blockade Runner | **N** | capital — faction changed from Rebel |
| 37 | `hammerheadcorvette` | Hammerhead Corvette | R | capital |
| 38 | — | *(orphaned: Medical Frigate)* | | card removed; art preserved, unused |
| 39 | `moncalamaricruiser` | Mon Calamari Cruiser | R | capital |
| 40 | `millenniumfalcon` | Millennium Falcon | R | Hero — now a **unit**, not a capital |
| 41 | `z95headhunter` | Z-95 Headhunter | N | |
| 42 | `jawascavenger` | Jawa Scavenger | N | |
| 43 | `keldormystic` | Kel Dor Mystic | N | |
| 44 | `rodiangunslinger` | Rodian Gunslinger | N | |
| 45 | `hwk290` | HWK-290 | N | |
| 46 | `twileksmuggler` | Twi'lek Smuggler | N | |
| 47 | `fangfighter` | Fang Fighter | N | |
| 48 | `quarrenmercenary` | Quarren Mercenary | N | |
| 49 | `bossk` | Bossk | N | Hero |
| 50 | `ig88` | IG-88 | N | Hero |
| 51 | `bobafett` | Boba Fett | **E** | Hero — faction changed from neutral |
| 52 | `jabbathehutt` | Jabba the Hutt | N | Hero |
| 53 | `crocruiser` | C-ROC Cruiser | N | capital |
| 54 | `jabbassailbarge` | Jabba's Sail Barge | N | Hero — reuses the Khetanna art; now a unit |
| **55** | `lobot` | **Lobot** | N | **NEW ART** — Hero; old spare cell (row 6, col 7) |
| **56** | `dengar` | **Dengar** | N | **NEW ART** — Hero bounty hunter |
| **57** | `nebulonbfrigate` | **Nebulon-B Frigate** | N | **NEW ART** — capital, medical/escort frigate |
| **58** | `landocalrissian` | **Lando Calrissian** | N | **NEW ART** — Hero |
| **59** | `bazemalbus` | **Baze Malbus** | R | **NEW ART** — Hero, heavy repeater gunner |
| **60** | `rebeltransport` | **Rebel Transport** | R | **NEW ART** — capital, GR-75 |
| **61** | `uwing` | **U-Wing** | R | **NEW ART** — troop dropship |
| **62** | `bwing` | **B-Wing** | R | **NEW ART** — heavy assault fighter |
| **63** | `admiralpiett` | **Admiral Piett** | E | **NEW ART** — Hero officer |
| **64** | `moffjerjerrod` | **Moff Jerjerrod** | E | **NEW ART** — Hero officer |
| **65** | `landingcraft` | **Landing Craft** | E | **NEW ART** — Sentinel-class shuttle |
| 66–71 | — | spare | | leave blank for future cards |

New-frame grid positions (300 × 155 px cells):

| Frame | Row | Col | Pixel box (x, y) |
|---:|---:|---:|---|
| 55 | 6 | 7 | 2100–2400, 930–1085 |
| 56–63 | 7 | 0–7 | 0–2400, 1085–1240 |
| 64, 65 | 8 | 0, 1 | 0–600, 1240–1395 |

> Priority for the new frames: the Heroes (55, 56, 58, 59, 63, 64) show the
> gold inset and get inspected most; the ships (57, 60, 61, 62, 65) read fine
> procedurally a while longer.

---

## 2. Base art sheet — `swdbg-bases-art.png` *(unchanged)*

| | |
|---|---|
| **Path** | `public/assets/images/swdbg-bases-art.png` |
| **Frame size** | **220 × 300 px** (aspect ≈ 0.733 : 1, portrait — matches the base art window) |
| **Sheet size** | **5 columns × 2 rows = 1100 × 600 px** holds all 10 frames |
| **Status** | ✅ painted — no changes needed (bases were not part of the card overhaul) |
| **JSON** | `baseSheet` + `bases` map (unchanged) |

Bases are the large planet/location cards planted on each player's side of the
board (shown at ~300×190 landscape during play — note the base *card* itself
is wider-than-tall on screen, but the art window inside it is a portrait
crop, so compose art with a strong vertical focal point that still reads when
letterboxed). Also shown up to 560×340 in the win/lose reveal.

### Frame map

| Frame | id | Name | Notes |
|---:|---|---|---|
| 0 | `dantooine` | Dantooine | Rebel base, grassy plains |
| 1 | `hoth` | Hoth | Rebel base, ice world |
| 2 | `sullust` | Sullust | Rebel base, volcanic |
| 3 | `moncala` | Mon Cala | Rebel base, ocean world |
| 4 | `yavin4` | Yavin 4 | Rebel base, jungle moon/temple |
| 5 | `lothal` | Lothal | Imperial base, plains/wheat |
| 6 | `corellia` | Corellia | Imperial base, shipyards |
| 7 | `coruscant` | Coruscant | Imperial base, cityscape |
| 8 | `deathstar` | Death Star | Imperial base, superweapon |
| 9 | `endor` | Endor | Imperial base, forest moon |

---

## 3. Menu icon — `game-icons.png` frame **78** *(shared sheet, unchanged)*

| | |
|---|---|
| **File** | `public/assets/images/game-icons.png` (existing shared sheet) |
| **Sheet size** | 660 × 660 px |
| **Frame size** | **44 × 44 px** |
| **Layout** | 15 columns × 15 rows |
| **SWDBG frame** | **78** → row 5, col 3 → pixel box **x 132–176, y 220–264** |

Add a 44×44 icon for the Star Wars Deckbuilder into cell 78 of the existing
sheet (the menu tile pulls `game-icons` frame `78`). Keep it readable at tiny
size — e.g. a crossed rebel/imperial insignia, a small TIE fighter or X-Wing
silhouette, or the Force-track balance symbol. This is the only sprite that
goes into an **existing** sheet rather than a new file.

---

## Quick checklist

- [ ] `swdbg-cards-art.png` — **extend the canvas from 2400×1085 to
      2400×1395** (add 310 px at the bottom; existing art untouched).
- [ ] Paint the 11 new frames:
  - [ ] 55 Lobot (old spare cell, row 6 col 7)
  - [ ] 56 Dengar · 57 Nebulon-B Frigate · 58 Lando Calrissian ·
        59 Baze Malbus · 60 Rebel Transport · 61 U-Wing · 62 B-Wing ·
        63 Admiral Piett (row 7)
  - [ ] 64 Moff Jerjerrod · 65 Landing Craft (row 8)
- [ ] *(optional)* Revisit frame 51 (Boba Fett — now Empire-framed) and
      frame 36 (Blockade Runner — now neutral-framed) if the palettes clash
      with their new faction edge colors.
- [x] Frame 54 — no repaint; the Khetanna art now serves Jabba's Sail Barge.
- [x] `swdbg-bases-art.png` — unchanged.
- [ ] `game-icons.png` frame 78 — 44×44 menu icon (still outstanding).

The frame→id mappings are already updated in `public/data/swdbg-artwork.json`
— the new cards render procedurally today and pick up your art automatically
as soon as the extended PNG contains their frames (no code or JSON changes
needed when you repaint).