search

fananek / hex-grid

HexGrid library provides easy and intuitive way of working with hexagonal grids.
MIT License
45 stars 8 forks source link
grid hex hexagon hexagonal-grid-library swift

readme

HexGrid

Swift 5.6+ Swift Package Manager Compatible MIT License Documentation 

Development in progress!

API might change without further notice until first major release 1.x.x.

The HexGrid library provides an easy and intuitive way of working with hexagonal grids. Under the hood it handles all the math so you can focus on more important stuff.

The library is meant for generic backend use. Therefore it doesn't perform any UI or rendering. However, it provides the calculations that will be needed for rendering.

Features

What's coming next?

HexGrid in action

HexGrid demo app using SpriteKit. (Also available in the App Store.) HexGrid demo app using SwiftUI.

Getting Started

Integrating HexGrid to your project

Add HexGrid as a dependency to your Package.swift file. 

import PackageDescription

let package = Package(
name: "MyApp",
dependencies: [
...
// Add HexGrid package here
.package(url: "https://github.com/fananek/hex-grid.git", from: "0.4.11")
],
...
targets: [
        .target(name: "App", dependencies: [
            .product(name: "HexGrid", package: "hex-grid"),
            ...

Import HexGrid package to your code.

import HexGrid
...
// your code goes here

Using

Creating a grid

Grids can be initialized either with a set of cell coordinates, or HexGrid can generate some standard shaped grids for you.

Standard shape grids

For example:

...
// create grid of hexagonal shape
var grid = HexGrid(shape: GridShape.hexagon(10))
// or rectangular shape
var grid = HexGrid(shape: GridShape.rectangle(8, 12))
// or triangular shape
var grid = HexGrid(shape: GridShape.triangle(6))

See the section on GridShape below for more details, and a full list of the available grid shapes.

Custom grids

Example:

...
// create new HexGrid

let gridCells: Set<Cell> = try [
Cell(CubeCoordinates(x:  2,  y: -2,  z:  0)),
Cell(CubeCoordinates(x:  0,  y: -1,  z:  1)),
Cell(CubeCoordinates(x: -1,  y:  1,  z:  0)),
Cell(CubeCoordinates(x:  0,  y:  2,  z: -2))
]
var grid = HexGrid(cells: gridCells)
...

Initializers and drawing

Note that, assuming you want to draw your grid, you'll want to think about whether to pass a size for each cell (hexSize) or a size for the entire Grid (pixelSize) to the initializer. (See "Drawing the Grid" below.)

HexGrid <-> JSON

HexGrid conforms to swift Codable protocol so it can be easily encoded to or decoded from JSON.

Example:

// encode (grid to JSON)
let grid = HexGrid(shape: GridShape.hexagon(5) )
let encoder = JSONEncoder()
let data = try encoder.encode(grid)
// decode (JSON to grid)
let decoder = JSONDecoder()
let grid = try decoder.decode(HexGrid.self, from: data)

Grid operations examples

Almost all functions have two variants. One that works with Cell and the other one works with CubeCoordinates. Use those which better fulfill your needs.

Get Cell at coordinates

let cell = grid.cellAt(try CubeCoordinates(x: 1, y: 0, z: -1))

Validate coordinates

Check whether a coordinate is valid (meaning it has a corresponding Cell in the grid's cells array).

// returns Bool
isValidCoordinates(try CubeCoordinates(x: 2, y: 4, z: -6))

Get blocked or non blocked Cells

let blockedCells = grid.blockedCells()
// or
let nonBlockedCells = grid.nonBlockedCells()

Get single neighbor

// get neighbor for a specific Cell
let neighbor = try grid.neighbor(
            for: someCell,
            at: Direction.Pointy.northEast.rawValue)

// get just neighbor coordinates
let neighborCoordinates = try grid.neighborCoordinates(
            for: someCoordinates,
            at: Direction.Pointy.northEast.rawValue)

Get all neighbors

// get all neighbors for a specific Cell
let neighbors = try grid.neighbors(for: someCell)

// get only coordinates of all neighbors
let neighborsCoords = try grid.neighbors(for: someCoordinates)

Get line from A to B

// returns nil in case line doesn't exist
let line = try grid.line(from: originCell, to: targetCell)

Get ring

// returns all cells making a ring from origin cell in radius
let ring = try grid.ring(from: originCell, in: 2)

Get filled ring

// returns all cells making a filled ring from origin cell in radius
let ring = try grid.filledRing(from: originCell, in: 2)

Find reachable cells

// find all reachable cells (max. 4 steps away from origin)
let reachableCells = try grid.findReachable(from: origin, in: 4)

Find shortest path

// returns nil in case path doesn't exist at all
let path = try grid.findPath(from: originCell, to: targetCell)

Calculate field of view (FOV)

Cell has an attribute called isOpaque. Its value can be true or false. Based on this information it's possible to calculate so called field of view. It means all cells visible from specific position on grid, considering all opaque obstacles.

// set cell as opaque
obstacleCell.isOpaque = true

In order to get field of view, simply call following function.

// find all hexes visible in radius 4 from origin cell
let visibleHexes = try grid.fieldOfView(from: originCell, in: 4)

By default cell is considered visible as soon as its center is visible from the origin cell. If you want to include partially visible cells as well, use optional paramter includePartiallyVisible.

// find all hexes even partially visible in radius 4 from origin cell
let visibleHexesIncludingPartials = try grid.fieldOfView(from: originCell, in: 4, includePartiallyVisible: true)

Drawing the Grid

Internally, HexGrid calculates all "pixel coordinates" using one of two methods:

  1. Using a size for each Cell (stored in the hexSize property).

...or...

  1. Using a size for the entire Grid (stored in the pixelSize property).

Note that both the hexSize and pixelSize properties are stored internally as HexSize structures. Try not to get confused by this! HexSize is just a convenient way to store width and height values.

Which flavor of HexGrid initializer you want to use will depend on which of these methods best applies to your use case. When specifying the hexSize, the pixelSize is calculated for you, and when specifying the pixelSize, the hexSize is likewise set automatically.

While it is not possible to modify the hexSize or pixelSize properties directly (after initialization), you can set the grid's pixelSize (and re-calculate hexSize from it) at any time using the fitGrid(in size: HexSize) function. Note that this also resets the origin property.

The origin property

You can think of the HexGrid's' origin property as the center point of the Cell at CubeCoordinate 0,0,0.

Note that you can specify the origin at initialization, but only when using the cellSize method. When specifying pixelSize, the origin is set for you, so the grid "fits" inside the specified width & height.

It will be important to change the origin property any time you want to change the pixel coordinates for your Grid. Changing the origin will modify the return values of all pixel-calculating functions. You can use this to apply an offset for your grid, or "re-center" it later.

Corner Pixel Coordinates

Usually, when drawing hexagons, you will want the screen coordinates of the polygon corners for each Cell.

let corners = grid.polygonCorners(for: someCell)

Center Pixel Coordinates

This function returns a Point struct (x: and y: values) for the center of a Cell.

let screenCoords = grid.pixelCoordinates(for: someCell)

Finding a Cell at screen coordinates

// return cell for specified screen coordinates (or nil if such cell doesn't exists)
let cell = try grid.cellAt(point)

Implementation fundamentals

For detailed information see complete documentation

Data structures you should know

HexGrid

Represents the grid itself as well as it's an entry point of the HexGrid library.

HexGrid is defined by set of Cells and few other properties. All together makes a grid setup. In other words it put grid cells into a meaningful context. Therefore most of available operations are being called directly on a grid instance because it make sense only with such context (grid setup).

Properties:

Cell

Cell is a building block of a grid.

Properties:

CubeCoordinates

The most common coordinates used within HexGrid library is cube coordinate system. This type of coordinates has three axis x, y and z. The only condition is that sum of its all values has to be equal zero.

// valid cube coordinates
CubeCoordinates(x: 1, y: 0, z: -1) -> sum = 0

// invalid cube coordinates
CubeCoordinates(x: 1, y: 1, z: -1) -> sum = 1 -> throws error

For more details check Amit Patel's explanation.

Enumerations

Orientation

Options:

OffsetLayout

OffsetLayout is used primarily for rectangular shaped grids. It has two options but their meaning can differ based on grid orientation.

Options:

There are four offset types depending on orientation of hexagons. The “row” types are used with with pointy top hexagons and the “column” types are used with flat top.

GridShape

Cases from this enumeration can be passed into the HexGrid constructor to generate grids of various shapes and sizes.

Options:

Rotation

Options:

Direction

Direction enumeration is consistent and human recognizable direction naming. Using direction enumeration is not only much more convenient but it also help to avoid errors. It's better to say just "Hey, I'm on cell X and want to go north." than think "What the hack was that index of north direction?", isn't it?

Options:

There is actually separate set of directions for each grid orientation. It's because of two reasons. First, some directions are valid only for one or another orientation. Second, direction raw values are shifted based on orientation.

Authors

See also the list of contributors who participated in this project.

License

All code contained in the HexGrid package is under the MIT license agreement.