docs: add master development document for Papaya Shooter project specifications
This commit is contained in:
DottsGit
@@ -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