major_tom/DESIGN.md

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, 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

Planned

• Charger — Detects player at range, charges in a straight line at high speed
• Shielder — Has a directional shield, must be hit from behind or above
• Spawner — Stationary, periodically spawns smaller enemies
• 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, BG_COLOR, MUSIC, PARALLAX_FAR, PARALLAX_NEAR, TILEDEF, ENTITY, LAYER

Needed additions:

• EXIT <tile_x> <tile_y> <next_level> — Level exit zone
• WIND, STORM, DRAG — 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

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

Medium Priority

• In-game level editor (tile/entity placement, save/load, test play)
• Wind / drag atmosphere properties
• Parallax scrolling backgrounds (procedural stars + nebula, or from image files)
• Per-level background color (BG_COLOR directive)
• Music playback per level (MUSIC directive)
• Weapon switching system
• Pickup entities (health, jetpack refill, drone companion)
• Better tileset art (space-themed)
• Player sprite polish (more animation frames)
• Death / respawn system
• 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	Implemented
Shoot	X / Space	Implemented
Aim up	UP (+ shoot)	Implemented
Aim diag	UP+LEFT/RIGHT (+ shoot)	Implemented
Dash	C	Implemented
Look up	UP (stand still)	Implemented
Pause	Escape	Quits game

---

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)