239 lines
9.8 KiB
Markdown
239 lines
9.8 KiB
Markdown
# 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.
|
|
|
|
---
|
|
|
|
## Hazards & Mechanics
|
|
|
|
### Implemented
|
|
- **Flame Vent** — Floor-mounted grate, toggles on/off on a timer
|
|
- **Force Field** — Vertical energy barrier, toggled by switch/timer
|
|
- **Moving Platform** — Horizontal/vertical patrol between two points
|
|
- **Laser Turret** — See Enemies above (also functions as a hazard)
|
|
|
|
### Planned
|
|
- **Bouncer** — Launch pad that shoots the player into the air on contact.
|
|
Two variants: straight (vertical impulse only) and angled (rotatable,
|
|
placed at arbitrary angles to launch the player diagonally or sideways).
|
|
Could also affect enemies and projectiles for puzzle potential.
|
|
|
|
---
|
|
|
|
## 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)
|