Repository navigation
bot player system implementation roadmap
Date: 2025-10-16
Updated: 2025-11-16
Status: Ready for Implementation
Based on: bot-player-system-prd.md
This document provides a concrete, actionable roadmap for implementing the bot player system in MakaMek. It distills the comprehensive analysis into specific tasks with clear acceptance criteria.
Before starting implementation, ensure you understand:
- MakaMek's command pattern: How commands flow from client → server → all clients
- ClientGame vs ServerGame: Client maintains local state, server is authoritative
- Phase management: How game phases transition and handle commands
-
UI state pattern: How
DeploymentState,MovementState, etc. work
Recommended Reading:
-
docs/architecture/bot-player-system-prd.md- Original design document -
src/MakaMek.Core/Models/Game/ClientGame.cs- Client game implementation -
src/MakaMek.Core/Models/Game/ServerGame.cs- Server game implementation
Before implementation, the following architectural decisions must be made:
DECIDED: BotManager is created by UI and is a singleton per client device. On game start the BotManager is reinitiated with a particular instance of a ClientGame.
Options:
- A) Add
IsBotproperty toPlayerViewModel - B) Create separate
BotViewModelclass - C) Use naming convention (e.g., "Bot 1234")
Recommendation: Option A
Rationale:
- Minimal code changes
- Consistent with existing
IsLocalPlayerpattern - Easy to add bot indicator in UI
- Read
ControlTypefromIPlayerinterface
Options:
- A) Fail fast (throw exceptions, stop game)
- B) Graceful degradation (log error, skip turn)
- C) Retry with fallback (retry decision, then skip)
Recommendation: Option B (Graceful degradation)
Rationale:
- Bots shouldn't break the game for human players
- Logging provides debugging information
- Skip turn is always a valid action
Goal: Set up separate project for bot logic
Files to Create:
src/MakaMek.Bots/
├── MakaMek.Bots.csproj
├── IBot.cs
├── Bot.cs
├── IBotManager.cs
├── BotManager.cs
├── BotDifficulty.cs
└── DecisionEngines/
├── IBotDecisionEngine.cs
├── DeploymentEngine.cs
├── MovementEngine.cs
├── WeaponsEngine.cs
└── EndPhaseEngine.cs
Dependencies:
- Reference:
MakaMek.Coreonly - No references to
MakaMek.PresentationorMakaMek.Avalonia
Acceptance Criteria:
- ✅ Project compiles
- ✅ No circular dependencies
- ✅ All interfaces defined
Goal: Add metadata to distinguish player control mechanisms (for UI purposes only)
File: src/MakaMek.Core/Models/Game/Players/IPlayer.cs
Changes:
/// <summary>
/// Player metadata to indicate player type for UI purposes only
/// </summary>
public enum PlayerControlType
{
Local, // Human player on this client
Bot, // AI-controlled player on this client
Remote // Human player on another client
}
public interface IPlayer
{
Guid Id { get; }
string Name { get; }
/// <summary>
/// Indicates how this player is controlled (for UI display only)
/// This is metadata, not behavior - ClientGame doesn't use this
/// </summary>
PlayerControlType ControlType { get; }
// ... existing properties
}Update Player Implementation:
public class Player : IPlayer
{
public Guid Id { get; }
public string Name { get; }
public PlayerControlType ControlType { get; set; } = PlayerControlType.Local;
// ... existing implementation
}Tests to Add:
// tests/MakaMek.Core.Tests/Models/Game/Players/PlayerTests.cs
[Fact]
public void Player_DefaultControlType_IsLocal()
{
// Arrange & Act
var player = new Player(Guid.NewGuid(), "Test Player");
// Assert
player.ControlType.ShouldBe(PlayerControlType.Local);
}
[Fact]
public void Player_CanSetControlType_ToBot()
{
// Arrange
var player = new Player(Guid.NewGuid(), "Bot Player");
// Act
player.ControlType = PlayerControlType.Bot;
// Assert
player.ControlType.ShouldBe(PlayerControlType.Bot);
}Acceptance Criteria:
- ✅
PlayerControlTypeenum added - ✅
IPlayerinterface hasControlTypeproperty - ✅
Playerclass implementsControlTypewith default valueLocal - ✅ All tests pass
- ✅ No changes to
ClientGamerequired
Goal: Create bot player that observes game and makes decisions
File: src/MakaMek.Bots/Bot.cs
Implementation:
public class Bot : IBot
{
private IBotDecisionEngine _decisionEngine;
private IDisposable? _commandSubscription;
// depends on current phase, stateless, the same as UIState for human players
private IBotDecisionEngine _currentDecisionEngine;
public IPlayer Player { get; }
public ClientGame ClientGame { get; }
public BotDifficulty Difficulty { get; }
public Bot(
IPlayer player,
ClientGame clientGame,
BotDifficulty difficulty)
{
Player = player;
ClientGame = clientGame;
Difficulty = difficulty;
_commandSubscription = ClientGame.Commands.Subscribe(OnCommandReceived);
}
private void OnCommandReceived(IGameCommand command)
{
switch (command)
{
case ChangeActivePlayerCommand activePlayerCmd:
if (activePlayerCmd.PlayerId == Player.Id)
_ = _currentDecisionEngine.MakeDecision();
break;
case ChangePhaseCommand phaseCmd:
// for better testability DecisionEngines can be created in BotManager
// and provided as collection via constructor
_currentDecisionEngine = TransferDecisionEngine(phaseCmd.Phase);
break;
case GameEndedCommand:
Dispose();
break;
// Ignore other commands
}
}
private int GetThinkingDelay()
{
// optionally introduce delay's to Bot's decision making to make it feel more natural
}
public void Dispose()
{
_commandSubscription?.Dispose();
}
}Tests:
// tests/MakaMek.Bots.Tests/BotTests.cs
[Fact]
public async Task OnCommandReceived_WhenBotIsActive_MakesDecision()
{
// Arrange
var mockDecisionEngine = Substitute.For<IBotDecisionEngine>();
var mockAction = Substitute.For<IBotAction>();
mockDecisionEngine.SelectAction(Arg.Any<ClientGame>(), Arg.Any<IPlayer>())
.Returns(mockAction);
var sut = new Bot(_player, _clientGame, mockDecisionEngine, BotDifficulty.Easy);
// Act
_clientGame.HandleCommand(new ChangeActivePlayerCommand
{
PlayerId = _player.Id,
GameOriginId = _clientGame.Id
});
await Task.Delay(2000); // Wait for thinking delay
// Assert
await mockDecisionEngine.Received(1).SelectAction(_clientGame, _player);
mockAction.Received(1).Execute(_clientGame);
}Acceptance Criteria:
- ✅ Bot subscribes to ClientGame.Commands
- ✅ Bot reacts to ChangePhaseCommand
- ✅ Bot reacts to ChangeActivePlayerCommand
- ✅ Thinking delay is applied
- ✅ Decision engine is called
- ✅ Action is executed
- ✅ Error handling works
- ✅ All tests pass
Goal: Manage bot lifecycle
File: src/MakaMek.Bots/BotManager.cs
Implementation:
public class BotManager : IBotManager
{
private readonly Dictionary<Guid, IBot> _bots = new(); // Key: PlayerId
private ClientGame? _clientGame;
public void Initialize(ClientGame clientGame)
{
_clientGame = clientGame;
// Clean up any existing bots
foreach (var bot in _bots.Values)
{
bot.Dispose();
}
_bots.Clear();
}
public IReadOnlyList<IBot> Bots => _bots.Values.ToList();
public void AddBot(IPlayer player, BotDifficulty difficulty = BotDifficulty.Easy)
{
if (_clientGame == null)
throw new InvalidOperationException("BotManager must be initialized before adding bots");
// Ensure player has correct control type
if (player.ControlType != PlayerControlType.Bot)
throw new ArgumentException("Player must have ControlType.Bot", nameof(player));
// Join the game like any local player - ClientGame doesn't know it's a bot
_clientGame.JoinGameWithUnits(player, units, pilotAssignments);
// BotManager tracks which players are bots
var bot = new Bot(player, _clientGame, difficulty);
_bots.Add(player.Id, bot);
}
public void RemoveBot(Guid botPlayerId)
{
if (_bots.TryGetValue(botPlayerId, out var bot))
{
bot.Dispose();
_bots.Remove(botPlayerId);
// Optionally remove player from game
// _clientGame.RemovePlayer(botPlayerId);
}
}
public bool IsBot(Guid playerId)
{
return _bots.ContainsKey(playerId);
}
public void Dispose()
{
foreach (var bot in _bots.Values)
{
bot.Dispose();
}
_bots.Clear();
}
}Acceptance Criteria:
- ✅ BotManager creates bots
- ✅ Bots are added to ClientGame.LocalPlayers (not a separate list)
- ✅ BotManager tracks bot instances internally
- ✅ Bots can be removed
- ✅ Cleanup works correctly
- ✅ All tests pass
Goal: Bot can deploy units randomly
File: src/MakaMek.Bots/DecisionEngines/DeploymentEngine.cs
Key Logic:
- Find undeployed units:
player.Units.Where(u => !u.IsDeployed) - Get valid deployment hexes from map
- Select random hex and direction
- Publish
DeployUnitCommand
Acceptance Criteria:
- ✅ Bot deploys all units
- ✅ Deployment positions are valid
Goal: Bot can move units randomly
File: src/MakaMek.Bots/DecisionEngines/MovementEngine.cs
Key Logic:
- Find unmoved units:
player.AliveUnits.Where(u => u.MovementTypeUsed == null) - Select random movement type (prefer Walk)
- Calculate random valid path using
BattleMap.FindPath() - Publish
MoveUnitCommand
Acceptance Criteria:
- ✅ Bot moves all units
- ✅ Movement paths are valid
- ✅ Handles standing still
Goal: Bot can attack targets randomly
File: src/MakaMek.Bots/DecisionEngines/WeaponsEngine.cs
Key Logic:
- Find units that haven't attacked:
player.AliveUnits.Where(u => !u.HasDeclaredWeaponAttack) - Find targets in range
- Select random target
- Select all weapons in range
- Publish
WeaponAttackDeclarationCommandand optionallyWeaponConfigurationCommand
Acceptance Criteria:
- ✅ Bot attacks when targets available
- ✅ Bot skips when no targets
- ✅ Weapon selection is valid
- ✅ Turns torso when needed
Goal: Bot can end turn
File: src/MakaMek.Bots/DecisionEngines/EndPhaseEngine.cs
Key Logic:
- Check for shutdown units (always attempt restart)
- Check for overheated units (shutdown if heat > 25)
- Publish
EndTurnCommand - Publish
ShutdownUnitCommandwhen overheated - Publish
StartupUnitCommandwhen shutdown
Acceptance Criteria:
- ✅ Bot attempts restart for shutdown units
- ✅ Bot shuts down overheated units
- ✅ Bot ends turn
Goal: Users can add bots from UI
Files to Modify:
- Files related to StartNewGame and JoinGame functionality
Key Changes:
- Add "Add Bot" button to lobby UI
- Create bot player with
ControlType = PlayerControlType.Bot - Call
BotManager.AddBot()instead of directly modifyingClientGame - Display bot indicator (check
player.ControlTypein UI) - Allow bot removal via
BotManager.RemoveBot()
Example ViewModel Integration:
public class StartNewGameViewModel
{
private readonly IBotManager _botManager;
private readonly ClientGame _clientGame;
public void AddBotPlayer(string name, BotDifficulty difficulty, List<Unit> units)
{
var botPlayer = new Player
{
Id = Guid.NewGuid(),
Name = name,
ControlType = PlayerControlType.Bot // This is the key
};
// BotManager handles the rest
_botManager.AddBot(botPlayer, difficulty);
}
}Acceptance Criteria:
- ✅ "Add Bot" button appears in lobby
- ✅ Clicking button adds bot to player list
- ✅ Bot has indicator (e.g., robot icon) based on
ControlType - ✅ Bot can be removed before game starts
- ✅ Existing AddPlayer infrastructure is reused as much as possible
- ✅ Bot joins game correctly
Components to Test:
- Bot: Activation, decision-making, error handling
- BotManager: Bot creation, removal, cleanup
- Decision Engines: Action selection for various game states
- Bot Actions: Command creation and execution
Scenarios:
- UI Flow: Add bot, remove bot, start game
- Performance: Decision times, memory usage
- User Experience: Bot behavior feels natural
Game Scenarios:
- Bot vs Bot: Full game completion
- Human vs Bot: Mixed gameplay
- Multiple Bots: 4 bots playing
- Error Scenarios: Invalid moves, exceptions, edge cases
- ✅ Bots can join games
- ✅ Bots can deploy units
- ✅ Bots can move units
- ✅ Bots can attack targets
- ✅ Bots can end turns
- ✅ Bots can complete full games
- ✅ Bot decisions < 3 seconds
- ✅ No UI freezing
- ✅ No memory leaks
- ✅ Network transparency maintained
- ✅ All unit tests pass
- ✅ Code coverage > 80%
- ✅ No compiler warnings
- ✅ Follows existing patterns
- ✅ Review and approve architectural decisions (Section: Critical Decisions Required)
- ✅ Create MakaMek.Bots project (Phase 0, Task 0.1)
- ✅ Extend IPlayer interface (Phase 0, Task 0.2) - No ClientGame changes needed
- ✅ Implement Bot (Phase 1, Task 1.1)
- ✅ Implement BotManager (Phase 1, Task 1.2)
- ✅ Continue with decision engines (Phase 2)
End of Roadmap