HexMapLibrary
HexMap Library Documentation
BannerCombined.png

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

Downloads

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:

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.

PointyAndFlatTopHexagon.png
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)

Copyright (c) 2018 Aurel "AurelWu" Wünsch

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.

Impressum

Electronic Sport Events UG (haftungsbeschränkt)
Geschäftsführer: Aurel Wünsch
Biedermannstraße 42
04277 Leipzig
Telefon: +49 (0)175 / 780 43 40
E-Mail: aurel.nosp@m.wuen.nosp@m.sch@g.nosp@m.mail.nosp@m..com
Registergericht: Amtsgericht Leipzig
Registernummer: HRB 27087
Umsatzsteuer-Identifikationsnummer gem. § 27 a Umsatzsteuergesetz: DE294361901