hex

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 27, 2025 License: MIT Imports: 8 Imported by: 0

README

Hexagon

Latest Stable Version Build Status Coverage Status Go Report Card Go Dev Reference Software License

Hexagon library for game development.

  • Convert between coordinate systems
  • Map hexes to pixels (and back)

Installation

go get github.com/gravitton/hexagon

Usage

package main

import (
	hex "github.com/gravitton/hexagon"
	geom "github.com/gravitton/geometry"
)

// create hexagon in axial coordinates (q,r) 
a := hex.H(1, -2)
b := hex.H(0, 3)

// use basic math on hexes
c := a.Add(b)
d := a.Subtract(b)
e := a.Multiply(2)
distance := a.DistanceTo(b)

// neighbors and range
neighbors := a.Neighbors()
neighbor := a.Neighbor(hex.DirectionQPlus)
ring := b.Range(2)

// conversions between coordinate systems
pOddR := a.To(hex.OffsetOddR)
pEvenQ := a.To(hex.OffsetEvenQ)
dw := a.To(hex.DoubleWidth)
dh := a.To(hex.DoubleHeight)

// hexagon map layout
layout := hex.LayoutFlatTop(geom.Sz(16, 16), geom.Pt(100, 80))
center := layout.ToPoint(a)
clicked := layout.FromPoint(geom.Pt(499.0, 123.4)).Round()

Credits

License

The MIT License (MIT). Please see License File for more information.

Documentation

Overview

Package hex provides utilities for working with hexagonal grids.

It implements axial (also called cube) coordinates and several common integer offset systems (odd-r, even-r, odd-q, even-q) along with double- width and double-height variants. The package also contains helpers for neighbor lookup, distances, ranges, and converting between axial and offset coordinate systems.

In addition, Layout converts between hex coordinates and pixel space for both flat-top and pointy-top hex orientations, and can generate basic shapes (like a regular hexagon) for rendering.

See README and unit tests for more examples.

Index

Constants

View Source 
const (
	DirectionFlatTopSE = DirectionSMinus
	DirectionFlatTopNE = DirectionQPlus
	DirectionFlatTopN  = DirectionRMinus
	DirectionFlatTopNW = DirectionSPlus
	DirectionFlatTopSW = DirectionQMinus
	DirectionFlatTopS  = DirectionRPlus
)

Direction aliases for flat-top hexes (Axial, OffsetOddQ, OffsetEvenQ, DoubleHeight)

View Source 
const (
	DirectionPointyTopE  = DirectionSMinus
	DirectionPointyTopNE = DirectionQPlus
	DirectionPointyTopNW = DirectionRMinus
	DirectionPointyTopW  = DirectionSPlus
	DirectionPointyTopSW = DirectionQMinus
	DirectionPointyTopSE = DirectionRPlus
)

Direction aliases for pointy-top hexes (Axial, OffsetOddR, OffsetEvenR, DoubleWidth)

Variables

View Source 
var Directions = [6]ints.Vector{
	geom.Vec(1, 0),
	geom.Vec(1, -1),
	geom.Vec(0, -1),
	geom.Vec(-1, 0),
	geom.Vec(-1, 1),
	geom.Vec(0, 1),
}

Directions lists neighbor vectors for axial coordinates in counter-clockwise, starting at (south)-east direction.

View Source 
var DirectionsDoubleHeight = [6]ints.Vector{
	geom.Vec(1, 1),
	geom.Vec(1, -1),
	geom.Vec(0, -2),
	geom.Vec(-1, -1),
	geom.Vec(-1, 1),
	geom.Vec(0, 2),
}

DirectionsDoubleHeight lists neighbor vectors for double-height coordinates.

View Source 
var DirectionsDoubleWidth = [6]ints.Vector{
	geom.Vec(2, 0),
	geom.Vec(1, -1),
	geom.Vec(-1, -1),
	geom.Vec(-2, 0),
	geom.Vec(-1, 1),
	geom.Vec(1, 1),
}

DirectionsDoubleWidth lists neighbor vectors for double-width coordinates.

View Source 
var DirectionsOffsetEvenQ = [2][6]ints.Vector{
	{
		geom.Vec(1, 1),
		geom.Vec(1, 0),
		geom.Vec(0, -1),
		geom.Vec(-1, 0),
		geom.Vec(-1, 1),
		geom.Vec(0, 1),
	},
	{
		geom.Vec(1, 0),
		geom.Vec(1, -1),
		geom.Vec(0, -1),
		geom.Vec(-1, -1),
		geom.Vec(-1, 0),
		geom.Vec(0, 1),
	},
}

DirectionsOffsetEvenQ lists neighbor vectors for even-q offset coordinates as [parityCol][direction], where parityCol=0 for even columns and 1 for odd columns.

View Source 
var DirectionsOffsetEvenR = [2][6]ints.Vector{
	{
		geom.Vec(1, 0),
		geom.Vec(1, -1),
		geom.Vec(0, -1),
		geom.Vec(-1, 0),
		geom.Vec(0, 1),
		geom.Vec(1, 1),
	},
	{
		geom.Vec(1, 0),
		geom.Vec(0, -1),
		geom.Vec(-1, -1),
		geom.Vec(-1, 0),
		geom.Vec(-1, 1),
		geom.Vec(0, 1),
	},
}

DirectionsOffsetEvenR lists neighbor vectors for even-r offset coordinates as [parityRow][direction], where parityRow=0 for even rows and 1 for odd rows.

View Source 
var DirectionsOffsetOddQ = [2][6]ints.Vector{
	{
		geom.Vec(1, 0),
		geom.Vec(1, -1),
		geom.Vec(0, -1),
		geom.Vec(-1, -1),
		geom.Vec(-1, 0),
		geom.Vec(0, 1),
	},
	{
		geom.Vec(1, 1),
		geom.Vec(1, 0),
		geom.Vec(0, -1),
		geom.Vec(-1, 0),
		geom.Vec(-1, 1),
		geom.Vec(0, 1),
	},
}

DirectionsOffsetOddQ lists neighbor vectors for odd-q offset coordinates as [parityCol][direction], where parityCol=0 for even columns and 1 for odd columns.

View Source 
var DirectionsOffsetOddR = [2][6]ints.Vector{
	{
		geom.Vec(1, 0),
		geom.Vec(0, -1),
		geom.Vec(-1, -1),
		geom.Vec(-1, 0),
		geom.Vec(-1, 1),
		geom.Vec(0, 1),
	},
	{
		geom.Vec(1, 0),
		geom.Vec(1, -1),
		geom.Vec(0, -1),
		geom.Vec(-1, 0),
		geom.Vec(0, 1),
		geom.Vec(1, 1),
	},
}

DirectionsOffsetOddR lists neighbor vectors for odd-r offset coordinates as [parityRow][direction], where parityRow=0 for even rows and 1 for odd rows.

Functions

func AssertFracHex added in v1.0.0 

func AssertFracHex(t *testing.T, h FractionalHex, q, r float64, messages ...string)

func AssertHex added in v1.0.0 

func AssertHex(t *testing.T, h Hex, q, r int, messages ...string)

func NeighborOffset 

func NeighborOffset(index ints.Point, system CoordinateSystem, direction Direction) ints.Vector

NeighborOffset returns the neighbor offset vector for the given coordinate in the specified direction and coordinate system.

func NeighborOffsets 

func NeighborOffsets(index ints.Point, system CoordinateSystem) []ints.Vector

NeighborOffsets returns the 6 neighbor offsets for the given coordinate index in the specified coordinate system. For offset systems this accounts for row/column parity when determining neighbor vectors.

func NeighborOffsetsAxial 

func NeighborOffsetsAxial() []ints.Vector

NeighborOffsetsAxial returns the neighbor offsets in axial (cube) coordinate system.

func NeighborOffsetsDoubleHeight 

func NeighborOffsetsDoubleHeight() []ints.Vector

NeighborOffsetsDoubleHeight returns the neighbor offsets in double-height coordinate system.

func NeighborOffsetsDoubleWidth 

func NeighborOffsetsDoubleWidth() []ints.Vector

NeighborOffsetsDoubleWidth returns the neighbor offsets in double-width coordinate system.

func NeighborOffsetsOffsetEvenQ 

func NeighborOffsetsOffsetEvenQ(index ints.Point) []ints.Vector

NeighborOffsetsOffsetEvenQ returns the neighbor offsets in even-q offset coordinate system.

func NeighborOffsetsOffsetEvenR 

func NeighborOffsetsOffsetEvenR(index ints.Point) []ints.Vector

NeighborOffsetsOffsetEvenR returns the neighbor offsets in even-r offset coordinate system.

func NeighborOffsetsOffsetOddQ 

func NeighborOffsetsOffsetOddQ(index ints.Point) []ints.Vector

NeighborOffsetsOffsetOddQ returns the neighbor offsets in odd-q offset coordinate system.

func NeighborOffsetsOffsetOddR 

func NeighborOffsetsOffsetOddR(index ints.Point) []ints.Vector

NeighborOffsetsOffsetOddR returns the neighbor offsets in odd-r offset coordinate system.

func To 

func To(hex Hex, system CoordinateSystem) ints.Point

To converts an axial hex to the given coordinate system as an ints.Point.

func ToAxial 

func ToAxial(hex Hex) ints.Point

ToAxial returns the axial (q,r) as an ints.Point.

func ToDoubleHeight 

func ToDoubleHeight(hex Hex) ints.Point

ToDoubleHeight converts axial to double-height coordinates (doubling the r axis).

func ToDoubleWidth 

func ToDoubleWidth(hex Hex) ints.Point

ToDoubleWidth converts axial to double-width coordinates (doubling the q axis).

func ToOffsetEvenQ 

func ToOffsetEvenQ(hex Hex) ints.Point

ToOffsetEvenQ converts axial to even-q offset coordinates. Even columns are shifted down by +1/2 row.

func ToOffsetEvenR 

func ToOffsetEvenR(hex Hex) ints.Point

ToOffsetEvenR converts axial to even-r offset coordinates. Even rows are shifted right by +1/2 column.

func ToOffsetOddQ 

func ToOffsetOddQ(hex Hex) ints.Point

ToOffsetOddQ converts axial to odd-q offset coordinates. Odd columns are shifted down by +1/2 row.

func ToOffsetOddR 

func ToOffsetOddR(hex Hex) ints.Point

ToOffsetOddR converts axial to odd-r offset coordinates. Odd rows are shifted right by +1/2 column.

Types

type CoordinateSystem 

type CoordinateSystem int

CoordinateSystem enumerates supported hexagonal grid coordinate systems. 

const (
	Axial        CoordinateSystem = iota // Axial (Cube) coordinates (q, r, s)
	OffsetOddR                           // Odd rows are offset (pointy-top hexes)
	OffsetEvenR                          // Even rows are offset (pointy-top hexes)
	OffsetOddQ                           // Odd columns are offset (flat-top hexes)
	OffsetEvenQ                          // Even columns are offset (flat-top hexes)
	DoubleWidth                          // Double cols (pointy-top hexes)
	DoubleHeight                         // Double rows (flat-top hexes)
)

type Direction 

type Direction int

Direction represents one of the six neighbor directions around a hex.

Constants for the directions from a Hex. - Q+ increments q and compensates by decrementing r. - R+ increments r and compensates by decrementing s (-q-r). - S+ increments s (-q-r) compensates by decrementing q. 

const (
	DirectionSMinus Direction = iota // -S, flat-top SE, pointy-top E
	DirectionQPlus                   // +Q, flat-top NE, pointy-top NE
	DirectionRMinus                  // -R, flat-top N,  pointy-top NW
	DirectionSPlus                   // +S, flat-top NW, pointy-top W
	DirectionQMinus                  // -Q, flat-top SW, pointy-top SW
	DirectionRPlus                   // +R, flat-top S,  pointy-top SE
)

func (Direction) NeighborOffset 

func (d Direction) NeighborOffset() ints.Vector

NeighborOffset returns the neighbor offset vector for the given direction.

type FractionalHex 

type FractionalHex struct {
	Q, R float64
}

FractionalHex represents a hex with floating-point axial coordinates. Useful for interpolation and conversions from pixel space before rounding.

func F 

func F(q, r float64) FractionalHex

F is shorthand for FractionalHex{q, r}.

func (FractionalHex) Lerp 

func (h FractionalHex) Lerp(hex FractionalHex, t float64) FractionalHex

Lerp creates a new FractionalHex in linear interpolation towards given hex.

func (FractionalHex) Point added in v1.0.0 

func (h FractionalHex) Point() floats.Point

Point returns the axial (q,r) as a floats.Point.

func (FractionalHex) QR 

func (h FractionalHex) QR() (float64, float64)

QR returns the (q, r) coordinates.

func (FractionalHex) QRS 

func (h FractionalHex) QRS() (float64, float64, float64)

QRS returns the (q, r, s) coordinates where s is implied.

func (FractionalHex) Round 

func (h FractionalHex) Round() Hex

Round converts a FractionalHex to the nearest Hex while preserving q+r+s=0.

func (FractionalHex) S 

func (h FractionalHex) S() float64

S returns the implied s coordinate (-q - r).

func (FractionalHex) String 

func (h FractionalHex) String() string

String returns a compact representation of the fractional hex as (q,r) with 2 decimals.

type Hex 

type Hex struct {
	Q, R int
}

Hex represents a hexagon in axial (cube) coordinates using integer q and r. The third coordinate s is implied by s = -q - r.

func From 

func From(index ints.Point, system CoordinateSystem) Hex

From converts a coordinate in the given system into an axial Hex.

func FromAxial 

func FromAxial(index ints.Point) Hex

FromAxial converts an ints.Point (q,r) into an axial Hex.

func FromDoubleHeight 

func FromDoubleHeight(index ints.Point) Hex

FromDoubleHeight converts a double-height coordinate to axial.

func FromDoubleWidth 

func FromDoubleWidth(index ints.Point) Hex

FromDoubleWidth converts a double-width coordinate to axial.

func FromOffsetEvenQ 

func FromOffsetEvenQ(index ints.Point) Hex

FromOffsetEvenQ converts an even-q offset coordinate to axial.

func FromOffsetEvenR 

func FromOffsetEvenR(index ints.Point) Hex

FromOffsetEvenR converts an even-r offset coordinate to axial.

func FromOffsetOddQ 

func FromOffsetOddQ(index ints.Point) Hex

FromOffsetOddQ converts an odd-q offset coordinate to axial.

func FromOffsetOddR 

func FromOffsetOddR(index ints.Point) Hex

FromOffsetOddR converts an odd-r offset coordinate to axial.

func FromPoint 

func FromPoint(index ints.Point) Hex

FromPoint is alias to FromAxial.

func H 

func H(q, r int) Hex

H is shorthand for Hex{q, r}.

func (Hex) Add 

func (h Hex) Add(hex Hex) Hex

Add returns a new Hex that is the vector sum of h and hex.

func (Hex) DistanceTo 

func (h Hex) DistanceTo(hex Hex) int

DistanceTo returns the hex distance between h and the given hex.

func (Hex) FieldOfView 

func (h Hex) FieldOfView(candidates []Hex, blocking []Hex) []Hex

FieldOfView returns the subset of candidate hexes visible from this hex, taking into account a set of blocking hexagons.

func (Hex) HasLineOfSight 

func (h Hex) HasLineOfSight(target Hex, blocking []Hex) bool

HasLineOfSight checks if the target hex is visible from this hex, taking into account a set of blocking hexagons.

func (Hex) Length 

func (h Hex) Length() int

Length returns the distance from the origin (0,0) in hex steps.

func (Hex) Line 

func (h Hex) Line(target Hex) []Hex

Line returns the sequence of hexes that connects this hex to target in a straight line.

func (Hex) Multiply 

func (h Hex) Multiply(factor int) Hex

Multiply creates a new Hex scaled by the given integer factor.

func (Hex) Neighbor 

func (h Hex) Neighbor(direction Direction) Hex

Neighbor returns the neighboring hex of h in the given direction.

func (Hex) Neighbors 

func (h Hex) Neighbors() []Hex

Neighbors returns the six neighboring hexes around h in axial coordinates.

func (Hex) Point added in v1.0.0 

func (h Hex) Point() ints.Point

Point returns (q,r) as a ints.Point.

func (Hex) QR 

func (h Hex) QR() (int, int)

QR returns the (q, r) coordinates.

func (Hex) QRS 

func (h Hex) QRS() (int, int, int)

QRS returns the (q, r, s) coordinates where s is implied.

func (Hex) Range 

func (h Hex) Range(n int) []Hex

Range returns the set of hexes within radius n around h, inclusive of h. When n < 0, it returns nil, when n == 0, it returns itself.

func (Hex) S 

func (h Hex) S() int

S returns the implied s coordinate (-q - r).

func (Hex) String 

func (h Hex) String() string

String returns a compact representation of the hex as (q,r).

func (Hex) Subtract 

func (h Hex) Subtract(hex Hex) Hex

Subtract creates a new Hex that is the vector difference h - hex.

func (Hex) To 

func (h Hex) To(system CoordinateSystem) ints.Point

To converts the hex into the specified coordinate system, returning an ints.Point.

type Layout 

type Layout struct {
	Size   floats.Size  // multiplication factor relative to the canonical hexagon
	Origin floats.Point // center Point for hexagon with coordinates (0,0)
	// contains filtered or unexported fields
}

Layout describes the mapping between hex coordinates and pixel space. It holds the hex orientation (flat-top or pointy-top), the hex Size (used as a scaling factor relative to a canonical hex), and the pixel Origin that corresponds to the axial hex (0,0) center.

func LayoutFlatTop 

func LayoutFlatTop(size floats.Size, origin floats.Point) Layout

LayoutFlatTop constructs a Layout for flat-top hexes with the given size and origin.

func LayoutPointyTop 

func LayoutPointyTop(size floats.Size, origin floats.Point) Layout

LayoutPointyTop constructs a Layout for pointy-top hexes with the given size and origin.

func (Layout) Bounds 

func (l Layout) Bounds() floats.Size

Bounds returns the pixel width/height of a single hex cell in this layout.

func (Layout) FromPoint 

func (l Layout) FromPoint(point floats.Point) FractionalHex

FromPoint converts a pixel point to a fractional hex in the layout.

func (Layout) Hexagon 

func (l Layout) Hexagon(h Hex) floats.RegularPolygon

Hexagon creates a floats.RegularPolygon representing the hex cell in pixel space.

func (Layout) Spacing 

func (l Layout) Spacing() floats.Size

Spacing returns the horizontal and vertical distances between adjacent hex centers.

func (Layout) ToPoint 

func (l Layout) ToPoint(hex Hex) floats.Point

ToPoint converts a hex to the pixel coordinates of its center in the layout.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.