Repository navigation
rules architecture refactor prd
Date: 2026-10-18
Status: Draft — decision aid
Related docs: Rule-Related-PRs.md · Rules-Provider-Analysis.md · Rules-Provider-Analysis-Updated.md
Related issues: #1105 (unify modifier values), #1028 (movement cost via rules provider)
Related PRs: #1443 · #1450 · #1445 · #1451
This PRD defines the target architecture for how MakaMek sources, resolves, and applies game-rule values. It resolves the four open "rules provider" PRs into a single coherent design, grounded in established software-engineering principles (interface segregation, dependency inversion, information hiding) and in the actual call graph on main.
The core thesis: entities are plain data, rules are resolved by services that already own the provider (or resolved once into unit state when the server applies a state change), and the provider is segregated by domain and composed — not inherited — into a rule set.
The codebase expresses the same class of information — a game-rule number — in several incompatible ways:
| Mechanism | Where | Example |
|---|---|---|
| Hardcoded on the entity |
src/MakaMek.Map/Models/Terrains/ — abstract int MovementCost, Height, InterveningFactor on every terrain subclass |
LightWoodsTerrain.MovementCost => 1 (additional cost on top of the 1 MP hex-entry cost) |
| Hardcoded on modifier records |
ProneAttackerModifier.DefaultValue, SkiddingAttackerModifier.DefaultValue, SkiddingTargetModifier.DefaultValue, PartialCoverModifier.DefaultValue
|
ProneAttackerModifier.DefaultValue = 2 |
| Hardcoded inline in domain logic |
Mech.MovementHeatPenalty, Mech.AttackHeatPenalty, Mech.ApplyHeatEffects (life-support pilot damage), Mech.GetMovementPoints (run ×1.5), sensor/actuator/leg/hip penalties |
if (CurrentHeat >= 15) hits = 1; |
Centralized in IRulesProvider |
TotalWarfareRulesProvider — 26 methods covering to-hit, hit location, cluster, heat, PSR, thresholds |
GetProneFiringModifier() => 2 |
| Provider passed as a method parameter on the unit API |
IUnit.GetHeatData(IRulesProvider), IUnit.GetProjectedHeatValue(IRulesProvider)
|
unit.GetHeatData(Game.RulesProvider) |
Concrete symptom (#1105): IRulesProvider.GetProneFiringModifier() exists but has zero callers — Mech.GetAttackModifiers reads ProneAttackerModifier.DefaultValue instead. A house-rule set that changes the prone modifier silently does nothing. Likewise, terrain movement cost cannot be changed without editing terrain classes (#1028).
A second, quieter symptom: GetTerrainToHitModifier(MakaMekTerrains) is a provider-side table with a _ => 0 fallback. A newly added terrain silently gets a 0 to-hit modifier — correct-looking, possibly wrong.
| PR | Scope | Approach | Key weakness |
|---|---|---|---|
| #1443 | Attack/to-hit modifiers only | Threads IRulesProvider? (optional) through GetAttackModifiers, AttackScenario, ToHitCalculator, bots |
Optional-nullable provider → branching, "silently does nothing" paths, latent NRE |
| #1450 | Heat, skid, falling, life-support + all of #1443 | Provider threaded into GetMovementPoints, CanStandup, UnitExtensions, MovementState, bots, MCP |
Largest ripple; adds parameterless "legacy wrappers" (3rd source of truth); commits BUG-INVENTORY.local.md
|
| #1445 | Terrain MP cost via provider | Introduces IMovementCostProvider in Map; keeps Terrain.MovementCost as default |
Duplicates the cost table in both Map and Core; IRulesProvider : IMovementCostProvider inverts the dependency |
| #1451 | Terrain MP cost via provider (full) | Deletes Terrain.MovementCost entirely; adds path-cache invalidation |
Largest blast radius (37 files); deletes the entity default the hybrid relies on; still duplicates table |
- #1443 is a subset of #1450 — landing both creates duplicate/conflicting definitions.
- #1445 and #1451 are mutually exclusive — both touch the identical seam.
- All four bump
Directory.Build.props(version collision).
Every architectural decision in this PRD is justified by one or more of these principles.
"The best modules are those that provide powerful functionality yet have simple interfaces." — John Ousterhout, A Philosophy of Software Design
Application: The caller (ToHitCalculator, pathfinding, MechFactory) makes one simple call — _rules.GetProneFiringModifier(), _movementCost.GetMovementCost(terrain). It never branches on nullability, never checks "is there an override?", never knows which rule set is active.
Caveat (same source): Ousterhout flags pass-through methods and shallow classes as red flags — a method that does nothing but invoke another with a similar signature adds no functionality and usually means the boundary between the classes is misplaced. Interface segregation must not degenerate into many tiny interfaces and forwarding layers. Hence: a small number of domains (five), no empty interfaces, and no forwarding class in the end state — consumers depend on the domain interface they use, and the whole rule set is held by a methodless RuleSet record whose properties expose the domains directly (§3.4). Exposing the lower-level object to the caller is Ousterhout's own remedy for a pass-through layer. A transitional forwarding composite exists only to keep existing tests compiling and is deleted in Phase 5.
"Hide implementation details. Don't leak them across module boundaries."
Application: Terrain classes expose Height, InterveningFactor, and a default MovementCost as intrinsic data. Callers never read terrain.MovementCost directly for gameplay; they ask IMovementCostProvider, which hides whether the value is the entity default or a rule-set override. The entity stays a POCO; the service hides the two-source merge.
"Clients should not be forced to depend on methods they do not use." — SOLID
Application: IRulesProvider has 26 methods, but every consumer uses a small, disjoint subset (verified on main):
| Consumer | Methods used |
|---|---|
ToHitCalculator |
attacker/target movement, range, terrain to-hit, aimed shot, secondary target, partial cover |
WeaponAttackResolver, AttackerPartialCoverGate, WeaponsAttackState
|
hit location, cluster hits, aimed-shot success values, partial cover |
PilotingSkillCalculator, FallProcessor, FallingDamageCalculator
|
PSR modifier, requires-PSR, heavy-damage threshold, water depth, skid, facing/direction after fall, hit location |
HeatEffectsCalculator, Unit.GetHeatData, HeatProjectionViewModel
|
shutdown, ammo explosion, movement heat, external heat cap, water dissipation cap |
MechFactory |
GetStructureValues only |
Split IRulesProvider along exactly these lines (§3.4).
"Software entities should be open for extension, but closed for modification." — SOLID
Application: Adding a new terrain type (SwampTerrain) must not require modifying any rules provider. The hybrid model (providerOverride ?? entityDefault) achieves this: a new terrain carries its own default, existing providers have no override for it, so the default stands.
Known limit: adding a terrain still touches the MakaMekTerrains enum, so Core/Map is never fully closed (noted in Rules-Provider-Analysis-Updated.md).
"Favor composition over class inheritance." — GoF, Design Patterns
Application, two levels:
-
Across domains — composition. A rule set is a composition of independent domain implementations (
RuleSet(toHit, damage, piloting, heat)).IRulesProvidermust not inherit Map'sIMovementCostProvider(the #1445 approach — "the whole Core rules surface becomes a subtype of a Map concern"). -
Within a domain — inheritance with virtual methods. Overriding a single heat threshold should be one
override, not a re-implementation or decorator of all ofIHeatRules.TotalWarfareHeatRulesexposes virtual methods;MyHouseHeatRules : TotalWarfareHeatRulesoverrides one.
The GoF maxim argues against deep hierarchies that couple unrelated concerns, not against a one-level, single-domain override.
"A class should have one, and only one, reason to change." — SOLID
Application: Mech should not own heat→movement tables, life-support damage thresholds, or prone/skidding modifier values — those are rules. Mech should change only when unit state changes; the rules change only when the rule set changes. Where a unit genuinely needs a rule-derived value on its own API (e.g. heat-reduced MP), the value is resolved by a service and stored as state (§3.3.2), not computed from a rule table inside the entity.
"Depend on abstractions, not concretions." — SOLID
Application: IMovementCostProvider and its default implementation live in MakaMek.Map (Map has no project references; Core references Map). Map code depends only on the abstraction; any house-rule implementation can live in Core (or elsewhere) and is supplied through IBattleMapFactory by DI. Map never references a Core type.
The foundational distinction — what varies together, and along which axis:
| Category | Definition | Where it lives | Examples |
|---|---|---|---|
| Game data | Intrinsic description of a thing. Varies per-instance, scales with content, is authored (MTF, map files). | Entity properties, data files | Terrain height, water depth, intervening factor; weapon damage/heat/ranges; unit tonnage, base movement, armor layout |
| Rules | Procedures and tables of the rule set. Bounded in count, varies when you switch Total Warfare → house rules. | Segregated rules domains (§3.4) | Hit-location tables, cluster hits, structure-by-tonnage, heat scale, PSR modifiers, terrain to-hit, thresholds, movement-cost overrides |
| State | Current transient condition of an entity — including rule-derived values resolved by the server at the moment state changes. | On the entity | Current heat, resolved heat penalties, MP spent, damage, prone/skidding flags |
This taxonomy is the acceptance test for every future "should this be a rule?" question.
Terrain.MovementCost is the additional MP cost of entering the terrain, on top of the fixed HexEnterMovementCost { Value = 1 } added by Hex.GetEnterMovementCost (Clear = 0, LightWoods = 1, HeavyWoods = 2, Water = 0/1/3 by depth). It stays on the entity as the default.
// MakaMek.Map — entity stays a POCO, carries the default. No provider reference.
public abstract class Terrain
{
public abstract MakaMekTerrains Id { get; }
public abstract int Height { get; } // data — intrinsic
public abstract int InterveningFactor { get; } // data — intrinsic
public abstract int MovementCost { get; } // data — default additional MP cost, overridable by rules
}
// MakaMek.Map — the seam. Receives the Terrain instance (not just its Id),
// so instance-dependent defaults such as water depth remain expressible.
public interface IMovementCostProvider
{
int GetMovementCost(Terrain terrain);
}
// MakaMek.Map — the default IS the Total Warfare rule set, because TW values
// are exactly the entity defaults. No table, no duplication.
public sealed class DefaultMovementCostProvider : IMovementCostProvider
{
public static readonly DefaultMovementCostProvider Instance = new();
public int GetMovementCost(Terrain terrain) => terrain.MovementCost;
}
// Anywhere (typically Core) — a house rule lists ONLY what it changes.
public sealed class HouseRuleMovementCostProvider(IReadOnlyDictionary<MakaMekTerrains, int> overrides)
: IMovementCostProvider
{
private readonly IReadOnlyDictionary<MakaMekTerrains, int> _overrides;
public HouseRuleMovementCostProvider(IReadOnlyDictionary<MakaMekTerrains, int> overrides)
{
_overrides = new Dictionary<MakaMekTerrains, int>(overrides);
}
public int GetMovementCost(Terrain terrain)
=> _overrides.TryGetValue(terrain.Id, out var cost) ? cost : terrain.MovementCost;
}Single source of truth: the TW cost table exists once — in the terrain classes. House-rule providers contain only deltas.
Why this is deep: Hex.GetEnterMovementCost (both the normal and road-to-road branches) calls _movementCostProvider.GetMovementCost(terrain) — one call, no branching, no null check.
Why this is open-closed: a new SwampTerrain with MovementCost => 2 works with every existing provider. Unknown terrains fall through to the default — no ArgumentOutOfRangeException.
Wiring: the provider is supplied once, at map creation, through IBattleMapFactory (BattleMapFactory is already the only creation seam — used by ClientGame, JoinGameViewModel, MapConfigViewModel). BattleMap passes it to its hexes. Because the provider is fixed for the lifetime of a map instance, the path caches (_movementPathCache, _movementLongPathCache) can never go stale — no cache invalidation is needed (consistent with the §8 non-goal of runtime rule switching).
Same treatment for terrain to-hit (follow-up): GetTerrainToHitModifier currently has the inverse shape (provider table, _ => 0). Either give Terrain a default to-hit modifier and apply the same hybrid, or explicitly document that unknown terrains have no to-hit modifier. This PRD recommends the hybrid for consistency, but defers it (§5, Phase 3 scope inventory).
These values are rules (heat penalties, prone/skidding modifiers, falling-levels modifier, life-support pilot damage). Two resolution strategies apply, chosen by who consumes the value.
Every attack-modifier consumer goes through AttackScenario → ToHitCalculator, and ToHitCalculator already resolves the skidding-target and partial-cover modifiers itself. Prone and skidding-attacker follow the same precedent:
// AttackScenario carries the facts (state), not the values (rules).
public record AttackScenario
{
// ...
public bool AttackerIsProne { get; init; }
public bool AttackerIsSkidding { get; init; }
}
// ToHitCalculator (already holds the rules) resolves the values.
private IReadOnlyList<RollModifier> GetDetailedOtherModifiers(AttackScenario scenario)
{
List<RollModifier> modifiers = [.. scenario.AttackerModifiers]; // component-state modifiers (sensors, actuators)
if (scenario.AttackerIsProne)
modifiers.Add(new ProneAttackerModifier { Value = _rules.GetProneFiringModifier() });
if (scenario.AttackerIsSkidding)
modifiers.Add(new SkiddingAttackerModifier { Value = _rules.GetSkiddingAttackerModifier() });
if (scenario.TargetUnit?.IsSkidding == true)
modifiers.Add(new SkiddingTargetModifier { Value = _rules.GetSkiddingTargetModifier() });
// ...
}AttackScenario.FromUnits and FromHypothetical (bots) populate the two flags. Mech.GetAttackModifiers stops emitting prone/skidding modifiers. No signature on IUnit/Unit/Mech changes.
Heat→movement penalty feeds GetMovementPoints, which feeds AvailableWalkingPoints, CanStandup, CanJump, the UI-bound MovementModifiers, ~13 call sites in MovementState, the bot MovementEngine, and MCP MovementTools. No single service owns all of those, so "resolve in the service" does not work here without threading the provider through the unit API (the #1450 ripple).
But CurrentHeat changes in exactly one place: Unit.ApplyHeat(HeatData), invoked from HeatUpdatedCommand on both server and client. HeatPhase (server) already holds the rules. Therefore:
// HeatPhase (server) resolves rule-derived effects with IHeatRules and broadcasts them.
var heatData = _heatCalculator.GetHeatData(unit); // service, see §3.3.3
var newHeat = heatData.ResultingHeat(unit.CurrentHeat);
heatData = heatData with
{
MovementPenalty = _heatRules.GetHeatMovementPenalty(newHeat),
AttackPenalty = _heatRules.GetHeatAttackPenalty(newHeat),
LifeSupportDamage = unit.HasDestroyedLifeSupport ? _heatRules.GetLifeSupportPilotDamage(newHeat) : 0
};
// Unit just stores what the server resolved — state, not rules.
public void ApplyHeat(HeatData heatData)
{
CurrentHeat = ...;
MovementHeatPenalty = heatData.MovementPenalty; // was computed from a table in Mech
AttackHeatPenalty = heatData.AttackPenalty;
ApplyLifeSupportDamage(heatData.LifeSupportDamage);
...
}This matches the documented architecture ("mechanics are performed server-side and broadcast for client display") and continues an existing migration — Mech.ApplyHeatEffects already notes that heat shutdown moved to HeatEffectsCalculator. GetMovementPoints and every caller keep their signatures.
Fallback (if the state approach is rejected): MechFactory supplies the unit with a narrow IHeatRules at construction. This is an explicit, documented exception to "entities hold no rules", limited to one narrow interface — never the full IRulesProvider, never a per-call parameter.
IUnit.GetHeatData(IRulesProvider) and IUnit.GetProjectedHeatValue(IRulesProvider) already push a rules service through the unit API. All three callers already hold a provider (HeatPhase, HeatProjectionViewModel, bot WeaponsEngine). Move both into an IHeatCalculator service in Models/Game/Mechanics that depends on IHeatRules; the unit exposes only the raw state it needs (movement taken, declared weapon targets, heat sinks, external heat).
// Domain interfaces — mapped from actual consumers (§2.3).
public interface IToHitRules
{
int GetAttackerMovementModifier(MovementType movementType);
int GetTargetMovementModifier(int hexesMoved);
int GetRangeModifier(RangeBracket rangeBracket, int rangeValue, int distance);
int GetTerrainToHitModifier(MakaMekTerrains terrainType);
int GetAimedShotModifier(PartLocation targetLocation);
int[] GetAimedShotSuccessValues();
int GetSecondaryTargetModifier(bool isFrontArc);
int GetProneFiringModifier();
int GetPartialCoverModifier();
bool HasPartialCover(IUnit targetUnit, LineOfSightResult losResult);
bool CanPartBeCovered(PartLocation location);
// Phase 2: GetSkiddingAttackerModifier, GetSkiddingTargetModifier
}
public interface IDamageRules
{
PartLocation GetHitLocation(int diceResult, HitDirection attackDirection);
int GetClusterHits(int diceResult, int weaponSize);
}
public interface IPilotingRules
{
int GetPilotingSkillRollModifier(PilotingSkillRollType psrType);
bool RequiresPilotingSkillRoll(PilotingSkillRollType rollType);
int GetHeavyDamageThreshold();
int GetWaterDepthModifier(int waterDepth);
int GetSkidModifier(int hexesMoved);
HexDirection GetFacingAfterFall(int roll, HexDirection currentFacing);
HitDirection GetAttackDirectionAfterFall(int roll);
// Phase 4: GetFallingLevelsModifier
}
public interface IHeatRules
{
int GetMovementHeatPoints(MovementType movementType, int movementPointSpent);
int GetHeatShutdownAvoidNumber(int heatLevel);
int GetHeatAmmoExplosionAvoidNumber(int heatLevel);
int GetExternalHeatCap();
int GetWaterHeatDissipationCap();
// Phase 4: GetHeatMovementPenalty, GetHeatAttackPenalty, GetLifeSupportPilotDamage
}
// Construction-only. Injected directly into MechFactory; NOT reachable from IRulesProvider.
public interface IUnitConstructionRules
{
Dictionary<PartLocation, int> GetStructureValues(int tonnage);
}There is no IMovementRules in Phase 1: on main no method belongs to it (movement heat is a heat rule). Terrain movement cost lives behind Map's IMovementCostProvider (§3.2). An empty interface is pure overhead; add one when a real movement rule appears.
Implementations — virtual methods per domain:
public class TotalWarfareHeatRules : IHeatRules
{
public virtual int GetHeatShutdownAvoidNumber(int heatLevel) => heatLevel switch { /* TW table */ };
// ...
}The end state: a methodless holder, no forwarding class.
// The rule set. Consumers take the domain interface they need; the rare
// multi-domain consumer calls ruleSet.Heat.GetX(). A record's properties
// expose state — they do not re-export behavior — so the holder adds no
// pass-through surface (Ousterhout's remedy: expose the lower-level object).
public sealed record RuleSet(IToHitRules ToHit, IDamageRules Damage, IPilotingRules Piloting, IHeatRules Heat);The Total Warfare rule set is new RuleSet(new TotalWarfareToHitRules(), new TotalWarfareDamageRules(), new TotalWarfarePilotingRules(), new TotalWarfareHeatRules()). BaseGame.RulesProvider is retyped to RuleSet in Phase 5; during the transition it remains IRulesProvider, backed by the composite below.
The transition: an aggregate interface and one forwarding class, both scheduled for demolition.
// Transitional aggregate: keeps existing IRulesProvider consumers and tests compiling.
// Keeps no members of its own. Retained after Phase 5 only as a test-substitution
// convenience; retired once tests migrate to domain substitutes.
public interface IRulesProvider : IToHitRules, IDamageRules, IPilotingRules, IHeatRules { }
// Transitional (deleted in Phase 5): the ONLY class that forwards.
public class CompositeRulesProvider(
IToHitRules toHit, IDamageRules damage, IPilotingRules piloting, IHeatRules heat) : IRulesProvider
{
public int GetProneFiringModifier() => toHit.GetProneFiringModifier();
// ... one line per method
}
// Transitional (deleted in Phase 5): keeps `new TotalWarfareRulesProvider()` compiling
// in tests while they migrate to `RuleSet` or domain substitutes.
public sealed class TotalWarfareRulesProvider()
: CompositeRulesProvider(new TotalWarfareToHitRules(), new TotalWarfareDamageRules(),
new TotalWarfarePilotingRules(), new TotalWarfareHeatRules());Why the transition works this way: 72 test files (127 occurrences) use Substitute.For<IRulesProvider>() or new TotalWarfareRulesProvider(). NSubstitute mocks the aggregate interface directly — no concrete implementation is ever needed for substitution — so the mock-based tests are untouched by the composite's deletion. Only tests constructing the concrete full set need the transitional TotalWarfareRulesProvider subclass, and they migrate mechanically. Because IRulesProvider is-a IToHitRules, consumers narrow their constructor parameter types (ToHitCalculator(IToHitRules)) while existing tests keep compiling. The answer to the §2.1 pass-through warning is therefore not a justification but a deletion plan: Phase 5 adds an exit criterion that no concrete type implements IRulesProvider by delegation.
DI registration: register each domain interface and IUnitConstructionRules individually (CoreServices.cs, BotContainerServices.cs), plus a RuleSet built from the same instances. During the transition, IRulesProvider → the transitional composite; that registration is removed in Phase 5.
// Override ONE heat rule — one class, one method.
public sealed class HarshHeatRules : TotalWarfareHeatRules
{
public override int GetHeatShutdownAvoidNumber(int heatLevel)
=> heatLevel >= 28 ? 13 : base.GetHeatShutdownAvoidNumber(heatLevel);
}
// Compose the rule set — no forwarding, no reimplementation of other domains.
var houseRules = new RuleSet(
ToHit: new TotalWarfareToHitRules(),
Damage: new TotalWarfareDamageRules(),
Piloting: new TotalWarfarePilotingRules(),
Heat: new HarshHeatRules());
var houseMovementCost = new HouseRuleMovementCostProvider(
new Dictionary<MakaMekTerrains, int> { [MakaMekTerrains.HeavyWoods] = 3 });The provider is a per-process DI singleton, registered separately in the desktop/mobile app and in the bot container. Movement costs are computed on the client and sent in PathSegmentData.Costs; the server derives MovementPointsSpent from MovementTaken.TotalCost and does not recompute path costs. If host, clients, and bot containers ran different rule sets, the mismatch would be accepted silently.
Requirement for this PRD (minimum): document the invariant "all peers and bot containers in a game run an identical rule set" beside IRulesProvider.
Future requirement (when the first non-TW rule set ships): a rule-set identifier is part of game setup, broadcast in the lobby, and validated on join. The identifier must encompass the full rule configuration: the four RuleSet domains (ToHit, Damage, Piloting, Heat) and the IMovementCostProvider configuration including any house-rule movement-cost overrides (e.g. houseMovementCost). Peer consistency and join validation must cover these movement-cost settings alongside the four RuleSet domains so that no peer can compute divergent path costs.
Decision: close both, implement the refactor directly.
- Both introduce the optional
IRulesProvider? = nullpattern (branching, silent no-op, latent NRE). - #1450 adds parameterless legacy wrappers (a third source of truth) and commits
BUG-INVENTORY.local.md. - Both thread the provider through
Mech/Unit/IUnitmethod signatures — the ripple §3.3 avoids.
Attack modifiers are resolved in ToHitCalculator (§3.3.1); heat-derived values become server-resolved state (§3.3.2).
Decision: close both, implement the hybrid directly.
- #1445's
IMovementCostProviderseam in Map is correct; itsIRulesProvider : IMovementCostProviderinheritance is not. ItsDefaultMovementCostProvidershould returnterrain.MovementCostinstead of re-listing terrains. - #1451's deletion of
Terrain.MovementCostremoves the entity default the hybrid relies on; its cache invalidation is unnecessary once the provider is fixed per map instance. - Both duplicate the cost table. In the target design the table exists once — on the terrain classes.
Decision: implement first. It is independent of the other work, behavior-neutral, and lets later phases depend on narrow interfaces.
Each phase is an independently mergeable PR with its own version bump.
- Create
IToHitRules,IDamageRules,IPilotingRules,IHeatRules,IUnitConstructionRulesinsrc/MakaMek.Core/Models/Game/Rules/with the method mapping from §3.4. - Create
TotalWarfareToHitRules,TotalWarfareDamageRules,TotalWarfarePilotingRules,TotalWarfareHeatRules,TotalWarfareUnitConstructionRuleswith virtual methods; move the bodies fromTotalWarfareRulesProvider. - Make
IRulesProviderthe aggregate of the four runtime domains; removeGetStructureValuesfrom it. Create theRuleSetrecord and the transitionalCompositeRulesProvider+TotalWarfareRulesProvidersubclass (§3.4), both marked for deletion in Phase 5. - Inject
IUnitConstructionRulesdirectly intoMechFactory. - Narrow mechanics-service constructors to the domain interface they use (
ToHitCalculator(IToHitRules),HeatEffectsCalculator(IHeatRules, …), etc.). - Update DI registration in
CoreServices.csandBotContainerServices.cs.
Exit criteria: all existing tests pass; no behavior change; MechFactory has no IRulesProvider dependency.
- Add
GetSkiddingAttackerModifier()/GetSkiddingTargetModifier()toIToHitRules. - Add
AttackerIsProne/AttackerIsSkiddingtoAttackScenario; populate inFromUnitsandFromHypothetical. -
ToHitCalculatoradds prone, skidding-attacker, and skidding-target modifiers from the rules (§3.3.1). - Remove prone/skidding emission from
Mech.GetAttackModifiers. - Delete the four
DefaultValueconsts (PartialCoverModifier.DefaultValueis already unused).
Exit criteria: GetProneFiringModifier has a caller; no DefaultValue consts on modifier records; bot hit-probability unchanged under TW rules; IUnit signatures unchanged.
- Keep
Terrain.MovementCostas the default additional cost. - Add
IMovementCostProviderandDefaultMovementCostProvider(returnsterrain.MovementCost) tosrc/MakaMek.Map/Models/. -
IBattleMapFactory/BattleMapFactoryreceive anIMovementCostProvidervia DI (defaultDefaultMovementCostProvider.Instance) and pass it toBattleMap, which passes it to hex cost evaluation. -
Hex.GetEnterMovementCostuses the provider in both the normal and road-to-road branches. - Decide terrain to-hit: apply the hybrid (
Terraindefault to-hit modifier) or document the_ => 0behavior. - Produce the rule-value inventory (below) and mark each row in-scope / deferred for Phase 4.
Exit criteria: standalone maps work unchanged; a custom provider injected via the factory changes pathfinding costs; unknown terrains fall back to the entity default; no Core type referenced from Map.
- Add
GetHeatMovementPenalty,GetHeatAttackPenalty,GetLifeSupportPilotDamagetoIHeatRules; addGetFallingLevelsModifiertoIPilotingRules. - Introduce
IHeatCalculator(depends onIHeatRules); moveGetHeatData/GetProjectedHeatValueoffIUnit(callers:HeatPhase,HeatProjectionViewModel,WeaponsEngine). - Extend
HeatDatawith resolvedMovementPenalty,AttackPenalty,LifeSupportDamage;HeatPhaseresolves them on the server. -
Unit.ApplyHeatstores the resolved penalties; remove the heat tables fromMech.MovementHeatPenalty/AttackHeatPenaltyand the thresholds fromMech.ApplyHeatEffects. - Ensure save/restore and unit-state reconstruction carry the resolved penalties.
Exit criteria: no heat thresholds remain in Mech; no IRulesProvider parameters on IUnit; GetMovementPoints and all ~13 MovementState call sites unchanged.
- Add the §3.1 "Data vs Rules vs State" note beside the rules interfaces.
- Document the
IMovementCostProvidercontract and theoverride ?? entityDefaultmodel. - Document the rule-set consistency invariant (§3.6).
- Add the §3.5 house-rule example to the docs.
- Delete the transitional
CompositeRulesProviderandTotalWarfareRulesProvider; retypeBaseGame.RulesProvidertoRuleSet; migrate the remaining concrete-full-set test usages toRuleSetor domain substitutes; remove theIRulesProviderDI registration.
Exit criteria: no concrete type implements IRulesProvider by delegation; BaseGame.RulesProvider is a RuleSet; IRulesProvider remains only as a memberless aggregate used by test substitutes.
| Value | Current location | Category | Target phase |
|---|---|---|---|
| Prone / skidding attacker / skidding target modifiers | modifier DefaultValue consts |
rule | Phase 2 |
| Terrain additional MP cost | Terrain.MovementCost |
rule (entity default) | Phase 3 |
| Terrain to-hit modifier |
GetTerrainToHitModifier table, _ => 0
|
rule | Phase 3 decision |
| Heat→movement / heat→attack penalty |
Mech.MovementHeatPenalty / AttackHeatPenalty
|
rule | Phase 4 |
| Life-support pilot damage (15 / 26) | Mech.ApplyHeatEffects |
rule | Phase 4 |
| Falling-levels modifier | piloting/fall code | rule | Phase 4 |
| Run MP multiplier (×1.5) | Mech.GetMovementPoints |
rule | deferred |
| Sensor-hit modifier | SensorHitModifier.Create |
rule | deferred |
| Arm/leg actuator, leg/hip-destroyed penalties |
Mech / penalty records |
rule | deferred |
| Stand-up cost | Mech.EffectiveStandupCost |
rule | deferred |
| # | Criterion | Verifies |
|---|---|---|
| 1 | A new terrain type (SwampTerrain) works with every existing IMovementCostProvider without modifying any provider |
Open-Closed |
| 2 | A house-rule set overrides a single rule (e.g. one heat threshold) with one subclass overriding one method, plus one RuleSet construction |
Composition / partial override |
| 3 |
MechFactory depends only on IUnitConstructionRules; GetStructureValues is not reachable from IRulesProvider
|
Interface Segregation |
| 4 | Each mechanics service depends only on the domain interface(s) it uses | Interface Segregation |
| 5 | No IUnit/Unit/Mech member takes IRulesProvider (or a domain interface) as a parameter — including the existing GetHeatData / GetProjectedHeatValue
|
Information Hiding |
| 6 |
IRulesProvider.GetProneFiringModifier is used by ToHitCalculator; no DefaultValue consts remain on modifier records |
Single source of truth (#1105) |
| 7 | No heat thresholds or heat tables remain in Mech
|
SRP |
| 8 | Terrain Height, InterveningFactor remain entity data; TW terrain MP costs exist only on terrain classes |
Data/Rules boundary, no duplication |
| 9 |
IMovementCostProvider and DefaultMovementCostProvider live in Map; Map references no Core type |
DIP |
| 10 | A custom IMovementCostProvider supplied via IBattleMapFactory affects pathfinding |
Testability (#1028) |
| 11 | Adding a new rules domain does not modify existing domain interfaces or their implementations | Interface Segregation |
| 12 | All existing tests pass after each phase | Regression |
| 13 | No concrete type implements IRulesProvider by delegation; the whole rule set is held by the methodless RuleSet record |
Deep Modules — no pass-through class |
| Risk | Mitigation |
|---|---|
| Phase 4 changes the heat command payload and unit-state restore | Isolated phase; HeatData already flows through HeatUpdatedCommand; add round-trip serialization and restore tests |
| Transitional forwarding composite becomes permanent | Scheduled for deletion in Phase 5 with an exit criterion; the end state holds the rule set in the methodless RuleSet record — no pass-through class survives |
Transitional IRulesProvider aggregate becomes permanent god interface |
Phase 1 narrows all mechanics-service constructors; AC 4 enforces it; the aggregate keeps no members of its own and has no concrete implementation after Phase 5 — what remains is a test-substitution convenience, retired once tests migrate to domain interfaces |
| Peers running different rule sets accept each other's values silently | §3.6 invariant documented now; rule-set ID handshake required before the first non-TW rule set ships |
Silent defaults for new content (_ => 0 style fallbacks) |
Prefer entity defaults authored with the entity (hybrid); Phase 3 decides terrain to-hit explicitly |
| Performance regression from indirection | One virtual call or dictionary lookup per value, in-memory, no I/O or reflection — negligible in a turn-based game |
Breaking external consumers of IRulesProvider
|
The aggregate keeps all runtime methods; only GetStructureValues moves (single caller: MechFactory) |
- Runtime rule switching (hot-swapping providers mid-game). The movement-cost provider is fixed per map instance; no cache invalidation is built.
- Rule-set selection UI / lobby negotiation. Only the invariant is documented (§3.6).
- GameOptions-style rule-option system (hundreds of toggleable options). House rules are code-level compositions.
- Era/tech-level/faction rules.
- Mod support / scripting.
- Alpha Strike / BattleForce rules.
- Deferred inventory rows (§5) — run multiplier, sensor/actuator penalties, stand-up cost.
| Decision | Justified by |
|---|---|
| Entities are POCOs carrying defaults; services resolve rules | Information Hiding, Deep Modules |
override ?? entityDefault for terrain cost; TW table lives only on terrain classes |
Open-Closed, single source of truth |
IMovementCostProvider + default (identity) provider in Map, injected via IBattleMapFactory
|
DIP (Map has no Core reference) |
| No path-cache invalidation — provider fixed per map | YAGNI, consistent with non-goals |
Rules split into four runtime domains + construction; no empty IMovementRules
|
Interface Segregation, derived from actual consumers |
Composition across domains (methodless RuleSet record), virtual inheritance within a domain |
Composition over Inheritance, minimal house-rule code; no pass-through class (Ousterhout) |
IRulesProvider aggregate and forwarding composite kept as migration aids only; composite deleted in Phase 5 |
Test compatibility (72 files) while narrowing consumers; the pass-through warning is answered with a deletion plan, not a justification |
IUnitConstructionRules injected directly into MechFactory
|
Interface Segregation (construction-only concern) |
Attack modifiers resolved in ToHitCalculator
|
Existing precedent (skidding-target, partial cover) |
Heat-derived values resolved server-side in HeatPhase, stored as unit state |
Server-authoritative architecture; avoids unit-API ripple |
GetHeatData / GetProjectedHeatValue move to a heat service |
Removes existing provider-as-parameter on IUnit
|
| All peers run an identical rule set (documented invariant) | Client-computed costs are not re-validated by the server |
| Close all four PRs; implement the refactor directly | The PRs' plumbing is incompatible with the target architecture |
Document Version: 1.3 — replaced the permanent CompositeRulesProvider forwarding class with the methodless RuleSet record as the end state (Ousterhout pass-through warning); the composite and TotalWarfareRulesProvider are now transitional and deleted in Phase 5, with BaseGame.RulesProvider retyped to RuleSet. v1.2: removed the external rules-engine comparison (former §4) and related references; renumbered sections 4–9. v1.1: corrected terrain cost semantics and prone value; replaced the duplicating movement-cost adapter with an identity default in Map; removed cache invalidation; split Phase 3 into attack (service) and heat (server-resolved state) strategies; added GetHeatData migration, concrete domain mapping, composite + virtual-domain house-rule model, rule-set consistency invariant, and rule-value inventory; corrected quote attribution.
Author: AI-assisted architecture analysis
Reviewers: TBD