# 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** |