Code_of_Conquest/docs/phases/Phase7-Multiplayer.md

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:

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