Repository navigation
Map
github-actions[bot] edited this page Nov 9, 2026
·
3 revisions
The Map module implements the core logic for the game's hex-based battle map. It encapsulates the structure, manipulation, and querying of map tiles (hexes), terrain, movement/pathfinding, line-of-sight (LOS), and firing arcs. The design supports extensibility (e.g., new terrain types, custom map generation) and efficient spatial calculations critical for gameplay.
- Purpose: Central manager for the game map, holding all hexes and providing high-level operations.
-
Responsibilities:
- Stores map dimensions and a dictionary of hexes (by coordinates).
- Adds, retrieves, and iterates over hexes.
- Pathfinding: Finds optimal paths between positions, considering movement cost, facing, and prohibited hexes. Supports both standard and jump movement.
- Computes reachable hexes for a given unit, considering movement points, terrain, and prohibited areas.
- Line-of-sight (LOS): Determines visibility between hexes, factoring in height, terrain, and intervening hexes. Uses a cache for performance.
- Exposes utility methods for LOS hex listing, LOS cache clearing and map boundary validation.
- Converts the map to data objects for serialization.
- Purpose: Models a single hex tile on the map.
-
Responsibilities:
- Stores position (
HexCoordinates), level (height), and an optional theme. - Manages a set of terrain objects, supporting addition, removal, and queries.
- Calculates movement cost (highest terrain cost), ceiling (level plus max terrain height), and terrain types present.
- Converts itself to a serializable data object.
- Stores position (
- Purpose: Represents a position in the hex grid using axial and cube coordinates.
-
Responsibilities:
- Stores Q (column), R (row), and derived S/X/Y/Z cube coordinates for advanced math.
- Provides pixel positions for rendering.
- Supplies methods for adjacency, neighbor lookup, direction calculation, and distance measurement.
- Implements algorithms for lines between hexes (for LOS), firing arc calculations, and range queries.
- Supports conversion to/from data objects and string representations.
- HexDirection: Enum representing the six possible directions in a hex grid (Top, TopRight, BottomRight, Bottom, BottomLeft, TopLeft).
- HexPosition: Combines a coordinate and facing direction, used for pathfinding and movement logic.
-
Pathfinding:
- The map supports both standard (terrain/facing-aware) and jump (distance-only) movement.
- Standard pathfinding accounts for turning costs, movement costs per terrain, and optionally prohibited hexes.
- Returns a sequence of
PathSegmentobjects representing each step (move/turn) with associated cost. -
Enhanced Parameters: Both
FindPathand reachability methods now supportprohibitedHexesparameter for avoiding specific areas.
-
Jump profile: Jump paths carry a single vertical profile on
HexPosition.AirborneLevel. The destination is grounded (null); the start is grounded except for an adjacent jump, whose start carries the approach waypoint. The last translation'sFrom(the approach position,destination - 1) is a hard waypoint atmax(referenceLevel(approach), referenceLevel(destination)) + offset, where the offset is supplied by the rules layer (IRulesProvider.GetDfaAirborneBaseOffset(), currently 2 for the DFA mid-air base); the map itself defaults to 0. Line of sight adds the unit height on top. An adjacent jump therefore stores it on the start position. Other intermediate levels are linearly interpolated, rounded up, and clamped between the hex reference level and the jump ceiling. The same values feed path validity and DFA LOS; presentation is flat top-down 2D and does not render a vertical arc. A completed DFA leaves that approach waypoint on the attacker'sPosition(airborne for LOS) until the attack resolves. - Reachability: Efficiently computes all hexes reachable within a movement budget, considering facing, terrain, and prohibited areas.
-
Jump movement: Ignores terrain/facing for cost; each crossed hex costs 1 MP. The path must be a shortest route and every crossed hex (destination included) must satisfy
referenceLevel(hex) <= startLevel + availableJumpingMP, wherestartLevelis the unit's standing level in the start hex (bridge deck when on a bridge, riverbed when in water). Jump pathfinding picks the first legal shortest route deterministically rather than enumerating every route.GetJumpReachableHexesruns one breadth-first search through clear hexes and includes a destination only when its legal search distance equals the geometric distance. Prohibited hexes only exclude destinations: a jump passes over them. The jump cache key includes the jump MP budget because the ceiling depends on it.
-
LOS Calculation:
- Determines if two hexes are mutually visible, considering height interpolation and terrain intervening factors.
- Uses a line-drawing algorithm on the hex grid, with special handling for ambiguous (divided) segments.
- LOS is blocked if intervening height or total terrain factor exceeds thresholds.
- Optional attacker and target base levels let an airborne position (a pending DFA approach) supply its absolute endpoint level instead of the surface standing level; such an endpoint is never treated as submerged. The path cache still keys on coordinates only.
- LOS paths are cached for efficiency.
-
LOS Hex Listing:
-
GetHexesAlongLineOfSightmethod returns detailed hex information along the LOS path. - Returns all hexes along the LOS between two points for tactical analysis.
-
-
Boundary Validation:
IsOnMapmethod provides efficient boundary checking for coordinate validation.
- FiringArc: Enum representing forward, left, right, and rear arcs.
-
Arc Calculation:
- HexCoordinates provides methods to determine if a target is within a given arc (using vector math and angles).
- Used for attack/defense logic and UI highlighting.
-
Terrains:
- Each hex may have multiple terrain objects (e.g., woods, clear), each with movement cost, height, and intervening (LOS) factor.
- Terrain types are extensible via the
Terrainssubdirectory. - Terrain affects both movement and LOS calculations.
-
BattleMapFactory/IBattleMapFactory:
- Abstract map creation logic, enabling custom map generation for different scenarios or tests.
-
BattleMapmanages allHexinstances and exposes high-level operations. - Each
Hexreferences itsHexCoordinatesand a set ofTerrainobjects. - Pathfinding, LOS, and firing arc logic operate on coordinates and hex data.
- Factories encapsulate map construction logic, supporting extensibility.
-
Terrains: Add new terrain types by extending the base
Terrainclass. - Map Generation: Implement custom factories for scenario-specific maps.
- LOS/Pathfinding: Algorithms are modular and can be replaced or extended for advanced rules.
The Map module offers a robust, extensible foundation for hex-based spatial logic in MakaMek. It supports complex movement, terrain, and visibility rules while remaining performant and maintainable. All core responsibilities (map structure, pathfinding, LOS, terrain, and arcs) are encapsulated and decoupled for easy evolution.