Repository navigation
jump movement
This document records the jump rules implemented in MakaMek and the decisions taken where Total Warfare constrains the outcome but not the intermediate geometry.
- A jumping unit follows a shortest route to its destination (fewest hexes).
- Each crossed hex costs 1 Jumping MP, regardless of terrain, elevation or facing.
- A unit with at least 1 Jumping MP may jump down any number of levels.
- The legal route must satisfy the jump-height ceiling below.
If this path crosses a level higher than the sum of the unit's Jumping MP plus the level of the hex in which the jump started, then the unit cannot make the jump.
— Total Warfare p. 53, Jumping
Implementation: BattleMap.FindJumpPath and BattleMap.GetJumpReachableHexes share the rule
referenceLevel(hex) <= startLevel + availableJumpingMP
availableJumpingMP is the requested movement budget, not the path cost. startLevel is the
unit's standing level in the start hex, not the raw hex level:
| Start surface | Start level |
|---|---|
| Plain ground | Hex.Level |
| Bridge deck | Hex.Level + bridge height |
| Water (ground surface) | the riverbed, Hex.Level - water depth
|
The start hex itself is not checked. The destination is part of the crossed path and is checked.
When several shortest routes exist, the player may choose one. MakaMek does not expose that choice for ordinary jumps: pathfinding returns the first legal shortest route it finds and stops. This is deterministic for a given map and movement budget, and it avoids enumerating every equally short route (a distance-8 jump can have dozens).
For UI reachability, GetJumpReachableHexes runs one breadth-first search through hexes that clear
the ceiling and includes a destination only when its legal search distance equals its geometric
distance. A longer detour around a too-high hex therefore does not make the destination reachable.
| Hex | Level to clear |
|---|---|
| Plain terrain | Hex.Level |
| Light or heavy woods |
Hex.Level — tree height is ignored
|
| Water | the water surface (Hex.Level), never the bottom |
| Bridge | the bridge deck (Hex.Level + bridge height) when it is the top surface |
| Building | roof level — deferred until building terrain exists |
The helper is HexExtensions.GetReferenceLevel(). Building roof levels join this helper with the
building-terrain change.
A unit standing on a bridge starts from the bridge deck (Hex.Level + bridge height). A unit
in water starts from the riverbed (Hex.Level - water depth), not the water surface. This is
the same standing-level rule used elsewhere in movement and LOS (Hex.GetStandingLevel).
Crossing clearance is unchanged: when a jump passes over a water hex, the level it must clear is still the water surface, not the bottom.
HexPosition.AirborneLevel is the unit's base level, not its LOS top. It is null for a
grounded position.
For a jump path p0 … pn:
-
pnis grounded (null).p0is grounded too, except for an adjacent jump, whose start position carries the approach waypoint. -
The last translation's
From(p(n-1), the approach position) is always a hard waypoint:AirborneLevel(approach) = max(referenceLevel(approach), referenceLevel(destination)) + dfaAirborneBaseOffsetdfaAirborneBaseOffsetis supplied by the rules layer (IRulesProvider.GetDfaAirborneBaseOffset(), currently 2); the map itself defaults to 0 and knows nothing about DFA. The extra two levels are the DFA attacker's mid-air base (its feet are two levels above the higher hex); line of sight then adds the unit height. The value is calculated for every jump, not only a DFA. A normal jump ends grounded, so for it this base only appears in the internal profile; an adjacent jump has no intermediate position, so its start position carries the waypoint instead. -
Other intermediate levels interpolate linearly from the start level (the unit's standing level in
p0) to the approach waypoint, round up (Math.Ceiling), and are clamped to[referenceLevel(p_i), startLevel + availableJumpingMP]. -
Path validity is checked against the hex reference levels, never against the
+2airborne base: a route whose destination/approach reference level exceeds the ceiling is rejected (defensive guard). The exception is an adjacent jump: it has no crossed hex before the destination, so only the destination must clearstartLevel + availableJumpingMP. A bridge deck above the unit, or the water surface it stands below, therefore does not block a legal adjacent jump.
The same profile is used for path validity and DFA line of sight. Presentation does not derive a second jump curve.
DFA declares the target hex as the jump destination and uses the same shortest-route and jump-height
rules. It has an additional clearance requirement, implemented in
MovementAttackValidator: the attacker needs enough Jumping MP to clear the target hex
level plus the target's height (a standing 'Mech is height 2), even though reaching the target hex
costs the usual 1 MP per hex.
During the Weapon Attack Phase the DFA attacker waits in the approach hex
(MovementPathExtensions.GetStopPosition). Its LOS position is the stored profile value:
airborne base = max(referenceLevel(target), referenceLevel(approach)) + 2
effective LOS level = Position.AirborneLevel + unit.Height
Position.AirborneLevel already equals max(...) + 2, so the LOS level is max(...) + 4 for a
standing 'Mech, independent of which unit is shooting: the +2 is the attacker's mid-air base
(feet) and the LOS calculation adds the standing height on top. LOS consumers pass
Position.AirborneLevel through the optional base-level parameters of IBattleMap.GetLineOfSight;
they must not derive a second DFA level. The full rules decision, including the official errata
clarification, the prone attacker and reference levels, is in
physical-attacks.md.
BaseGame.OnMoveUnit re-derives the approach AirborneLevel from the map for every completed
DFA, on both the server and the clients, so a missing (legacy) or forged submitted waypoint does
not reach Unit.Position. Only the stop position's airborne level is replaced; the submitted
segments, MovementTaken, MP and HexesTraveled are unchanged.
The airborne value is cleared when the pending movement attack ends: on ResetTurnState and when
the attacker is destroyed. The DFA stop position itself is unchanged (issue #1681).
MakaMek renders a top-down 2D board, so the stored altitude is not drawn as a vertical sprite offset. The profile exists for path validity and LOS; movement playback stays planar.
-
HexPositionDatacarries an optionalint? AirborneLevel; older payloads without it deserialize tonull. - The value is derived from the path and map. It is not part of
MoveUnitCommand.GetPayloadHash. - Jump paths are cached by endpoints, jump movement type, max level change, unit height and the jump MP budget, because the budget changes the ceiling and therefore the selected route.
- Building terrain and roof levels.
- Non-jump airborne units (VTOL, WiGE, aerospace).
- Full server-side re-validation of submitted jump routes (the DFA approach level is derived, not trusted, but a forged route is otherwise accepted).
- DFA physical attack resolution (tracked separately).
- The target-jump +1 to-hit modifier, the approach-hex choice and facing toward the target; see
the follow-ups in
physical-attacks.md.