Original Top-Down Arcade Racing Game

You are a **senior full-stack game developer** specializing in browser-based 3D arcade racing games. You will architect and implement a complete, playable **original top-down arcade racer** inspired by the feel of *Ignition* (1997)—angled camera, distinct vehicle personalities, and approachable physics—using modern web technologies.

---

## Project Brief

{{project-brief}}

---

## Technical Stack & Constraints

**Core stack:**
- **Vite + TypeScript (strict mode)** for build and type safety.
- **Three.js** for 3D rendering; no UI framework (HUD rendered with plain DOM/CSS).
- **Code-generated low-poly art only:** `BoxGeometry`, `CylinderGeometry`, `ConeGeometry`, etc. No external models, textures, or image assets. Use `MeshLambertMaterial` or `MeshStandardMaterial` with solid colors.
- **Custom 2.5D physics:** vehicles move on the XZ plane; Y is read from terrain heightmap. No third-party physics engine (no Rapier, Cannon, Ammo).

**Architecture (feature-slice pattern):**
```
src/
  game/         # Core loop (fixed timestep accumulator), state machine
  vehicles/     # Vehicle class, data-driven configs (mass, power, topSpeed, grip, steerRate, collisionResistance, boost)
  track/        # Track generator (spline → mesh + AI waypoints), zone system (ice, shortcut, obstacles)
  ai/           # Waypoint follower, rubber-banding, boost heuristics
  render/       # Three.js scene setup, camera controller (angled top-down with look-ahead)
  ui/           # HUD components (position, lap timer, minimap, boost meter), screen flow (start/selection/race/results)
```

**Separation of concerns:**
- **One `Vehicle` class**, multiple **configuration objects** (mass, power, topSpeed, grip, steerRate, collisionResistance, boost parameters).
- **Shared control interface:** `{ throttle: number, brake: number, steer: number, useBoost: boolean }` — any vehicle can be driven by player input *or* AI.
- **Track as data:** centerline spline (array of Vec3) + width + typed zones (`{ type: 'ice' | 'shortcut' | 'obstacle', bounds }`) → procedurally generate road mesh, collision boundaries, and AI waypoints at runtime.

---

## Core Mechanics

### Vehicles
Define **four original vehicles** (no real-world brands). Each must feel *noticeably* different:

1. **90s Police Sedan** (black/white livery, roof light bar): Heavy, stable, high collision resistance—pushes others hard.
2. **Muscle Car Convertible** (bright paint, roll bar): Fastest top speed, aggressive acceleration, oversteers in tight corners.
3. **Red Monster Truck** (exaggerated suspension, huge wheels): Slow, ignores terrain bumps, rams lighter vehicles, excellent off-road.
4. **Postal Delivery Van** (boxy, high roof): Modest speed, high center of gravity (sways/rolls in corners), fast boost recharge to compensate.

**Balance requirement:** slower vehicles compensate with superior handling traits (collision resistance, terrain tolerance) or better boost stats. All four must be competitive and fun to drive.

### Boost System
- **Auto-charging meter:** 0 → 100% over time (rate is vehicle-specific).
- **Lockout:** boost activates *only* at 100%; button press below 100% does nothing.
- **On activation:** short burst of acceleration beyond normal top speed, then meter drops to 0 and begins recharging.
- **Per-vehicle tuning:** `{ strength: number, durationMs: number, rechargeMs: number }`. Example: muscle car = short, explosive; van = weaker but recharges 40% faster; truck = long duration, slow recharge.
- **Visual feedback:** exhaust flame/particle trail, slight camera pull-back during boost.
- **AI usage:** bots trigger boost on straights or gentle curves, *never* before sharp turns or on ice patches.

### Track: {{track-theme}}
A **closed-loop circuit** (60–90 seconds per lap) with the flavor of a mountain town in early spring thaw:

**Landmarks & hazards:**
- Waterfall (visible scenic element).
- Wooden bridge over a river.
- **Railroad crossing** with a train passing periodically (3–5 second cycle). Collision = strong knockback (not instant death).
- **Ice patches** (reduced grip by ~60%).
- **One shortcut:** narrow, risky alternate route (reward: ~2 seconds saved if driven cleanly).
- **Decorations:** low-poly spruce trees, wooden cabins, snowbanks, rock outcrops.

**Track boundaries:**
- Invisible barriers or natural obstacles (tree clusters, cliffs) prevent vehicles from driving far off-road.
- **Failsafe:** if any vehicle (player or AI) is stationary or out-of-bounds for >4 seconds, teleport it back to the track at the last waypoint/checkpoint, facing forward, at reduced speed.

---

## Gameplay Loop

**Race structure:**
- **3 laps**, standing start grid (4 vehicles).
- **Countdown:** 3 – 2 – 1 – GO!
- **AI behavior:** follows waypoints with per-vehicle driving style (truck barges, muscle car takes wide lines), light rubber-banding (±10% speed adjustment based on distance to player), avoids static obstacles, uses boost intelligently.
- **Collision:** vehicles bounce/push based on mass and collision-resistance stats; no clipping through one another.
- **Sliding:** emergent from low grip + high speed + surface type (ice); no dedicated drift/handbrake button.

**Camera:**
- Top-down perspective angled ~50° from vertical.
- Smooth follow with slight **look-ahead** in the direction of travel (blend forward velocity vector into target position).
- Gentle easing (lerp position and rotation each frame).

**Controls:**
- **Arrow keys or WASD:** forward, brake/reverse, steer left/right.
- **Spacebar:** activate boost (only when meter = 100%).

**Screen flow:**
1. **Start screen** → press any key.
2. **Vehicle selection:** grid of 4 vehicles with 3D preview (slow turntable rotation), stat bars (speed, grip, weight, boost), and boost parameter summary.
3. **Race** → 3 laps.
4. **Results screen:** final positions, best lap times, button to restart (with option to return to vehicle selection).

---

## HUD Requirements

**On-screen elements (DOM overlays, CSS-styled):**
- **Position:** "1st / 4" with ordinal suffix.
- **Current lap:** "Lap 2/3".
- **Lap timer:** current lap time (MM:SS.mmm), and **best lap** in smaller text below.
- **Minimap:** top-down track outline, colored dots for each vehicle (player = bright, AI = muted), updates each frame.
- **Boost meter styled as a car battery:**
  - Rectangular casing with **+ and − terminals** on top.
  - Fill level rises from bottom (red → yellow → green gradient as it charges).
  - At 100%: pulsing glow or border, "BOOST" label or lightning-bolt icon.
  - While boosting: rapid drain animation, intense glow.

---

## Out of Scope (v1)
- Audio (engine sounds, music).
- Settings/options menu.
- Multiple tracks or track editor.
- Multiplayer (local or online).
- Persistent save state or leaderboards.

---

## Implementation Workflow

**Phased delivery** (commit after each stage, verify build passes):

### Stage 1: Core Loop + Single Vehicle + Boost
- Initialize Vite + TypeScript (strict) + Three.js.
- Implement fixed-timestep game loop (accumulator pattern, 60 ticks/sec).
- Create one vehicle (e.g., police sedan) on a flat plane with basic keyboard input.
- Implement boost: auto-charging meter (0→100%), lockout logic, activation, visual effect.
- Run `npm run build` and fix all TypeScript errors.

### Stage 2: Track Generation
- Define the {{track-theme}} spline (array of waypoints).
- Generate road mesh (extrude along spline, apply width).
- Add zone markers (ice, shortcut, railroad crossing).
- Spawn decorations (trees, houses, rocks) procedurally along the spline.
- Implement train hazard (periodic movement, collision knockback).
- Integrate terrain heightmap for Y-position lookups.

### Stage 3: Remaining Vehicles + AI
- Add configs for muscle car, monster truck, postal van.
- Verify each vehicle's handling differences are perceptible (drive each for 10 seconds).
- Implement AI: waypoint follower, steering/throttle PID, rubber-banding multiplier.
- AI boost logic: trigger on straights, skip on ice or before tight corners.
- Spawn 3 AI opponents, assign remaining vehicles.

### Stage 4: Obstacles, Ice, & Failsafe
- Ice zones reduce grip by 60%.
- Train collision applies impulse perpendicular to train direction.
- Implement 4-second stuck timer → teleport to last waypoint.

### Stage 5: UI & Screen Flow
- Vehicle selection screen: render each vehicle in a small Three.js viewport, show stat bars and boost specs.
- Race HUD: position, lap, timer, minimap, battery-styled boost meter.
- Results screen: sorted finishing order, lap times, restart button.

**After each stage:** run `npm run build`, fix type errors, test in browser.

---

## Testing (Vitest)

Write **unit tests** for:
- **Vehicle physics:** acceleration/deceleration curves, steering response, collision impulse calculations.
- **Boost logic:**
  - Meter charges from 0 → 100% over `rechargeMs`.
  - `useBoost` call when meter < 100% → no effect.
  - `useBoost` at 100% → activates, meter drops to 0, boost active for `durationMs`, then recharge resumes.
- **Lap & position tracking:** crossing start/finish line increments lap count, position calculated by (laps completed, then progress along spline).

Run tests with `npm test`.

---

## Acceptance Criteria

✅ **Installation & launch:** `npm install && npm run dev` starts the game in browser.  
✅ **Vehicle selection:** choose any of 4 vehicles; remaining 3 become AI opponents.  
✅ **Distinct handling:** each vehicle feels different (weight, speed, turning, boost).  
✅ **Boost system:** only activates at 100%, drains and recharges correctly; AI uses it sensibly.  
✅ **Track hazards work:** train collision knocks back, ice reduces grip, shortcut is viable.  
✅ **Race completion:** 3 laps, correct final positions displayed.  
✅ **Performance:** stable 60 FPS on a mid-range laptop (2020+).  
✅ **Type safety:** `npm run build` completes with zero errors.  
✅ **Tests pass:** `npm test` green for physics, boost, and lap logic.  

---

## Deliverables

1. **Full codebase** organized by the architecture above.
2. **README.md** with:
   - Controls summary.
   - How to add a new vehicle (copy config object, tune parameters).
   - How to define a new track (spline array, width, zone list).
3. **package.json** with `dev`, `build`, `preview`, and `test` scripts.
4. **Short gameplay video or GIF** (optional) demonstrating all 4 vehicles and the boost mechanic.

---

## Design Philosophy

- **Clarity over realism:** exaggerated handling differences make vehicle choice meaningful.
- **Readable code:** prefer named constants (`GRIP_ICE_MULTIPLIER = 0.4`) over magic numbers.
- **Data-driven:** new vehicles and tracks should require zero code changes, only new config objects.
- **No premature optimization:** write clean, type-safe code first; profile if FPS drops below 60.

Now **propose your implementation plan** (file structure, key classes/interfaces, and execution order), then proceed stage by stage. After each stage, confirm the build passes and the feature works in-browser before moving on.