# Jump 'n Run - Game Design Document

## Concept

2D side-scrolling platformer with run-and-gun combat.
Inspired by **Jazz Jackrabbit 2**, **Metal Slug**, **Mega Man**, and classic 90s side-scrollers.

**Theme:** Sci-fi / space western (think *Cowboy Bebop*).
The player is a bounty hunter traveling between planets and space stations,
taking on jobs that play out as platformer levels.

---

## Game Structure

### Two Main Modes

**1. World Map (Spacecraft Navigation)**
- Top-down or side-view map showing planets, stations, asteroids
- Player pilots a spacecraft between locations
- Each location is a level (or hub with multiple levels)
- Map could be a simple node graph or free-flight between points
- Unlocking new areas as the story progresses
- Ship could have upgrades (fuel range, shields, scanner)

**2. Platformer Levels**
- Core gameplay: run, jump, shoot, explore
- Each level is a self-contained planet/station/ship with its own atmosphere
- Levels end with reaching an exit zone (or defeating a boss)
- Collectibles: currency (bounty credits), health pickups, weapon upgrades
- Optional objectives for bonus rewards

---

## Atmosphere System

Each level defines its own atmosphere, affecting gameplay feel:

| Property       | Effect                                      | Example Values          |
|----------------|---------------------------------------------|-------------------------|
| `GRAVITY`      | Fall speed and jump arc                     | 980 (earth), 400 (moon) |
| `WIND`         | Constant horizontal force on entities       | -50 to 50 px/s^2        |
| `STORM`        | Visual effect + periodic strong wind gusts  | 0 (calm) to 3 (severe)  |
| `DRAG`         | Air resistance (underwater, thick atmo)     | 0.0 (none) to 0.9       |
| `BG_COLOR`     | Background clear color                      | hex color               |
| `PARALLAX_FAR` | Far background image path                   | assets/bg/stars.png     |
| `PARALLAX_NEAR`| Near background image path                  | assets/bg/nebula.png    |
| `MUSIC`        | Level music track                           | assets/music/level1.ogg |
| `PALETTE`      | Color mood (warm, cold, toxic, void)        | tint/filter values      |

Already implemented: `GRAVITY`, `WIND`, `BG_COLOR`, `MUSIC`, `PARALLAX_FAR`, `PARALLAX_NEAR` (all per-level). Parallax backgrounds are procedurally generated (starfield + nebula) when no image path is specified.

---

## Player

- **Size:** 12x16 px hitbox, 16x16 sprite
- **Movement:** Run, jump (variable height, coyote time, jump buffer)
- **Dash:** C key, directional (horizontal, up, diagonal, down while airborne).
  Brief i-frames during dash. 0.15s duration, 0.4s cooldown.
- **Combat:** Shoot projectiles (X or Space), directional aiming with UP key
  (straight up, or diagonal when combined with LEFT/RIGHT)
- **Camera:** Holding UP while standing still pans the camera upward
- **Health:** 3 HP (expandable), invincibility frames + knockback on hit
- **Death / Respawn:** Death animation plays, then 1s delay before respawning at level spawn with full HP, charges, and brief invincibility. Falling off the level kills instantly with 0.3s delay.
- **Future abilities:**
  - Wall slide / wall jump
  - Weapon switching (multiple projectile types from the def system)
  - Double jump (upgrade)
  - Melee attack (close range, stronger)

---

## Enemies

### Implemented
- **Grunt** — Red spiky ground patrol. Walks back and forth, turns at edges/walls. 2 HP.
- **Flyer** — Purple bat-like. Bobs in air, chases player when close, shoots fireballs. 1 HP.
- **Turret** — Stationary, rotates to aim at player, fires periodically

- **Charger** — Ground patrol, detects player in 200 px horizontal LOS, ALERT → CHARGE (150 px/s) → STUNNED on wall hit. 2 HP.
- **Spawner** — Stationary, spawns grunts every 4.5 s (max 3 alive). 3 HP, destructible.
- **Laser Turret** — State machine (IDLE → CHARGING → FIRING → COOLDOWN). Per-pixel beam raycast. Fixed variant aims left; tracking variant rotates toward player at 1.5 rad/s.

### Planned
- **Shielder** — Has a directional shield, must be hit from behind or above
- **Boss** — Large, multi-phase encounters. One per world area.

---

## Weapons / Projectiles

Data-driven system: each weapon type is a `ProjectileDef` struct describing speed,
damage, lifetime, hitbox, behavior flags, and animations. Adding a new weapon =
adding a new def. See `src/game/projectile.h` for the full definition.

### Behavior flags
- `PROJ_PIERCING` — Passes through enemies (up to `pierce_count` times)
- `PROJ_BOUNCY` — Ricochets off walls (up to `bounce_count` times)
- `PROJ_GRAVITY` — Affected by level gravity (scaled by `gravity_scale`)
- `PROJ_HOMING` — Steers toward nearest valid target

### Implemented weapon defs
| Weapon          | Speed | Damage | Special                  | Owner  |
|-----------------|-------|--------|--------------------------|--------|
| `WEAPON_PLASMA` | 400   | 1      | Default player weapon    | Player |
| `WEAPON_SPREAD` | 350   | 1      | Short range, fan pattern | Player |
| `WEAPON_LASER`  | 600   | 1      | Pierces 3 enemies        | Player |
| `WEAPON_ROCKET` | 200   | 3      | Slight gravity drop      | Player |
| `WEAPON_BOUNCE` | 300   | 1      | 3 wall bounces + gravity | Player |
| `WEAPON_ENEMY_FIRE` | 180 | 1    | Enemy fireball           | Enemy  |

### Directional aiming
- Forward (default) — shoots horizontally in facing direction
- Up — hold UP to shoot straight up
- Diagonal up — hold UP + LEFT/RIGHT to shoot at 45 degrees

---

## Levels

### Format (.lvl)
Current directives: `TILESET`, `SIZE`, `SPAWN`, `GRAVITY`, `WIND`, `BG_COLOR`, `MUSIC`, `PARALLAX_FAR`, `PARALLAX_NEAR`, `TILEDEF`, `ENTITY`, `EXIT`, `LAYER`

**Needed additions:**
- `STORM`, `DRAG` — Remaining atmosphere settings

### Level Ideas

0. **Intro Level (Moon)** - Low gravity, bright surface, spacey/no obstacles
1. **Mars Surface** - Low gravity, red surface, spacey, little to no obstacles, transition area is entry to base
2. **Mars Base** - Normal gravity, very vertical, narrow, 90 degree turns, lots of enemies 
3. **Derelict Station** — Low gravity, dark, flickering lights, abandoned corridors
4. **Desert Planet (Saturn)** — High gravity, sand storm wind, bright orange palette
5. **Gas Giant (Jupiter)** — Very low gravity, floating platforms, toxic atmosphere
6. **Asteroid Belt** — Zero-G sections, small disconnected platforms
7. **Space Freighter** — Normal gravity, tight corridors, turret enemies
8. **Ice World** — Normal gravity, strong winds, slippery surface

---

## World Map

### Structure
- Graph of nodes (planets/stations) connected by routes
- Player selects destination, spacecraft flies there (short animation or instant)
- Some routes may require fuel/upgrades to unlock
- Map reveals new nodes as levels are completed

### Implementation Notes
- Separate game state from the platformer (own update/render)
- Needs: node data structure, spacecraft position, route rendering
- Could start simple: linear level select, evolve into open map

---

## Technical TODO

### High Priority
- [x] Entity spawn directives in .lvl format (`ENTITY` directive)
- [x] Level exit zones and level transitions
- [x] Dash mechanic
- [x] Particle system (death puffs, landing dust, projectile impact sparks, wall slide dust)
- [x] Screen shake on damage / enemy kills
- [x] Sound effects (jump, shoot, hit, enemy death, dash)
- [x] Basic HUD (health hearts + jetpack charges)

### Medium Priority
- [x] In-game level editor (tile/entity placement, save/load, test play)
- [x] Wind atmosphere property (`WIND` directive, affects all entities/particles/projectiles)
- [ ] Drag atmosphere property
- [x] Parallax scrolling backgrounds (procedural stars + nebula, or from image files)
- [x] Per-level background color (`BG_COLOR` directive)
- [x] Music playback per level (`MUSIC` directive)
- [ ] Weapon switching system
- [x] Pickup entities (health, jetpack refill, drone companion)
- [ ] Better tileset art (space-themed)
- [ ] Player sprite polish (more animation frames)
- [x] Death / respawn system
- [x] Pause menu

### Low Priority (Future)
- [ ] World map mode
- [ ] Spacecraft navigation
- [ ] Boss encounters
- [ ] Dialogue / mission briefing system
- [ ] Save system
- [ ] Controller support (SDL_GameController is initialized)
- [ ] Multiple playable characters

---

## Art Direction

- Pixel art, 16x16 tile grid
- Logical resolution: 640x360 (rendered at 2x = 1280x720)
- Nearest-neighbor scaling for crisp pixels
- Dark, moody color palettes with bright projectile/effect accents
- Inspired by: Cowboy Bebop color grading, retro sci-fi, neon-on-dark

---

## Controls

| Action    | Key          | Status        |
|-----------|--------------|---------------|
| Move      | Arrow keys   | Implemented   |
| Jump      | Z / Space    | Implemented   |
| Shoot     | X            | Implemented   |
| Aim up    | UP (+ shoot) | Implemented   |
| Aim diag  | UP+LEFT/RIGHT (+ shoot) | Implemented |
| Dash      | C            | Implemented   |
| Look up   | UP (stand still) | Implemented |
| Pause     | Escape       | Implemented   |

---

## Reference Games
- Jazz Jackrabbit 2 (movement feel, weapon variety, level design)
- Metal Slug (run-and-gun, enemy variety, visual flair)
- Mega Man X (dash, tight controls)
- Cowboy Bebop (aesthetic, tone, music style)