# Peggle Sprite Sheet Spec

Drop-in art for the pegs and ball. Physics and geometry are unchanged — these
frames are pure display skins drawn at each peg's/ball's existing position and
size.

## What to create

**One PNG:** `assets/images/peggle-sprites.png`

- **Frame size:** 64 × 64 px per cell
- **Grid:** 8 columns × 2 rows → the PNG is exactly **512 × 128 px**
- **Background:** fully transparent (32-bit PNG with alpha)

## Frame map

Frames are numbered left→right, top→bottom (row 0 = frames 0–7,
row 1 = frames 8–15).

| Frame | Content            | Notes |
|-------|--------------------|-------|
| 0     | Blue peg           | The common filler peg |
| 1     | Blue peg — LIT     | Hit state: brighter / glowing version of frame 0 |
| 2     | Orange peg         | The objective peg |
| 3     | Orange peg — LIT   | |
| 4     | Green peg          | The power peg |
| 5     | Green peg — LIT    | |
| 6     | Purple peg         | The bonus (500-pt) peg |
| 7     | Purple peg — LIT   | |
| 8     | Ball               | The silver launch ball |
| 9–15  | *(reserved)*       | Leave empty/transparent — future use (e.g. fireball ball, brick pegs) |

## Drawing guidance

- **Pegs (frames 0–7):** draw a circle that **fills the full 64 px cell**
  (i.e. 64 px diameter, touching the cell edges). In game a peg is 32 px
  across, so the art renders at 2× resolution and is scaled down — keep
  detail readable at 50%.
- **LIT variants (odd frames):** same silhouette as the unlit frame, but
  clearly "switched on" — brighter core, inner glow, or highlight ring. The
  game swaps unlit↔lit frames instantly on hit, and lit pegs fade out 1.5 s
  later, so the two states should read at a glance.
- **Ball (frame 8):** draw a circle filling the full 64 px cell. In game the
  ball is 26 px across. It's seen against a dark blue board — a light,
  specular look (chrome/silver) reads best.
- Do **not** bake in drop shadows that extend outside the circle — pegs sit
  close together and overhang would overlap neighbours.
- Keep each sprite centered in its cell; the game positions frames by cell
  center.

## How it activates

1. Save the PNG as `assets/images/peggle-sprites.png`. That's it — no code or
   config changes. The sheet is registered in `src/data/assetManifest.js` and
   lazy-loads the first time Peggle is entered.
2. Until the file exists (or if it fails to load) the game silently falls back
   to the current procedural circles — you'll just see a `[assets] failed to
   load peggle-sprites` console warning, which is harmless.
3. To revert to procedural art, delete the PNG.

## Board backgrounds (per master)

One optional PNG per friend/master, shown behind the peg field on their levels.

- **Path & naming:** `assets/images/peggle/<masterId>.png`, where `<masterId>`
  is the opponent's key from `levels.json` — e.g. `ethel.png`, `kona.png`,
  `zanthor.png`, `fireball.png`, `victor.png`.
- **Dimensions:** exactly **1200 × 900 px** (4:3). The board window is
  1200×900 logical pixels rendered 1:1 on the 1920×1080 canvas, so this is
  native resolution. If you want extra sharpness on large/4K displays, paint
  at **2400 × 1800** (same 4:3 ratio) — any other aspect ratio will be
  stretched to fit.
- **Style:** the game lays a dark scrim (38% opacity, near-black blue) over
  the image so pegs, the ball, and the aim guide stay readable — so paint at
  full vibrancy and expect it to read darker in game. Avoid fine high-contrast
  detail in the central play area; big soft shapes work best behind ~50 pegs.
- **Loading:** lazy-loaded when Peggle is first entered (listed from
  `levels.json` masterIds automatically — a new master's background needs no
  code change). Missing files fall back to the procedural starfield with a
  harmless console warning.

## Intro videos (per friend)

One optional MP4 per friend, played on the intro screen that precedes their
first level (levels 1, 6, 11, 16, 21 — detected automatically as the first
level of each friend's block in `levels.json`).

- **Path & naming:** `assets/videos/peggle/<masterId>.mp4` — e.g. `ethel.mp4`
  (already saved), `kona.mp4`, `zanthor.mp4`, `fireball.mp4`, `victor.mp4`.
- **Dimensions:** **720 × 720 px**, MP4 (H.264 video + AAC audio for the widest
  browser support). Displayed at 560×560 in the intro window.
- **Behavior:** autoplays when the intro opens (the level click counts as the
  user gesture browsers require); when it finishes, a ▶ Replay overlay appears
  and clicking the video plays it again. The Continue button starts the level
  (and never auto-fires the cannon).
- **Fallback:** a friend with no video yet shows their static 300×300 roster
  portrait in the same window — the intro screen works either way.
- The intro shows on every fresh entry to that level (level select or "Next
  Level") but is skipped on Replay / Try Again.

## Brick curves

Wavy lines of peg-like brick sections (the classic Peggle curved walls).
Authored in the editor with the **Brick Curve** tool; stored in the level file
as a `curves` array (`anchors` + per-segment `bends` + `orangeEligible`) and
tessellated into 36×22 brick sections at load. Each brick behaves exactly
like a peg — same color pool (blue/orange/green/purple), scoring, fade, and
fever sweep.

Bricks are **procedurally drawn** (not in the sprite sheet): color fill with a
dark outer stroke and a light inner inset stroke, using the same palette as
the pegs. The palette (`PEG_TINT`/`PEG_LIT` in `src/games/peggle/PeggleGame.js`)
is sampled from the dominant fill of each peg frame in `peggle-sprites.png` —
**if you repaint the peg colors, re-sample those two constants** so bricks
stay in scheme. The reserved sheet frames 9–15 could skin them later if wanted.

## Not covered by the sheet

- **Level editor** (`?peggle-editor=1`) intentionally keeps procedural circles —
  its colors encode editing state (gold = orange-eligible, blue = normal,
  red = invalid), not gameplay colors.
- Bucket, launcher, background, and particles remain procedural for now. If
  you want art for those later, the reserved frames 9–15 (or a second sheet)
  can take them.