Files
sor/Server/src/SOR.Game/GameMessages.cs
T
0e85441fa1 feat(phase10): ChannelCardFromZone, ObstructMovementType, and pause-model completions
- Implement ChannelCardFromZoneEffect: zone lookup, dest-player resolution
  (Self/Target/Opponent/Ally/Random/Choice), channel-range tile selection,
  affinity check, cost deduction, KeepInZone, TargetTile pause, board
  placement with aura/passive hooks and Channeled trigger
- Add PendingPlayerPick.EffectType="ChannelCardFromZone" dispatch in
  ResumePlayerPick: random-tile path + chained PendingTilePick for
  TargetTile=true
- Add ResumeTilePick case "ChannelCardFromZone": place card at chosen tile
  under DestPlayerAccountId, affinity/cost/KeepInZone-aware
- Implement ObstructMovementTypeEffect: stores ActiveEffect marker;
  ApplyReversal is no-op (duration:null guard); BuildBlockedSet extended
  via AbilitySystem.GetUnitsObstructingMovementType to honour obstructors
  for pathfinding (e.g. Walk unit blocking Flight paths)
- Add PendingTilePick.DestPlayerAccountId and .EffectJson fields
- Add PendingPlayerPick.EffectJson field
- Thread ctx.ContinuationActions + ctx.ActivationRange through
  AbilityContext so ExecuteEffect can populate pause models without an
  extra method parameter

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
2026-04-21 07:34:17 -04:00

952 lines
40 KiB
C#

namespace SOR.Game;
// ── AI lobby requests / responses / pushes ────────────────────────────────────
/// <summary>Host adds an AI player to a custom lobby.</summary>
public sealed record GameAddAiRequest(Guid LobbyId, int Difficulty, string Strategy);
public sealed record GameAddAiResponse(Guid AiAccountId, string AiDisplayName, int SeatIndex);
/// <summary>Host removes an AI player from a custom lobby.</summary>
public sealed record GameRemoveAiRequest(Guid LobbyId, Guid AiAccountId);
public sealed record GameRemoveAiResponse(bool Success);
/// <summary>Host changes the difficulty or strategy of an existing AI slot.</summary>
public sealed record GameConfigureAiRequest(Guid LobbyId, Guid AiAccountId,
int? Difficulty, string? Strategy);
public sealed record GameConfigureAiResponse(bool Success);
/// <summary>
/// Pushed to all lobby members when the AI slot list changes
/// (AI added, removed, or configured).
/// </summary>
public sealed record CustomLobbyAiSlotsChangedPush(
Guid LobbyId,
IReadOnlyList<AiSlotInfo> CurrentAiSlots);
/// <summary>One AI seat in a custom lobby.</summary>
public sealed record AiSlotInfo(
Guid AccountId,
string DisplayName,
int Difficulty,
string Strategy,
int SeatIndex);
// ── Requests ─────────────────────────────────────────────────────────────────
/// <summary>Signal that the player has loaded the game screen and is ready to start.</summary>
public sealed record GameReadyRequest(Guid SessionId);
/// <summary>Request the current (filtered) game state for the caller.</summary>
public sealed record GameGetStateRequest(Guid SessionId);
/// <summary>Draw a card from the player's deck.</summary>
public sealed record GameDrawRequest(Guid SessionId);
/// <summary>
/// Place the player's ArchSpirit on their starting row (Placement phase only).
/// P1 must place in row y=0; P2 must place in row y=Height-1.
/// </summary>
public sealed record GamePlaceArchSpiritRequest(Guid SessionId, CoordDto Position);
/// <summary>
/// Channel (play) a card from hand.
/// Spirit cards require TargetTile (single tile within ArchSpirit's channeling range).
/// Terramorpha cards require TargetTiles (1 tile for Mono, 2 for Di, 3 for Tri — each
/// subsequent tile must be orthogonally adjacent to the previous).
/// Repentance / Instinct: pass ability targets via Targets when effects need unit/tile input.
/// Ruin / Other: no tile required.
/// </summary>
public sealed record GamePlayCardRequest(
Guid SessionId,
string CardInstanceId,
CoordDto? TargetTile = null,
IReadOnlyList<CoordDto>? TargetTiles = null,
IReadOnlyList<AbilityTarget>? Targets = null);
/// <summary>Move a unit on the board to a new tile.</summary>
public sealed record GameMoveUnitRequest(Guid SessionId, string UnitInstanceId, CoordDto TargetPosition);
/// <summary>Attack an opponent card (or their ArchSpirit) with one of your field cards.</summary>
public sealed record GameAttackRequest(
Guid SessionId,
string AttackerInstanceId,
string TargetInstanceId);
/// <summary>
/// Sacrifice one of your Spirits adjacent to your ArchSpirit (§6.15).
/// Sacrifice is a free action — does not consume an attack or ability use.
/// </summary>
public sealed record GameSacrificeRequest(Guid SessionId, string UnitInstanceId);
/// <summary>End the active player's turn.</summary>
public sealed record GameEndTurnRequest(Guid SessionId);
/// <summary>Concede the game (forfeit).</summary>
public sealed record GameConcedeRequest(Guid SessionId);
/// <summary>
/// Ascend the active player's ArchSpirit to the next tier (§6.7.2).
/// IncomingCardInstanceId is the instance ID of the higher-tier ArchSpirit — it may
/// reside in any zone (hand, deck, discard, or even field in edge cases).
/// The incoming ArchSpirit must be exactly one tier above the current and must link
/// back to it via PreviousTierId. Cost is the incoming ArchSpirit's SP/ST cost.
/// </summary>
public sealed record GameAscendRequest(Guid SessionId, string IncomingCardInstanceId);
/// <summary>
/// Transition the active player's ArchSpirit with a Tier 1 ArchSpirit from hand (§6.7.1).
/// The current ArchSpirit goes to discard; the incoming enters with full HP/Defense/MP.
/// Cost is the incoming ArchSpirit's SP/ST cost.
/// </summary>
public sealed record GameTransitionRequest(Guid SessionId, string IncomingCardInstanceId);
/// <summary>
/// Activate an Active ability on one of the player's field units.
/// AbilityIndex is 0-based into the source unit's AbilitiesJson array.
/// Targets is required when the ability needs player-chosen targets.
/// </summary>
public sealed record GameActivateAbilityRequest(
Guid SessionId,
string SourceInstanceId,
int AbilityIndex,
IReadOnlyList<AbilityTarget>? Targets = null);
/// <summary>Query whether the caller has an Active game session they can rejoin.</summary>
public sealed record GameGetActiveSessionRequest();
/// <summary>Force-concede a game where the opponent has been inactive.</summary>
public sealed record GameForceConcedeRequest(Guid SessionId);
// ── Custom lobby requests ─────────────────────────────────────────────────────
/// <summary>Create a new custom lobby. Host provides their deck and optional rule overrides.</summary>
public sealed record CreateCustomLobbyRequest(
string LobbyName,
Guid DeckId,
string? Password = null,
CustomRulesOverride? Rules = null,
int MaxPlayers = 2,
string GameMode = "FFA",
int TeamCount = 1);
/// <summary>
/// Per-field rule overrides for a custom lobby. Null fields inherit from the
/// active custom-default GameRuleSet.
/// </summary>
public sealed record CustomRulesOverride(
int? OpeningHandSize = null,
bool? FirstPlayerSkipsDraw = null,
int? SpAccumulationPerTurn = null,
int? DrawPerTurn = null,
bool? SpHasCap = null,
int? SpCap = null,
int? BoardWidth = null,
int? BoardHeight = null,
int? HandSizeCap = null,
bool? DiscardOnMaxHand = null,
int? MaxDeckSize = null,
int? MinDeckSize = null,
int? MaxArchTier1 = null,
int? TurnTimerSeconds = null,
int? TimeLimitMinutes = null,
int? TurnLimit = null,
int? MpBuff = null,
int? StartingRandomTilePct = null,
/// <summary>
/// Board shape. Null or "Default" = auto-select by player count via BoardShapeGenerator.AutoShape.
/// Explicit values: "Rectangle" | "Cross" | "Triangular" | "RadialStar" | "HexRing".
/// </summary>
string? BoardShape = null,
/// <summary>
/// When set, use this board template instead of generating a board from BoardShape.
/// Null or absent = no template (use shape generator).
/// </summary>
Guid? BoardTemplateIdOverride = null,
/// <summary>Hex sides (N) when BoardShape is "Hexagon". 0 = server default (5).</summary>
int? HexSides = null);
/// <summary>Join an open custom lobby with the specified deck.</summary>
public sealed record JoinCustomLobbyRequest(Guid LobbyId, Guid DeckId, string? Password = null);
/// <summary>
/// Serialized JSON entry in CustomLobby.AdditionalPlayersJson and GameSession.AdditionalPlayersJson.
/// </summary>
public sealed record AdditionalLobbyPlayer(Guid AccountId, Guid DeckId, bool IsReady = false);
/// <summary>Leave or cancel a custom lobby.</summary>
public sealed record LeaveCustomLobbyRequest(Guid LobbyId);
/// <summary>Fetch full details for a specific custom lobby.</summary>
public sealed record GetCustomLobbyRequest(Guid LobbyId);
// ── Preset requests ───────────────────────────────────────────────────────────
/// <summary>Save the current lobby's rule overrides as a named preset (participants only).</summary>
public sealed record SavePresetRequest(Guid LobbyId, string PresetName);
/// <summary>List all presets owned by the calling player.</summary>
public sealed record ListPresetsRequest();
/// <summary>Delete a preset owned by the calling player.</summary>
public sealed record DeletePresetRequest(Guid PresetId);
/// <summary>Host proposes loading a preset; triggers a yes/no vote for the other participant.</summary>
public sealed record ProposePresetRequest(Guid LobbyId, Guid PresetId);
/// <summary>Cast a yes/no vote on the active preset-load proposal for a lobby.</summary>
public sealed record VotePresetRequest(Guid LobbyId, bool Accept);
// ── Spectator requests ────────────────────────────────────────────────────────
/// <summary>Join a game session as a spectator.</summary>
public sealed record SpectateRequest(Guid SessionId);
/// <summary>Stop spectating a game session.</summary>
public sealed record StopSpectatingRequest(Guid SessionId);
/// <summary>List open custom lobbies. NameSearch filters by lobby name (case-insensitive contains).</summary>
public sealed record ListCustomLobbiesRequest(
int Page = 1,
int PageSize = 20,
string? NameSearch = null,
bool ShowPasswordProtected = true);
// ── Ready-up requests ─────────────────────────────────────────────────────────
/// <summary>Mark the caller as ready in a Full lobby with their final deck and first-turn preference.</summary>
public sealed record LobbyReadyRequest(Guid LobbyId, Guid DeckId, string FirstTurnPref);
/// <summary>Withdraw the caller's ready status in a Full lobby.</summary>
public sealed record UnreadyInLobbyRequest(Guid LobbyId);
/// <summary>Change the caller's deck selection while in a Full lobby (not yet ready).</summary>
public sealed record ChangeLobbyDeckRequest(Guid LobbyId, Guid DeckId);
/// <summary>Host updates lobby rule overrides while in Full state (neither player ready yet).</summary>
public sealed record UpdateLobbyRulesRequest(Guid LobbyId, CustomRulesOverride Rules);
/// <summary>List all in-progress custom games (Status == Started). Supports paging.</summary>
public sealed record ListActiveLobbiesRequest(int Page = 1, int PageSize = 20);
// ── Rule suggestion requests (guest → host) ───────────────────────────────────
/// <summary>Guest proposes rule overrides to the host. Host can accept or reject.</summary>
public sealed record SuggestRulesRequest(Guid LobbyId, CustomRulesOverride Rules);
/// <summary>Host accepts the guest's pending rule suggestion; applies it as the new overrides.</summary>
public sealed record AcceptRuleSuggestionRequest(Guid LobbyId);
/// <summary>Host rejects the guest's pending rule suggestion.</summary>
public sealed record RejectRuleSuggestionRequest(Guid LobbyId);
/// <summary>Host-only: move a player seat to a different team.</summary>
public sealed record ReassignTeamRequest(Guid LobbyId, int SeatIndex, int TeamIndex);
// ── Responses ─────────────────────────────────────────────────────────────────
public sealed record GameReadyResponse(
Guid SessionId,
string Status, // "WaitingForOpponent" | "AlreadyStarted" | "Started"
string? OpponentDisplayName = null); // populated only when Status == "AlreadyStarted"
public sealed record GameGetStateResponse(GameStateDto State);
public sealed record GameDrawResponse(GameStateDto State);
public sealed record GamePlaceArchSpiritResponse(GameStateDto State);
public sealed record GamePlayCardResponse(GameStateDto State);
public sealed record GameMoveUnitResponse(GameStateDto State);
public sealed record GameAttackResponse(GameStateDto State);
public sealed record GameSacrificeResponse(GameStateDto State);
public sealed record GameEndTurnResponse(GameStateDto State);
public sealed record GameConcedeResponse(GameStateDto State);
public sealed record GameAscendResponse(GameStateDto State);
public sealed record GameTransitionResponse(GameStateDto State);
public sealed record GameActivateAbilityResponse(GameStateDto State);
/// <summary>
/// Response for game.get_active_session.
/// SessionId is null when the player has no in-progress game.
/// CanRejoinAsPlayer=false indicates the caller is in-session but eliminated/conceded.
/// </summary>
public sealed record GameGetActiveSessionResponse(
Guid? SessionId,
string? Phase,
bool? CanRejoinAsPlayer,
bool? IsEliminated);
public sealed record GameForceConcedeResponse(GameStateDto State);
// ── Custom lobby responses ─────────────────────────────────────────────────────
public sealed record CreateCustomLobbyResponse(
Guid LobbyId,
string LobbyName,
CustomRulesDto ActiveRules,
int MaxPlayers,
string GameMode,
int TeamCount);
public sealed record JoinCustomLobbyResponse(
Guid LobbyId,
string Status, // "WaitingForReady" | "WaitingForPlayers"
CustomRulesDto ActiveRules,
Guid? GameSessionId, // always null; reserved for future use
Guid HostAccountId,
string HostDisplayName,
Guid GuestAccountId,
string GuestDisplayName,
int MaxPlayers,
string GameMode,
int TeamCount,
bool IsAdditionalPlayer = false, // true for 3rd+ players (not host or first guest)
IEnumerable<AdditionalLobbyPlayerViewDto>? AdditionalPlayers = null,
/// <summary>Seat index → team index map. Null = default (seat % teamCount).</summary>
Dictionary<int, int>? SeatTeams = null);
public sealed record LeaveCustomLobbyResponse(Guid LobbyId);
public sealed record GetCustomLobbyResponse(CustomLobbyDetailDto Lobby);
// ── Preset responses ──────────────────────────────────────────────────────────
public sealed record SavePresetResponse(Guid PresetId, string Name);
public sealed record ListPresetsResponse(IEnumerable<LobbyPresetDto> Presets);
public sealed record DeletePresetResponse(Guid PresetId);
public sealed record ProposePresetResponse(Guid LobbyId, string Status); // "VoteStarted"
public sealed record VotePresetResponse(Guid LobbyId, string Outcome); // "Approved" | "Rejected" | "Pending"
// ── Spectator responses ───────────────────────────────────────────────────────
/// <summary>Ack for game.spectate — spectator receives current filtered game state.</summary>
public sealed record SpectateResponse(GameStateDto State);
/// <summary>Ack for game.spectate.stop.</summary>
public sealed record StopSpectatingResponse(Guid SessionId);
public sealed record ListCustomLobbiesResponse(
IEnumerable<CustomLobbyDto> Lobbies,
int TotalCount,
int Page,
int PageSize);
// ── Ready-up responses ────────────────────────────────────────────────────────
public sealed record LobbyReadyResponse(Guid LobbyId, bool IsReady);
public sealed record UnreadyInLobbyResponse(Guid LobbyId);
public sealed record ChangeLobbyDeckResponse(Guid LobbyId);
public sealed record UpdateLobbyRulesResponse(Guid LobbyId, CustomRulesDto Rules);
public sealed record SuggestRulesResponse(Guid LobbyId);
public sealed record AcceptRuleSuggestionResponse(Guid LobbyId);
public sealed record RejectRuleSuggestionResponse(Guid LobbyId);
public sealed record ReassignTeamResponse(Guid LobbyId, Dictionary<int, int> SeatTeams);
public sealed record ListActiveLobbiesResponse(
IEnumerable<ActiveLobbyDto> Games,
int TotalCount,
int Page,
int PageSize);
// ── Server Pushes ─────────────────────────────────────────────────────────────
/// <summary>
/// Pushed to both players after any game action that changes state.
/// Each player receives a version filtered for their perspective
/// (opponent hand/deck contents are hidden).
/// </summary>
public sealed record GameStateUpdatePush(GameStateDto State);
/// <summary>
/// Pushed to all active players when a player is eliminated mid-game (ArchSpirit destroyed)
/// but the game continues (more than one surviving team).
/// </summary>
public sealed record PlayerEliminatedPush(
Guid SessionId,
Guid EliminatedAccountId,
int SeatIndex,
int TeamIndex);
/// <summary>Per-player outcome entry for N-player game-over pushes.</summary>
public sealed record PlayerOutcomeDto(
Guid AccountId,
string Outcome, // "Winner" | "Loser"
int RankDelta,
int OpDelta);
/// <summary>Pushed to all players when the game ends.</summary>
public sealed record GameOverPush(
Guid SessionId,
Guid WinnerAccountId, // primary winner (backward-compat; first of winners list)
Guid LoserAccountId, // primary loser (backward-compat; first of losers list)
string WinCondition, // "health" | "concede" | "disconnect" | "time_limit"
int WinnerRankDelta,
int LoserRankDelta,
int WinnerOpDelta,
int LoserOpDelta,
// N-player: individual outcomes for every participant (null for 1v1 backward compat).
IEnumerable<PlayerOutcomeDto>? PlayerOutcomes = null);
/// <summary>
/// Pushed to both players when a session that was Initializing is abandoned
/// (e.g., server restart before both players sent game.ready).
/// Clients should return to the main menu and show an appropriate message.
/// </summary>
public sealed record GameSessionAbandonedPush(Guid SessionId, string Reason);
/// <summary>
/// Pushed to the active player when they have been inactive for 5 minutes.
/// Their opponent now has the option to accept the forfeit.
/// </summary>
public sealed record GameInactiveWarningPush(Guid SessionId);
/// <summary>
/// Pushed to the non-active player when the opponent has been inactive for 5 minutes.
/// The client should offer "Accept forfeit" or "Wait" options.
/// </summary>
public sealed record GameOpponentInactivePush(Guid SessionId);
/// <summary>
/// Pushed to BOTH players when neither has acted for 10 minutes (mutual idle).
/// The client must show only a "Wait" option — no concede or force-concede.
/// Replaces any open inactive dialog on the client.
/// </summary>
public sealed record GameBothIdlePush(Guid SessionId);
/// <summary>
/// Pushed to both players when a custom lobby is full and a GameSession has been created.
/// Players should navigate to the game screen and send game.ready.
/// </summary>
public sealed record CustomLobbyGameStartedPush(
Guid SessionId,
Guid OpponentAccountId,
string OpponentDisplayName);
/// <summary>Pushed to the host when a guest joins their open lobby.</summary>
public sealed record CustomLobbyGuestJoinedPush(
Guid LobbyId,
Guid GuestAccountId,
string GuestDisplayName,
string LobbyName,
IEnumerable<AdditionalLobbyPlayerViewDto>? AdditionalPlayers = null);
/// <summary>
/// Pushed to the non-proposing participant when the host proposes loading a preset.
/// The recipient should display the proposed rules and prompt Accept/Reject.
/// </summary>
public sealed record PresetVoteRequestedPush(
Guid LobbyId,
Guid PresetId,
string PresetName,
CustomRulesOverride Rules);
/// <summary>
/// Pushed to both participants when a preset-load vote is approved and lobby rules update.
/// </summary>
public sealed record LobbyUpdatedPush(Guid LobbyId, CustomRulesDto NewRules);
/// <summary>Pushed to both participants when a preset-load vote is rejected.</summary>
public sealed record PresetVoteRejectedPush(Guid LobbyId, Guid PresetId);
/// <summary>Pushed to both participants whenever a lobby participant's ready status changes.</summary>
public sealed record LobbyReadyStatusPush(
Guid LobbyId,
bool HostReady,
bool GuestReady,
IEnumerable<AdditionalLobbyPlayerViewDto>? AdditionalPlayers = null);
/// <summary>Pushed to both participants when a lobby participant changes their selected deck.</summary>
public sealed record LobbyDeckChangedPush(Guid LobbyId, Guid AccountId, Guid DeckId);
/// <summary>
/// Pushed to the remaining participant when the other player leaves a Full lobby.
/// Reason is "host_cancelled" (host left) or "guest_left" (guest left).
/// </summary>
public sealed record LobbyPartnerLeftPush(Guid LobbyId, string Reason);
/// <summary>
/// Pushed to the host when the guest submits a rule suggestion.
/// The host can accept (game.custom.suggest_rules.accept) or reject (game.custom.suggest_rules.reject).
/// </summary>
public sealed record LobbyRuleSuggestionPush(
Guid LobbyId,
Guid SuggesterAccountId,
CustomRulesOverride SuggestedRules);
/// <summary>Pushed to the guest when the host rejects their rule suggestion.</summary>
public sealed record LobbyRuleSuggestionRejectedPush(Guid LobbyId);
/// <summary>
/// Pushed to all lobby participants when the host changes a seat's team assignment.
/// SeatTeams is the full seat → team map for all seats.
/// </summary>
public sealed record LobbyTeamAssignmentChangedPush(Guid LobbyId, Dictionary<int, int> SeatTeams);
/// <summary>
/// Pushed to each viewer after any game action that changes state.
/// Replaces the full <see cref="GameStateUpdatePush"/> for incremental updates.
/// </summary>
public sealed record GameStateDeltaPush(GameStateDelta Delta);
/// <summary>
/// Viewer-specific state delta. Null collections mean no change for that category.
/// Own hand is shown in full; opponent hand = count only.
/// </summary>
public sealed record GameStateDelta(
int StateVersion,
IReadOnlyList<TileDelta>? ChangedTiles,
IReadOnlyList<UnitSnapshot>? UnitsAdded,
IReadOnlyList<string>? UnitsRemoved,
IReadOnlyList<UnitDelta>? UnitsChanged,
IReadOnlyDictionary<string, ArchSpiritUpdate>? ArchSpiritByAccount,
IReadOnlyDictionary<string, PlayerStatsDelta>? PlayerStatsByAccount,
IReadOnlyDictionary<string, PublicCountsDelta>? PublicCountsByAccount,
PrivateViewerDelta? PrivateByViewer,
GameMetaDelta? MetaDelta,
IReadOnlyList<ActiveEffectDto>? ActiveEffects = null); // full replacement when changed
public sealed record TileDelta(
int X,
int Y,
string? Base1,
string? Base2,
string? ResolvedAffinity,
string? OccupantId,
bool OccupantCleared,
string? OccupantOwner,
string? RuinId,
bool RuinCleared,
string? RuinOwner);
public sealed record UnitSnapshot(
string OwnerAccountId,
CardInstanceDto Unit);
public sealed record UnitDelta(
string InstanceId,
int? CurrentHealth,
int? MaxHealth,
int? CurrentDefense,
int? MaxDefense,
int? Damage,
bool? IsExhausted,
bool? CanMove,
bool? CanAttack,
bool? CanBeAttacked,
bool? CanUseAbility,
int? CurrentMp,
int? MaxMp,
int? ExtraAttacksRemaining,
CoordDto? Position,
string? AbilitiesJson,
string? AbilityUsesJson);
public sealed record PublicCountsDelta(
int? DeckCount,
int? HandCount,
int? DiscardCount);
public sealed record ArchSpiritUpdate(
CardInstanceDto? Full,
UnitDelta? Delta);
public sealed record PrivateViewerDelta(
IReadOnlyList<CardInstanceDto>? HandAdded,
IReadOnlyList<string>? HandRemovedIds,
IReadOnlyList<CardInstanceDto>? DiscardAdded);
public sealed record PlayerStatsDelta(
int? CurrentSp,
int? CurrentSt,
int? DeckCount,
int? HandCount,
int? DiscardCount);
public sealed record GameMetaDelta(
string? Phase,
string? ActivePlayerAccountId,
int? TurnNumber);
// ── Skybox activity feed ───────────────────────────────────────────────────────
/// <summary>
/// Subscribe to game activity events so the client can animate its live star skybox.
/// The response includes IDs of currently active sessions to initialise the star field.
/// </summary>
public sealed record GameSubscribeActivityRequest;
public sealed record GameSubscribeActivityResponse(IReadOnlyList<string> ActiveSessionIds);
/// <summary>Unsubscribe from game activity events.</summary>
public sealed record GameUnsubscribeActivityRequest;
public sealed record GameUnsubscribeActivityResponse;
/// <summary>
/// Pushed to all subscribed clients when a game session starts or ends.
/// EventType: "started" | "ended"
/// </summary>
public sealed record GameActivityPush(string EventType, string SessionId);
// ── DTOs ─────────────────────────────────────────────────────────────────────
/// <summary>
/// Client-facing game state — opponent's private zones (hand, deck) are filtered.
///
/// StateVersion is a monotonically-increasing counter incremented after every game action.
/// Clients should track the last received StateVersion. If a GameStateUpdatePush arrives
/// with StateVersion > lastSeen + 1, the client missed a push and should call game.get_state
/// to request a full board refresh.
/// </summary>
public sealed record GameStateDto(
Guid SessionId,
string Phase, // Placement | Draw | Main | End | GameOver
string ActivePlayerAccountId,
string PlayerOneAccountId, // used by client to determine placement row
int TurnNumber,
int StateVersion, // monotonic; use for client mismatch detection
IEnumerable<PlayerStateDto> Players,
BoardDto? Board, // full board state including tile affinities
IEnumerable<string> SeatOrder, // account IDs in seat/turn order; empty = legacy 1v1
string GameMode, // "FFA" | "Teams" | "MultiTeam"
Dictionary<int, string> TeamColors, // teamIndex → hex color e.g. "4488FF"
IEnumerable<ActiveEffectDto> ActiveEffects); // currently tracked duration effects
/// <summary>
/// Client-facing view of a single duration-tracked active effect.
/// </summary>
public sealed record ActiveEffectDto(
string SourceInstanceId,
string SourceName, // resolved display name of the source unit
string TargetRef, // InstanceId of target unit or AccountId of target player
string Label, // human-readable description of the applied effect e.g. "ATK +2"
string DurationType, // e.g. "UntilEndOfTurn", "ForNTurns", "WhileSourceOnBattlefield"
int TurnsRemaining); // non-zero only for ForNTurns
public sealed record PlayerStateDto(
Guid AccountId,
string DisplayName, // resolved display name; never empty (falls back to truncated ID)
int HandCount, // always shown; actual cards visible only to self
int DeckCount,
IEnumerable<CardInstanceDto>? Hand, // null for opponent
IEnumerable<CardInstanceDto> Field, // always visible
IEnumerable<CardInstanceDto> Discard, // always visible
CardInstanceDto? ArchSpirit,
int CurrentSp,
int CurrentSt,
int SeatIndex, // 0-based turn order position
int TeamIndex, // same value = allies; FFA = SeatIndex
bool IsEliminated); // true when ArchSpirit has been destroyed
public sealed record CardInstanceDto(
string InstanceId,
Guid CardDefinitionId,
string Name,
string CardType,
string Affinity,
string Rarity,
int? CurrentHealth,
int? MaxHealth,
int? CurrentDefense,
int? MaxDefense,
int? Damage,
bool IsExhausted,
bool IsLeader,
CoordDto? Position, // null when not on field or not yet placed
int? CurrentMp,
int? MaxMp,
string? MovementType, // enum as string, null for non-unit cards
int? Tier, // ArchSpirit only; 1 = base form
string? TerramorphaMode, // Terramorpha only: "Mono" | "Di" | "Tri"
// --- fields needed for client-side display and valid-tile computation ---
int SpCost,
int StCost,
IEnumerable<string>? Genus,
int? MinChannelRange,
int? MaxChannelRange,
int? MinAttackRange,
int? MaxAttackRange,
bool CanMove,
bool CanAttack,
bool AttackRequiresLos,
int ExtraAttacksRemaining,
bool CanBeAttacked,
string? AbilitiesJson);
public sealed record BoardDto(
int Width,
int Height,
IEnumerable<TileDto> Tiles,
/// <summary>Seat index → list of valid ArchSpirit placement coords. Empty for legacy 1v1.</summary>
Dictionary<int, IEnumerable<CoordDto>>? StartingZones = null,
string GridType = "Square",
int HexSides = 0);
public sealed record TileDto(
CoordDto Coord,
string Base1,
string Base2,
string ResolvedAffinity,
string? OccupantId,
string? OccupantOwner,
string? RuinId,
string? RuinOwner);
/// <summary>Client-facing 2D coordinate.</summary>
public sealed record CoordDto(int X, int Y);
/// <summary>Client-facing additional (3rd+) custom-lobby participant.</summary>
public sealed record AdditionalLobbyPlayerViewDto(
Guid AccountId,
string DisplayName,
bool IsReady);
public sealed record CustomLobbyDto(
Guid LobbyId,
string LobbyName,
Guid HostAccountId,
string HostDisplayName,
bool HasGuest,
string? GuestDisplayName,
CustomRulesDto Rules,
DateTimeOffset CreatedAt,
int MaxPlayers = 2,
int CurrentPlayerCount = 1,
string GameMode = "FFA",
int TeamCount = 1);
/// <summary>Summary of an in-progress custom game, shown in the Active Games browser.</summary>
public sealed record ActiveLobbyDto(
Guid LobbyId,
string LobbyName,
Guid HostAccountId,
string HostDisplayName,
Guid GuestAccountId,
string GuestDisplayName,
Guid GameSessionId,
bool HasPassword,
CustomRulesDto Rules);
/// <summary>
/// Detailed view of a custom lobby, including full rule set and participant presence.
/// Returned by game.custom.get.
/// </summary>
public sealed record CustomLobbyDetailDto(
Guid LobbyId,
string LobbyName,
string Status, // Open | Full | Started | Cancelled
Guid HostAccountId,
Guid? GuestAccountId,
CustomRulesDto Rules,
DateTimeOffset CreatedAt,
Guid? GameSessionId);
public sealed record CustomRulesDto(
int OpeningHandSize,
bool FirstPlayerSkipsDraw,
int SpAccumulationPerTurn,
int DrawPerTurn,
bool SpHasCap,
int SpCap,
int BoardWidth,
int BoardHeight,
int HandSizeCap,
bool DiscardOnMaxHand,
int MaxDeckSize,
int MinDeckSize,
int MaxArchTier1,
int TurnTimerSeconds,
int TimeLimitMinutes,
int TurnLimit,
int MpBuff,
int StartingRandomTilePct,
/// <summary>"Default" = auto by player count; otherwise explicit shape name.</summary>
string BoardShape,
bool HasPassword,
Guid? BoardTemplateIdOverride = null);
/// <summary>Client-facing lobby preset summary.</summary>
public sealed record LobbyPresetDto(
Guid PresetId,
string Name,
CustomRulesOverride Rules,
DateTimeOffset CreatedAt);
/// <summary>
/// A single client-provided target for one action in an ability.
/// Exactly one of InstanceId or Coord should be set, matching the action's TargetType.
/// </summary>
public sealed record AbilityTarget(
/// <summary>0-based index of the ability action this target satisfies.</summary>
int ActionIndex,
/// <summary>Set for unit/card targets.</summary>
string? InstanceId = null,
/// <summary>Set for tile targets.</summary>
CoordDto? Coord = null,
/// <summary>Set for ChooseOne actions: the 0-based index of the chosen branch.</summary>
int? BranchIndex = null);
// ── Triggered ability target prompting ───────────────────────────────────────
/// <summary>
/// Pushed to the owning player when a Triggered ability fires and requires a
/// manual target selection before it can complete.
/// The client should enter ability-targeting mode using the provided action definition,
/// then reply with <see cref="GameTriggeredTargetRequest"/>.
/// </summary>
public sealed record TriggeredTargetRequestPush(
/// <summary>Correlation ID — must be echoed back in the response.</summary>
string RequestId,
/// <summary>InstanceId of the unit whose triggered ability is waiting.</summary>
string SourceInstanceId,
/// <summary>Display name of the ability, for UI labelling.</summary>
string AbilityName,
/// <summary>JSON-serialized <c>Action</c> for the first client-pick action.</summary>
string ActionJson,
/// <summary>JSON-serialized <c>AbilityRange</c>? — for client highlight validation. Null if no range.</summary>
string? RangeJson);
/// <summary>
/// Sent by the client to submit target picks for a pending triggered ability.
/// </summary>
public sealed record GameTriggeredTargetRequest(
Guid SessionId,
string RequestId,
IReadOnlyList<AbilityTarget> Targets);
/// <summary>
/// Pushed to the picker player when an Active ability cost requires interactive card/unit
/// selection (e.g. "Discard a Spirit card of your choice").
/// The client shows a zone picker and replies with <see cref="GameCostPickRequest"/>.
/// </summary>
public sealed record CostPickRequestPush(
/// <summary>Correlation ID — must be echoed back in the response.</summary>
string RequestId,
/// <summary>InstanceId of the unit whose ability cost is being resolved.</summary>
string SourceInstanceId,
/// <summary>The cost type being resolved (e.g. "DiscardFromHand").</summary>
string CostType,
/// <summary>How many cards/units the picker must select.</summary>
int Amount,
/// <summary>Who is picking: "SelfPick", "EnemySeePick", "EnemyRandomPick", "EnemyPick".</summary>
string PickMode,
/// <summary>JSON-serialized Filter[]? constraining valid selections. Null = no constraint.</summary>
string? FiltersJson);
/// <summary>
/// Sent by the picker to submit their card/unit selections for a pending cost.
/// </summary>
public sealed record GameCostPickRequest(
Guid SessionId,
string RequestId,
/// <summary>InstanceIds of the selected cards or units.</summary>
IReadOnlyList<string> SelectedInstanceIds);
/// <summary>Acknowledged response for a cost pick submission.</summary>
public sealed record GameCostPickResponse(bool Success);
/// <summary>
/// Sent by the chooser to select which CostGroup option to pay when logic is OR/XOR.
/// </summary>
public sealed record GameCostGroupPickRequest(
Guid SessionId,
string RequestId,
/// <summary>0-based index of the chosen cost option within the pending group.</summary>
int ChoiceIndex);
/// <summary>Acknowledged response for a cost-group pick submission.</summary>
public sealed record GameCostGroupPickResponse(bool Success);
/// <summary>
/// Sent by the chooser to select which ActionGroup branch to execute when logic is OR/XOR.
/// </summary>
public sealed record GameActionGroupPickRequest(
Guid SessionId,
string RequestId,
/// <summary>0-based index of the chosen child action/group.</summary>
int ChoiceIndex);
/// <summary>Acknowledged response for an action-group pick submission.</summary>
public sealed record GameActionGroupPickResponse(bool Success);
/// <summary>
/// Sent by the chooser (Opponent/Ally) to pick a ChooseOne branch.
/// </summary>
public sealed record GameBranchPickRequest(
Guid SessionId,
string RequestId,
/// <summary>0-based index of the chosen branch.</summary>
int BranchIndex);
/// <summary>Acknowledged response for a branch pick submission.</summary>
public sealed record GameBranchPickResponse(bool Success);
/// <summary>
/// Sent by the chooser to order the revealed cards (e.g. StackDeckEffect interactive).
/// </summary>
public sealed record GameRevealChoicePickRequest(
Guid SessionId,
string RequestId,
/// <summary>
/// 0-based indices of the revealed cards in the desired top-to-bottom order.
/// Cards not listed are placed at the bottom of the deck.
/// </summary>
int[] OrderedIndices);
/// <summary>Acknowledged response for a reveal-choice pick submission.</summary>
public sealed record GameRevealChoicePickResponse(bool Success);
/// <summary>
/// Sent by the chooser (Opponent/Ally) to supply target picks for a paused leaf action.
/// The same <see cref="AbilityTarget"/> shape used by game.activate_ability is reused here.
/// </summary>
public sealed record GameTargetPickRequest(
Guid SessionId,
string RequestId,
IReadOnlyList<AbilityTarget> Targets);
/// <summary>Acknowledged response for a target pick submission.</summary>
public sealed record GameTargetPickResponse(bool Success);
/// <summary>
/// Sent by the chooser to pick a specific tile for an effect that requires one
/// (e.g. CloneSpiritAsToken with DestinationScope=TargetTile).
/// </summary>
public sealed record GameTilePickRequest(
Guid SessionId,
string RequestId,
/// <summary>The chosen tile coordinates.</summary>
int X,
int Y);
/// <summary>Acknowledged response for a tile pick submission.</summary>
public sealed record GameTilePickResponse(bool Success);
/// <summary>
/// Sent by the chooser to pick a specific player for an effect that requires one
/// (e.g. ChannelCardFromZoneEffect with UnderControlOf=Choice).
/// </summary>
public sealed record GamePlayerPickRequest(
Guid SessionId,
string RequestId,
/// <summary>AccountId of the chosen player.</summary>
string PickedPlayerId);
/// <summary>Acknowledged response for a player pick submission.</summary>
public sealed record GamePlayerPickResponse(bool Success);