# Peggle Powers

Every power lives in the `POWERS` map in `src/games/peggle/PeggleLogic.js`
(id, display name, trigger type, player-facing description, and tuning
`params`). A level grants a power by setting `powerId` on its entry in
`levels.json`; hitting a green peg charges/fires it. Any friend can be paired
with any power — the mapping below is the intended one.

**Trigger types:**
- **instant** — fires the moment the green peg is hit
- **next ball** — banks a charge; applied to your next launched ball
- **current ball** — applied to the ball in flight when the green peg is hit
- **charge** — banks a lasting effect (multiple shots, or "next time X happens")

## Live powers (levels 1–85)

| Levels | Friend | Power (`powerId`) | Trigger | What it does |
|---|---|---|---|---|
| 1–5 | Ethel | Super Guide (`superguide`) | next 3 balls | The aim guide extends through extra bounces, showing where the ball goes after it hits pegs |
| 6–10 | Kona | Multiball (`multiball`) | instant | Kona fetches three more balls — they spawn at the current ball's position, fanned out (mirrored + ±18°) |
| 11–15 | Zanthor | Space Blast (`spaceblast`) | instant | The green peg explodes, instantly lighting and scoring every peg within 150px |
| 16–20 | Fireball | Fireball (`fireball`) | next ball | The ball is tripled in size and blazes straight through pegs without bouncing, lighting everything it touches |
| 21–25 | Victor | Zen Ball (`zenball`) | next 3 balls per hit, stacking | Each shot is silently nudged to the best-scoring angle within ±6° of your aim |
| 26–30 | The Smasher | Body Slam (`bodyslam`) | next ball | The ball becomes a massive slam ball (×1.6 size) that lumbers at ×0.7 launch speed and gravity but barely slows down when it hits pegs |
| 31–35 | Maurice | Beaver Dam (`beaverdam`) | 3 shots | The free-ball bucket is dammed up to nearly double width (×1.9) for the next 3 shots |
| 36–40 | Schooner | Tailwind (`tailwind`) | next ball | The ball rides the sea breeze at ~half gravity — long, floaty, controllable arcs |
| 41–45 | Terry | Meteor Strike (`meteor`) | instant | A meteor crashes down through the green peg, lighting every peg in its column |
| 46–50 | Gerome | Extreme Ball (`extremeball`) | next ball (×2) | Launches at ×1.45 speed, walls never absorb any of its speed, and it splits into two balls (fanned ±15°) on its 2nd bounce — each split ball splits once more on its own 2nd bounce, then stops |
| 51–55 | Blackwind | Cannonball (`cannonball`) | current ball | An explosion (Space Blast-style) lights every peg near the green peg, then the ball turns to iron and plows straight through the next 3 pegs it strikes |
| 56–60 | Steve | Beam Up (`beamup`) | current ball | If the ball falls off the bottom, a beam catches it and drops it back in from the top, retargeted over a clear-path orange peg (falls back to any orange peg, then the original spot, once per charge) |
| 61–65 | Nicole | Overclock (`overclock`) | instant | The system is hacked — every peg scores DOUBLE for the rest of the shot and all of the next, and every 6 pegs cleared while it's active earns a free ball |
| 66–70 | DV-8-2303 | Laser Sweep (`lasergrid`) | instant | The green peg fires a horizontal laser across the board, lighting every peg in its row — then one more sweep fires on a random untouched orange peg, at +1s |
| 71–75 | Kage | Shadow Slash (`shadowslash`) | instant | A blade of shadow slashes an X through the green peg, lighting pegs along both diagonals — then one more slash fires on a random untouched orange peg, at +1s |
| 76–80 | Aiko | Cosmic Bloom (`cosmicbloom`) | instant | Alien spores drift out — 2 random blue pegs bloom into new GREEN power pegs (hitting those charges the power again), plus a small Space Blast (90 radius) lights pegs around the green peg |
| 81–85 | Nadia | Rewind (`rewind`) | charge | The next ball that drains without being caught glitches out (fx + screen glitch), then 0.9s later a portal opens at the top and fires a fresh ball, angled ±15° off vertical, at a random clear-path orange peg — that ball's eventual drain refunds it to your reserve |

Levels 26–85 are generated by `tools/genPeggleLevels.js` (levels 1–25 are
hand-tuned and the script never rewrites them). Each new friend can get a
board background at `assets/images/peggle/<masterId>.png` (1200×900) and an
intro video at `assets/videos/peggle/<masterId>.mp4`; until those exist the
game falls back to the procedural background and the portrait card.

## Adding a new power

1. Add an entry to `POWERS` in `src/games/peggle/PeggleLogic.js` (put tuning
   values in `params`) and implement its behavior in `applyPower` (and, if it
   changes ball physics, via per-ball flags set in `launchBall`/`substep`).
2. Add its banner/FX/sound to `onPowerFired` (and an event case if it has a
   custom effect) in `src/games/peggle/PeggleGame.js`, plus a status line in
   `updatePowerHud` if it banks charges.
3. Add a check-cluster to `tools/verifyPeggle.js`.
4. Reference it from a level's `powerId` — the editor's power dropdown picks
   it up automatically.