hextille v0.1.0 Hextille.Cube View Source

Cube module that represents hexagon tiles using Cube coordinates. Instead of names x, y, z this module uses names q, r, s.

Cube coordinates have a constraint q + r + s = 0, even with floating point cube coordinates. This has to be always respected.

Axes are aligned in the following order:

       -r
  +s   .^.   +q
    .´     `.
    |       |
    `.     .´
  -q   `.´   -s
       +r

Link to this section Summary

Functions

Addition of cube coordinates. Returns a new Cube with added coordinates

Creates a Cube or throws ArgumentError if the given arguments don’t satisfy constraint q + r + s = 0. This function should be the preferred way to create new Hexagons when using this module

Returns a new Cube representing the direction as a vector

Calculates the distance between hexagons a and b. Return value is an integer value

Returns the distance of hexagon a from origo as an integer

Finds the neighbouring tile of hexagon a at the given direction. Returns a new Cube representing the neighbour Cube

Rotate cube coordinates 60° to given direction :left or :right. Returns a new Cube at rotated position

Rounds up an hexagon with float values to integer coordinates

Scale cube coordinates with given multiplier k. Returns a new scaled Cube

Subtraction of cube coordinates. Returns a new Cube with subtracted coordinates

Link to this section Functions

Addition of cube coordinates. Returns a new Cube with added coordinates.

Examples:

iex> a = %Cube{q: 1, r: -2, s: 1} iex> b = %Cube{q: 3, r: -2, s: -1} iex> Cube.add(a, b) %Cube{q: 4, r: -4, s: 0}

Creates a Cube or throws ArgumentError if the given arguments don’t satisfy constraint q + r + s = 0. This function should be the preferred way to create new Hexagons when using this module.

Examples:

iex> Cube.create!(1, -2, 1) %Cube{q: 1, r: -2, s: 1} iex> Cube.create!(4, -2, 1) ** (ArgumentError) Invalid coordinates, constraint q + r + s = 0

Returns a new Cube representing the direction as a vector.

Directions are enumerated in following order:


:north_west        :north_east
             .^.
          .´s   q`.
  :west   |       |  :east
          `.  r  .´
             `.´
:south_west        :south_east

Examples:

iex> Cube.directions(:north_east) %Cube{q: 1, r: -1, s: 0}

iex> Cube.directions(:east) %Cube{q: 1, r: 0, s: -1}

iex> Cube.directions(:south_east) %Cube{q: 0, r: 1, s: -1}

iex> Cube.directions(:south_west) %Cube{q: -1, r: 1, s: 0}

iex> Cube.directions(:west) %Cube{q: -1, r: 0, s: 1}

iex> Cube.directions(:north_west) %Cube{q: 0, r: -1, s: 1}

Calculates the distance between hexagons a and b. Return value is an integer value.

Examples:

iex> a = %Cube{q: 1, r: -2, s: 1} iex> b = %Cube{q: -2, r: -3, s: 5} iex> Cube.distance(a, b) 4

Returns the distance of hexagon a from origo as an integer.

Examples:

iex> a = %Cube{q: 1, r: -2, s: 1} iex> Cube.length(a) 2

iex> b = %Cube{q: -2, r: -3, s: 5} iex> Cube.length(b) 5

Finds the neighbouring tile of hexagon a at the given direction. Returns a new Cube representing the neighbour Cube.

Directions are enumerated in following order:


:north_west        :north_east
             .^.
          .´s   q`.
  :west   |       |  :east
          `.  r  .´
             `.´
:south_west        :south_east

Neighbours visualized


         .^.     .^.
      .´1   1`.´0   2`.
      |       |       |
     .^. -2  .^. -2  .^.
  .´1   0`.´0   1`.´-1  2`.
  |       |       |       |
  `. -1  .^. -1  .^. -1  .´
     `.´0   0`.´-1  1`.´
      |       |       |
      `.  0  .^.  0  .´
         `.´     `.´

Examples:

iex> a = %Cube{q: 1, r: -1, s: 0} iex> Cube.neighbour(a, :north_east) %Cube{q: 2, r: -2, s: 0} iex> Cube.neighbour(a, :north_west) %Cube{q: 1, r: -2, s: 1}

Rotate cube coordinates 60° to given direction :left or :right. Returns a new Cube at rotated position.

Rotations visualized


         .^.     .^.     .^.
      .´2   0`.´     `.´0   2`.
      |       |       |       |
     .^. -2  .^.     .^. -2  .^.
  .´     `.´     `.´     `.´     `.
  |       |       |       |       |
  `.     .^.     .^.     .^.     .^.
     `.´     `.´s   q`.´     `.´-2  2`.
      |       |       |       |       |
      `.     .^.  r  .^.     .^.  0  .´
         `.´     `.´     `.´     `.´
          |       |       |       |
          `.     .^.     .^.     .´
             `.´     `.´     `.´

Examples:

iex> a = %Cube{q: 2, r: -2, s: 0} iex> Cube.rotate(a, :left) %Cube{q: 0, r: -2, s: 2} iex> Cube.rotate(a, :right) %Cube{q: 2, r: 0, s: -2}

Rounds up an hexagon with float values to integer coordinates.

Examples:

iex> a = %Cube{q: 1.5, r: -2.25, s: 0.75} iex> Cube.round_hex(a) %Cube{q: 1, r: -2, s: 1}

iex> b = %Cube{q: 1.2, r: 2.5, s: -3.7} iex> Cube.round_hex(b) %Cube{q: 1, r: 3, s: -4}

Scale cube coordinates with given multiplier k. Returns a new scaled Cube.

Examples:

iex> a = %Cube{q: 1, r: -2, s: 1} iex> Cube.scale(a, 3) %Cube{q: 3, r: -6, s: 3}

Subtraction of cube coordinates. Returns a new Cube with subtracted coordinates.

Examples:

iex> a = %Cube{q: 1, r: -2, s: 1} iex> b = %Cube{q: 3, r: -2, s: -1} iex> Cube.subtract(a, b) %Cube{q: -2, r: 0, s: 2}