GDHexGrid

Tools for using hexagonal grids in GDScript.

The reference used for creating this was the amazing guide: https://www.redblobgames.com/grids/hexagons/

Copyright 2018 Mel Collins. Distributed under the MIT license (see LICENSE.txt).

Orientation

There are many ways to orient a hex grid, this library was written using the following assumptions:

• The hexes use a flat-topped orientation;
• Axial coordinates use +x => NE; +y => N;
• Offset coords have odd rows shifted up half a step;
• Projections of the hex grid into Godot-space use +x => E, +y => S.

Using x,y instead of the reference's preferred x,z for axial coords makes following along with the reference a little more tricky, but is less confusing when using Godot's Vector2(x, y) objects.

We map hex coordinates to Godot-space with +y flipped to be the down vector so that it maps neatly to both Godot's 2D coordinate system, and also to x,z planes in 3D space.

Usage

HexGrid

HexGrid is used when you want to position hexes in a 2D or 3D scene. It translates coordinates between the hex grid and conventional spaces.

var hex_scale = Vector2(...)

If you want your hexes to display larger than the default 1 x 0.866 units, then you can customise the scale of the hexes using this property.

func get_hex_center(hex)

Returns the Godot-space coordinate of the center of the given hex coordinates.

The coordinates can be given as either a HexCell instance; a Vector3 cube coordinate, or a Vector2 axial coordinate.

func get_hex_center3(hex [, y])

Returns the Godot-space Vector3 of the center of the given hex.

The coordinates can be given as either a HexCell instance; a Vector3 cube coordinate, or a Vector2 axial coordinate.

If a second parameter is given, it will be used for the y value in the returned Vector3. Otherwise, the y value will be 0.

func get_hex_at(coords)

Returns HexCell whose grid position contains the given Godot-space coordinates.

The given value can either be a Vector2 on the grid's plane or a Vector3, in which case its (x, z) coordinates will be used.

HexGrid pathfinding

HexGrid also includes an implementation of the A* pathfinding algorithm. The class can be used to populate an internal representation of a game grid with obstacles to traverse.

This was written with the aid of another amazing guide: https://www.redblobgames.com/pathfinding/a-star/introduction.html

func set_bounds(min_coords, max_coords)

Sets the hard outer limits of the path-finding grid.

The coordinates given are the min and max corners inside a bounding square (diamond in hex visualisation) region. Any hex outside that area is considered an impassable obstacle.

The default bounds consider only the origin to be inside, so you're probably going to want to do something about that.

func get_obstacles()

Returns a dict of all obstacles and their costs

The keys are Vector2s of the axial coordinates, the values will be the cost value. Zero cost means an impassable obstacle.

func add_obstacles(coords, cost=0)

Adds one or more obstacles to the path-finding grid

The given coordinates (axial or cube), HexCell instance, or array thereof, will be added as path-finding obstacles with the given cost. A zero cost indicates an impassable obstacle.

func remove_obstacles(coords)

Removes one or more obstacles from the path-finding grid

The given coordinates (axial or cube), HexCell instance, or array thereof, will be removed as obstacles from the path-finding grid.

func get_barriers()

Returns a dict of all barriers in the grid.

A barrier is an edge of a hex which is either impassable, or has a non-zero cost to traverse. If two adjacent hexes both have barriers on their shared edge, their costs are summed. Barrier costs are in addition to the obstacle (or default) cost of moving to a hex.

The outer dict is a mapping of axial coords to an inner barrier dict. The inner dict maps between HexCell.DIR_* directions and the cost of travel in that direction. A cost of zero indicates an impassable barrier.

func add_barriers(coords, dirs, cost=0)

Adds one or more barriers to locations on the grid.

The given coordinates (axial or cube), HexCell instance, or array thereof, will have path-finding barriers added in the given HexCell.DIR_* directions with the given cost. A zero cost indicates an impassable obstacle.

Existing barriers at given coordinates will not be removed, but will be overridden if the direction is specified.

func remove_barriers(coords, dirs=null)

Remove one or more barriers from the path-finding grid.

The given coordinates (axial or cube), HexCell instance, or array thereof, will have the path-finding barriers in the supplied HexCell.DIR_* directions removed. If no direction is specified, all barriers for the given coordinates will be removed.

func get_hex_cost(coords)

Returns the cost of moving into the specified grid position.

Will return 0 if the given grid position is inaccessible.

func get_move_cost(coords, direction)

Returns the cost of moving from one hex to an adjacent one.

This method takes into account any barriers defined between the two hexes, as well as the cost of the target hex. Will return 0 if the target hex is inaccessible, or if there is an impassable barrier between the hexes.

The direction should be provided as one of the HexCell.DIR_* values.

func find_path(start, goal, exceptions=[])

Calculates an A* path from the start to the goal.

Returns a list of HexCell instances charting the path from the given start coordinates to the goal, including both ends of the journey.

Exceptions can be specified as the third parameter, and will act as impassable obstacles for the purposes of this call of the function. This can be used for pathing around obstacles which may change position (eg. enemy playing pieces), without having to update the grid's list of obstacles every time something moves.

If the goal is an impassable location, the path will terminate at the nearest adjacent coordinate. In this instance, the goal hex will not be included in the returned array.

If there is no path possible to the goal, or any hex adjacent to it, an empty array is returned. But the algorithm will only know that once it's visited every tile it can reach, so try not to path to the impossible.

HexCell

A HexCell represents a single hex in the grid, and is the meat of the library.

var cube_coords; var axial_coords; var offset_coords

Cube coordinates are used internally as the canonical representation, but both axial and offset coordinates can be read and modified through these properties.

func get_adjacent(direction)

Returns the neighbouring HexCell in the given direction.

The direction should be one of the DIR_N, DIR_NE, DIR_SE, DIR_S, DIR_SW, or DIR_NW constants provided by the HexCell class.

func get_all_adjacent()

Returns an array of the six HexCell instances neighbouring this one.

func get_all_within(distance)

Returns an array of all the HexCells within the given number of steps, including the current hex.

func get_ring(distance)

Returns an array of all the HexCells at the given distance from the current.

func distance_to(target)

Returns the number of hops needed to get from this hex to the given target.

The target can be supplied as either a HexCell instance, cube or axial coordinates.

func line_to(target)

Returns an array of all the hexes crossed when drawing a straight line between this hex and another.

The target can be supplied as either a HexCell instance, cube or axial coordinates.

The items in the array will be in the order of traversal, and include both the start (current) hex, as well as the final target.