15. Ember Glider

# 15. Ember Glider

Build a serene 3D gliding game at sunset. The player pilots a small glider across a chain of three floating islands, riding thermal updrafts to stay aloft and passing through glowing ember rings that mark the route. The goal: reach the final beacon on the third island, finishing under the par time. A defined journey with an end — not an endless flight.

The point is calm, legible purpose: follow the rings, manage altitude, reach the beacon. Altitude is the resource — it always drains, thermals restore it, and the rings form both the path and the progression meter. A first-time player should understand everything from one sentence and one HUD.

The first screen must state the goal in one line ("Ride the thermals through the rings. Reach the beacon before sunset.") with the controls below it. One key press launches. No other menus.

## Core Loop

- The glider flies forward continuously; the player controls pitch and bank. Speed ties to pitch: diving gains speed, climbing bleeds it.
- Altitude decays constantly in still air. Cylindrical thermal columns rising from the islands restore altitude while inside them; each thermal is marked by rising ember particles visible from far away.
- Rings sit along the route as checkpoints: pass through to bank progress and respawn there on a crash. A HUD counter tracks them (e.g. "Rings 7 / 14").
- Running out of altitude over open air means a water crash: brief splash, then respawn at the last ring with a small time penalty.
- Landing on an island is safe (rolling stop, relaunch by pitching down off the edge or pressing R).
- Passing the final ring and flying through the beacon gate ends the run: a finish screen with total time vs par, rings hit, and crashes. A defined ending, then Free Flight stays available.

## The Journey

- Three floating-island groups in sequence: **Ember Shore** (low thermals, wide ring spacing, teaches the loop), **Ashen Peaks** (taller islands, thermals off the direct line, forces route choices), **The Beacon** (a climb: rings stack upward on strong thermals to the beacon gate).
- Ring count and positions are fixed per run; the route must be completable without exploits: each leg is flyable from thermal to thermal with sensible margins.
- Par time is shown on the first screen and in the HUD; finishing under par earns an Ember Medal on the finish screen.
- Best time and medal persist in `localStorage` and show on the first screen.

## Flight Model

- Simple but honest energy management: airspeed, altitude, and sink rate trade against each other. Thermals add climb. No fuel gauge, no unrealistic hovering.
- Stall behavior: too slow and the nose drops with a warning shudder until speed recovers.
- Controls must feel smooth: banked turns roll the glider and the horizon; pitch inputs are gentle, not twitchy.
- A compass ribbon or subtle on-screen marker points toward the next ring when it is off-screen.

## HUD and Screens

- Always visible: altitude (bar or tape), airspeed, ring counter, current island name, elapsed time vs par.
- Next-ring direction indicator when the ring is off-screen.
- Crash: brief splash/fade, "+10s" penalty notice, respawn at last ring.
- Finish screen: total time, par time, medal earned or missed, rings hit, crashes; buttons for Retry and Free Flight.
- Free Flight: same world, no timer, no crash penalty.

## Controls

- **W / S or Arrow Up / Down**: pitch up / down
- **A / D or Arrows**: bank left / right
- **R**: relaunch from last ring — **Esc / P**: pause — **Enter**: start, confirm
- Mouse drag to look around is allowed; keyboard alone must be fully playable.

## Visual Rules

- Full-screen 3D rendered into a `<canvas>` via Three.js (or comparable WebGL via CDN, listed in `manifest.json.externalAssets`).
- Sunset mood: warm gradient sky, low sun, drifting clouds, god-ray-like light shafts if cheap, ember particles rising from thermals, water with sun glitter below.
- Islands are stylized floating landmasses: low-poly cliffs, trees, grass caps, waterfalls spilling off edges. Beautiful stillness, not empty grey rocks.
- The glider banks and pitches visibly; a soft ember trail marks its path. Rings glow and burst gently when passed.
- No external models, textures, or audio fetched at runtime; everything procedural or code-built (one CDN font allowed).
- Honor `prefers-reduced-motion`: no camera roll exaggeration or shake; flight unchanged.
- 30+ fps at 1280×800 on a 2020 laptop.

## Hard Requirements

- Single `index.html`, no build step; opens over `file://`.
- Keyboard accessible; `lang="en"` on `<html>`.
- No login, no analytics, no network requests for runtime art, models, audio, or data.

Expose a small automated verification hook:

```js
window.__glider = {
  ready: true,
  getState(),        // phase (start/flying/crashed/finish/freeflight), island, ringsHit, time, crashes
  start(),           // launch the run
  setInput(input),   // { pitch, bank } for scripted flight
  getGlider(),       // position, altitude, airspeed, heading, inThermal
  getRings(),        // all rings with position and passed state
  getThermals(),     // thermal columns with position and strength
  teleportToRing(i), // for testing later legs
  getTiming(),       // elapsed, par, penalties
  resetProgress()    // clear localStorage bests
};
```

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, par time, controls, and any stored best; launching has no console errors.
2. Pitch and bank respond smoothly; diving gains speed, climbing bleeds it, and a stall drops the nose with a warning.
3. Altitude decays in still air and rises inside a marked thermal; the HUD altitude readout matches the glider.
4. Passing through a ring increments the counter and sets the respawn point; the ring burst plays.
5. Crashing into water respawns the glider at the last ring with the time penalty applied; the ring counter and route state are preserved.
6. The off-screen ring indicator points correctly toward the next ring.
7. Using the hook to teleport to the final island, the beacon gate ends the run with a finish screen showing correct time, par, medal, rings, and crashes.
8. Finishing under par awards the medal; over par does not; best time persists across a page reload via `localStorage`.
9. Pause works; Retry restarts cleanly without reload; Free Flight removes timer and crash penalty.
10. Landing on an island is safe and relaunch works.
11. Reduced-motion mode keeps flight identical with camera effects removed.
12. The game holds 30+ fps at 1280×800 while inside a thermal with full ember particles.

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