12. Starfall Arena

# 12. Starfall Arena

Build a single-screen arena survival game with a visible build-up of power and a defined end. The player pilots a lone ship on a dark neon battlefield, survives 15 escalating waves of enemies, and kills the final boss — the Starfall — that descends on wave 15. Victory is a win screen, not an endless mode.

The point is progression the player can feel every few seconds: kills drop XP, XP levels the ship, each level offers a choice of upgrades, and the build visibly snowballs from a pea-shooter to a screen-clearing storm of particles. A first-time player should understand the goal in one sentence.

The first screen must state the goal in one line ("Survive to Wave 15. Kill the Starfall.") with the controls listed below it. Pressing Space or Enter starts immediately. No menus, no settings pages, no tutorial modals.

## Core Loop

- The player ship moves freely inside a bounded circular or rectangular arena with a visible boundary.
- The ship fires automatically at the nearest enemy in range. The player aims by moving; no manual fire button.
- Enemies spawn at the arena edge in timed waves and die in a burst of particles, dropping XP gems.
- Collecting gems fills the XP bar. On level-up, the game pauses and offers exactly 3 upgrade cards. Picking one applies it immediately and resumes play.
- Contact with an enemy or enemy projectile costs HP. HP reaching 0 ends the run on a defeat screen showing waves survived, level reached, and kills.
- Wave 15 spawns the Starfall boss instead of a normal wave. Killing it ends the run on a victory screen with run stats.

## Progression and Purpose

- The goal, the current wave, and the next milestone must be visible at all times (e.g. "Wave 4 / 15").
- Every upgrade must stack and produce a measurable change: more damage, more projectiles, faster fire, larger pickup radius, more HP, faster movement, orbiting blades, piercing shots, or similar. At least 8 distinct upgrade types.
- Waves escalate visibly: more enemies, new enemy types introduced on named waves, and elites with more HP from wave 6 onward.
- A run lasts roughly 6–10 minutes. Difficulty must be tuned so a decent first run reaches waves 5–8, not wave 15.

## Enemies

At least 4 distinct behaviors, each visually distinguishable by shape and color:

- **Chaser** — moves directly at the player.
- **Weaver** — approaches with a sinusoidal drift.
- **Splitter** — divides into two smaller enemies on death.
- **Elite** — slow, high HP, drops a large XP burst; appears from wave 6.

## The Starfall

- Wave 15 replaces normal spawns with a single boss: a large, unmistakable entity with its own HP bar.
- The boss has at least 3 phases keyed to HP thresholds, each adding a new attack pattern (radial bursts, aimed volleys, spawning chasers).
- Phase transitions must be telegraphed by a visible change in the boss's appearance and a brief pause in its attack pattern.
- On death, the boss explodes in the largest particle effect in the game, then the victory screen appears.

## HUD

Always visible, compact, at the screen edges:

- Top left: HP bar with numeric value
- Top center: wave counter ("Wave 4 / 15") and run timer
- Bottom: XP bar with current level
- During boss fight: boss HP bar, centered, below the wave counter
- Defeat and victory screens: waves survived, level, kills, time; a Restart button that starts a fresh run without reloading the page

## Controls

- **WASD / Arrow keys**: move
- **Space / Enter**: start, confirm upgrade choice, restart
- **1 / 2 / 3**: pick an upgrade card by keyboard
- **P or Esc**: pause
- Mouse or touch may also move the ship (ship steers toward pointer), but keyboard alone must be fully playable.

## Visual Rules

- Full-screen 2D or 3D rendered into a `<canvas>`; dark background, neon palette, glowing projectiles.
- Heavy particle feedback: enemy deaths, gem pickups, level-up flash, boss phases. The screen at wave 12+ should look like a light show.
- Damage numbers on hits, brief screen shake on player damage and boss death.
- No external art, textures, fonts fetched beyond a CDN font, or audio files at runtime; all sprites/shapes are drawn in code.
- Honor `prefers-reduced-motion`: disable screen shake and reduce particle counts; gameplay unchanged.
- Keep 30+ fps at 1280×800 with 200+ enemies and active particles on screen.

## Hard Requirements

- Single `index.html`, no build step; opens over `file://`.
- Canvas 2D or WebGL via a CDN library (Three.js, PixiJS, or raw canvas); any CDN assets listed in `manifest.json.externalAssets`.
- Keyboard accessible; `lang="en"` on `<html>`.
- Store the best run (waves survived / victory) in `localStorage` and show it on the start screen.
- No login, no analytics, no network requests for runtime art, audio, or data.

Expose a small automated verification hook:

```js
window.__starfall = {
  ready: true,
  getState(),        // phase (start/playing/levelup/boss/victory/defeat), wave, level, hp, kills, time
  start(),           // begin a run
  pause(), resume(),
  getPlayer(),       // position, hp, level, xp, applied upgrades
  getEnemies(),      // live enemies with type and hp
  grantXP(n),        // add XP, triggering level-up offers
  chooseUpgrade(i),  // pick the i-th offered card
  skipToWave(n),     // jump the run to wave n for testing
  getBoss()          // boss hp and phase, null before wave 15
};
```

The hook must call the same game functions the UI uses, not a parallel simulation.

## Loop / Validation Rule

Do not stop until you have personally verified all of the following in a browser:

1. The first screen states the goal and controls; pressing Space starts a run with no console errors.
2. The ship moves with keyboard in all directions, stays inside the arena, and auto-fires at the nearest enemy.
3. Enemies spawn per wave, die to projectiles, drop XP gems, and gems are collected on contact.
4. Filling the XP bar pauses the game and offers 3 upgrade cards; choosing one (keyboard and click) applies a measurable effect.
5. The wave counter, HP bar, XP bar, and timer update correctly and are always readable.
6. All 4 enemy types appear by wave 10 and behave distinctly (chaser pursues, weaver drifts, splitter splits, elite is tanky).
7. Taking damage reduces HP; HP 0 shows the defeat screen with correct stats; Restart starts a clean run without reload.
8. Using the hook to jump to wave 15 spawns the boss with its own HP bar; the boss changes attack pattern at its HP thresholds.
9. Killing the boss shows the victory screen with correct stats.
10. Pause/resume works; reduced-motion mode removes shake while the game stays playable.
11. After finishing one run, the start screen shows the recorded best run from `localStorage`.
12. The game holds 30+ fps at 1280×800 during wave 12+ combat.

If any check fails, fix the specific mechanism and run all twelve checks again.