Neon Galaxy (Galaxy Force / CPC464-inspired)
Game Design Document (Godot 4.5)
Version: 0.1 (single-run, Energy=0 fail; mouse-first; ship dodges)

============================================================
1) High Concept
============================================================
An arcade on-rails neon-branded shoot-’em-up inspired by Sega’s Galaxy Force and the Amstrad CPC464 port vibe: bold HUD frame, fast targets, readable bullet patterns, and score-chasing in short missions. The player aims with a reticle (mouse-first) while the ship also moves within a bounded playfield to dodge incoming fire.

============================================================
2) Design Pillars
============================================================
1. Readable chaos:
   - Dense action, but threats are visually clear and patterns are learnable.
2. Arcade numbers:
   - Score, Bonus, Energy are always active and meaningful.
3. Tight control:
   - Mouse aiming feels immediate; ship dodging is responsive and fair.
4. Short sessions:
   - Missions are bite-sized; restart is instant; tuning encourages “one more run.”

============================================================
3) Player Fantasy
============================================================
“I’m a lone pilot tearing through waves, dodging bullet curtains, building weapon power, and pushing for a ridiculous score—until one mistake drains my Energy and the run ends.”

============================================================
3.1) Galaxy Force Core Feel (Reference Pillars)
============================================================
Core feel:
- Forward-thrusting, on-rails flight through space and planetary vistas.
- The world rushes toward you; enemies scale up rapidly as they approach, creating depth and velocity.
- Sessions are short, intense, arcade-pure—built for score-chasing and quick restarts.

Visual identity:
- Bright, saturated colors with clean silhouettes.
- Huge sprite scaling creates the illusion of 3D without polygons.
- Dramatic set-pieces: asteroid fields, enemy armadas, space stations, planetary fly-bys.
- Minimal background clutter so enemy bullets and targets read instantly.

Gameplay:
- Crosshair aiming with continuous forward motion.
- Enemies arrive in clear formations and patterns, not random swarms.
- Dodging is as important as shooting—bullets form lanes you learn to read.
- Power-ups and score bonuses reward aggression and precision.

Audio & presentation:
- High-energy synth soundtrack pushing urgency and momentum.
- Loud, punchy SFX—shots, hits, explosions—never subtle, always readable.
- Sit-down/motion-cabinet energy: the player feels hurled through space.

Why it matters (fit for this project):
- Readable chaos: dense action without visual noise.
- Neon arcade framing: bold HUD elements and color-coded threats.
- Short, replayable runs driven by score, not narrative.

============================================================
4) Target Platforms + Inputs (Locked)
============================================================
Primary input target:
- Mouse (Amstrad CPC464 / arcade feel; modern PC mouse)

Secondary inputs (same gameplay parity):
- Keyboard
- Controller

Run structure (locked):
- Single-run; Energy to zero = fail (no extra lives).

============================================================
5) Core Gameplay Loop
============================================================
1) Enter mission (on-rails forward motion).
2) Aim with reticle; ship drifts within bounds to dodge.
3) Destroy enemies -> score increases; multiplier rises.
4) Collect pickups (Energy, Weapon Power, Bonus).
5) Survive waves until mission ends (timer or boss).
6) Mission end converts Bonus meter to score.
7) Results screen -> restart or next mission.

============================================================
6) Camera + World Model
============================================================
Primary style:
- On-rails forward motion (the world advances continuously).

Rendering approach (assumption, changeable):
- 2D implementation with “depth illusion”:
  - Enemies spawn “far” (smaller), scale up as they approach.
  - Background uses parallax layers and perspective-ish motion.
  - Bullets can remain screen-space for readability.

Note:
- If you later want true 3D terrain and enemies, this design still holds, but the rendering pipeline changes.

============================================================
7) Controls (Mouse-first + ship dodging)
============================================================
7.1 Mouse (Primary)
- Aim reticle: mouse movement
- Fire: Left click (hold for auto-fire)
- Bomb/Special: Right click
- Focus/Slow: Middle click OR Shift (optional)

Ship movement:
- The ship moves independently within the playfield to dodge.
- By default:
  - Ship “follows” the reticle position (soft spring), but is clamped to bounds.
  - This keeps mouse aiming dominant while preserving true dodging.

7.2 Keyboard (Fallback)
- Reticle move: WASD or Arrow keys (accelerated cursor)
- Fire: Space (hold)
- Bomb: Ctrl
- Focus/Slow: Shift

7.3 Controller (Fallback)
- Reticle move: Left stick
- Fire: A / Cross
- Bomb: X / Square
- Focus/Slow: LB / L1

Input parity rule:
- All input methods control the reticle.
- The ship movement model is derived from reticle position (plus clamping), so tuning is consistent.

============================================================
8) Player Mechanics
============================================================
8.1 Movement (Ship dodging)
- Playfield bounds: ship cannot leave the action frame.
- Ship position is a smoothed function of reticle target:
  - ship_target = screen_center + (reticle_pos - screen_center) * drift_scale
  - ship_pos moves toward ship_target with spring smoothing
  - ship_pos clamped to bounds

Parameters to tune:
- drift_scale (0.4–1.0)
- max_speed
- acceleration / spring strength
- focus modifier (reduces ship speed + reticle sensitivity)

8.2 Fire
- Continuous primary fire while held.
- Weapon upgrades change shot pattern (see 10).

8.3 Energy (Locked: single-run)
- Energy is a numeric pool shown prominently in HUD.
- Player hit reduces Energy.
- Energy reaching 0 ends the run immediately (fail state).

8.4 Bomb / Special
- Limited per mission (e.g., 2–3).
- Clears bullets in radius or screen; deals heavy damage.
- Optional scoring penalty:
  - bomb use reduces multiplier temporarily (prevents bomb spam dominance).

============================================================
9) Enemy Design
============================================================
Goal: distinct silhouettes + distinct bullet behavior.

Baseline enemy set:
1) Drone:
   - Slow, straight approach; single shots.
2) Striker:
   - Fast fly-by; attempts flank lines; short burst.
3) Turret:
   - Stationary or slow drift; patterned spread.
4) Carrier:
   - Higher HP; periodically spawns drones.
5) Elite:
   - Mini-boss; higher HP; drops good loot; signature pattern.
6) Boss:
   - Multi-phase, clear patterns, “safe lanes” to learn.

Readability rules:
- Bullets must be visible against background (contrast).
- Enemy bullets should be slightly larger than true hitbox fairness implies.
- Telegraph elites/bosses with sound + color.

============================================================
10) Weapons + Power Progression
============================================================
Weapon power is a pickup-driven ladder (fast to understand, arcade feel).

Weapon Levels (example):
- L1: single shot
- L2: double shot
- L3: triple spread
- L4: forward + side shots
- L5: forward + wide side shots

Optional alternate weapons (later):
- Laser (piercing, narrow)
- Spread (wide, lower DPS)
- Homing (low damage, convenience)

Rules:
- Weapon power can drop by 1–2 levels on taking damage (optional).
- Max weapon level capped (e.g., 5).

============================================================
11) Scoring, Multiplier, Bonus (Galaxy Force-ish HUD)
============================================================
11.1 Score
- Points awarded per enemy kill (tier-based).
- Total points = base_points * current_multiplier.

11.2 Multiplier
Multiplier increases by:
- Chaining kills within a combo window
- Collecting Bonus pickups
- Optional “grazing” (near-miss bullets) if you want extra skill expression

Multiplier decreases by:
- Taking damage (big drop)
- Letting combo window expire (gradual decay)
- Optional: using Bomb (small temporary penalty)

11.3 Bonus Meter (HUD: BONUS)
Bonus fills by:
- Bonus pickups
- Elite kills
- “Clean play” time without taking damage (optional)

Cash-out:
- At mission end: Bonus_meter converts to score using a formula:
  - bonus_score = Bonus_meter * bonus_multiplier (tied to max multiplier achieved)

Death penalty (recommended):
- If the run ends by Energy=0:
  - only 30–50% of stored Bonus converts (keeps tension without lives).

============================================================
12) Mission Structure
============================================================
Mission length target:
- 2–4 minutes per mission (early missions shorter).

Mission types:
1) Survival (timer-based):
   - Survive 120 seconds; escalating waves.
2) Wave Clear:
   - Clear N waves; faster if you kill efficiently.
3) Assassination:
   - Kill an Elite target + escorts.
4) Boss Mission:
   - 60–90 seconds of lead-in waves then boss.

Difficulty curve:
- Mission 1: low density; teaches dodging + reticle aiming.
- Mission 2: introduces patterned spreads + elites.
- Mission 3: mixed waves + higher speed.
- Mission 4+: dense patterns; demands Focus usage.

Branching path plan (OutRun-like):
- End of a stage presents a left/right (or multi) route choice that leads to a different next stage.
- For MVP: implement a single straight line (Stage 1 only), but structure the flow so branches can be added later.
- Short-term: all branches can point to the same next stage data (placeholder) while we build content.
- Goal: complete Stage 1 with a clear stage-end and a branch selection moment (even if it loops to the same content).

Stage 1 (MVP) content outline:
- Length: ~2:00 total (3 segments: intro, mid, finish).
- Beat 1 (0:00-0:40): light Drone waves, single-shot patterns, gentle reticle/ship drift tutorial pacing.
- Beat 2 (0:40-1:20): add Strikers with fly-by bursts; introduce simple 3-way Turret spreads.
- Beat 3 (1:20-2:00): mixed waves + one Elite with a readable signature pattern; clear stage-end.
- Pickups: Energy and Bonus in early beats; first Weapon Power in Beat 2; second Weapon Power near Elite.
- Background: parallax starfield with a single landmark pass (planet or station) near the stage-end.

Stage 1 wave timeline (draft):
Time     | Spawn group         | Count | Pattern/Notes
0:05     | Drone line          | 6     | Straight approach, single shots
0:15     | Drone arc           | 8     | Shallow arc, staggered fire
0:25     | Turret pair         | 2     | 3-way slow spread, center lane
0:35     | Drone sweep         | 10    | Left-to-right sweep, light fire
0:45     | Striker duo         | 2     | Fast fly-by, short burst
0:55     | Drone line          | 6     | Straight approach, single shots
1:05     | Turret trio         | 3     | 3-way spread, offset lanes
1:15     | Striker trio        | 3     | Staggered fly-bys, alternating sides
1:25     | Mixed wave          | 8     | Drones + 1 Turret, light overlap
1:35     | Elite entry         | 1     | Signature pattern, drop Weapon Power
1:50     | Cleanup wave        | 6     | Drones, low density, lead-out

Drop rules (MVP):
- Clearing a spawn group rolls a random drop (score/bonus or shield/energy).
- Timed drop spawner for additional weapon types (rockets, lasers, missiles, etc.).

Drop table (group-clear roll, MVP):
- Score Chip: 40% (score-only pickup; small value)
- Bonus Chip: 30% (fills Bonus meter)
- Shield Cell: 20% (restores Energy)
- Weapon Power: 10% (only if not at max; otherwise convert to Bonus)

Timed weapon drop cadence (MVP):
- Spawn every 25 seconds during active combat (skip if Elite is active).
- Sequence: Rocket -> Laser -> Missile -> repeat (initial order fixed, later can randomize).
- If player already has that weapon type, convert to Score Chip.

Stage-end branch selection (MVP UI/HUD):
- At stage clear, slow world motion and present a center-screen fork banner (LEFT / RIGHT).
- Show two route cards with short labels (e.g., "Nebula Run" / "Orbital Grid") even if they both map to the same data.
- Input: reticle hover + click, or left/right + confirm on keyboard/controller.
- Timer: 5 seconds; default to highlighted route if time expires.
- After selection, fade to next stage (for MVP, loop to the same Stage 1 data or a placeholder "Stage 2" stub).

============================================================
12.1) FINAL STAGE STRUCTURE (LOCKED)
============================================================

STAGE 1 — NEON FRONTIER
Theme: Open space / swarms
What the player experiences:
- Pure space combat
- Large enemy formations
- Learning speed, depth, passing enemies

Stage-select image should show:
- Neon grid fading into space
- Starfield + abstract light streaks
- No terrain, no clutter

Feeling: confidence, scale, velocity
Boss: Capital ship / swarm controller

STAGE 2 — ASTEROID BELT
Theme: Navigation + precision
What the player experiences:
- Dense asteroid fields
- Tight dodging
- Shooting enemies while threading gaps
- First real environmental pressure

Stage-select image should show:
- Asteroids forming a tunnel or arc
- Explosions embedded in rock
- Harsh lighting, sparks

Feeling: danger, compression
Boss: Asteroid-embedded fortress or drilling core

STAGE 3 — FORGE WORLD
Theme: Surface combat + industry
What the player experiences:
- Breaking through clouds
- Flying low over the surface
- Lava flows, foundries, mining structures
- Digging around lava mountains
- Heavy industrial enemies

Stage-select image should show:
- Cloud break revealing glowing lava below
- Industrial silhouettes / heat glow
- No cities, no realism — stylised industry

Feeling: heat, scale, hostility
Boss: Planetary forge guardian / molten war engine

STAGE 4 — CAVERN RUN
Theme: Confinement + tension
What the player experiences:
- Diving into caverns
- Tight gaps, walls closing in
- Reduced visibility
- Enemies ambushing from sides and ceilings
- Pressure ramps continuously

Stage-select image should show:
- Cavern mouth with glowing veins
- Crystalline or molten highlights
- Strong tunnel perspective

Feeling: claustrophobia, momentum
Boss: Cavern leviathan / ancient drill guardian

STAGE 5 — CORE BATTLE
Theme: Final escalation
What the player experiences:
- Caverns open into a vast core chamber
- Abstract geometry
- Energy conduits, impossible scale
- Minimal terrain, maximum threat
- Everything learned is tested

Stage-select image should show:
- Glowing planetary core
- Symmetry and menace
- Abstract shapes, not rocks

Feeling: finality, power
Boss: The Core Entity (final game boss)

IMPORTANT: STAGE-SELECT IMAGE RULES
For stage select only (not gameplay backgrounds):
- One strong, readable idea per stage
- No HUD
- No enemies required (suggested, not necessary)
- High contrast
- Thumbnail-readable at small sizes
- 16:9
- Title text separate or optional

These are signposts, not environments.

============================================================
13) HUD + UI Specification (framed arcade look)
============================================================
Top bar:
- Left: MISSION {n}
- Right: SCORE {value}

Bottom bar:
- Left: ship icon + bombs count (icon row)
- Center: ENERGY {value} (big numeric) + bar
- Right: BONUS {value} + bar
- Optional small: MULTI x{n}

Results screen:
- Mission result: CLEAR / FAIL
- Score breakdown:
  - Kill score
  - Bonus cash-out
  - Max multiplier
  - Accuracy (optional)
  - Damage taken / hits

============================================================
14) Visual Direction (Neon-drenched shooter + CPC464 vibe)
============================================================
- Retro sprites with limited palette feel (CPC-ish), but with modern clarity.
- Big, bold HUD frame, neon-drenched glow and signage (logo plates, glowing trim, sponsor-like tags).
- Explosions: chunky sprite anims + additive-like particles (fake with bright sprites).
- Background: parallax starfields / planet surfaces / abstract “tunnel” lanes.

Pixel rules:
- Use integer scaling and nearest-neighbor filtering.
- Lock internal resolution (e.g., 320x180 or 400x225) then scale.

============================================================
15) Audio Direction
============================================================
- High-tempo arcade synth / FM-ish tone.
- SFX priority:
  - Player shot (not too loud)
  - Enemy shot (sharp)
  - Player hit (very clear)
  - Pickup (satisfying)
  - Bomb (big, distinctive)
- Music ramps at elites/boss.

============================================================
16) Technical Plan (Godot 4.5)
============================================================
16.1 Scene Tree
Main.tscn
- GameController (Node)          // mission state, transitions
- World (Node2D)                 // gameplay root
  - Background (Node2D)          // parallax layers
  - Spawner (Node)               // spawn director
  - Player (CharacterBody2D)
  - Enemies (Node2D)
  - Bullets (Node2D)
  - Pickups (Node2D)
  - Effects (Node2D)
- HUD (CanvasLayer)
- PauseMenu (Control)

16.2 Key Scenes
- Player.tscn (CharacterBody2D)
- Reticle.tscn (Node2D / Sprite2D)
- Enemy_Base.tscn (Node2D)
- Bullet_Player.tscn (Area2D)
- Bullet_Enemy.tscn (Area2D)
- Pickup.tscn (Area2D)
- Explosion.tscn (AnimatedSprite2D)

16.3 Autoloads (recommended)
- GameState.gd     // score, bonus, energy, multiplier
- SpawnDirector.gd // reads mission data, emits spawns
- AudioManager.gd  // music/SFX
- Settings.gd      // scaling, input, volume
- Pool.gd          // bullet pooling

16.4 Data-driven Missions
Mission JSON example fields:
- id, name, duration
- wave_events: list of {time, group_id, count, pattern}
- boss_id (optional)
- reward modifiers (optional)

============================================================
17) Performance Notes
============================================================
- Bullets should use pooling (avoid per-bullet instancing churn).
- Tight collision layers:
  - Player hitbox vs enemy bullets
  - Enemies vs player bullets
  - Player vs pickups
- Recycle off-screen bullets quickly.

============================================================
18) MVP Scope (first playable)
============================================================
Must have:
- Reticle input (mouse + keyboard + controller)
- Ship drift movement (bounded dodging)
- Primary fire + bullets + collisions
- Energy system (single-run fail)
- Score + multiplier + bonus meter
- HUD frame with live numbers
- 1 mission (2 minutes survival) + results screen
- 3 enemies (Drone, Striker, Turret)

Next (iteration):
- Bomb
- Weapon power levels (to L5)
- Elite
- Boss mission

============================================================
19) Key Tuning Checklist
============================================================
- Reticle sensitivity (mouse)
- drift_scale, ship max speed, focus modifiers
- Bullet readability (contrast, speed, density)
- Energy drain per hit (fair but punishing)
- Bonus cash-out fraction on fail (30–50% recommended)
- Mission length and escalation pacing

============================================================
20) Open Decisions (not blocking MVP)
============================================================
- True 3D vs 2D depth illusion
- Grazing mechanic (yes/no)
- Weapon power loss on hit (yes/no)
- Bomb scoring penalty (yes/no)

End of document.