Package megamek.common.moves

Class ClimbingHelper

java.lang.Object
megamek.common.moves.ClimbingHelper
public final class ClimbingHelper extends Object
Utility class for Mek climbing rules (TO:AR p.20).

Climbing allows a Mek to enter a hex that is 3 or more levels higher or lower than the hex it occupies, provided it has at least one arm with all four actuators functional and the hand free. Only walking MP can be used when climbing.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    CLIMBING_PSR_MODIFIER
    PSR modifier applied to all piloting rolls while climbing.
    static final int
    DANGLE_LEVELS_PER_TURN
    Number of levels lowered per Dangle-and-Drop turn.
    static final int
    DROP_MP_COST
    MP cost for dropping from a dangle position.
    static final int
    MIN_CLIMBING_LEVELS
    Minimum level difference that requires climbing or dangle-and-drop.
    static final int
    MP_COST_ONE_HAND
    MP cost per level when climbing with one functional hand.
    static final int
    MP_COST_TWO_HANDS
    MP cost per level when climbing with two functional hands.
    static final int
    ONE_ARM_PSR_MODIFIER
    Additional PSR modifier when climbing with only one functional arm.
    static final int
    TARGET_CLIMBING_MODIFIER
    To-hit modifier applied against a climbing target (easier to hit).

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    canClimb(Entity entity)
    Returns true if the given entity is a Mek capable of climbing (TO:AR p.20).
    static boolean
    canClimb(Entity entity, boolean isProne)
    Path-aware variant of canClimb(Entity) that evaluates against the supplied prone state rather than the entity's live prone state.
    static boolean
    canDangle(Entity entity)
    Returns true if the given entity can perform a Dangle-and-Drop maneuver (TO:AR p.20).
    static int
    countClimbableArms(Mek mek)
    Returns the number of arms (0, 1, or 2) eligible for climbing on the given Mek.
    static int
    getClimbDestinationElevation(Hex hex)
    Same as getClimbDestinationLevel(Hex) but expressed as elevation relative to the hex's own level — so a building roof returns BLDG_ELEV, a bridge surface returns BRIDGE_ELEV, and a bare hex (cliff top, dry ground) returns 0.
    static int
    getClimbDestinationLevel(Hex hex)
    Returns the absolute level of the top climbable surface in the given hex — the building roof, the bridge surface, or the bare hex level if neither is present.
    static String
    getClimbingImpossibleReason(Entity entity)
    Returns a human-readable reason why the entity cannot climb, or null if climbing is possible.
    static int
    getClimbingMPCostPerLevel(Mek mek)
    Returns the MP cost per level climbed for the given Mek (TO:AR p.20).
    static String
    getDangleImpossibleReason(Entity entity)
    Returns a human-readable reason why the entity cannot dangle, or null if dangling is possible.
    static int
    getEdgeDropHeight(Entity entity, Coords targetCoords, Game game)
    Checks if an entity is at the edge of a cliff or building roof, with an adjacent hex that is 3+ levels lower.
    static boolean
    isArmClimbCapable(Mek mek, int location)
    Checks whether a specific arm on a Mek has all four actuators functional and the hand is free (not holding a physical weapon or carried object).
    static boolean
    isAtEdge(Entity entity, Coords targetCoords, Game game)
    Returns true if the entity is at the edge of a cliff or building roof, with the target hex being 3+ levels lower.
    static boolean
    isOnBuildingRoof(Entity entity, Game game)
    Returns true if the entity is standing on a building roof.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • MP_COST_TWO_HANDS

      public static final int MP_COST_TWO_HANDS
      MP cost per level when climbing with two functional hands.
      See Also:

    • MP_COST_ONE_HAND

      public static final int MP_COST_ONE_HAND
      MP cost per level when climbing with one functional hand.
      See Also:

    • CLIMBING_PSR_MODIFIER

      public static final int CLIMBING_PSR_MODIFIER
      PSR modifier applied to all piloting rolls while climbing.
      See Also:

    • ONE_ARM_PSR_MODIFIER

      public static final int ONE_ARM_PSR_MODIFIER
      Additional PSR modifier when climbing with only one functional arm.
      See Also:

    • TARGET_CLIMBING_MODIFIER

      public static final int TARGET_CLIMBING_MODIFIER
      To-hit modifier applied against a climbing target (easier to hit).
      See Also:

    • DANGLE_LEVELS_PER_TURN

      public static final int DANGLE_LEVELS_PER_TURN
      Number of levels lowered per Dangle-and-Drop turn.
      See Also:

    • DROP_MP_COST

      public static final int DROP_MP_COST
      MP cost for dropping from a dangle position.
      See Also:

    • MIN_CLIMBING_LEVELS

      public static final int MIN_CLIMBING_LEVELS
      Minimum level difference that requires climbing or dangle-and-drop.
      See Also:

  • Method Details

    • getEdgeDropHeight

      public static int getEdgeDropHeight(Entity entity, Coords targetCoords, Game game)
      Checks if an entity is at the edge of a cliff or building roof, with an adjacent hex that is 3+ levels lower. Returns the level difference to the lowest adjacent hex in the given direction, or 0 if not at an edge.
      Parameters:
      entity - the entity to check
      targetCoords - the adjacent hex to check (the potential lower hex)
      game - the current game
      Returns:
      the level difference (positive = entity is higher), or 0 if not an edge

    • isAtEdge

      public static boolean isAtEdge(Entity entity, Coords targetCoords, Game game)
      Returns true if the entity is at the edge of a cliff or building roof, with the target hex being 3+ levels lower.
      Parameters:
      entity - the entity to check
      targetCoords - the adjacent hex to check
      game - the current game
      Returns:
      true if the entity is at a climbable/dangleable edge

    • isOnBuildingRoof

      public static boolean isOnBuildingRoof(Entity entity, Game game)
      Returns true if the entity is standing on a building roof.
      Parameters:
      entity - the entity to check
      game - the current game
      Returns:
      true if the entity is on a building roof

    • isArmClimbCapable

      public static boolean isArmClimbCapable(Mek mek, int location)
      Checks whether a specific arm on a Mek has all four actuators functional and the hand is free (not holding a physical weapon or carried object).
      Parameters:
      mek - the Mek to check
      location - the arm location (Mek.LOC_LEFT_ARM or Mek.LOC_RIGHT_ARM)
      Returns:
      true if the arm is fully functional and hand is free

    • countClimbableArms

      public static int countClimbableArms(Mek mek)
      Returns the number of arms (0, 1, or 2) eligible for climbing on the given Mek.
      Parameters:
      mek - the Mek to check
      Returns:
      the number of climbable arms

    • canClimb

      public static boolean canClimb(Entity entity)
      Returns true if the given entity is a Mek capable of climbing (TO:AR p.20). Requires at least one arm with all four actuators functional and hand free, and the unit must not be prone or shut down.
      Parameters:
      entity - the entity to check
      Returns:
      true if this entity can climb

    • canClimb

      public static boolean canClimb(Entity entity, boolean isProne)
      Path-aware variant of canClimb(Entity) that evaluates against the supplied prone state rather than the entity's live prone state. Used during MovePath compilation so a GET_UP step earlier in the path lets the subsequent climbing branch engage — even though the entity itself is still prone on the board until the turn commits.
      Parameters:
      entity - the entity to check
      isProne - the per-step prone state to evaluate against
      Returns:
      true if this entity can climb given the supplied prone state

    • getClimbingImpossibleReason

      public static String getClimbingImpossibleReason(Entity entity)
      Returns a human-readable reason why the entity cannot climb, or null if climbing is possible.
      Parameters:
      entity - the entity to check
      Returns:
      the reason climbing is impossible, or null if climbing is allowed

    • canDangle

      public static boolean canDangle(Entity entity)
      Returns true if the given entity can perform a Dangle-and-Drop maneuver (TO:AR p.20). Requires two arms with all four actuators functional and hands free.
      Parameters:
      entity - the entity to check
      Returns:
      true if this entity can dangle

    • getDangleImpossibleReason

      public static String getDangleImpossibleReason(Entity entity)
      Returns a human-readable reason why the entity cannot dangle, or null if dangling is possible.
      Parameters:
      entity - the entity to check
      Returns:
      the reason dangling is impossible, or null if dangling is allowed

    • getClimbingMPCostPerLevel

      public static int getClimbingMPCostPerLevel(Mek mek)
      Returns the MP cost per level climbed for the given Mek (TO:AR p.20). 2 MP per level with two functional hands, 3 MP per level with one.
      Parameters:
      mek - the Mek to check
      Returns:
      the MP cost per level of climbing

    • getClimbDestinationLevel

      public static int getClimbDestinationLevel(Hex hex)
      Returns the absolute level of the top climbable surface in the given hex — the building roof, the bridge surface, or the bare hex level if neither is present. Used by the climbing dialog to compute remaining levels of an in-progress climb; without the bridge branch a continuation climb toward a bridge hex measures only to the bare hex level (the water/ground beneath the bridge), reports 0 levels remaining, and skips the dialog entirely.
      Parameters:
      hex - the hex whose climbable top to measure
      Returns:
      the absolute level of the building roof, bridge surface, or bare hex level

    • getClimbDestinationElevation

      public static int getClimbDestinationElevation(Hex hex)
      Same as getClimbDestinationLevel(Hex) but expressed as elevation relative to the hex's own level — so a building roof returns BLDG_ELEV, a bridge surface returns BRIDGE_ELEV, and a bare hex (cliff top, dry ground) returns 0. Used by MoveStep.compile(megamek.common.game.Game, megamek.common.units.Entity, megamek.common.moves.MoveStep, megamek.common.pathfinder.CachedEntityState) to place a continuation-climbing Mek on the destination hex's top surface, bypassing the water-emergence math in Entity.calcElevation(megamek.common.Hex, megamek.common.Hex, int, boolean) that doesn't apply when the Mek is on a cliff face above the waterline.
      Parameters:
      hex - the destination hex
      Returns:
      the elevation of the climbable top surface, relative to the hex's own level