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

12 KiB
Raw Blame History

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

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:

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

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:

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).

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:

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.