Papay-Shooter/DESIGN_MASTER.md

Papaya Shooter — Master Development Document

Status: v0.1 DRAFT — Living document, updated as phases complete
Engine: Godot 4.6 (Forward Plus renderer, Jolt Physics)
Goal: Steam-publishable fast-paced FPS with juice, movement depth, and content
References: Banana Shooter, Titanfall 2, Karlson, ULTRAKILL, DOOM Eternal

---

1. Game Vision

Papaya Shooter is a speed-first, juice-heavy FPS where movement is the primary weapon. Combat rewards aggression, creativity, and chain-movement mastery. Every frame should feel responsive, every kill should feel like a touchdown.

Core pillars:

1. Movement is gameplay — not just traversal
2. Juice everywhere — screen shake, hit-stop, particle bursts, audio feedback
3. Simple to learn, skill-ceiling to master — basic shooting works, chaining rocket+jumpshot+wallrun feels divine
4. Accessible but competitive — solo content first, MP stretch goal

---

2. Movement System Specification

2.1 Base Locomotion

Mechanic	Key	Trigger	Parameters
Walk	WASD	Always	Speed: 7.0 m/s
Sprint	Shift	Hold	Speed: 11.0 m/s
Jump	Space	Press	Height: 1.2m, Coyote: 150ms
Bunny Hop	Space (air)	Frame-perfect	+0.5m/s per hop, cap: 16m/s
Slide	Ctrl (sprint)	Hold	Speed: 14m/s, friction: 0.85/s
Wall Run	Jump (wall)	±80° wall angle	Speed: 12m/s, vertical: 8m/s
Wall Cling	Wall + no input	Wall + normal	Drain stamina 2/s
Wall Jump	Jump (wall cling)	—	Push: 12m/s +8m/s off-normal
Rocket Jump	Fire (down)	Explosion below	Damage: self 15%, Speed: impulse 20m/s
Shotgun Jump	Fire (down)	Pellet hit feet	Same impulse, no self-damage
Dash	L-Shift	Air only, 1s CD	15m/s burst, 0.3s duration
Double Jump	Double-tap jump	Air, double-tap	Second jump: 8m/s, no reset

2.2 Momentum Chaining (The Juice Core)

Jetpack (stretch) ← Slide → Wall Run → Wall Jump → Bunny Hop → Rocket Jump
      ↑                                                          |
      └──────────────────────────────────────────────────────────┘

Chaining rules:

• Speed carries between mechanics (no hard cut)
• Each successful chain adds 5% bonus speed (stacking, cap +50%)
• Score multiplier scales with consecutive unique mechanics used
• HUD shows chain meter with mechanic icons

2.3 Implementation (movement/)

movement/
├── player_movement_controller.gd        # Main state machine (FPS)
├── movement_state_machine.gd            # Generic SM base
├── states/
│   ├── ground_state.gd                  # Walk/sprint/slide
│   ├── air_state.gd                     # Jump/fall/bunny hop
│   ├── wall_run_state.gd
│   ├── wall_cling_state.gd
│   ├── slide_state.gd
│   └── dash_state.gd
├── movement_params.tres                 # Tunable parameters resource
└── tests/
    ├── test_sliding.gd
    ├── test_wallrun.gd
    └── test_bunny_hop.gd

2.4 Remaining Implementation

Implementation continues with the complete movement mechanics specification:

Implementation Details:

• Player movement controller handles full state machine with physics optimization
• Each state tracks transitions to maintain momentum fluidity
• Physics interactions preserve velocity across mechanic switches
• Transfer function f(old_velocity, direction) → new_velocity ensures seamless movement

Testing Approach:

• Comprehensive GDScript test suite
• Physics simulation testing for edge cases
• Regression tests for mechanic interactions

---

3. Combat System Specification

3.1 Weapons

Weapon	Type	Damage	Fire Rate	Special
Blaster	Hitscan	15	0.15s	—
Shotgun	Spread (8 pellets)	8/pellet	0.6s	Self-impulse on pellets
Rocket Launcher	Projectile	80 splash	1.0s	Rocket Jump enabler
Plasma	Charge	25-100	0.8s	Overcharge mechanic

3.2 Enemy Types

Wave 1 — Grunt (banana-themed):

• Health: 30 HP
• Behavior: Charge, stop, fire
• Art: Low-poly banana with bandolier

---

4. Implementation Roadmap

Development is tracked through GitHub Issues (Gitea). Each phase resolves into labeled, claimable issues. The autonomous dev loop (Ralph Loop) processes issues in priority order.

Phase 1: Foundation (P0)

#	Issue	Scope
1	Movement state machine	Core locomotion
2	Weapon framework	Base weapon class
3	Banana enemy AI	Basic enemy

Phase 2: Combat (P1)

#	Issue	Scope
4	Weapon implementation	All 4 weapons
5	Damage system	Health, hurtboxes

Phase 3: Polishing (P2)

#	Issue	Scope
6	Juice & VFX	Screen shake, particles
7	UI/HUD	Score, chain meter
8	Audio	Footsteps, impacts

Phase 4: Content (P3)

#	Issue	Scope
9	Level 1	First playable level
10	Menus	Main menu, pause

---

5. Decision Log

Date	Decision	Rationale
—	Godot 4.6 Forward Plus	Best FPS support, open source
—	Jolt Physics	Active, fast, well-tested
—	GDScript	Team familiarity, fast iteration

---

6. Agent Operating Protocol

The autonomous dev team reads this document and:

1. Strategist agent:

   • Closes issues once merged
   • Removes in-progress label after PRs closed
   • Creates new issues based on design doc priorities when backlog drops below 5

2. Dev agent (Ralph Loop):

   • Claims P0 first, then P1, P2, P3
   • Max 3 attempts per issue before escalating
   • Commits only after tests pass

3. Reviewer agent:

   • Reviews PRs against requirements in this doc
   • Merges when CI green + acceptance criteria met

4. Enforcement:

   • Each subagent receives this document in its context
   • Issue descriptions reference exact sections of this doc
   • PR descriptions cite the spec section implemented