Repository navigation
roads pavement bridges prd
Date: 2026-05-30
Status: Ready for Implementation
This document specifies the requirements for implementing road, pavement, and bridge terrain mechanics in MakaMek. Roads and paved areas allow units to ignore underlying terrain movement penalties while introducing a skidding hazard at Running speed. Bridges extend road mechanics over lower terrain or water and introduce weight-based collapse. The implementation extends the existing terrain, movement-phase, PSR, and to-hit modifier subsystems without altering their fundamental contracts.
The rules below are the authoritative source for this feature. Implementation must satisfy all of them except those explicitly marked Out of Scope.
- Pavement — large paved surfaces (landing fields, urban blocks, sidewalks).
- Road — narrow paved strip passing through other terrain types.
- LOS & height — roads and pavement sit at the printed level of the hex; they do not add height or block LOS.
- Movement cost — entering a paved/road hex costs +0 MP (total 1 MP when no elevation change).
- "On road" status — a unit is "on" a road only when it moves from a road/paved hex to another road/paved hex.
- Underlying terrain ignored — while on the road, the unit ignores the movement penalties and restrictions of the underlying terrain (e.g., heavy woods under a road still costs 1 MP).
- Prohibited terrain — a unit may traverse normally-prohibited terrain (e.g., deep water via bridge) while staying on the road.
- Elevation changes — units still pay normal MP for level changes even when following a road.
- Backward movement — units moving backward cannot change levels; this applies on roads and bridges.
- Trigger — a 'Mech using Running movement makes a facing change in a paved or road hex and then enters a new hex.
- Piloting Skill Roll (PSR) — the pilot must pass a PSR or the 'Mech skids.
- Skid distance — if the PSR fails, the 'Mech falls and slides a number of hexes equal to ⌈hexes moved ÷ 2⌉ (rounded up).
- Skid damage — the skidding 'Mech takes half normal falling damage per hex traveled during the skid.
- To-hit vs. skidding unit — +2 to-hit modifier against the skidding 'Mech.
- Skidding unit's own attacks — +1 to-hit penalty on attacks made by the skidding unit.
- Definition — a road is treated as a bridge when it passes over water or terrain at a lower elevation.
- On top of bridge — a unit moving road-to-road is on the bridge surface. It ignores the underlying terrain and follows all road rules.
- Construction Factor (CF) — each bridge hex has a CF representing the maximum tonnage it can support. When the total tonnage of units on a bridge hex exceeds its current CF, the bridge hex collapses; units fall to the underlying terrain and take standard falling damage.
-
Below bridge — a unit not traveling on the road is on the underlying terrain, positioned underneath the bridge. The existing z-layer rendering system in
HexControlsupports this without new infrastructure. -
Clearance — the usable vertical space below the bridge surface equals
BridgeTerrain.Height − lowestTerrainHeight, wherelowestTerrainHeightis theHeightof the deepest terrain in the hex (e.g., water depth −1). If this clearance is less than the unit's height, the bridge acts as a building hex; the unit cannot pass underneath.
| # | Capability |
|---|---|
| 1 | Road and Pavement terrain types with movement cost 1 (no underlying terrain penalty when on-road) |
| 2 | Bridge terrain type with configurable Construction Factor (CF) |
| 3 | "On road" status detection (source and destination both road/paved) |
| 4 | Skid PSR trigger on Running + facing change on paved/road hex |
| 5 | Skid outcome: fall + slide, damage per skid hex, attacker/target to-hit modifiers |
| 6 | Bridge CF check on unit entry; collapse → units fall to underlying terrain |
| 7 | Serialization via TerrainData record (schema extended with ConstructionFactor field) |
| 8 | Network propagation via existing SegmentEvent mechanism |
| 9 | Under-bridge unit positioning using the existing z-layer rendering system |
| 10 | Bridge clearance calculation and bridge-as-building-hex enforcement for insufficient clearance |
- Ground vehicle +1 MP pavement bonus (no vehicle unit type yet)
- VTOL/WiGE road-following through woods below treetop elevation
- Aerospace unit landing modifier on paved hexes
File: src/MakaMek.Map/Models/Terrains/MakaMekTerrains.cs
Road, // Narrow paved strip through other terrain
Pavement, // Broad paved surface
Bridge, // Paved road over lower terrain or water; Height = bridge height, ConstructionFactor = max tonnageAll three live alongside the existing terrain classes in src/MakaMek.Map/Models/Terrains/.
| Property | Value |
|---|---|
Id |
MakaMekTerrains.Road |
Height |
0 |
InterveningFactor |
0 |
MovementCost |
1 |
| Property | Value |
|---|---|
Id |
MakaMekTerrains.Pavement |
Height |
0 |
InterveningFactor |
0 |
MovementCost |
1 |
| Property | Notes |
|---|---|
Id |
MakaMekTerrains.Bridge |
Height |
Physical height of the bridge surface above the base hex level (positive integer, e.g., Height = 1 → bridge sits 1 level above the hex floor). Used to compute under-bridge clearance. |
InterveningFactor |
0 |
MovementCost |
1 |
ConstructionFactor |
Independent integer property representing maximum supported tonnage (e.g., 60 → CF 60 tons). Every structure terrain carries a CF. Stored in TerrainData.ConstructionFactor. |
BridgeTerrain is serialized via TerrainData with Type = Bridge, Height = bridge height, and ConstructionFactor = CF. This requires adding a ConstructionFactor field to TerrainData (see Serialization section).
Clearance is the usable vertical space below the bridge surface within the hex:
clearance = BridgeTerrain.Height − min(terrain.Height for all non-bridge terrains in hex)
Example: hex level 0, water (Height = −1), bridge (Height = 1)
→ clearance = 1 − (−1) = 2 levels
A unit can move underneath when its own height ≤ clearance. When clearance is insufficient, the bridge hex is treated as a building hex for the under-bridge movement attempt — the unit cannot enter from below.
File: src/MakaMek.Map/Models/Terrains/Terrain.cs — FromData() and GetTerrainType() factory methods get new case entries for Road, Pavement, and Bridge.
A new extension method on Hex (file: src/MakaMek.Map/Models/HexExtensions.cs):
public bool IsRoadOrPaved(Hex hex)
=> hex.HasTerrain(MakaMekTerrains.Road)
|| hex.HasTerrain(MakaMekTerrains.Pavement)
|| hex.HasTerrain(MakaMekTerrains.Bridge);A unit is on the road for a given movement step when both the source hex and the destination hex satisfy IsRoadOrPaved().
File: src/MakaMek.Map/Models/BattleMap.cs — segment cost calculation
When the unit is on the road (both hexes paved), the hex entry cost is 1 MP (road surface cost) regardless of the underlying terrain's MovementCost. Elevation change costs are still added on top.
segmentCost = (isOnRoad ? 1 : destinationHex.MovementCost) + Math.Abs(elevationChange)
This change is localized to the segment cost calculation in ConvertPathToSegments() (or equivalent method). The Hex.MovementCost property itself is not changed.
The existing rule that backward movement cannot change levels remains unchanged and applies on roads and bridges. No new code is required.
File: src/MakaMek.Core/Data/Game/Mechanics/PilotingSkillRollType.cs
SkidCheck, // Running + facing change on paved/road hexFile: src/MakaMek.Map/Models/SegmentEventType.cs
Skid, // Mech skids after failed SkidCheck PSR
BridgeCollapse, // Bridge hex collapses under weightFile: src/MakaMek.Core/Data/Game/Mechanics/PilotingSkillRollContexts/SkidCheckRollContext.cs
public record SkidCheckRollContext(int HexesMoved)
: PilotingSkillRollContext(PilotingSkillRollType.SkidCheck);HexesMoved is used to compute the skid distance (⌈HexesMoved ÷ 2⌉) if the roll fails.
File: src/MakaMek.Core/Models/Game/Phases/MovementPhase.cs
After the movement path is built, the movement phase checks each segment pair for the skid trigger. The pattern mirrors the existing water-entry detection:
- Movement type is
Run. - The source hex of the current segment
IsRoadOrPaved(). - The previous step included a facing change (turn segment in the same hex, or the
TurnsTakencounter advanced). - The current step enters a new hex.
On trigger:
- Create
SkidCheckRollContext(hexesMoved). - Evaluate PSR via
FallProcessor/PilotingSkillCalculator(existing infrastructure). - On failure: emit
SegmentEvent(SegmentEventType.Skid, skidDistance)whereskidDistance = ⌈hexesMoved ÷ 2⌉. - The fall processor handles the fall and skid slide, applying half normal falling damage per skid hex.
Skid damage is calculated as half the standard falling damage for each hex traveled during the skid. The existing FallingDamageCalculator is extended or wrapped to support a half-damage mode for skid hexes.
Two new RollModifier subclasses in src/MakaMek.Core/Models/Game/Mechanics/Modifiers/Attack/:
Applied to attacks against a unit that is currently in a skid state.
| Property | Value |
|---|---|
| Modifier value | +2 |
| Condition | Target unit has UnitStatus skidding flag (or equivalent transient state) |
Applied to attacks by a unit that is currently in a skid state.
| Property | Value |
|---|---|
| Modifier value | +1 |
| Condition | Attacker unit has skidding flag |
Both modifiers follow the same pattern as existing AttackerMovementModifier / TargetMovementModifier and are collected in ToHitCalculator.
File: src/MakaMek.Core/Models/Game/Phases/MovementPhase.cs
When a unit steps onto a hex containing BridgeTerrain:
- Sum the
Tonnageof all units currently occupying that hex (including the entering unit). - Compare to
BridgeTerrain.ConstructionFactor. - If total tonnage > CF:
- Emit
SegmentEvent(SegmentEventType.BridgeCollapse, 0)into the path. - Remove
BridgeTerrainfrom the hex (bridge is destroyed). - All units on the hex fall to the underlying terrain; apply standard falling damage via
FallProcessor.
- Emit
Unit.Tonnage is already defined on the Unit base class.
BridgeCollapse is a SegmentEventType and propagates as a SegmentEvent within PathSegmentData.Events, consistent with the existing Fall event. No new command types are required.
TerrainData gains a new ConstructionFactor field to support structures (bridges and future building types):
public record TerrainData
{
public required MakaMekTerrains Type { get; init; }
public int? Height { get; init; }
public int? ConstructionFactor { get; init; } // CF for structures; null for non-structural terrains
}Mapping:
| Terrain | Type |
Height |
ConstructionFactor |
|---|---|---|---|
| Road | Road |
null |
null |
| Pavement | Pavement |
null |
null |
| Bridge | Bridge |
bridge height above hex base (e.g., 1) |
CF in tons (e.g., 60) |
The MMTX terrain format document (docs/architecture/MMTX-Terrain-Format.md) must be updated to list the three new terrain types, the bridge Height / ConstructionFactor encoding, and the new terrains/road/ bitmask directory.
Roads, pavement, and bridges are rendered as texture overlays above all other terrain overlays (woods, rough, etc.) but below the hex polygon outline. The full z-index stack for HexControl is:
| Z-index | Layer |
|---|---|
| 0 | Base terrain |
| 10–17 | Edge effects |
| 18 | Water bitmask layer |
| 20+ | Terrain overlays (woods, rough, …) |
| 25 | Road / pavement / bridge overlay ← new |
| 30 | Hex polygon outline |
| 31 | Labels |
This ensures that a hex containing woods and a road renders correctly: base → woods → road.
Roads and bridges use the same 6-bit neighbor bitmask mechanism as water (TerrainBitmaskService). The canonical bitmask encodes which of the 6 neighboring hexes also contain a road or bridge terrain, enabling seamless road-network rendering (T-junctions, curves, straights, etc.).
Roads and bridges share one texture set — they are visually the same surface.
A new bitmask directory is added to the MMTX structure:
terrains/road/ # Road / bridge bitmask textures
000001.png # Road connects to neighbor in direction 0 only
000011.png # Road connects to neighbors in directions 0 and 1
… # All 13 canonical 6-bit patterns
Files are named using the 6-bit binary representation of CanonicalBitmaskResult.CanonicalMask (same convention as terrains/water/). Rotation is applied at render time using CanonicalBitmaskResult.RotationSteps.
File: src/MakaMek.Assets/Models/Terrains/TerrainAssetType.cs
/// <summary>
/// Road/bridge bitmask texture (from terrains/road/ folder).
/// Files are named using the 6-bit binary representation of the canonical bitmask, e.g. 000001.png.
/// </summary>
RoadFile: src/MakaMek.Assets/Services/ITerrainAssetService.cs
/// <summary>
/// Gets a road/bridge bitmask texture image for the specified canonical bitmask.
/// Files are stored in the <c>terrains/road/</c> folder.
/// </summary>
Task<byte[]?> GetRoadTextureImage(string biomeId, CanonicalBitmaskResult canonicalBitmask);TerrainCachingService implements this by extracting images from terrains/road/ (same logic as GetWaterTextureImage / terrains/water/).
File: src/MakaMek.Avalonia/MakaMek.Avalonia.Controls/HexControl.cs
-
Add z-index constant:
private const int ZIndexRoadLayer = 25;
-
On construction, compute a road/bridge bitmask (analogous to
_waterBitmask) when the hex containsRoad,Pavement, orBridgeterrain:private readonly CanonicalBitmaskResult? _roadBitmask; // Computed as: bitmaskService.ComputeCanonicalBitmask(map, hex.Coordinates, MakaMekTerrains.Road) // (Road and Bridge neighbors both count toward road connectivity)
-
Add
UpdateRoadLayer()that loads the bitmask texture and renders it atZIndexRoadLayerwith appropriate rotation — mirroringUpdateWaterLayer().
Units positioned under a bridge occupy the hex at the base terrain level. The existing z-index layer system in HexControl already renders multiple visual layers within a single hex; no additional rendering infrastructure is needed. Under-bridge units are drawn at the base terrain z-level, while the bridge overlay sits above them at ZIndexRoadLayer.
| File | Change |
|---|---|
src/MakaMek.Map/Models/Terrains/MakaMekTerrains.cs |
Add Road, Pavement, Bridge values |
src/MakaMek.Map/Models/Terrains/Terrain.cs |
Add case entries in FromData() / GetTerrainType()
|
src/MakaMek.Map/Data/TerrainData.cs |
Add ConstructionFactor field |
src/MakaMek.Core/Data/Game/Mechanics/PilotingSkillRollType.cs |
Add SkidCheck
|
src/MakaMek.Map/Models/SegmentEventType.cs |
Add Skid, BridgeCollapse
|
src/MakaMek.Map/Models/BattleMap.cs |
On-road cost substitution; under-bridge clearance check |
src/MakaMek.Core/Models/Game/Phases/MovementPhase.cs |
Skid trigger detection; bridge CF check |
src/MakaMek.Assets/Models/Terrains/TerrainAssetType.cs |
Add Road asset type |
src/MakaMek.Assets/Services/ITerrainAssetService.cs |
Add GetRoadTextureImage method |
src/MakaMek.Assets/Services/TerrainCachingService.cs |
Implement GetRoadTextureImage; extract terrains/road/
|
src/MakaMek.Avalonia/MakaMek.Avalonia.Controls/HexControl.cs |
Add ZIndexRoadLayer; compute road bitmask; add UpdateRoadLayer()
|
docs/architecture/MMTX-Terrain-Format.md |
Document new terrain types, CF encoding, and terrains/road/ directory |
| File | Purpose |
|---|---|
src/MakaMek.Map/Models/Terrains/RoadTerrain.cs |
Road terrain implementation |
src/MakaMek.Map/Models/Terrains/PavementTerrain.cs |
Pavement terrain implementation |
src/MakaMek.Map/Models/Terrains/BridgeTerrain.cs |
Bridge terrain with Height and ConstructionFactor
|
src/MakaMek.Core/Data/Game/Mechanics/PilotingSkillRollContexts/SkidCheckRollContext.cs |
Skid PSR context record |
src/MakaMek.Core/Models/Game/Mechanics/Modifiers/Attack/SkiddingTargetModifier.cs |
+2 to-hit against skidding unit |
src/MakaMek.Core/Models/Game/Mechanics/Modifiers/Attack/SkiddingAttackerModifier.cs |
+1 to-hit penalty for skidding attacker |
src/MakaMek.Map/Models/HexExtensions.cs already exists; add the IsRoadOrPaved() extension method to it.
-
Road,Pavement, andBridgeappear inMakaMekTerrainsenum. - A hex containing
RoadoverHeavyWoodscosts 1 MP to enter when moving road-to-road (not 3 MP). - A unit moving from a non-road hex into a road hex pays the underlying terrain cost (not the road bonus).
- Elevation change MP costs are added even when on road.
- A 'Mech on
Runthat changes facing on aRoad/Pavementhex and then enters a new hex triggers a PSR. - A 'Mech on
Walkspeed that changes facing on a road hex does not trigger a skid PSR. - A 'Mech on
Runthat does not change facing on a road hex does not trigger a skid PSR.
- On PSR failure, the 'Mech falls and skids
⌈hexesMoved ÷ 2⌉hexes. - Skid damage = half normal falling damage per skid hex traversed.
- Attacking the skidding 'Mech applies a +2 to-hit modifier.
- The skidding 'Mech's own attacks apply a +1 to-hit penalty.
-
BridgeTerrain.Heightstores the physical bridge height above the hex base (e.g.,1); serializes to/fromTerrainData.Height. -
BridgeTerrain.ConstructionFactorstores CF in tons (e.g.,60); serializes to/fromTerrainData.ConstructionFactor. - When units on a bridge hex exceed its CF, the bridge collapses.
- Collapsed bridge hex has
BridgeTerrainremoved. - Units on the collapsed hex fall to underlying terrain and take standard falling damage.
-
TerrainDataroundtrip preservesRoad,Pavement, andBridge(includingHeightandConstructionFactor). -
SkidandBridgeCollapsesegment events propagate correctly over the network.
- Given a hex at level 0 with water depth −1 and
BridgeTerrain.Height = 1, clearance computes to 2. - A unit whose height ≤ clearance may enter the hex from the underlying terrain (moving under the bridge).
- A unit whose height > clearance cannot move through that hex at the lower level; the bridge hex is treated as a building hex for that movement attempt.
- A hex containing
LightWoodsandRoadrenders in the order: base → light woods overlay → road overlay. - Road textures are selected via the same 6-bit canonical bitmask mechanism as water.
- A road hex with no road neighbors uses the
000000(isolated) bitmask texture. - A road hex connected to all 6 neighbors uses the fully-connected bitmask texture.
- Bridge hexes participate in road connectivity (a bridge neighbor counts as a road neighbor for bitmask purposes).