464 lines
12 KiB
Markdown
464 lines
12 KiB
Markdown
# WebSocket Game Server Architecture
|
|
|
|
## Overview
|
|
|
|
The MTG Online WebSocket game server provides real-time game state synchronization and player action handling for multiplayer Magic: The Gathering sessions. This document defines the architecture, protocol, and message formats.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
│ Player 1 │────▶│ WebSocket │────▶│ Game Server │
|
|
│ Browser │◀────│ Connection │◀────│ (asyncio) │
|
|
└─────────────┘ └─────────────────┘ └────────┬────────┘
|
|
│
|
|
┌─────────────┐ ┌─────────────────┐ ┌────────┴────────┐
|
|
│ Player 2 │────▶│ WebSocket │────▶│ Game State │
|
|
│ Browser │◀────│ Connection │◀────│ Manager │
|
|
└─────────────┘ └─────────────────┘ └────────┬────────┘
|
|
│
|
|
┌─────────────┐ ┌─────────────────┐ ┌────────┴────────┐
|
|
│ Player 3 │────▶│ WebSocket │────▶│ PostgreSQL │
|
|
│ Browser │◀────│ Connection │◀────│ (Persistence) │
|
|
└─────────────┘ └─────────────────┘ └─────────────────┘
|
|
```
|
|
|
|
### Components
|
|
|
|
1. **WebSocket Endpoint** (`/ws/game/{game_id}`)
|
|
- Accepts connections
|
|
- Authenticates players
|
|
- Routes messages to/from game instances
|
|
|
|
2. **Game Server Manager**
|
|
- Manages active game instances
|
|
- Handles game lifecycle (create, join, start, end)
|
|
- Coordinates between players
|
|
|
|
3. **Game State Manager**
|
|
- Maintains authoritative game state
|
|
- Validates player actions
|
|
- Emits state changes to all players
|
|
|
|
4. **Persistence Layer**
|
|
- Saves game state to PostgreSQL
|
|
- Enables game replay and recovery
|
|
|
|
## Protocol Design
|
|
|
|
### Message Format
|
|
|
|
All messages use JSON with the following envelope:
|
|
|
|
```json
|
|
{
|
|
"type": "message_type",
|
|
"seq": 123,
|
|
"ts": 1697750000.123,
|
|
"data": {
|
|
// Message-specific payload
|
|
}
|
|
}
|
|
```
|
|
|
|
- `type`: Message type identifier
|
|
- `seq`: Sequence number for ordering and gap detection
|
|
- `ts`: Unix timestamp (milliseconds)
|
|
- `data`: Message-specific payload
|
|
|
|
### Message Types
|
|
|
|
#### Connection Management
|
|
|
|
| Type | Direction | Description |
|
|
|------|-----------|-------------|
|
|
| `hello` | Client → Server | Initial connection with auth token |
|
|
| `welcome` | Server → Client | Connection established, game info |
|
|
| `bye` | Client → Server | Player disconnecting |
|
|
| `ping` | Either | Keepalive |
|
|
| `pong` | Either | Keepalive response |
|
|
|
|
#### Game Lifecycle
|
|
|
|
| Type | Direction | Description |
|
|
|------|-----------|-------------|
|
|
| `game_start` | Server → Client | Game starting, initial state |
|
|
| `game_state` | Server → Client | Full game state snapshot |
|
|
| `state_update` | Server → Client | Incremental state change |
|
|
| `game_over` | Server → Client | Game ended with results |
|
|
|
|
#### Player Actions
|
|
|
|
| Type | Direction | Description |
|
|
|------|-----------|-------------|
|
|
| `action` | Client → Server | Player takes an action |
|
|
| `action_ack` | Server → Client | Action acknowledged |
|
|
| `action_error` | Server → Client | Action failed validation |
|
|
|
|
#### Turn Management
|
|
|
|
| Type | Direction | Description |
|
|
|------|-----------|-------------|
|
|
| `turn_start` | Server → Client | New turn beginning |
|
|
| `phase_change` | Server → Client | Phase transition |
|
|
| `priority` | Server → Client | Player has priority |
|
|
| `stack_empty` | Server → Client | Stack is empty |
|
|
|
|
#### Chat
|
|
|
|
| Type | Direction | Description |
|
|
|------|-----------|-------------|
|
|
| `chat` | Either | Chat message |
|
|
| `chat_history` | Server → Client | Chat history on join |
|
|
|
|
### Authentication
|
|
|
|
Players authenticate via JWT token in the `hello` message:
|
|
|
|
```json
|
|
{
|
|
"type": "hello",
|
|
"data": {
|
|
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
|
"game_id": 42,
|
|
"seat": 1
|
|
}
|
|
}
|
|
```
|
|
|
|
## Game State Model
|
|
|
|
### Full State Snapshot
|
|
|
|
```json
|
|
{
|
|
"game_id": 42,
|
|
"room_id": 5,
|
|
"game_type": "Commander",
|
|
"state": "IN_PROGRESS",
|
|
"turn": 3,
|
|
"phase": "main1",
|
|
"players": [
|
|
{
|
|
"player_id": 1,
|
|
"user_id": 101,
|
|
"seat": 1,
|
|
"life_total": 18,
|
|
"hand_size": 5,
|
|
"library_size": 95,
|
|
"graveyard_size": 3,
|
|
"is_active": true,
|
|
"has_priority": true
|
|
},
|
|
{
|
|
"player_id": 2,
|
|
"user_id": 102,
|
|
"seat": 2,
|
|
"life_total": 20,
|
|
"hand_size": 6,
|
|
"library_size": 94,
|
|
"graveyard_size": 2,
|
|
"is_active": false,
|
|
"has_priority": false
|
|
}
|
|
],
|
|
"battlefield": {
|
|
"player_1": [
|
|
{
|
|
"card_id": "card_123",
|
|
"name": "Lightning Bolt",
|
|
"type": "Creature",
|
|
"power": 2,
|
|
"toughness": 2,
|
|
"is_tapped": false,
|
|
"is_attacking": false,
|
|
"damage": 0
|
|
}
|
|
],
|
|
"player_2": []
|
|
},
|
|
"stack": [],
|
|
"graveyard": {
|
|
"player_1": [],
|
|
"player_2": []
|
|
}
|
|
}
|
|
```
|
|
|
|
### Incremental State Update
|
|
|
|
```json
|
|
{
|
|
"type": "state_update",
|
|
"seq": 124,
|
|
"data": {
|
|
"changes": [
|
|
{
|
|
"player_id": 1,
|
|
"field": "life_total",
|
|
"old_value": 20,
|
|
"new_value": 18
|
|
},
|
|
{
|
|
"player_id": 1,
|
|
"field": "hand_size",
|
|
"old_value": 6,
|
|
"new_value": 5
|
|
}
|
|
],
|
|
"reason": "played_lightning_bolt"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Player Action Protocol
|
|
|
|
### Action Submission
|
|
|
|
```json
|
|
{
|
|
"type": "action",
|
|
"seq": 125,
|
|
"data": {
|
|
"action_type": "play_card",
|
|
"card_id": "card_456",
|
|
"target": null,
|
|
"mode": "attack"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Action Types
|
|
|
|
| Action Type | Description | Required Fields |
|
|
|-------------|-------------|-----------------|
|
|
| `play_card` | Play a card from hand | `card_id`, `target` (optional) |
|
|
| `tap_card` | Tap a card | `card_id` |
|
|
| `untap_card` | Untap a card | `card_id` |
|
|
| `attack` | Declare attacker | `card_id`, `target_player` |
|
|
| `block` | Declare blocker | `card_id`, `target_card_id` |
|
|
| `assign_damage` | Assign combat damage | `card_id`, `target_card_id`, `damage` |
|
|
| `pass_priority` | Pass priority | - |
|
|
| `cast_spell` | Cast a spell | `card_id`, `target` (optional) |
|
|
| `activate_ability` | Activate ability | `card_id`, `ability_id`, `target` (optional) |
|
|
| `end_turn` | End current turn | - |
|
|
| `concede` | Concede the game | - |
|
|
|
|
### Action Validation
|
|
|
|
The server validates all actions against the current game state:
|
|
|
|
1. **Turn/Phase Check**: Is this action legal in the current phase?
|
|
2. **Priority Check**: Does the player have priority?
|
|
3. **Card State Check**: Is the card in the correct zone?
|
|
4. **Target Check**: Is the target valid?
|
|
5. **Cost Check**: Can the player pay the cost?
|
|
|
|
## Turn and Phase Management
|
|
|
|
### Turn Structure
|
|
|
|
```
|
|
Turn Start
|
|
└─ Untap Phase
|
|
└─ Untap all permanents
|
|
└─ Upkeep Phase
|
|
└─ Upkeep costs
|
|
└─ Draw Phase
|
|
└─ Draw a card
|
|
└─ Main Phase 1
|
|
└─ Play lands, creatures, instants
|
|
└─ Combat Phase
|
|
└─ Beginning of Combat
|
|
└─ Declare Attackers
|
|
└─ Declare Blockers
|
|
└─ Combat Damage
|
|
└─ End of Combat
|
|
└─ Main Phase 2
|
|
└─ Play lands, creatures, instants
|
|
└─ End Phase
|
|
└─ Cleanup
|
|
Turn End
|
|
```
|
|
|
|
### Priority System
|
|
|
|
The server tracks priority and only accepts actions from the player with priority:
|
|
|
|
```json
|
|
{
|
|
"type": "priority",
|
|
"data": {
|
|
"player_id": 1,
|
|
"phase": "main1",
|
|
"stack_size": 0
|
|
}
|
|
}
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
### Action Errors
|
|
|
|
```json
|
|
{
|
|
"type": "action_error",
|
|
"seq": 126,
|
|
"data": {
|
|
"action_seq": 125,
|
|
"error_code": "INVALID_TARGET",
|
|
"error_message": "Target player is not in the game",
|
|
"action_type": "play_card"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Error Codes
|
|
|
|
| Code | Description |
|
|
|------|-------------|
|
|
| `INVALID_ACTION` | Action not legal in current phase |
|
|
| `NO_PRIORITY` | Player does not have priority |
|
|
| `INVALID_TARGET` | Target is not valid |
|
|
| `CARD_NOT_IN_HAND` | Card not in player's hand |
|
|
| `CARD_NOT_ON_BATTLEFIELD` | Card not on battlefield |
|
|
| `CANT_PAY_COST` | Player cannot pay the cost |
|
|
| `STACK_NOT_EMPTY` | Stack is not empty |
|
|
| `GAME_OVER` | Game is already over |
|
|
|
|
## Reconnection and Recovery
|
|
|
|
### Reconnection Protocol
|
|
|
|
When a player reconnects:
|
|
|
|
1. Client sends `hello` with same game_id and seat
|
|
2. Server validates player is still in the game
|
|
3. Server sends `welcome` with current game state
|
|
4. Server sends `chat_history` for the session
|
|
5. Player resumes play
|
|
|
|
### State Recovery
|
|
|
|
If the server crashes:
|
|
|
|
1. Game state is loaded from PostgreSQL
|
|
2. Players are notified to reconnect
|
|
3. Game resumes from last saved state
|
|
|
|
## Concurrency Model
|
|
|
|
### asyncio-based Architecture
|
|
|
|
```python
|
|
class GameServer:
|
|
def __init__(self):
|
|
self.games: Dict[int, GameInstance] = {}
|
|
self.player_connections: Dict[int, WebSocket] = {}
|
|
|
|
async def handle_connection(self, websocket, game_id):
|
|
"""Handle a single WebSocket connection."""
|
|
pass
|
|
|
|
async def game_loop(self, game_id):
|
|
"""Main game loop for a game instance."""
|
|
pass
|
|
|
|
class GameInstance:
|
|
def __init__(self, game_id, players):
|
|
self.game_id = game_id
|
|
self.players = players
|
|
self.state = GameState()
|
|
self.lock = asyncio.Lock()
|
|
|
|
async def process_action(self, player_id, action):
|
|
"""Process a player action with locking."""
|
|
async with self.lock:
|
|
return self.state.apply_action(player_id, action)
|
|
```
|
|
|
|
### Locking Strategy
|
|
|
|
- **Game-level lock**: Protects game state mutations
|
|
- **Action queue**: Orders actions within a turn
|
|
- **Phase transitions**: Synchronized across all players
|
|
|
|
## Performance Considerations
|
|
|
|
### Message Size
|
|
|
|
- Full state snapshots: ~5-10 KB
|
|
- Incremental updates: ~100-500 bytes
|
|
- Chat messages: ~50-200 bytes
|
|
|
|
### Latency Targets
|
|
|
|
- Action acknowledgment: < 100ms
|
|
- State update delivery: < 200ms
|
|
- Turn transition: < 500ms
|
|
|
|
### Scaling
|
|
|
|
- Single server: ~50 concurrent games
|
|
- Multiple servers: Use Redis pub/sub for cross-server communication
|
|
- Database: PostgreSQL for persistence, Redis for caching
|
|
|
|
## Security
|
|
|
|
### Message Validation
|
|
|
|
- All messages validated against schema
|
|
- Sequence numbers prevent replay attacks
|
|
- JWT tokens expire after 1 hour
|
|
- Rate limiting on actions per second
|
|
|
|
### Data Integrity
|
|
|
|
- Server is authoritative
|
|
- Client cannot modify game state directly
|
|
- All actions validated before application
|
|
|
|
## Implementation Plan
|
|
|
|
### Phase 1: Basic Infrastructure
|
|
- [ ] WebSocket endpoint setup
|
|
- [ ] Connection management
|
|
- [ ] Authentication
|
|
- [ ] Basic message routing
|
|
|
|
### Phase 2: Game State Management
|
|
- [ ] Game state model
|
|
- [ ] State serialization
|
|
- [ ] Full state snapshots
|
|
- [ ] Incremental updates
|
|
|
|
### Phase 3: Turn and Phase Management
|
|
- [ ] Turn structure implementation
|
|
- [ ] Phase transitions
|
|
- [ ] Priority system
|
|
- [ ] Action validation
|
|
|
|
### Phase 4: Player Actions
|
|
- [ ] Card play actions
|
|
- [ ] Combat actions
|
|
- [ ] Spell casting
|
|
- [ ] Ability activation
|
|
|
|
### Phase 5: Persistence and Recovery
|
|
- [ ] Game state persistence
|
|
- [ ] Reconnection handling
|
|
- [ ] Game recovery
|
|
- [ ] Chat history
|
|
|
|
### Phase 6: Testing and Optimization
|
|
- [ ] Unit tests
|
|
- [ ] Integration tests
|
|
- [ ] Load testing
|
|
- [ ] Performance optimization
|
|
|
|
## References
|
|
|
|
- [FastAPI WebSocket Documentation](https://fastapi.tiangolo.com/advanced/websockets/)
|
|
- [Magic: The Gathering Comprehensive Rules](https://magic.wizards.com/en/rules)
|
|
- [WebSocket Protocol RFC 6455](https://tools.ietf.org/html/rfc6455)
|