Repository navigation
Movement Phase Interrupt Pattern
How the Movement phase evaluates terrain/movement hazards (bridge collapse, skid, water entry, jump-landing damage) without hard-coding each one into the phase. The pattern keeps MovementPhase thin and orchestration-only, while each hazard lives in its own self-contained handler.
A unit moving along a path can trigger hazards mid-move: it may skid off pavement on a sharp turn, plunge through a collapsing bridge, fall entering deep water, or take a piloting roll when landing from a jump. Each hazard has its own trigger condition, its own roll, and its own consequence (truncate the path, broadcast a fall, defer the next step, etc.).
Encoding all of that inline in ProcessMoveCommand would produce one large, branchy method that is hard to test and hard to extend. The interrupt pattern decomposes it into three roles:
- The phase orchestrates: it walks the path, asks each handler about each segment, and applies whatever the handler returns.
- Interrupt handlers decide: each one inspects a segment (or the landing hex) and decides whether its hazard fires, producing a result describing what should happen.
-
Game actions execute: small command objects that mutate game state (
game.OnX(...)) and return the commands to publish.
This is a Chain-of-Responsibility (handlers) feeding a Command pattern (actions), with the phase as the mediator.
MovementPhase ──walks path / landing──► IMovementInterruptHandler.Check(context)
│
▼
MovementInterruptResult? (null = no fire)
│
▼
MovementPhase.ProcessInterruptResult(...)
│
▼
IGameAction.Process(game) ──► IReadOnlyList<IGameCommand>
│
▼
Game.CommandPublisher.PublishCommand(...)
public interface IMovementInterruptHandler
{
MovementInterruptResult? Check(MovementInterruptContext context);
}A handler evaluates one segment for one hazard type and returns null when its hazard does not apply. Handlers are pure decision logic: they read the game/map, run the relevant piloting-skill roll through Game.FallProcessor, and package the outcome as actions. They never publish commands or mutate state directly — that is deferred to the actions they emit.
An immutable bundle passed to every handler:
| Field | Meaning |
|---|---|
MoveCommand |
The full original MoveUnitCommand
|
SegmentIndex |
Index of the segment being evaluated |
Unit |
The moving unit (may or may not be a Mech) |
Game |
The ServerGame (map lookups, FallProcessor, players) |
IsLandingCheck |
true when evaluating a post-jump landing rather than a per-segment walk/run interrupt |
IsLandingCheck lets a single handler serve both phases of evaluation (e.g. BridgeCollapseInterruptHandler and WaterEntryInterruptHandler behave differently for landing vs. walk-through).
public bool ShouldStop { get; init; } // stop the whole move; no further segments/handlers
public bool DeferStepConsumption { get; init; } // only meaningful when ShouldStop
public IReadOnlyList<IGameAction> GameActions { get; init; }-
ShouldStop = false→ the handler produced side effects (typically a PSR command) but movement continues to the next segment/handler. Used when a roll succeeds and the unit keeps going. -
ShouldStop = true→ the move is interrupted; the phase applies the actions and stops checking. -
DeferStepConsumption→ tells the phase to hold the unit's turn open (the unit fell and may stand up next). See Step deferral below.
public interface IGameAction
{
IReadOnlyList<IGameCommand> Process(ServerGame game);
}Each action performs a unit of state mutation against ServerGame and returns the commands the phase should publish. Keeping OnX mutation and command production together (and out of the handlers) means the phase can collect all commands and publish them in a single, ordered pass.
Concrete actions:
| Action | Mutation | Publishes |
|---|---|---|
MoveUnitAction(command, publish) |
game.OnMoveUnit(command) |
the command iff publish
|
BridgeCollapsedAction(command, publish) |
game.OnBridgeCollapsed(command) |
the command iff publish
|
ApplyFallAction(mech, fallCommand) |
game.OnMechFalling + crit hits + consciousness rolls |
fall command + derived commands |
FallBroadcastAction(mech, truncatedCommand) |
builds the post-fall broadcast, completing the move if the mech can't stand up | broadcast command |
PublishCommandAction(command) |
none | the command (pure broadcast) |
The publish flag matters for ordering: a handler can mutate state silently first (publish: false), interleave another action, then emit the publishable command later (publish: true). BridgeCollapseInterruptHandler uses exactly this to land the unit, collapse the bridge, then re-broadcast the completed move.
ProcessMoveCommand runs two distinct evaluation modes:
For non-jump moves, the phase iterates every segment and, for each, runs the segment handler chain in order:
private readonly IReadOnlyList<IMovementInterruptHandler> _segmentInterruptHandlers =
[
new BridgeCollapseInterruptHandler(),
new SkidInterruptHandler(),
new WaterEntryInterruptHandler(),
new RubbleEntryInterruptHandler()
];The first handler returning a ShouldStop result ends the move. Handlers returning null are skipped; handlers returning a non-stopping result (e.g. a successful PSR) emit their commands and the loop continues.
For jumps, the phase first completes the move normally (OnMoveUnit + broadcast IsCompleted = true), then evaluates the landing hex against the landing handler chain:
private readonly IReadOnlyList<IMovementInterruptHandler> _landingInterruptHandlers =
[
new BridgeCollapseInterruptHandler(),
new JumpDamageInterruptHandler(),
new WaterEntryInterruptHandler(),
new RubbleEntryInterruptHandler()
];These run with IsLandingCheck = true and SegmentIndex pointing at the final segment.
Note the two chains share handlers but differ in membership and order: skid only applies to running, jump-landing damage only applies to landing. A handler that does not apply to its mode simply guards and returns null (e.g. SkidInterruptHandler requires MovementType.Run; JumpDamageInterruptHandler requires Jump + IsLandingCheck).
FallProcessor.ProcessMovementAttempt accepts a trailing optional fallPosition (HexPosition?). Movement interrupts calculate the fall before the unit moves, so at that point mech.Position still points at the previous hex — handlers must pass the hex where the unit will actually land so the fall processor can resolve water depth there:
| Handler | fallPosition |
|---|---|
WaterEntryInterruptHandler / RubbleEntryInterruptHandler
|
segment.To (the hex being entered) |
BridgeCollapseInterruptHandler |
bridgeCoords with HexSurface.Ground (post-collapse landing) |
SkidInterruptHandler |
segment.From for the initial skid fall, the final skid segment's To for the cliff fall |
JumpDamageInterruptHandler |
omitted — movement is already applied, the current position is correct |
FallProcessor resolves the landing water depth from that position (only on a Ground surface) and delegates the water damage reduction to the rules provider (IRulesProvider.CalculateFallingDamageInWater). A fall that ends in a water hex drops the unit to the hex bottom, so LevelsFallen equals the water depth for every water-entry fall — walk, run and jump alike — and the resulting damage is halved per the TW two-stage rule (see TotalWarfareRulesProvider).
private bool ProcessInterruptResult(MovementInterruptResult result, IUnit unit)
{
var commands = new List<IGameCommand>();
bool? deferAfterFall = null;
foreach (var action in result.GameActions)
{
commands.AddRange(action.Process(Game));
if (unit is Mech fallingMech && action is ApplyFallAction)
deferAfterFall = fallingMech.CanStandup();
}
foreach (var cmd in commands)
Game.CommandPublisher.PublishCommand(cmd);
if (!result.ShouldStop) return false;
_requestDeferStepConsumption = deferAfterFall ?? result.DeferStepConsumption;
return true;
}Actions are processed in order, their commands accumulated, then published as a batch. The return value tells the segment loop whether to stop.
When a mech falls mid-move it may be able to stand up and continue, so its turn must stay open. The phase coordinates this across two flags and an override of MainGamePhase.ShouldFinalizeUnitsTurn:
-
_requestDeferStepConsumption— set inProcessInterruptResultwhen a stopping interrupt fired. It is computed fromMech.CanStandup()after the fall (queried live, becauseApplyFallActionhas already applied damage that may change the answer), falling back to the result's declaredDeferStepConsumption. -
_deferredMovementUnitId— the unit whose turn is held open.
ShouldFinalizeUnitsTurn consumes the request: on a deferred MoveUnitCommand it records the unit id and returns false (do not advance the per-step counter); the follow-up command for that same unit clears the deferral and lets the turn finalize.
While a unit is deferred, HandleCommand rejects MoveUnitCommand/TryStandupCommand for other units, ensuring the interrupted unit resolves first. Both flags are reset on Enter/Exit via ClearMovementDeferralState.
- Unit walks onto a bridge hex whose construction factor is exceeded by the combined tonnage.
-
BridgeCollapseInterruptHandler.Check(walk branch) detects overweight, truncates the path at the bridge segment, tags it withBridgeCollapse+Fallevents, and builds an action list:-
MoveUnitAction(truncatedCommand, publish: false)— silently place the unit on the bridge hex. -
BridgeCollapsedAction(bridgeCmd, publish: true)— collapse the bridge, broadcast it. -
MoveUnitAction(truncatedCommand with { IsCompleted = true }, publish: true)— re-broadcast the completed move. - one
ApplyFallActionper mech on the hex (each rolled throughFallProcessor). - the
DisplaceUnitActions of the sharedDominoEffectResolver(far-to-near), when other units occupy the hex or the chain reaches them. - a final
DominoEffectRollActionwith the dislodged Mechs, so their mandatory domino PSRs resolve immediately (Mechs that already fell are prone and skipped).
-
- The handler returns
ShouldStop = true. -
ProcessInterruptResultruns the actions in order, publishes all commands, and — because anApplyFallActionran — sets_requestDeferStepConsumptionfrom the triggering mech's post-fallCanStandup(). - The segment loop returns; the unit's turn is held open if it can stand.
Because handlers are pure (Check(context) → result?) they are unit-tested in isolation, with no phase or publisher involved. BridgeCollapseInterruptHandlerTests constructs a MovementInterruptContext directly, stubs MockFallProcessor.ProcessMovementAttempt(...), and asserts on the returned MovementInterruptResult — e.g. ShouldStop is true and GameActions contains a BridgeCollapsedAction and an ApplyFallAction. Actions and the phase orchestration are tested separately, so each layer's responsibility is verified independently.
- Implement
IMovementInterruptHandler. Guard early and returnnullwhen the hazard does not apply (wrong movement type, wrong segment, not aMech,IsLandingCheckmismatch, etc.). - Run any roll through
context.Game.FallProcessor.ProcessMovementAttempt(...)with the appropriate*RollContext, passing the hex where the unit will land asfallPosition(see Landing position above). - Return a
MovementInterruptResult:ShouldStop = falsefor a passed roll that only needs a PSR broadcast,trueto interrupt the move. - Build the consequence from existing
IGameActions; add a new action only if no current one fits, keeping mutation + publish-list together in the action. - Register the handler in
_segmentInterruptHandlersand/or_landingInterruptHandlersat the correct position in the chain.