# Master of Vega — art spec

Every sheet below is **optional**. Each one starts with `"path": null` in
`data/mastervega-artwork.json`, and `VegaArt.js` paints a procedural stand-in
with the identical frame layout — the game is fully playable with zero art
files. To use real art: drop the PNG in `assets/images/vega/` and set its
`path` in the artwork JSON. **No code changes are needed.**

Frame indexes are **APPEND-ONLY**. Never renumber an existing frame — the
indexes are baked into `data/mastervega-rules.json` and shifting them silently
mismaps every piece of artwork already drawn.

Status: ⬜ = not painted yet (procedural fallback in use).

Two different pictures of a planet are used and they are **not** interchangeable:
the `planets` sheet (§2) is a transparent 192 px disc for the orrery, and the
world backdrops (§2b) are opaque 1920 × 1080 scenes for the colony screen.

---

## 1. `ships` — ✅ `assets/images/vega/ships.png`

| | |
|---|---|
| Sheet size | **1536 × 1920** |
| Frame | **192 × 192** |
| Grid | 8 cols × 10 rows = 80 frames |

**One row per species, one column per hull.** Frame = `species.shipFrame × 8 + hull.frame`.

Columns (hull):

| Col | Hull | Notes |
|---|---|---|
| 0 | Scout | Small, fast, unarmed |
| 1 | Colony Ship | Bulbous, carries a habitat pod |
| 2 | Troop Transport | Boxy, no guns |
| 3 | Frigate | Smallest warship |
| 4 | Destroyer | Mid warship |
| 5 | Cruiser | Heavy warship |
| 6 | Battleship | The big one — should read as huge even at 24px |
| 7 | Star Base | Immobile orbital fortress; a ring/station, not a ship |

Rows (species): 0 Human, 1 Kestrelli, 2 Ursaal, 3 Umbrix, 4 Kkrix, 5 Mekhan,
6 Rrashaa, 7 Cerebrai, 8 Ssakar, 9 Lithox.

**Ships face UP.** The battle screen rotates them ±90° so the two sides face each
other. Each species has a colour in the rules file — art can ignore it (the
sprite is used as-is) or lean into it.

Only the human row is painted so far; the other nine fall back to the procedural
stand-in, which is cut at the same 192px geometry.

> The **thumbnails and the detail window turn the hull a full 180°** — a
> deliberate look, not a correction. `makeShipIcon` in `VegaShipMedia.js` is the
> one place that does it, with `setAngle(180)` rather than `setFlipY`: a flip
> would mirror the hull's asymmetries, a rotation does not.

---

### 1b. Ship commander videos — 🟨 `assets/videos/vega/ship-<species>-<hull>.mp4`

**Not part of the sheet.** One looping **256 × 256** muted clip per species *per
hull* — the officer who flies that class — shown beside the hull on every ship
row and at full size in the detail window.

Declared in `shipVideos` in `data/mastervega-artwork.json`, nested
`species → hull id → { key, path }`. A species with none recorded is a single
`null`. Same drop-in contract as everything else: drop the files, add the lines,
no code changes.

The fallback ladder is one tier deeper than the species portraits:

1. this species' clip for this hull — `shipVideos[species][hull]`
2. the species' own portrait video — `portraitVideos[species]` (§ below)
3. its 1024px still — `portraitStills[species]`
4. a frame on the procedural `portraits` sheet

So a gap is never a hole: every row shows a moving face from day one, and each
new race lights up one clip at a time. `starbase` has no clip for anyone and is
expected to keep falling through.

| Hull id | File suffix | Human |
|---|---|---|
| `scout` | `ship-human-scout.mp4` | ✅ |
| `colonyship` | ⚠️ `ship-human-**colony**.mp4` | ✅ |
| `transport` | `ship-human-transport.mp4` | ✅ |
| `frigate` | `ship-human-frigate.mp4` | ✅ |
| `destroyer` | `ship-human-destroyer.mp4` | ✅ |
| `cruiser` | `ship-human-cruiser.mp4` | ✅ |
| `battleship` | `ship-human-battleship.mp4` | ✅ |
| `starbase` | — | ⬜ falls back |

> ⚠️ The colony ship's file is `ship-human-colony.mp4` while its hull id is
> `colonyship`. Same class of mismatch as `char-cerebai.mp4`: the manifest points
> at the real filename and the verifier confirms both the file and the derived
> texture key, so wiring it the wrong way round fails immediately rather than
> 404ing in the browser.

Rows: kestrelli, ursaal, umbrix, kkrix, mekhan, rrashaa, cerebrai, ssakar and
lithox are all ⬜ — nine species × seven hulls outstanding.

---

## 2. `planets` — ⬜ `assets/images/vega/planets.png`

| | |
|---|---|
| Sheet size | **960 × 576** |
| Frame | **192 × 192** |
| Grid | 5 cols × 3 rows = 15 frames |

One frame per planet type, in rules order. Draw the planet as a **centred disc**
filling ~84% of the frame, transparent outside it — the orrery and system view
both place these on a black background and scale them.

| Frame | Type | Look |
|---|---|---|
| 0 | Terran | Blue oceans, green continents, white cloud |
| 1 | Ocean | Almost entirely water, scattered islands |
| 2 | Jungle | Deep green, permanent cloud banding |
| 3 | Steppe | Olive grassland, thin atmosphere |
| 4 | Arid | Tan, dry riverbeds |
| 5 | Desert | Orange sand seas, no water |
| 6 | Tundra | Pale blue-grey, heavy ice caps |
| 7 | Minimal | Grey-green, very thin air |
| 8 | Barren | Airless grey rock, craters |
| 9 | Dead | Darker, cracked, lifeless |
| 10 | Inferno | Molten orange, volcanic |
| 11 | Toxic | Sickly yellow-green fog |
| 12 | Radiated | Livid yellow-green, glowing |
| 13 | Gas Giant | Banded, a storm spot — **not colonisable** |
| 14 | Asteroid Belt | Scattered rocks, no disc — **not colonisable** |

---

### 2b. World backdrops — ✅ mostly painted, `assets/images/vega/world-<type>-01.png`

**Not part of the `planets` sheet.** These are full-screen **1920 × 1080 opaque**
backdrops for the colony screen (`VegaColonyView.js`) — the same worlds seen from
the ground rather than from orbit. The sheet above stays what it is: transparent
192 px discs for the orrery.

Declared per planet type in `worldBackgrounds` in `data/mastervega-artwork.json`,
exactly like the species stills. A `null` path is a legitimate "not painted yet"
and falls back to a gradient built from that type's `color` in the rules file, so
the set can be finished one world at a time with no code change.

The `-01` suffix is a **variant slot** — nothing reads a variant index yet, but
the naming leaves room for `world-terran-02.png` and a roll.

| Type | File | |
|---|---|---|
| Terran | `world-terran-01.png` | ✅ |
| Ocean | `world-ocean-01.png` | ✅ |
| **Jungle** | — | ⬜ **outstanding** |
| Steppe | `world-steppe-01.png` | ✅ |
| Arid | `world-arid-01.png` | ✅ |
| Desert | `world-desert-01.png` | ✅ |
| Tundra | `world-tundra-01.png` | ✅ |
| Minimal | `world-minimal-01.png` | ✅ |
| Barren | `world-barren-01.png` | ✅ |
| Dead | `world-dead-01.png` | ✅ |
| Inferno | `world-inferno-01.png` | ✅ |
| Toxic | `world-toxic-01.png` | ✅ |
| Radiated | `world-radiated-01.png` | ✅ |
| Gas Giant | ⚠️ `world-gas-**giant**-01.png` | ✅ |
| Asteroid Belt | — | ⬜ not needed — neither type is colonisable, so the colony screen never opens on one |

> ⚠️ The gas giant's filename is `world-gas-giant-01.png` **with a hyphen** while
> its rules id is `gasgiant`. Same class of mismatch as `char-kestralli.png`: the
> manifest points at the real filename, and the verifier fails immediately if a
> declared path stops resolving.

Text is drawn over the top-left of these (name, owner, world details) with a drop
shadow, and the right ~500 px sits under a semi-transparent panel — so keep the
top-left readable and do not put the subject of the picture on the far right.

---

## 3. `stars` — ⬜ `assets/images/vega/stars.png`

| | |
|---|---|
| Sheet size | **576 × 576** |
| Frame | **192 × 192** |
| Grid | 3 cols × 3 rows = 9 frames |

One frame per star class, in rules order: 0 Blue, 1 White, 2 Yellow, 3 Orange,
4 Red, 5 Brown Dwarf, 6 Binary, 7 Pulsar, 8 Black Hole.

Drawn with **ADD blending** on the star map (except the black hole, which is
drawn normally) — so paint them **glowing on transparent black**, with the
corona fading to fully transparent at the frame edge. The star map rotates the
pulsar frame continuously and orbits a scaled copy of the binary frame, so keep
the pulsar's beam axis vertical and the binary's companion at the frame centre.

---

## 4. Species portraits — **video**, with a sheet fallback

Portraits are **looping, muted 256 × 256 videos**, one per species, at
`assets/videos/vega/char-<speciesId>.mp4`. They play silently on a loop wherever
a species portrait appears — the setup screen's species cards (84 px), the
species detail pop-over (**full 256 px**), and the diplomacy screen (96 px).

Clicking a card grows it into a centred pop-over showing the portrait at native
resolution. The card's portrait is *reparented* into the pop-over rather than a
second one being created, so there is only ever one video object per species.

**To add one:** drop the file in, then change that species' `path` from `null`
to it in `portraitVideos` in `data/mastervega-artwork.json`. Nothing else. The
verifier checks every species has an entry, that the key matches, and that every
non-null path points at a file that exists.

**All ten species have both a video and a still.** ✅

| Species | Video (256 × 256) | Still (1024 × 1024) |
|---|---|---|
| Human | `char-human.mp4` | `char-human.png` |
| Kestrelli | `char-kestrelli.mp4` | ⚠️ `char-kestr**a**lli.png` |
| Ursaal | `char-ursaal.mp4` | `char-ursaal.png` |
| Umbrix | `char-umbrix.mp4` | `char-umbrix.png` |
| Kkrix | `char-kkrix.mp4` | `char-kkrix.png` |
| Mekhan | `char-mekhan.mp4` | `char-mekhan.png` |
| Rrashaa | `char-rrashaa.mp4` | `char-rrashaa.png` |
| Cerebrai | ⚠️ `char-cereb**a**i.mp4` | `char-cerebrai.png` |
| Ssakar | `char-ssakar.mp4` | `char-ssakar.png` |
| Lithox | `char-lithox.mp4` | `char-lithox.png` |

### Fallback order

Three tiers, best first — no caller knows which it got, so the roster can be
finished a species at a time with no code changes:

1. **Video** — `assets/videos/vega/char-<id>.mp4`, listed in `portraitVideos`.
2. **Still** — `assets/images/vega/char-<id>.png` (1024 × 1024), listed in
   `portraitStills`. Used when there is no video, and as the recovery path if a
   video is present but the browser refuses to decode it.
3. **Painted sheet** — the optional ⬜ `assets/images/vega/portraits.png`
   (1280 × 512, 256 × 256 frames, 5 × 2, one per `species.portraitFrame` in the
   ship-row order), which itself falls back to a procedural painting.

> ⚠️ **Two filenames do not match their species id**, each with a correctly
> spelled counterpart: the kestrelli *still* is `char-kestralli.png`, and the
> cerebrai *video* is `char-cerebai.mp4` (no `r`). The manifest points at the
> real filenames so both work as-is — rename a file and its one path together
> if you want the spelling fixed. The verifier fails immediately if a declared
> path stops resolving, so a rename cannot go unnoticed.

These are **species portraits, not characters** — this game deliberately does
not use the `data/opponents.json` roster or its videos.

| Frame | Species | Identity |
|---|---|---|
| 0 | Human | Traders and diplomats |
| 1 | Kestrelli | Avian aristocrats, superb pilots |
| 2 | Ursaal | Ursine heavy-worlders |
| 3 | Umbrix | Shapeshifters, spies, universally distrusted |
| 4 | Kkrix | Insect hive, tireless industry |
| 5 | Mekhan | Cyborgs, factories everywhere, filthy |
| 6 | Rrashaa | Feline gunners |
| 7 | Cerebrai | Vast fragile intellects |
| 8 | Ssakar | Reptilian broodmothers |
| 9 | Lithox | Crystalline, breathe nothing, colonise anywhere |

---

## 5. `leaders` — ⬜ `assets/images/vega/leaders.png`

| | |
|---|---|
| Sheet size | **640 × 640** |
| Frame | **160 × 160** |
| Grid | 4 cols × 4 rows = 16 frames |

One frame per leader (`leader.portraitFrame`), rules order. Frames 0–7 are
colony administrators, 8–15 are ship captains. Shown at 40–60 px.

---

## 6. `buildings` — ⬜ `assets/images/vega/buildings.png`

| | |
|---|---|
| Sheet size | **512 × 128** |
| Frame | **64 × 64** |
| Grid | 8 cols × 2 rows = 16 frames |

One frame per building (`building.frame`), rules order: Automated Factory,
Research Laboratory, Missile Base, Pollution Processor, Space Port, Cloning
Center, Ground Battery, Spy Center, Planetary Shield, Terraforming Plant, Stock
Exchange, Holo Simulator, Robotic Miners, Super Computer, Artemis System Net,
Enrichment Facility.

---

## 7. `techicons` — ⬜ `assets/images/vega/techicons.png`

| | |
|---|---|
| Sheet size | **480 × 336** |
| Frame | **48 × 48** |
| Grid | 10 cols × 7 rows = 70 frames |

- Frames **0–5**: the six tech *fields* — Computers, Construction, Force Fields,
  Planetology, Propulsion, Weapons.
- Frames **6–65**: the sixty individual techs, in the order they appear in
  `data/mastervega-rules.json` (`techs[].iconFrame`).
- Frames 66–69: spare.

---

## 8. Menu icon — ✅ `assets/images/game-icons.png` frame **92**

The shared 660 × 660 sheet, 44 × 44 cells, 15 per row. Frame 92 is row 6,
column 2 → pixel origin **(88, 264)**. **Painted.**

---

## Already supplied

| File | Size | Used for |
|---|---|---|
| `assets/images/vega/background-menu.png` | 1920 × 1080 | Backdrop for both menus — dimmed 34% on the landing screen, 62% on the setup screen so the species cards stay legible |
| `assets/images/vega/menu-title.png` | 1368 × 768 | Title logo. Large on the **left** of the landing screen (contained in 900 × 560 → 900 × 505), and small as the setup screen's header (contained in 760 × 132). Always contained, never stretched. |
| `assets/images/vega/world-*-01.png` | 1920 × 1080 | Colony-screen backdrops, one per planet type — see §2b. |

## Speech — ✅ `assets/speech/vega/`

| Clip | When it plays |
|---|---|
| `ui-choose-start.mp3` | On arriving at the choose-a-species screen |
| `char-<speciesId>.mp3` | Once, when that species' detail pop-over opens |

All ten species lines are present and correctly named.

Unlike the portraits, speech is **not** declared in the artwork manifest:
`ui/SpeechQueue.js` streams it straight from `assets/speech/<clip>.mp3` without
going through Phaser's loader, so the filename convention *is* the wiring. Drop
in a replacement and it plays — the verifier checks every species resolves.

Each new line cuts off whatever was playing rather than letting two voices
overlap — so opening a species interrupts the greeting, opening a second species
interrupts the first, and closing the window stops playback.

---

## Sound

Menu clicks use the shared `8bit-activate` cue (already preloaded globally as
`sfx-8bit-activate`) — every button on the landing and species screens, the
species cards, and the detail pop-over.

Combat effects already wired, no new audio needed: `laser-zap.mp3`, `scifi-explode.mp3`,
`ta-rocket-1.mp3`, `ta-rocket-2.mp3`.

**Soundtrack** is the game's own set, `data/masterofvega-music.json` →
`assets/music/vega/`, at volume 0.6. Four tracks are declared: *Power Down*
(DV-8-2303), *High Orbit* (Klaxon), *Master of Vega Main Theme* (Aiko), *Defend
the Colony* (Cy-Bro).

> ⚠️ `assets/music/vega/track-05.mp3` is on disk but **not listed** in
> `masterofvega-music.json`, so it never plays. Add an entry for it if that was
> not deliberate. The verifier checks every declared track exists, but cannot
> know about files you meant to declare.