docs: add DESIGN_MASTER.md — §1–§6 master spec for Papaya-Shooter
Covers: vision, movement mechanics (ground/air/wallrun/cling/slide/dash/chain), combat (weapons/enemies), audio/juice, content roadmap, and decision log.
This commit is contained in:
@@ -0,0 +1,175 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user