Introduction

This library makes working with hexagonal grids and maps an intuitive, easy and maybe even fun process.
All the details of hexagonal-grid-coordinate systems and the mathematics behind it are abstracted away from you so you can focus on building your game logic using declarative statements.
We include multiple example scenes displaying some approaches how the library can be used and showing how easily common features like line-of-sight or turn-based movement with movement costs based on map features can be implemented.
At the bottom of this page you will find step-by-step walkthroughs for the first three examples.

The visual representation of the hexagonal map is not part of the library as that is highly implementation specific. The sample scenes however come with some very basic visualisations.

Key Features

support for Tiles, Edges and Corners
supports workflows for finite maps as well as an infinite grid
maps can optionally be periodic (wrap around). Currently only "cylindrical" (repeating on x-axis) wrapping logic is included directly with the library but you can easily write your own wrap around logic
support for generics: a tile,edge or corner can have any class/struct as data type
alternatively derive from the non generic base class or keep the data of the game logic completely separate in arrays aligned with the tile/edge/corner indices of the HexMap
extensive amount of easy to use methods which can be used as building blocks to solve complex problems
build with ease of use as primary design
uses primarily "cube" coordinates. An explanation about the different coordinate systems used in this library can be found here: HexConverter
fully documented API
source code available
MIT license

Downloads

from itch.io : https://aurelwu.itch.io/hexmaplibrary
from github (library code only without examples) : https://github.com/AurelWu/HexMapLibrary

General Usage Principle

The Library has a consistent method naming scheme based on their return value allowing for intuitive usage:

result1 = map.GetTiles.Line(origin,target,true); //returns all tiles forming a line from origin to target (3rd param set to true specifies that the origin is included)
result2 = map.GetEdges.AdjacentToCorner(corner); //return all edges which are neighbouring the corner (usually 3 but at map border it can be just 2)
result3 = map.GetCorners.WithinDistance(centerCorner,distance,false); // returns all corners which are no further than distance away from the center (3rd param set to false specifies that origin is not included)
result4 = map.GetTileDistance.Grid(TileA,TileB); // returns the grid distance between those 2 tiles (there is also GetTileDistance.Euclidean if you want the euclidean distance)
result5 = map.GetEdge.BetweenTiles(TileA,TileB); // returns the edge which is between the 2 input tiles (throws an argument exception if the input tiles are not neighbouring)

Overview over the classes you will use mostly:

HexGrid
- This is a static class representing an infinite grid on the xz-plane.
- The methods of this class form the foundation of HexMap (which then adds bound checks and wrapping logic on top).
- often useful for intermediate steps even when the final results are on a finite-sized HexMap
HexMap
- an instance of HexMap represents a specific map instance with a defined set of Tiles ,Edges and Corners.
- optionally it can be periodic (i.e. wraps around at some or all the map borders)
- takes care of all bound checks and wrapping logic
HexMap<T>, HexMap<T,E>, HexMap<T,E,C>
- please note that they are called HexMapT<T> , HexMapTE<T,E> , HexMapTEC<T,E,C> in this documentation, this is just because the documentation generation software we use does not properly work with generics classes with different overloads and same class name. In the actual library they are all called HexMap<...> .
- generic variants of HexMap in which every Tile (and Edge / Corner) is an object of arbitrary type.
HexConverter
- static class to convert coordinates between different coordinate systems (cartesian, cube, offset)
HexMapBuilder
- static class to easily generate rectangular ,hexagonal or triangular shaped maps.
HexMouse
- Monobehaviour which updates information about the mouse position every frame (current tile, nearest edge, nearest corner, is cursor on map)

About "Pointy-Top" and "Flat-Top"-Hexagons

Everything in this library is build around pointy-top hexagons, however flat-top hexagons are just rotated pointy-top hexagons so you can just rotate the input and output coordinates, or even just your camera. Generally we recommend using pointy-top hexagons because you can fit more hexagons vertically this way which partly balances out the fact that computer screens are wider than tall. If you are not convinced by that, take a look at honeybees and how they build their combs.

left: pointy-top hexagon, right: flat-top hexagon

Performance:

While we made sure that the library does have reasonable performance we always prioritised useability and flexibility over raw performance. We made that decision because in most use cases it won't matter at all, and in those where it does, the solution will most likely be to just cache results. For example instead of always recalculating the result of HexMap.GetTiles.OfRing() which might become costly if the radius is big you can just calculate the relative position of the resulting tiles to the center once for each radius you need and store them. If you ever encounter a performance issue which is not solvable this way and you also don't find another solution, please message us and we will try to find a solution (no promises that we can solve your particular problem but we will try our best as long as it is within reasonable scope)

Examples

These examples are kept as simple and as possible so you can focus on the usage of the library, this code is by no means intended to be used in production code and is not suitable structured for that but for ease of understanding. You will also notice some duplicate code between them, that is consciously done to keep each example self-contained.

All these examples use a very simple way to visualise the map which is far from perfect in many ways, especially when it comes to performance as we use one GameObject per tile. We use custom shader which draws the hex grid lines on top of the mesh based on the world position. As this is not fundamental for the library itself we omit an explanation what this shader does in detail.

Please keep in mind that this library is not tied to a certain visualisation and you can easily use procedurally generated meshes, Environments created in 3D modelling software or even handpainted backgrounds instead.

You can either follow the tutorials step by step or take a look at the finished scene & script for each example.

-Example 0: Hello hex world

-Example 1: Mouse markers and simple map manipulation

-Example 2: Line of sight

There are two more scenes in the example folder, one covering path finding while the other is about building and road placement. The script files are documented so by now they are hopefully easily understood.

Reading Recommendation

If you want to understand hexagonal grids in depth we recommend reading Amit Patel's excellent page about hexagons: https://www.redblobgames.com/grids/hexagons/

License

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.