Repository navigation
Rules Provider Analysis
📋 Document Context: This is the original analysis focusing on centralized rules provider benefits. For an updated perspective that addresses extensibility concerns and proposes a hybrid solution, see Rules-Provider-Analysis-Updated.md. Both documents provide valuable insights for different architectural priorities and should be considered together when making implementation decisions.
This document analyzes the architectural inconsistency in how the MakaMek codebase handles game rule values and provides recommendations for standardization.
Location: src/MakaMek.Core/Models/Map/Terrains/
Implementation: Each terrain class directly contains its game rule values as hardcoded properties.
public class ClearTerrain : Terrain
{
public override MakaMekTerrains Id => MakaMekTerrains.Clear;
public override int Height => 0;
public override int InterveningFactor => 0;
public override int MovementCost => 1;
}Characteristics:
- Values embedded in class definitions
- No external dependencies
- Direct property access
Location: src/MakaMek.Core/Utils/TechRules/ClassicBattletechRulesProvider.cs
Implementation: Game rule values are centralized in a rules provider with dependency injection.
public int GetPilotingSkillRollModifier(PilotingSkillRollType psrType)
{
return psrType switch
{
PilotingSkillRollType.GyroHit => 3,
PilotingSkillRollType.GyroDestroyed => 6,
PilotingSkillRollType.LowerLegActuatorHit => 1,
// ...
};
}Characteristics:
- Centralized rule management
- Dependency injection through
IRulesProvider - Clear method signatures organized by rule type
| Aspect | Hardcoded Approach | Centralized Rules Provider |
|---|---|---|
| Rule Changes | ❌ Requires modifying multiple classes | ✅ Single location to update |
| Consistency | ❌ Risk of inconsistent values across classes | ✅ Guaranteed consistency |
| Code Duplication | ❌ Similar logic scattered across classes | ✅ No duplication |
| Debugging | ❌ Must search multiple files for rule issues | ✅ Single source of truth |
| Aspect | Hardcoded Approach | Centralized Rules Provider |
|---|---|---|
| Unit Testing | ❌ Cannot mock rule values for edge cases | ✅ Easy to mock IRulesProvider
|
| Test Isolation | ❌ Tests coupled to hardcoded values | ✅ Tests can use custom rule sets |
| Rule Validation | ❌ Must test each terrain class separately | ✅ Comprehensive rule testing in one place |
| Aspect | Hardcoded Approach | Centralized Rules Provider |
|---|---|---|
| Multiple Rule Sets | ❌ Would require separate terrain class hierarchies | ✅ Simply implement different IRulesProvider
|
| Runtime Rule Switching | ❌ Impossible without major refactoring | ✅ Swap provider implementations |
| Custom Rules | ❌ Requires creating new terrain classes | ✅ Create custom provider implementation |
| Mod Support | ❌ Very difficult to implement | ✅ Natural extension point |
| Aspect | Hardcoded Approach | Centralized Rules Provider |
|---|---|---|
| Memory Usage | ✅ Minimal - values embedded in classes | |
| Access Speed | ✅ Direct property access | |
| Initialization | ✅ No setup required |
| Aspect | Hardcoded Approach | Centralized Rules Provider |
|---|---|---|
| Separation of Concerns | ❌ Business logic mixed with data | ✅ Clear separation |
| Domain Modeling | ✅ Terrain behavior independent | |
| Dependency Management | ✅ No external dependencies |
Decision: Adopt the Centralized Rules Provider approach throughout the MakaMek codebase.
-
Future-Proofing for Multiple Rule Sets: MakaMek will likely need to support different BattleTech rule variants or house rules. The centralized approach makes this trivial.
-
Superior Maintainability: Having all game rules in one location dramatically reduces maintenance burden and eliminates consistency issues.
-
Enhanced Testability: The ability to mock rule providers enables comprehensive testing of edge cases and rule interactions.
-
Professional Architecture: The centralized approach follows established enterprise patterns and separation of concerns principles.
-
Create Terrain Rules Provider Methods: Add methods like
GetTerrainMovementCost(),GetTerrainHeight(),GetTerrainInterveningFactor()toIRulesProvider -
Refactor Terrain Classes: Remove hardcoded values and inject
IRulesProviderdependency -
Maintain Backward Compatibility: Keep existing terrain class interfaces while changing internal implementation
-
Gradual Migration: Apply this pattern to other hardcoded rule areas (weapon stats, heat values, etc.)
public class ClearTerrain : Terrain
{
private readonly IRulesProvider _rules;
public ClearTerrain(IRulesProvider rules)
{
_rules = rules;
}
public override MakaMekTerrains Id => MakaMekTerrains.Clear;
public override int Height => _rules.GetTerrainHeight(Id);
public override int InterveningFactor => _rules.GetTerrainInterveningFactor(Id);
public override int MovementCost => _rules.GetTerrainMovementCost(Id);
}While the centralized approach has slight performance overhead, this is negligible in the context of a turn-based strategy game. The benefits far outweigh the minimal performance cost.
The centralized rules provider approach provides superior maintainability, testability, and extensibility. This architectural decision will position MakaMek for long-term success with multiple rule sets, easier maintenance, and more robust testing capabilities.
- Extend
IRulesProviderinterface with terrain-related methods - Update
ClassicBattletechRulesProviderimplementation - Refactor terrain classes to use dependency injection
- Update terrain factory and dependency injection configuration
- Migrate other hardcoded rule areas using the same pattern
Document Version: 1.0
Date: 2025-07-09
Author: Augment Agent
Status: Recommendation