Repository navigation
game shutdown edge cases
This document covers edge cases, error scenarios, and best practices for the game shutdown implementation with proper client-server separation. It complements the main architectural design and implementation guide.
Scenario: Server sends GameEndedCommand but network fails before clients receive it.
Problem: Clients remain in game state, unaware the server has shut down.
Solution: Add heartbeat detection in ClientGame
// ClientGame.cs - Add heartbeat detection
private Timer? _heartbeatTimer;
private DateTime _lastCommandReceived;
public ClientGame(/* ... */)
{
// Start heartbeat monitor
_heartbeatTimer = new Timer(CheckServerHeartbeat, null,
TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(5));
_lastCommandReceived = DateTime.UtcNow;
}
private void CheckServerHeartbeat(object? state)
{
var timeSinceLastCommand = DateTime.UtcNow - _lastCommandReceived;
// If no command received in 30 seconds, assume disconnected
if (timeSinceLastCommand > TimeSpan.FromSeconds(30))
{
// Simulate GameEndedCommand
var disconnectCommand = new GameEndedCommand
{
GameOriginId = Id,
Reason = GameEndReason.HostDisconnected,
Timestamp = DateTime.UtcNow
};
HandleCommand(disconnectCommand);
}
}
public override void HandleCommand(IGameCommand command)
{
_lastCommandReceived = DateTime.UtcNow;
// ... existing logic
}
public void Dispose()
{
_heartbeatTimer?.Dispose();
// ... existing disposal
}Scenario: User rapidly clicks "Back to Menu" button multiple times.
Problem: Multiple PlayerLeftCommand sent, potential race conditions.
Solution: Add guard flag in BattleMapViewModel
// BattleMapViewModel.cs
private bool _isNavigatingBack;
private readonly SemaphoreSlim _navigationLock = new(1, 1);
private async Task BackToMenu()
{
// Guard against multiple simultaneous calls
if (_isNavigatingBack) return;
await _navigationLock.WaitAsync();
try
{
if (_isNavigatingBack) return;
_isNavigatingBack = true;
// Send PlayerLeftCommand for each local player
foreach (var player in Game.LocalPlayers)
{
var playerLeftCommand = new PlayerLeftCommand
{
GameOriginId = Game.Id,
PlayerId = player.Id,
Timestamp = DateTime.UtcNow
};
_commandPublisher.PublishCommand(playerLeftCommand);
}
await Task.Delay(100);
Dispose();
await NavigationService.NavigateToRootAsync();
}
finally
{
_navigationLock.Release();
}
}
public void Dispose()
{
// ... existing disposal
_navigationLock?.Dispose();
}Scenario: Player leaves during deployment or combat phase.
Problem: Game state may be inconsistent (e.g., waiting for player's action).
Solution: Handle player removal in ServerGame with phase awareness
// ServerGame.cs
private void HandlePlayerLeft(PlayerLeftCommand command)
{
var player = Players.FirstOrDefault(p => p.Id == command.PlayerId);
if (player == null) return;
// If it's this player's turn, advance to next player
if (ActivePlayer?.Id == player.Id)
{
AdvanceToNextPlayer();
}
// Remove all units owned by this player
var playerUnits = UnitsToPlay.Where(u => u.OwnerId == player.Id).ToList();
foreach (var unit in playerUnits)
{
UnitsToPlay.Remove(unit);
}
// Remove player
Players.Remove(player);
// Check if all players have left
if (Players.Count == 0)
{
StopGame(GameEndReason.AllPlayersLeft);
}
}Scenario: Client sends PlayerLeftCommand multiple times (e.g., network retry).
Problem: Server tries to remove already-removed player.
Solution: Make HandlePlayerLeft idempotent
// ServerGame.cs
private void HandlePlayerLeft(PlayerLeftCommand command)
{
var player = Players.FirstOrDefault(p => p.Id == command.PlayerId);
if (player == null)
{
// Player already removed - ignore
return;
}
// ... rest of logic
}Scenario: Server process crashes or is force-killed.
Problem: No GameEndedCommand sent to clients.
Solution: The relay notifies clients when the host's connection is lost. The client's RelayClientPublisher raises HostDisconnected, the adapter forwards it via RegisterDisconnectHandler, and GameConnector synthesizes a local GameEndedCommand delivered through the shared receive path — no network traffic:
// RelayClientPublisher - raises HostDisconnected when the relay reports host loss
// CommandTransportAdapter.cs - forward relay host-loss notifications to a single handler
public void RegisterDisconnectHandler(Action<ITransportPublisher> onPublisherDisconnected) { ... }
// GameConnector.cs - synthesize a local GameEndedCommand, no network round-trip
private void OnRelayHostDisconnected(ITransportPublisher publisher)
{
if (publisher != _relayPublisher) return;
if (!IsConnected) return;
IsConnected = false;
var command = new GameEndedCommand
{
GameOriginId = Guid.NewGuid(),
Reason = GameEndReason.HostDisconnected,
Timestamp = DateTime.UtcNow
};
_commandPublisher.Adapter.DispatchLocalCommand(command, publisher);
}DispatchLocalCommand invokes the same _onCommandReceived callback used for inbound transport messages, so the command reaches local subscribers without a serialization round-trip and without attempting to publish to the disconnected relay. BattleMapViewModel handles the GameEndedCommand and navigates the player back to the main menu with a host-disconnected dialog.
Scenario: User starts new game before previous game fully shut down.
Problem: Two games running simultaneously, resource conflicts.
Solution: Add shutdown completion tracking in GameManager
// GameManager.cs
private Task? _resetTask;
public async Task ResetForNewGame()
{
if (_resetTask != null)
{
// Already resetting - wait for completion
await _resetTask;
return;
}
_resetTask = ResetForNewGameInternal();
await _resetTask;
_resetTask = null;
}
private async Task ResetForNewGameInternal()
{
// Dispose current server game if exists
if (_serverGame != null)
{
_serverGame.Dispose();
// Wait a bit for disposal to complete
await Task.Delay(200);
_serverGame = null;
_isGameActive = false;
}
// ... rest of reset logic
}
public async Task InitializeLobby()
{
// Wait for any pending reset
if (_resetTask != null)
{
await _resetTask;
}
// ... existing initialization logic
}Scenario: Remote client closes app abruptly without sending disconnect command.
Problem: Server doesn't know client left, may wait for their actions.
Solution: Track player activity and detect timeouts
// ServerGame.cs - Track player activity
private readonly Dictionary<Guid, DateTime> _playerLastActivity = new();
private Timer? _activityMonitor;
public ServerGame(/* ... */)
{
// Monitor player activity every 10 seconds
_activityMonitor = new Timer(CheckPlayerActivity, null,
TimeSpan.FromSeconds(10), TimeSpan.FromSeconds(10));
}
public override void HandleCommand(IGameCommand command)
{
// Update activity timestamp for player commands
if (command is IClientCommand clientCommand)
{
_playerLastActivity[clientCommand.PlayerId] = DateTime.UtcNow;
}
// Existing logic
}
private void CheckPlayerActivity(object? state)
{
var inactivePlayers = _playerLastActivity
.Where(kvp => DateTime.UtcNow - kvp.Value > TimeSpan.FromMinutes(2))
.Select(kvp => kvp.Key)
.ToList();
foreach (var playerId in inactivePlayers)
{
// Simulate PlayerLeftCommand for inactive player
var playerLeftCommand = new PlayerLeftCommand
{
GameOriginId = Id,
PlayerId = playerId,
Timestamp = DateTime.UtcNow
};
HandleCommand(playerLeftCommand);
_playerLastActivity.Remove(playerId);
}
}
public void Dispose()
{
_activityMonitor?.Dispose();
// Existing disposal
}Scenario: Event handlers not unsubscribed, keeping objects alive.
Problem: Memory leaks over multiple game cycles.
Solution: Comprehensive subscription tracking
// BattleMapViewModel.cs - Track all subscriptions
private readonly List<IDisposable> _subscriptions = new();
public BattleMapViewModel(/* ... */)
{
// Track all subscriptions
_subscriptions.Add(Game.PhaseChanges.Subscribe(OnPhaseChanged));
_subscriptions.Add(Game.ActivePlayerChanges.Subscribe(OnActivePlayerChanged));
_subscriptions.Add(Game.Commands.Subscribe(OnCommandReceived));
}
public void Dispose()
{
if (_isDisposed) return;
_isDisposed = true;
// Dispose all subscriptions
foreach (var subscription in _subscriptions)
{
subscription?.Dispose();
}
_subscriptions.Clear();
// Existing disposal
}// GOOD - Using commands
var playerLeftCommand = new PlayerLeftCommand
{
GameOriginId = Game.Id,
PlayerId = player.Id,
Timestamp = DateTime.UtcNow
};
_commandPublisher.PublishCommand(playerLeftCommand);
// BAD - Direct method call (violates client-server separation)
_gameManager.StopGame(GameEndReason.GameAborted);// Command handlers should handle duplicate commands gracefully
private void HandlePlayerLeft(PlayerLeftCommand command)
{
var player = Players.FirstOrDefault(p => p.Id == command.PlayerId);
if (player == null) return; // Already removed - safe to ignore
// ... rest of logic
}public void Dispose()
{
if (_isDisposed) return; // Guard against multiple calls
_isDisposed = true;
// Dispose managed resources
_timer?.Dispose();
_subscription?.Dispose();
GC.SuppressFinalize(this);
}public async Task BackToMenu(CancellationToken cancellationToken = default)
{
// Send commands
foreach (var player in Game.LocalPlayers)
{
_commandPublisher.PublishCommand(new PlayerLeftCommand { /*...*/ });
}
// Respect cancellation
await Task.Delay(100, cancellationToken);
Dispose();
await NavigationService.NavigateToRootAsync();
}// ServerGame.cs
public void StopGame(GameEndReason reason)
{
_logger?.LogInformation($"Stopping game {Id} - Reason: {reason}");
// Shutdown logic
_logger?.LogInformation("Game stopped successfully");
}[Fact]
public void HandlePlayerLeft_CalledTwice_OnlyRemovesOnce()
{
// Arrange
var player = CreatePlayer();
var sut = CreateServerGameWithPlayer(player);
var command = new PlayerLeftCommand { PlayerId = player.Id };
// Act
sut.HandleCommand(command);
sut.HandleCommand(command); // Second call
// Assert - should not throw
sut.Players.ShouldNotContain(player);
}
[Fact]
public async Task BackToMenu_CalledMultipleTimes_OnlySendsCommandsOnce()
{
// Test guard against multiple calls
}
[Fact]
public void Dispose_CalledMultipleTimes_DoesNotThrow()
{
// Test idempotent disposal
}[Fact]
public async Task PlayerLeaves_ServerRemovesPlayer_OtherClientsNotified()
{
// Test full flow of player leaving
}
[Fact]
public async Task AllPlayersLeave_ServerStopsGame_SendsGameEndedCommand()
{
// Test game shutdown when all players leave
}Proper edge case handling with client-server separation ensures:
- Architectural Integrity: Commands-only communication maintained
- Robustness: System handles failures gracefully
- Resource Management: No leaks or zombie processes
- User Experience: Smooth transitions, no hangs
- Maintainability: Clear patterns for future development