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