Package megamek.common.board

Class Coords

java.lang.Object
megamek.common.board.Coords
All Implemented Interfaces:
Serializable
public class Coords extends Object implements Serializable
Coords stores x and y values. Since these are hexes, coordinates with odd x values are a half-hex down. Directions work clockwise around the hex, starting with zero at the top. For a hex with an even x, the hexes in directions 2 and 4 (left and right downward) have the same y. 
       -y
        0
      _____
   5 /     \ 1
 -x /       \ +x
    \       /
   4 \_____/ 2
        3
       +y
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int[]
    ALL_DIRECTIONS
     
    static final double
    HEX_SIDE
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    Coords(int x, int y)
    Constructs a new coordinate pair at (x, y).
    Coords(Coords other)
    Constructs a new coordinate pair at Coords(x, y).

  • Method Summary

    Modifier and Type
    Method
    Description
    Coords
    add(Coords centroid)
     
    ArrayList<Coords>
    allAdjacent()
    Returns a list of all adjacent coordinates (distance = 1), regardless of whether they're on the board or not.
    ArrayList<Coords>
    allAtDistance(int dist)
    Returns a list of all coordinates at the given distance dist, regardless of whether they're on the board or not.
    ArrayList<Coords>
    allAtDistanceOrLess(int dist)
    Returns a list of all coordinates at the given distance dist and anything less than dist as well.
    ArrayList<Coords>
    allLessThanDistance(int dist)
    Returns a list of all coordinates at the given distance (dist - 1) and anything less than dist as well.
    int
    approximateDirection(Coords second, int initialDirection, int previousDirection)
    Returns an approximate direction in which another coordinate lies; 0 if the coordinates are equal
    static Coords
    average(List<Coords> positions)
     
    boolean
    between(Coords s, Coords e)
    return true if this is between s and e based on distance
    Coords
    closestCoords(List<Coords> coords)
     
    int
    degree(Coords d)
     
    int
    direction(Coords d)
    Returns the direction in which another coordinate lies; 0 if the coordinates are equal.
    int
    distance(int distX, int distY)
    Returns the distance to the coordinate given as distX, distY.
    int
    distance(Coords coordinates)
     
    int
    dotProduct(Coords d)
     
    boolean
    equals(Object object)
    Coords are equal if their x and y components are equal
    static Coords
    fromHexCode(String hexCode)
    Deprecated, for removal: This API element is subject to removal in a future version.
    String
    getBoardNum()
    Returns a string representing a coordinate in "board number" format.
    int
    getX()
     
    int
    getY()
     
    int
    hashCode()
    Returns the hash code for these coords.
    static String
    hexCode(int x, int y, Board board)
    Returns the hex code for the given coordinates.
    String
    hexCode(Board board)
    Returns the hex code for this coordinate on the given board.
    static String
    hexCode(Coords coords, Board board)
    Returns the hex code for the given coordinates on the given board.
    static ArrayList<Coords>
    intervening(Coords src, Coords dest)
    Returns an array of the Coords of hexes that are crossed by a straight line from the center of src to the center of dest, including src and dest.
    static ArrayList<Coords>
    intervening(Coords src, Coords dest, boolean split)
    Returns an array of the Coords of hexes that are crossed by a straight line from the center of src to the center of dest, including src and dest.
    boolean
    isOnHexRow(int direction, Coords other)
    Returns true when the given other Coords are exactly on the hex row (line) from this Coords in the given direction.
    boolean
    isXOdd()
    Returns true when the x coordinate of this Coords is odd.
    double
    magnitude()
     
    static Coords
    median(List<Coords> positions)
    Returns the median of the given list of positions.
    static Coords
    nextHex(Coords current, Coords destination)
    Pass-thru version of the above that assumes current = iSrc.
    static Coords
    nextHex(Coords current, IdealHex iSrc, IdealHex iDest, int[] directions)
    Returns the first further hex found along the line from the centers of src to dest.
    static Coords
    of(int x, int y)
     
    static Coords
    parse(String input, int offset)
    Parses a string into a Coords object.
    static Coords
    parseHexNumber(String input)
    Parses a string into a Coords object.
    double
    radian(Coords d)
    Returns the radian direction of another Coords.
    Coords
    subtract(Coords centroid)
     
    CubeCoords
    toCube()
     
    String
    toFriendlyString()
    this makes the coordinates 1 based instead of 0 based to match the tiles displayed on the grid.
    String
    toString()
     
    String
    toTSV()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Coords
    translated(int dir)
    Returns the coordinate 1 unit in the specified direction dir.
    Coords
    translated(int dir, int distance)
    Returns the coordinate the given distance away in the specified direction dir.
    Coords
    translated(String dir)
     
    int
    xInDir(int dir)
    Returns the x value of the adjacent Coords in the direction dir.
    int
    xInDir(int dir, int distance)
    Returns the x value of the Coords the given distance in the direction dir.
    static int
    xInDir(int x, int y, int dir)
    Returns the x value of the adjacent Coords in the direction dir.
    static int
    xInDir(int x, int y, int dir, int distance)
    Returns the x value of the Coords the given distance in the direction dir.
    int
    yInDir(int dir)
    Returns the y value of the adjacent Coords in the direction dir.
    int
    yInDir(int dir, int distance)
    Returns the y value of the Coords the given distance in the direction dir.
    static int
    yInDir(int x, int y, int dir)
    Returns the y value of the adjacent Coords in the direction dir.
    static int
    yInDir(int x, int y, int dir, int distance)
    Returns the x value of the Coords the given distance in the direction dir.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • HEX_SIDE

      public static final double HEX_SIDE
      See Also:

    • ALL_DIRECTIONS

      public static final int[] ALL_DIRECTIONS

  • Constructor Details

    • Coords

      public Coords(int x, int y)
      Constructs a new coordinate pair at (x, y). Note: Coords are immutable.

    • Coords

      public Coords(Coords other)
      Constructs a new coordinate pair at Coords(x, y). Note: Coords are immutable.

  • Method Details

    • parseHexNumber

      public static Coords parseHexNumber(String input)
      Parses a string into a Coords object. The string can be in the format x,y or HexNumber. HexNumbers are offset by 1, so we have to reduce it here. 
      String hexNUmber = "0423";
 Coords coords = Coords.parse(hexNumber);
 assert coords.getX() == 3;
 assert coords.getY() == 22;

      Using X and Y is also easy

      String xy = "4,23";
 Coords coords = Coords.parse(xy);
 assert coords.getX() == 3;
 assert coords.getY() == 22;
      Parameters:
      input - the string to parse
      Returns:
      the Coords object

    • parse

      public static Coords parse(String input, int offset)
      Parses a string into a Coords object. The string can be in the format x,y or HexNumber. You can also apply any offset you want to compensate different starting points or uses. 
      String hexNUmber = "0423";
 Coords coords = Coords.parse(hexNumber, -1);
 assert coords.getX() == 3;
 assert coords.getY() == 22;

      Using X and Y is also easy

      String xy = "4,23";
 Coords coords = Coords.parse(xy, 0);
 assert coords.getX() == 4;
 assert coords.getY() == 23;
      Parameters:
      input - the string to parse
      Returns:
      the Coords object
      Throws:
      IllegalArgumentException - if the input is not in the correct format or is null

    • closestCoords

      @Nullable public Coords closestCoords(List<Coords> coords)

    • average

      @Nullable public static Coords average(List<Coords> positions)

    • median

      @Nullable public static Coords median(List<Coords> positions)
      Returns the median of the given list of positions. The median is the point that minimizes the sum of the distances to all other points in the list. The algorithm is based on the Weiszfeld algorithm.
      Parameters:
      positions - list of positions
      Returns:
      the median of the given list of positions

    • translated

      public Coords translated(int dir)
      Returns the coordinate 1 unit in the specified direction dir.

    • translated

      public Coords translated(int dir, int distance)
      Returns the coordinate the given distance away in the specified direction dir.

    • translated

      public Coords translated(String dir)

    • xInDir

      public static int xInDir(int x, int y, int dir)
      Returns the x value of the adjacent Coords in the direction dir.

    • xInDir

      public static int xInDir(int x, int y, int dir, int distance)
      Returns the x value of the Coords the given distance in the direction dir.

    • yInDir

      public static int yInDir(int x, int y, int dir)
      Returns the y value of the adjacent Coords in the direction dir.

    • yInDir

      public static int yInDir(int x, int y, int dir, int distance)
      Returns the x value of the Coords the given distance in the direction dir.

    • xInDir

      public int xInDir(int dir)
      Returns the x value of the adjacent Coords in the direction dir.

    • xInDir

      public int xInDir(int dir, int distance)
      Returns the x value of the Coords the given distance in the direction dir.

    • yInDir

      public int yInDir(int dir)
      Returns the y value of the adjacent Coords in the direction dir.

    • yInDir

      public int yInDir(int dir, int distance)
      Returns the y value of the Coords the given distance in the direction dir.

    • isXOdd

      public boolean isXOdd()
      Returns true when the x coordinate of this Coords is odd. This is significant in determining where this coordinate lies in relation to other coordinates.

    • direction

      public int direction(Coords d)
      Returns the direction in which another coordinate lies; 0 if the coordinates are equal.
      Parameters:
      d - the destination coordinate.

    • approximateDirection

      public int approximateDirection(Coords second, int initialDirection, int previousDirection)
      Returns an approximate direction in which another coordinate lies; 0 if the coordinates are equal

    • radian

      public double radian(Coords d)
      Returns the radian direction of another Coords.
      Parameters:
      d - the destination coordinate.

    • dotProduct

      public int dotProduct(Coords d)
      Parameters:
      d - the destination coordinate.
      Returns:
      the degree direction of another Coords

    • degree

      public int degree(Coords d)
      Parameters:
      d - the destination coordinate.
      Returns:
      the degree direction of another Coords

    • distance

      public int distance(@Nullable Coords coordinates)
      Parameters:
      coordinates - the coordinates to get the distance to, or null
      Returns:
      the distance from these coordinates to the provided coordinates, or Integer.MAX_VALUE if the provided coordinates are null

    • distance

      public int distance(int distX, int distY)
      Returns the distance to the coordinate given as distX, distY.

    • getBoardNum

      public String getBoardNum()
      Returns a string representing a coordinate in "board number" format.

    • equals

      public boolean equals(Object object)
      Coords are equal if their x and y components are equal
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Returns the hash code for these coords.
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • intervening

      public static ArrayList<Coords> intervening(Coords src, Coords dest)
      Returns an array of the Coords of hexes that are crossed by a straight line from the center of src to the center of dest, including src and dest. The returned coordinates are in line order, and if the line passes directly between two hexes, it returns them both. Based on the degree of the angle, the next hex is going to be one of three hexes. We check those three hexes, sides first, add the first one that intersects and continue from there. Based off of some of the formulas at Amit's game programming site.

      Amit’s Game Programming Information

      Note: this function can return Coordinates that are not on the board.

      Parameters:
      src - Starting point.
      dest - Ending Point.
      Returns:
      The list of intervening coordinates.

    • intervening

      public static ArrayList<Coords> intervening(Coords src, Coords dest, boolean split)
      Returns an array of the Coords of hexes that are crossed by a straight line from the center of src to the center of dest, including src and dest. The returned coordinates are in line order, and if the line passes directly between two hexes, it returns them both. Based on the degree of the angle, the next hex is going to be one of three hexes. We check those three hexes, sides first, add the first one that intersects and continue from there. Based off of some of the formulas at Amit's game programming site.

      Amit’s Game Programming Information

      Note: this function can return Coordinates that are not on the board.

      Parameters:
      src - Starting point.
      dest - Ending Point.
      split - Set TRUE to make left appear before right in the sequence reliably
      Returns:
      The list of intervening coordinates.

    • nextHex

      public static Coords nextHex(Coords current, IdealHex iSrc, IdealHex iDest, int[] directions)
      Returns the first further hex found along the line from the centers of src to dest. Checks the three directions given and returns the closest. This relies on the side directions being given first. If it checked the center first, it would end up missing the side hexes sometimes. Not the most elegant solution, but it works.

    • nextHex

      public static Coords nextHex(Coords current, Coords destination)
      Pass-thru version of the above that assumes current = iSrc.

    • isOnHexRow

      public boolean isOnHexRow(int direction, @Nullable Coords other)
      Returns true when the given other Coords are exactly on the hex row (line) from this Coords in the given direction. For example, if the direction is 0 (north), returns true only for Coords that are above this Coords at the same x. Returns false when the other Coords are null, the other Coords are equal to this or the direction is outside 0 to 5.
      Parameters:
      direction - The direction, 0 = N, 2 = SE ...
      other - The Coords to test
      Returns:
      True when the other Coords are on the hex row from this Coords in the given direction

    • allAdjacent

      public ArrayList<Coords> allAdjacent()
      Returns a list of all adjacent coordinates (distance = 1), regardless of whether they're on the board or not.

    • allLessThanDistance

      public ArrayList<Coords> allLessThanDistance(int dist)
      Returns a list of all coordinates at the given distance (dist - 1) and anything less than dist as well.

    • allAtDistanceOrLess

      public ArrayList<Coords> allAtDistanceOrLess(int dist)
      Returns a list of all coordinates at the given distance dist and anything less than dist as well.

    • allAtDistance

      public ArrayList<Coords> allAtDistance(int dist)
      Returns a list of all coordinates at the given distance dist, regardless of whether they're on the board or not. Returns an empty Set for dist < 0 and the calling Coords itself for dist == 0.

    • toFriendlyString

      public String toFriendlyString()
      this makes the coordinates 1 based instead of 0 based to match the tiles displayed on the grid.

    • toTSV

      @Deprecated(since="0.51.0", forRemoval=true) public String toTSV()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Returns the coordinates in TSV format for logging purposes
      Returns:
      the coordinates in TSV format `x`\t`y`

    • getX

      public int getX()

    • getY

      public int getY()

    • between

      public boolean between(Coords s, Coords e)
      return true if this is between s and e based on distance

    • toCube

      public CubeCoords toCube()
      Returns:
      CubeCoords representation of this Coords

    • subtract

      public Coords subtract(Coords centroid)

    • add

      public Coords add(Coords centroid)

    • magnitude

      public double magnitude()

    • hexCode

      public String hexCode(Board board)
      Returns the hex code for this coordinate on the given board.
      Parameters:
      board - the board
      Returns:
      the hex code for this coordinate

    • hexCode

      public static String hexCode(Coords coords, Board board)
      Returns the hex code for the given coordinates on the given board.
      Parameters:
      coords - the coordinates
      board - the board
      Returns:
      the hex code for the given coordinates

    • hexCode

      public static String hexCode(int x, int y, Board board)
      Returns the hex code for the given coordinates.
      Parameters:
      x - the x coordinate
      y - the y coordinate
      board - the board
      Returns:
      the hex code for the given coordinates

    • fromHexCode

      @Deprecated(since="0.51.0", forRemoval=true) public static Coords fromHexCode(String hexCode)
      Deprecated, for removal: This API element is subject to removal in a future version.

    • of

      public static Coords of(int x, int y)