Files
sor/multiplayer-plan.md
2026-03-29 22:03:52 -04:00

334 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Multiplayer Plan: 2–10 Players, FFA / Team / Multi-Team
## Overview
The existing 1v1 system handles all the hard parts: combat resolution, ability triggers, SP/ST economy, channeling, movement, LoS, aura propagation, and win detection. Multiplayer is primarily an extension of **player-slot management**, **team affiliation**, and **board geometry** — the core rules don't change.
---
## 1. Game Modes
| Mode | Description | Example |
|---|---|---|
| **FFA** (Free-for-All) | Every player is their own team. Last ArchSpirit standing wins. | 4-player FFA |
| **N vs N** | Two teams of equal size. First team to eliminate all opposing ArchSpirits wins. | 3v3, 5v5 |
| **Multi-Team** | Three or more teams of equal size. Last team standing wins. | 2v2v2, 3v3v3, 2v2v2v2 |
| **Asymmetric** *(stretch goal)* | Teams of unequal size with handicap modifiers. | 1v2, 1v3 |
### Turn Order
Round-robin across all players in seat order (seat 0 → seat 1 → … → seat N-1 → back to 0).
Within a team, each player takes their own individual turn — teammates do not share a turn. This keeps the core turn loop unchanged and preserves all existing trigger semantics (`IsOwnTurn`, `UntilEndOfTurn`, etc.).
### Win Conditions
- **FFA**: A player is eliminated when their ArchSpirit is destroyed. The last player with a living ArchSpirit wins.
- **Team modes**: A team is eliminated when every member's ArchSpirit has been destroyed. The last surviving team wins.
- Eliminated players continue to spectate but their units stay removed (no "ghost" turns — eliminated players are skipped in turn order).
---
## 2. Server Architecture
### 2a. `GameConfiguration` — new lobby-time record
```csharp
public sealed record GameConfiguration
{
public required string Mode { get; init; } // "FFA" | "Teams" | "MultiTeam"
public required int PlayerCount { get; init; } // 2–10
public required int TeamCount { get; init; } // 1 = FFA, 2 = N vs N, N = multi-team
public required string BoardShape { get; init; } // "Rectangle" | "Cross" | "Hexagonal" | "Decagonal" | ...
// Board size hint — meaning varies per shape (e.g. radius for radial shapes, rows×cols for rectangle)
public int BoardParam1 { get; init; } = 8;
public int BoardParam2 { get; init; } = 8;
}
```
### 2b. `PlayerSlot` — replaces hardcoded player1/player2
Current `GameState` has `Player1` and `Player2` properties. Replace with:
```csharp
public IReadOnlyList<PlayerSlot> Players { get; init; }
public sealed class PlayerSlot
{
public required string AccountId { get; init; }
public required int SeatIndex { get; init; } // 0-based turn order
public required int TeamIndex { get; init; } // same value = same team; FFA = SeatIndex
public required string TeamColor { get; init; } // hex color for UI ("FF4444", etc.)
public bool Eliminated { get; set; }
// Existing per-player state
public int SP { get; set; }
public int ST { get; set; }
public List<CardInstance> Hand { get; init; } = new();
public List<CardInstance> Deck { get; init; } = new();
public List<CardInstance> Discard { get; init; } = new();
}
```
`CurrentTurnSeatIndex` replaces the current binary turn flag. The engine cycles:
```
CurrentTurnSeatIndex = (CurrentTurnSeatIndex + 1) % ActivePlayerCount
// skip eliminated players
```
### 2c. Team helper methods on `GameState`
```csharp
public bool AreAllies(string actorId, string targetId) =>
Players.First(p => p.AccountId == actorId).TeamIndex
== Players.First(p => p.AccountId == targetId).TeamIndex;
public IEnumerable<PlayerSlot> GetTeam(int teamIndex) =>
Players.Where(p => p.TeamIndex == teamIndex);
public bool IsTeamEliminated(int teamIndex) =>
GetTeam(teamIndex).All(p => p.Eliminated);
```
### 2d. Win detection change
Replace the current "player1 ArchSpirit destroyed → player2 wins" check with:
```csharp
private void CheckVictory(GameState state)
{
var survivingTeams = state.Players
.Where(p => !p.Eliminated)
.Select(p => p.TeamIndex)
.Distinct()
.ToList();
if (survivingTeams.Count == 1)
{
var winners = state.GetTeam(survivingTeams[0]).Select(p => p.AccountId).ToList();
EndGame(state, winners);
}
}
```
### 2e. Ability system — team-awareness
The ability `Ownership` values already cover the needed semantics:
- `Owner` / `Ally` = same team (update `Own()` to compare `TeamIndex` instead of `AccountId`)
- `Enemy` = any unit on a different team
- `Any`, `ExactSelf`, `Random` = unchanged
No new ownership values needed for team play.
---
## 3. Board Geometry System
### 3a. Design principle
The board is currently a rectangle described by `(rows, cols)`. Extend to a **tile mask** model: a board is a set of `Coord` positions that are valid, plus per-player **starting zones** (a sub-set of tiles designated as the home area for each player slot).
```csharp
public sealed class BoardLayout
{
public required string ShapeName { get; init; }
public required HashSet<Coord> ValidTiles { get; init; }
public required List<HashSet<Coord>> StartingZones { get; init; } // index = SeatIndex
}
```
The existing `Grid` class only needs to know which `Coord` values are navigable — it already operates on individual tile lookups, so making the tile mask sparse is a small change.
### 3b. Shape library — one generator per shape
Each generator takes `(playerCount, sizeHint)` and returns a `BoardLayout`.
#### Rectangle (current — 2 players)
```
rows = sizeHint, cols = sizeHint
Starting zones: top 2 rows for P0, bottom 2 rows for P1
```
#### Cross / Plus (4 players)
```
Three overlapping rectangles forming a plus sign.
Starting zones: each arm tip.
```
```
[P1]
[P3][ ][P2]
[P0]
```
#### Triangular (3 players)
```
Equilateral hexagonal triangle, 3 corners.
Starting zones: corner clusters.
```
#### Hexagonal Ring (6 players)
```
Hexagon of hexagonal tiles; 6 equidistant perimeter clusters as starting zones.
```
#### Decagonal (10 players)
```
Large circular arrangement, ~10 radial segments.
Starting zones: one segment per player, evenly distributed around perimeter.
```
#### Radial Star (5, 8 players)
```
Spokes radiating from a shared central arena.
Each player controls one spoke; central tiles are neutral/contested.
```
### 3c. Automatic shape selection by player count
| Player count | Recommended shapes |
|---|---|
| 2 | Rectangle (8×12), Rectangle (10×10) |
| 3 | Triangular, T-shape |
| 4 | Cross, Rectangle (12×12 with 4 quadrant starting zones) |
| 5 | Radial Star |
| 6 | Hexagonal Ring, 6-arm Star |
| 7–8 | Radial Star (8-spoke) |
| 9–10 | Decagonal Ring |
The host can override this selection in the lobby.
### 3d. Starting-zone enforcement
When a player channels a Spirit onto the battlefield, valid placement tiles are restricted to that player's starting zone (same as current 1v1 behavior, but the zone is derived from `BoardLayout.StartingZones[SeatIndex]` instead of a hardcoded row range).
---
## 4. Lobby & Matchmaking Changes
### 4a. Room creation
Extend `CreateRoomRequest` / `RoomDto`:
```csharp
public record CreateRoomRequest(
string Mode, // "FFA" | "Teams" | "MultiTeam"
int PlayerCount, // 2–10
int TeamCount, // 1 for FFA, 2+ for team modes
string BoardShape // "" = auto-select by player count
);
```
### 4b. Team assignment in lobby
For team modes, the room UI shows players grouped by team color. The room host can drag players between teams before starting. For FFA, no team UI is shown.
### 4c. Deck selection
Each player selects their own deck (same as now). No shared/team decks in v1.
---
## 5. Client Changes
### 5a. Player info panel
Currently two side panels (my stats / opponent stats). Replace with a **player ring** that dynamically generates one entry per player, grouped by team color.
```
[P0 - Blue | SP:3 ST:2 | HP:■■■□] [P1 - Blue | SP:2 ST:1 | HP:■■□□]
vs
[P2 - Red | SP:4 ST:3 | HP:■■■■] [P3 - Red | SP:1 ST:2 | HP:■■■□]
```
For FFA, each player's color is unique. For team modes, team members share a color.
### 5b. Turn indicator
The current "your turn / opponent's turn" banner extends to show the active seat's player name and team color.
### 5c. Camera / map view
- The camera must center and zoom to fit whatever board shape is in use
- For non-rectangular boards, the tile placer should mask the valid tile set
- Fog of war remains per-player (each player only sees tiles in their own LoS/range)
### 5d. Targeting highlights
Team-aware: ally units highlighted in blue, enemy units in red, self in white — consistent with `TeamIndex` comparisons.
### 5e. Turn-order display
A compact strip at the top of the screen shows all players in seat order with a pointer to the current active player (inspired by board game UX). Eliminated players are greyed out.
---
## 6. Protocol Changes
### 6a. New events
| Event | Payload |
|---|---|
| `player_eliminated` | `{ playerId, seatIndex, teamIndex }` |
| `team_eliminated` | `{ teamIndex }` |
| `game_won` | `{ winnerTeamIndex, winnerPlayerIds[] }` (replaces `game_over` for team modes) |
| `turn_changed` | `{ newSeatIndex, playerId }` (replaces current binary turn flag) |
### 6b. `game_state` snapshot changes
- `current_turn_player_id` field replaces `is_your_turn` boolean
- New `players` array with full `PlayerSlot` data for all N players
- New `board_shape` field with the layout name for client-side rendering
---
## 7. Phased Implementation
### Phase 1 — 2-player team-aware foundation (low risk)
- Refactor `PlayerSlot` list; keep backward compat for existing 1v1 by auto-assigning two slots with different team indices
- Update `Own()` helper to use `TeamIndex`
- Add `CheckVictory` team logic
- All existing 1v1 games use `FFA` mode with 2 players — no behavioral change
### Phase 2 — Multi-player FFA (3–6 players)
- Round-robin turn engine
- Eliminated-player skip logic
- Cross and Radial board shapes
- Client player ring + turn-order strip
- Lobby room with N-slot capacity
### Phase 3 — Team modes
- N vs N lobby team assignment UI
- Multi-team (2v2v2 etc.) win condition
- Team color system in client
### Phase 4 — Board shape library
- Hexagonal Ring, Decagonal, Triangular generators
- Auto-selection by player count
- Admin tool for previewing/testing board layouts
### Phase 5 — Polish
- Asymmetric team sizes with SP/ST handicap
- Spectator mode for eliminated players
- Ranked matchmaking with multi-player ELO
---
## 8. Critical Files
| File | Change |
|---|---|
| `SOR.Game/GameState.cs` | Replace Player1/Player2 with `IReadOnlyList<PlayerSlot>` |
| `SOR.Game/GameEngine.cs` | Round-robin turn logic, elimination detection, team win check |
| `SOR.Game/Grid/GridFactory.cs` *(new)* | Board shape generators for each layout |
| `SOR.Game/Grid/BoardLayout.cs` *(new)* | `ValidTiles` + `StartingZones[]` model |
| `SOR.Game/Abilities/AbilitySystem.cs` | `Own()` uses `TeamIndex` comparison |
| `SOR.Content/Lobby/` | Room creation with mode/team config |
| `Client/scenes/game/game_screen.gd` | Dynamic player panel, camera fit, turn strip |
| `Client/scenes/free_play/lobby_room_screen.gd` | Team assignment UI, seat slots |
| `Client/autoloads/GameProtocol.gd` | New events: `player_eliminated`, `team_eliminated`, `turn_changed` |
---
## Notes
- **Rules don't change.** Combat, abilities, SP/ST, channeling, LoS — all preserved exactly as-is.
- **The tile coordinate system stays.** `Coord(row, col)` continues to work; non-rectangular boards simply have sparse valid-tile sets.
- **Backward compatibility.** Existing 1v1 games just use two `PlayerSlot` entries with different `TeamIndex` values; no migration of saved games needed.
- **Board shapes are data.** A generator function produces a `BoardLayout` record from `(playerCount, sizeHint)` — no hardcoded map files.