334 lines
12 KiB
Markdown
334 lines
12 KiB
Markdown
# 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.
|