ptarrant/Code_of_Conquest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Implement Phase 5 Quest System (100% complete)

Browse Source 
Add YAML-driven quest system with context-aware offering:

Core Implementation:
- Quest data models (Quest, QuestObjective, QuestReward, QuestTriggers)
- QuestService for YAML loading and caching
- QuestEligibilityService with level, location, and probability filtering
- LoreService stub (MockLoreService) ready for Phase 6 Weaviate integration

Quest Content:
- 5 example quests across difficulty tiers (2 easy, 2 medium, 1 hard)
- Quest-centric design: quests define their NPC givers
- Location-based probability weights for natural quest offering

AI Integration:
- Quest offering section in npc_dialogue.j2 template
- Response parser extracts [QUEST_OFFER:quest_id] markers
- AI naturally weaves quest offers into NPC conversations

API Endpoints:
- POST /api/v1/quests/accept - Accept quest offer
- POST /api/v1/quests/decline - Decline quest offer
- POST /api/v1/quests/progress - Update objective progress
- POST /api/v1/quests/complete - Complete quest, claim rewards
- POST /api/v1/quests/abandon - Abandon active quest
- GET /api/v1/characters/{id}/quests - List character quests
- GET /api/v1/quests/{quest_id} - Get quest details

Frontend:
- Quest tracker sidebar with HTMX integration
- Quest offer modal for accept/decline flow
- Quest detail modal for viewing progress
- Combat service integration for kill objective tracking

Testing:
- Unit tests for Quest models and serialization
- Integration tests for full quest lifecycle
- Comprehensive test coverage for eligibility service

Documentation:
- Reorganized docs into /docs/phases/ structure
- Added Phase 5-12 planning documents
- Updated ROADMAP.md with new structure

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Phillip Tarrant
2025-11-29 15:42:55 -06:00
parent e7e329e6ed
commit df26abd207
42 changed files with 8421 additions and 2227 deletions
Download Patch File Download Diff File Expand all files Collapse all files

247
docs/phases/Phase7-Multiplayer.md Normal file
View File

@@ -0,0 +1,247 @@
# Phase 7: Multiplayer Sessions
**Goal:** Invite-based, time-limited co-op sessions for Premium/Elite players
**Priority:** Low
**Status:** Not Started
**Last Updated:** November 29, 2025
---
## Overview
Multiplayer is a paid-tier feature focused on short co-op adventures. Unlike solo story progression, multiplayer sessions are time-limited (2 hours), invite-based, and combat-focused.
**Key Features:**
- Premium/Elite tier only
- Shareable invite links (8-char alphanumeric codes)
- 2-4 player parties
- 2-hour session duration
- AI-generated custom campaigns
- Realtime synchronization via Appwrite
- Character snapshots (doesn't affect solo campaigns)
**Reference:** See `/api/docs/MULTIPLAYER.md` for detailed technical specification.
---
## Task Groups
### Core Infrastructure (7 tasks)
| Task ID | Task | Status | Notes |
|---------|------|--------|-------|
| 7.1 | Create MultiplayerSession dataclass | ⬜ | Extends GameSession with time limits, invite codes |
| 7.2 | Create PartyMember dataclass | ⬜ | Player info, character snapshot, ready status |
| 7.3 | Create MultiplayerCampaign models | ⬜ | Campaign, CampaignEncounter, CampaignRewards |
| 7.4 | Implement invite code generation | ⬜ | 8-char alphanumeric, unique, 24hr expiration |
| 7.5 | Implement 2-hour timer logic | ⬜ | Session expiration, warnings (10min, 5min, 1min) |
| 7.6 | Set up Appwrite Realtime subscriptions | ⬜ | WebSocket for live session updates |
| 7.7 | **Checkpoint:** Verify data models | ⬜ | Test serialization and Appwrite storage |
**Deliverable:** Core multiplayer data structures ready
---
### Session Management APIs (5 tasks)
| Task ID | Task | Status | Notes |
|---------|------|--------|-------|
| 7.8 | Implement session creation API | ⬜ | `POST /api/v1/multiplayer/create` (Premium/Elite only) |
| 7.9 | Implement join via invite API | ⬜ | `POST /api/v1/multiplayer/join/{invite_code}` |
| 7.10 | Implement lobby system | ⬜ | Ready status, player list, host controls |
| 7.11 | Implement session start API | ⬜ | Host starts when all players ready |
| 7.12 | Implement session end/cleanup | ⬜ | Auto-end at 2 hours, manual end by host |
**API Endpoints:**
```
POST /api/v1/multiplayer/create - Create new session (host)
POST /api/v1/multiplayer/join/{code} - Join via invite code
GET /api/v1/multiplayer/{id}/lobby - Get lobby state
POST /api/v1/multiplayer/{id}/ready - Toggle ready status
POST /api/v1/multiplayer/{id}/start - Start session (host only)
POST /api/v1/multiplayer/{id}/leave - Leave session
POST /api/v1/multiplayer/{id}/end - End session (host only)
```
**Deliverable:** Full session lifecycle management
---
### Campaign Generation (4 tasks)
| Task ID | Task | Status | Notes |
|---------|------|--------|-------|
| 7.13 | Create campaign templates | ⬜ | Pre-built structures for AI to fill |
| 7.14 | Implement AI campaign generator | ⬜ | Generate 3-5 encounters based on party composition |
| 7.15 | Implement encounter sequencing | ⬜ | Linear progression through encounters |
| 7.16 | **Checkpoint:** Test campaign generation | ⬜ | Verify AI creates balanced encounters |
**Campaign Structure:**
```yaml
campaign:
name: "The Cursed Crypt"
description: "A short adventure into an undead-infested tomb"
encounters:
- type: "exploration"
description: "Navigate the tomb entrance"
- type: "combat"
enemies: [skeleton_warrior, skeleton_archer]
- type: "puzzle"
description: "Ancient door mechanism"
- type: "boss"
enemies: [lich_lord]
rewards:
gold_per_player: 500
experience_per_player: 1000
item_pool: ["rare", "epic"]
```
**Deliverable:** AI-generated campaigns for parties
---
### Multiplayer Combat (4 tasks)
| Task ID | Task | Status | Notes |
|---------|------|--------|-------|
| 7.17 | Implement turn management for parties | ⬜ | Initiative, turn order, action validation |
| 7.18 | Extend combat system for multi-player | ⬜ | Reuse Phase 4 combat, add party support |
| 7.19 | Implement disconnect handling | ⬜ | Auto-defend mode, host promotion on disconnect |
| 7.20 | Implement reward distribution | ⬜ | Calculate and grant rewards at session end |
**Turn Order:**
```
1. Roll initiative for all players and enemies
2. Sort by initiative (highest first)
3. Each turn:
- Notify current player via Realtime
- Wait for action (30 second timeout → auto-defend)
- Process action
- Update all clients via Realtime
4. After all enemies defeated → next encounter
```
**Deliverable:** Working party combat system
---
### Multiplayer UI (4 tasks)
| Task ID | Task | Status | Notes |
|---------|------|--------|-------|
| 7.21 | Create lobby UI | ⬜ | `templates/multiplayer/lobby.html` - Player list, ready status, invite link |
| 7.22 | Create active session UI | ⬜ | `templates/multiplayer/session.html` - Timer, party status, combat, narrative |
| 7.23 | Create session complete UI | ⬜ | `templates/multiplayer/complete.html` - Rewards, stats, MVP badges |
| 7.24 | Implement Realtime UI updates | ⬜ | WebSocket subscription for live state |
**Deliverable:** Full multiplayer UI experience
---
### Testing & Validation (4 tasks)
| Task ID | Task | Status | Notes |
|---------|------|--------|-------|
| 7.25 | Write unit tests | ⬜ | Invite generation, join validation, timer logic |
| 7.26 | Write integration tests | ⬜ | Full session flow: create → join → play → complete |
| 7.27 | Test realtime synchronization | ⬜ | Multiple browsers simulating party gameplay |
| 7.28 | **Final Checkpoint:** Test session expiration | ⬜ | Force expiration, verify cleanup and reward distribution |
**Deliverable:** Validated multiplayer system
---
## API Endpoints Summary
| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/v1/multiplayer/create` | Create new multiplayer session |
| `POST` | `/api/v1/multiplayer/join/{code}` | Join via invite code |
| `GET` | `/api/v1/multiplayer/{id}/lobby` | Get lobby state |
| `POST` | `/api/v1/multiplayer/{id}/ready` | Toggle ready status |
| `POST` | `/api/v1/multiplayer/{id}/start` | Start session (host) |
| `POST` | `/api/v1/multiplayer/{id}/action` | Take action during session |
| `GET` | `/api/v1/multiplayer/{id}/state` | Get current session state |
| `POST` | `/api/v1/multiplayer/{id}/leave` | Leave session |
| `POST` | `/api/v1/multiplayer/{id}/end` | End session (host) |
---
## Files to Create/Modify
**New Files:**
- `/api/app/models/multiplayer.py` - MultiplayerSession, PartyMember, Campaign
- `/api/app/services/multiplayer_service.py` - Session management
- `/api/app/services/campaign_service.py` - AI campaign generation
- `/api/app/api/multiplayer.py` - Multiplayer API blueprint
- `/public_web/templates/multiplayer/lobby.html`
- `/public_web/templates/multiplayer/session.html`
- `/public_web/templates/multiplayer/complete.html`
- `/public_web/static/js/multiplayer-realtime.js` - WebSocket handling
**Modified Files:**
- `/api/app/services/combat_service.py` - Add party combat support
- `/api/app/__init__.py` - Register multiplayer blueprint
---
## Testing Criteria
### Unit Tests
- [ ] Invite code generation (uniqueness, format)
- [ ] Join validation (code exists, not expired, not full)
- [ ] Timer logic (warnings, expiration)
- [ ] Turn order calculation
### Integration Tests
- [ ] Full session flow: create → join → ready → start → play → complete
- [ ] Disconnect handling (player leaves mid-session)
- [ ] Host promotion when original host disconnects
- [ ] Reward distribution at session end
### Manual Testing
- [ ] Multiple browsers simulating party
- [ ] Realtime updates between players
- [ ] Timer warnings display correctly
- [ ] Combat turns cycle correctly
---
## Success Criteria
- [ ] Premium/Elite tier restriction enforced
- [ ] Invite codes work correctly
- [ ] Lobby system functional
- [ ] 2-hour timer with warnings
- [ ] Realtime synchronization working
- [ ] Party combat functional
- [ ] Campaign generation working
- [ ] Rewards distributed at session end
---
## Dependencies
**Requires (already implemented):**
- Combat system (Phase 4)
- Character system
- Session system
- Authentication with tiers
**Requires (from earlier phases):**
- Quest system (optional: party quests)
- Lore system (shared world knowledge)
---
## Task Summary
| Group | Tasks | Checkpoints |
|-------|-------|-------------|
| Core Infrastructure | 6 | 1 |
| Session Management APIs | 5 | 0 |
| Campaign Generation | 3 | 1 |
| Multiplayer Combat | 4 | 0 |
| Multiplayer UI | 4 | 0 |
| Testing & Validation | 3 | 1 |
| **Total** | **25** | **3** |