# 2.5D Browser Game Specification

## Project Overview
- **Project Name**: Neon Runner 2.5D
- **Type**: Browser-based 2.5D endless runner/collector game
- **Core Functionality**: Player controls a character running on a 3D track, collecting coins while avoiding obstacles
- **Target Users**: Casual gamers looking for quick, engaging browser gameplay

## Technical Approach
- **Rendering**: Three.js for 3D graphics with fixed isometric-style camera angle
- **Perspective**: 2.5D - 3D graphics but gameplay confined to 2D plane (left/right movement)
- **Camera**: Fixed angle (~45°) looking down at the track, creating depth illusion

## Visual & Rendering Specification

### Scene Setup
- **Camera**: PerspectiveCamera at 45° angle, positioned above and behind player
- **Camera Position**: (0, 8, 12) looking at (0, 0, -5)
- **Lighting**:
  - Ambient light: soft purple (#6644aa) at intensity 0.4
  - Directional light: cyan (#00ffff) at intensity 0.8, position (5, 10, 5)
  - Point light: magenta (#ff00ff) following player for glow effect

### Environment
- **Background**: Dark gradient (deep purple to black)
- **Fog**: Linear fog, color #1a0a2e, near 20, far 80
- **Ground**: Infinite scrolling neon grid track

### Materials & Effects
- **Track**: Emissive grid material with cyan glow lines
- **Player**: Glowing cube/sphere with magenta emissive material + pulsing animation
- **Obstacles**: Red/orange glowing geometric shapes (cubes, pyramids)
- **Coins**: Yellow/gold rotating torus with golden emissive glow
- **Post-processing**: Bloom effect for neon glow aesthetic

### Color Palette
- Primary: Cyan (#00ffff)
- Secondary: Magenta (#ff00ff)
- Accent: Gold (#ffd700)
- Danger: Red (#ff3333)
- Background: Deep Purple (#1a0a2e)

## Game Mechanics Specification

### Player Controls
- **Left/Right Movement**: A/D or Arrow Keys or Mouse click (left/right side of screen)
- **Movement Range**: -3 to +3 units on X-axis
- **Movement Speed**: Smooth interpolation, 0.15 units per frame

### Gameplay Elements
- **Track Width**: 7 units total (-3.5 to +3.5)
- **Player Position**: Fixed Z at 0, moves only on X-axis
- **Speed**: Starts at 0.3 units/frame, increases 0.001 per frame (max 0.8)

### Obstacles
- **Types**: 
  - Low barrier (must dodge)
  - Tall pillar (full lane blocker)
- **Spawn Rate**: Every 30-50 frames, random lane
- **Colors**: Red/orange emissive, slight pulsing

### Coins
- **Shape**: Torus (ring)
- **Spawn Rate**: Every 20-40 frames, random lane
- **Rotation**: Continuous Y-axis rotation
- **Collection**: Player proximity triggers collection (+10 points)

### Scoring
- **Distance Score**: +1 point per 10 frames survived
- **Coin Bonus**: +10 points per coin collected
- **High Score**: Stored in localStorage

### Game States
- **Start Screen**: "Click to Start" overlay
- **Playing**: Active gameplay
- **Game Over**: Show score, "Click to Restart" overlay

## UI Specification

### HUD Elements
- **Score Display**: Top-left, large neon font
- **High Score**: Top-right, smaller font
- **Style**: Cyberpunk/retro-futuristic with text-shadow glow

### Overlays
- **Start Screen**: Semi-transparent dark overlay with game title and instructions
- **Game Over**: Score display, high score, restart prompt

## Audio (Optional Enhancement)
- No audio required for MVP

## Performance Targets
- **Target FPS**: 60fps
- **Object Pooling**: Reuse obstacles and coins to prevent garbage collection

## Acceptance Criteria
1. Game loads and displays 3D scene with neon aesthetic
2. Player can move left/right using keyboard or mouse
3. Obstacles spawn and scroll toward player
4. Coins spawn and can be collected for points
5. Collision with obstacle ends game
6. Score displays and updates in real-time
7. Game can be restarted after game over
8. High score persists between sessions
9. Smooth 60fps performance
10. Responsive to window resize