Development in progress!
API might change without further notice until first major release 1.x.x.
HexGrid library provides 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 not offer any UI or rendering stuff. However, it provides calculations needed for grid rendering.
n
steps (Breath First Search).ShadowCasting
designed for hexagonal grids).See the demo app.
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.6")
],
...
targets: [
.target(name: "App", dependencies: [
.product(name: "HexGrid", package: "hex-grid"),
...
Import HexGrid package to your code.
import HexGrid
...
// your code goes here
Grid can be initialized either with set of cells or HexGrid can generate some of standard shapes for you.
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))
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)
...
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)
Almost all functions has two variants. One works with Cell
and the other one works with CubeCoordinates
. Use those which better fulfill your needs.
let cell = grid.cellAt(try CubeCoordinates(x: 1, y: 0, z: -1))
Check whether some coordinates are valid (means it exist on a grid).
// returns Bool
isValidCoordinates(try CubeCoordinates(x: 2, y: 4, z: -6))
let blockedCells = grid.blockedCells()
// or
let nonBlockedCells = grid.nonBlockedCells()
// 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 for a specific Cell
let neighbors = try grid.neighbors(for: someCell)
// get only coordinates of all neighbors
let neighborsCoords = try grid.neighbors(for: someCoordinates)
// returns nil in case line doesn't exist
let line = try grid.line(from: originCell, to: targetCell)
// returns all cells making a ring from origin cell in radius
let ring = try grid.ring(from: originCell, in: 2)
// returns all cells making a filled ring from origin cell in radius
let ring = try grid.filledRing(from: originCell, in: 2)
// find all reachable cells (max. 4 steps away from origin)
let reachableCells = try grid.findReachable(from: origin, in: 4)
// returns nil in case path doesn't exist at all
let path = try grid.findPath(from: originCell, to: targetCell)
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 opque 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)
If you want to render a grid, you will need screen coordinates of polygon corners for a Cell
.
let corners = grid.polygonCorners(for: someCell)
Converting cell coordinates to pixel coordinates and vice versa might be handy as well.
// return Ponit struct with x: and y: values
let screenCoords = grid.pixelCoordinates(for: cell)
// return cell for specified screen coordinates (or nil if such cell doesn't exists)
let cell = try grid.cellAt(point)
For detailed information see complete documentation
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:
Set<Cell>
- grid cellsOrientation
- see Orientation enumerationOffsetLayout
- see OffsetLayout enumerationHexSize
- width and height of a hexagonPoint
- 'display coordinates' (x, y) of a grid originDouble
- pixel width of a gridDouble
- pixel width of a grid[String: Attribute]
- dictionary of custom attributes (most primitive types are supported as well as nesting)Cell is a building block of a grid.
Properties:
CubeCoordinates
- cell placement on a grid coordinate system[String: Attribute]
- dictionary of custom attributes (most primitive types are supported as well as nesting)Bool
- used by algorithms (reachableCells, pathfinding etc.)Bool
- used by fieldOfView algorithmFloat
- used by pathfinding algorithm. For the sake of simplicity let's put graph theory aside. You can imagine cost as an amount of energy needed to pass a cell. Pathfinding algorithm then search for path requiring the less effort.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.
Options:
pointyOnTop
- β¬’flatOnTop
- ⬣OffsetLayout is used primarily for rectangular shaped grids. It has two options but their meaning can differ based on grid orientation.
Options:
odd
even
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.
Options:
rectangle(Int, Int)
- rectangle width and heighthexagon(Int)
- radius of hexagontriangle(Int)
- size of triangle sideOptions:
left
right
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:
Direction.Flat
north
northEast
southEast
south
southWest
northWest
Direction.Pointy
northEast
east
southEast
southWest
west
northWest
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.
See also the list of contributors who participated in this project.
All code contained in the HexGrid package is under the MIT license agreement.
link |
Stars: 21 |
Last commit: 2 weeks ago |
Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics