Repository navigation
Rules Provider Analysis Updated
🔄 Document Context: This is an updated analysis that addresses extensibility concerns raised about the original centralized rules provider recommendation. For the original analysis focusing on centralized rules provider benefits, see Rules-Provider-Analysis.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, with special consideration for the Open-Closed Principle.
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;
}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,
// ...
};
}Problem Identified: The centralized rules provider approach violates the Open-Closed Principle for entity extension.
Adding a new terrain type currently requires:
Hardcoded Approach:
- Add enum value to
MakaMekTerrains - Create new terrain class (e.g.,
SwampTerrain.cs) - Update factory method in
Terrain.GetTerrainType()
Pure Rules Provider Approach would require:
- All of the above PLUS
- Modify
ClassicBattletechRulesProvider.GetTerrainToHitModifier() - Potentially modify other rule methods
This breaks the Open-Closed Principle - the system should be open for extension but closed for modification.
Decision: Adopt a Hybrid Approach that combines the benefits of both patterns while maintaining extensibility.
- Entity-Level Defaults: Terrain classes contain default rule values (maintaining Open-Closed compliance)
- Rules Provider Overrides: Rules provider can override defaults for specific rule sets
- Fallback Mechanism: System falls back to entity defaults when rules provider doesn't specify values
public interface IRulesProvider
{
// Existing methods...
// New optional override methods
int? GetTerrainMovementCostOverride(MakaMekTerrains terrainType);
int? GetTerrainHeightOverride(MakaMekTerrains terrainType);
int? GetTerrainInterveningFactorOverride(MakaMekTerrains terrainType);
}public abstract class Terrain
{
protected IRulesProvider? _rulesProvider;
public abstract MakaMekTerrains Id { get; }
// Default values defined in derived classes
protected abstract int DefaultHeight { get; }
protected abstract int DefaultInterveningFactor { get; }
protected abstract int DefaultMovementCost { get; }
// Public properties with rules provider fallback
public int Height => _rulesProvider?.GetTerrainHeightOverride(Id) ?? DefaultHeight;
public int InterveningFactor => _rulesProvider?.GetTerrainInterveningFactorOverride(Id) ?? DefaultInterveningFactor;
public int MovementCost => _rulesProvider?.GetTerrainMovementCostOverride(Id) ?? DefaultMovementCost;
public void SetRulesProvider(IRulesProvider rulesProvider)
{
_rulesProvider = rulesProvider;
}
}public class ClearTerrain : Terrain
{
public override MakaMekTerrains Id => MakaMekTerrains.Clear;
protected override int DefaultHeight => 0;
protected override int DefaultInterveningFactor => 0;
protected override int DefaultMovementCost => 1;
}
// New terrain types can be added without modifying existing code
public class SwampTerrain : Terrain
{
public override MakaMekTerrains Id => MakaMekTerrains.Swamp;
protected override int DefaultHeight => 0;
protected override int DefaultInterveningFactor => 1;
protected override int DefaultMovementCost => 3;
}public class ClassicBattletechRulesProvider : IRulesProvider
{
// Existing methods...
public int? GetTerrainMovementCostOverride(MakaMekTerrains terrainType)
{
// Only override if different from default
return terrainType switch
{
MakaMekTerrains.HeavyWoods => 4, // Override default of 3
_ => null // Use terrain default
};
}
public int? GetTerrainHeightOverride(MakaMekTerrains terrainType) => null; // Use defaults
public int? GetTerrainInterveningFactorOverride(MakaMekTerrains terrainType) => null; // Use defaults
}| Aspect | Hybrid Approach |
|---|---|
| Open-Closed Principle | ✅ New terrain types require no modification of existing code |
| Multiple Rule Sets | ✅ Rules provider can override defaults for different variants |
| Backward Compatibility | ✅ Existing terrain classes work unchanged |
| Testability | ✅ Can mock rules provider and test with different rule sets |
| Performance | ✅ Minimal overhead - only checks override when rules provider is set |
| Maintainability | ✅ Clear separation between defaults and rule-specific overrides |
- Phase 1: Implement hybrid terrain system
- Phase 2: Update terrain factory to inject rules provider
- Phase 3: Apply pattern to other entity types (weapons, equipment, etc.)
- Phase 4: Create alternative rules providers for different BattleTech variants
The hybrid approach provides the best of both worlds:
- Maintains extensibility for adding new entities without code modification
- Supports multiple rule sets through optional overrides
- Preserves performance with minimal overhead
- Enables comprehensive testing through dependency injection
This architectural decision positions MakaMek for long-term success while respecting fundamental software design principles.
Even with the hybrid model we still must touch the MakaMekTerrains enum when a new terrain is introduced, so the core assembly is not completely “closed for modification”. The same is true for any *TypeEnums. That approach might be revisited.
Document Version: 2.0
Date: 2025-07-09
Author: Augment Agent
Status: Updated Recommendation