Struct HexCoord

Represents an axial coordinate in a hexagonal grid. Uses the axial (q, r) system where the third cube coordinate s = -q - r is computed on demand. This is the recommended storage format for hex grids (Amit Patel / Red Blob Games).

Implements

IEquatable<HexCoord>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.Core.Structures

Assembly: ScyllaCore.dll

Syntax

public readonly struct HexCoord : IEquatable<HexCoord>

Remarks

Axial coordinates store only two of the three cube-coordinate axes (Q and R). The third axis S is always derivable as S = -Q - R, satisfying the cube constraint Q + R + S = 0. This saves one integer of storage per cell while preserving all geometric properties of cube coordinates.

The six static direction vectors (NE, E, SE, SW, W, NW) are unit steps in axial space. Adding one to a coordinate moves to the adjacent hex in that direction. Directions are indexed 0-5 in clockwise order starting from NE; use Direction(int) to retrieve them by index with automatic wrapping.

HexCoord is a value type and safe to use as a dictionary key. It implements IEquatable<T> and overrides GetHashCode().

To convert between axial coordinates and world-space positions, use GridToWorld(HexCoord) and WorldToGrid(Vector2). For intermediate floating-point positions (e.g. during line drawing or world-to-grid snapping), use FractionalHexCoord and its Round() method.

Constructors

HexCoord(int, int)

Creates a new hex coordinate with the specified axial values. The S axis value is derived on demand as -q - r.

Declaration

public HexCoord(int q, int r)

Parameters

Type	Name	Description
int	q	The Q axis value (column).
int	r	The R axis value (row).

Fields

E

Direction vector for east: (+1, 0).

Declaration

public static readonly HexCoord E

Field Value

Type	Description
HexCoord

NE

Direction vector for northeast: (+1, -1).

Declaration

public static readonly HexCoord NE

Field Value

Type	Description
HexCoord

NW

Direction vector for northwest: (0, -1).

Declaration

public static readonly HexCoord NW

Field Value

Type	Description
HexCoord

Q

The Q axis value (column in axial coordinates). In a pointy-top grid, Q increases toward the right; in a flat-top grid, Q increases toward the lower-right.

Declaration

public readonly int Q

Field Value

Type	Description
int

R

The R axis value (row in axial coordinates). In a pointy-top grid, R increases downward; in a flat-top grid, R increases downward-right.

Declaration

public readonly int R

Field Value

Type	Description
int

SE

Direction vector for southeast: (0, +1).

Declaration

public static readonly HexCoord SE

Field Value

Type	Description
HexCoord

SW

Direction vector for southwest: (-1, +1).

Declaration

public static readonly HexCoord SW

Field Value

Type	Description
HexCoord

W

Direction vector for west: (-1, 0).

Declaration

public static readonly HexCoord W

Field Value

Type	Description
HexCoord

Zero

The origin coordinate (0, 0). Represents the center hex of a grid centered at the origin. Equivalent to default(HexCoord).

Declaration

public static readonly HexCoord Zero

Field Value

Type	Description
HexCoord

Properties

S

The computed S axis value: -Q - R. Satisfies the cube constraint Q + R + S = 0. Not stored directly; computed on demand to save memory.

Declaration

public int S { get; }

Property Value

Type	Description
int

Methods

Diagonal(int)

Returns the diagonal direction vector at the given index (0-5), wrapping around using modular arithmetic. Each diagonal points to a hex two steps away through a shared corner (cube distance 2).

Declaration

public static HexCoord Diagonal(int index)

Parameters

Type	Name	Description
int	index	The diagonal index. Values outside the range 0-5 are wrapped using ((index % 6) + 6) % 6, so negative indices are also handled correctly.

Returns

Type	Description
HexCoord	One of the six diagonal direction vectors as a HexCoord.

See Also

DiagonalNeighbor(int)

DiagonalNeighbor(int)

Returns the diagonal neighbor of this coordinate in the specified direction. Equivalent to this + Diagonal(int)(direction); the result is two steps away through a shared corner.

Declaration

public HexCoord DiagonalNeighbor(int direction)

Parameters

Type	Name	Description
int	direction	The diagonal index (0-5). Values outside this range are wrapped automatically.

Returns

Type	Description
HexCoord	The HexCoord two steps away at the given diagonal.

Direction(int)

Returns the direction vector at the given index (0-5), wrapping around using modular arithmetic. Index 0 = NE, 1 = E, 2 = SE, 3 = SW, 4 = W, 5 = NW (clockwise order).

Declaration

public static HexCoord Direction(int index)

Parameters

Type	Name	Description
int	index	The direction index. Values outside the range 0-5 are wrapped using ((index % 6) + 6) % 6, so negative indices are also handled correctly.

Returns

Type	Description
HexCoord	One of the six unit direction vectors as a HexCoord.

Distance(HexCoord, HexCoord)

Computes the hex distance between two coordinates. Equivalent to the minimum number of steps required to walk from a to b moving through adjacent hexes one step at a time.

Declaration

public static int Distance(HexCoord a, HexCoord b)

Parameters

Type	Name	Description
HexCoord	a	The first coordinate.
HexCoord	b	The second coordinate.

Returns

Type	Description
int	The non-negative hex distance. Returns 0 when a equals b.

Remarks

The hex distance is computed using the cube-coordinate formula: max(|dq|, |dr|, |ds|) where dq = a.Q - b.Q, etc. All three differences are computed using long arithmetic to prevent integer overflow when coordinates have extreme values near MinValue or MaxValue.

DistanceTo(HexCoord)

Computes the hex distance from this coordinate to other. Convenience wrapper for Distance(HexCoord, HexCoord).

Declaration

public int DistanceTo(HexCoord other)

Parameters

Type	Name	Description
HexCoord	other	The target coordinate.

Returns

Type	Description
int	The non-negative minimum number of steps to reach other.

Equals(HexCoord)

Determines whether this coordinate equals another coordinate.

Declaration

public bool Equals(HexCoord other)

Parameters

Type	Name	Description
HexCoord	other	The coordinate to compare with.

Returns

Type	Description
bool	True if both coordinates have equal Q and R values.

Equals(object)

Determines whether this coordinate equals another object.

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
object	obj	The object to compare with.

Returns

Type	Description
bool	True if the object is a HexCoord with equal values.

Overrides

ValueType.Equals(object)

GetHashCode()

Returns a hash code for this coordinate.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	A hash code based on Q and R.

Overrides

ValueType.GetHashCode()

GetNeighbor(int)

Returns the neighbor of this coordinate in the specified direction. Equivalent to this + Direction(int)(direction).

Declaration

public HexCoord GetNeighbor(int direction)

Parameters

Type	Name	Description
int	direction	The direction index (0-5). 0 = NE, 1 = E, 2 = SE, 3 = SW, 4 = W, 5 = NW. Values outside this range are wrapped automatically.

Returns

Type	Description
HexCoord	The HexCoord one step away in the given direction.

ReflectQ(HexCoord)

Reflects a coordinate across the Q axis by swapping R and S: (q, r, s) -> (q, s, r). In axial form this returns (q, -q - r).

Declaration

public static HexCoord ReflectQ(HexCoord coord)

Parameters

Type	Name	Description
HexCoord	coord	The coordinate to reflect.

Returns

Type	Description
HexCoord	The coordinate reflected across the Q axis.

See Also

ReflectR(HexCoord)

ReflectS(HexCoord)

ReflectQ(HexCoord, HexCoord)

Reflects a coordinate across the Q axis passing through center. Equivalent to translating so center is the origin, reflecting, then translating back.

Declaration

public static HexCoord ReflectQ(HexCoord coord, HexCoord center)

Parameters

Type	Name	Description
HexCoord	coord	The coordinate to reflect.
HexCoord	center	The pivot the reflection axis passes through.

Returns

Type	Description
HexCoord	The coordinate reflected across the Q axis through center.

See Also

ReflectQ(HexCoord)

ReflectR(HexCoord)

Reflects a coordinate across the R axis by swapping Q and S: (q, r, s) -> (s, r, q). In axial form this returns (-q - r, r).

Declaration

public static HexCoord ReflectR(HexCoord coord)

Parameters

Type	Name	Description
HexCoord	coord	The coordinate to reflect.

Returns

Type	Description
HexCoord	The coordinate reflected across the R axis.

See Also

ReflectQ(HexCoord)

ReflectS(HexCoord)

ReflectR(HexCoord, HexCoord)

Reflects a coordinate across the R axis passing through center. Equivalent to translating so center is the origin, reflecting, then translating back.

Declaration

public static HexCoord ReflectR(HexCoord coord, HexCoord center)

Parameters

Type	Name	Description
HexCoord	coord	The coordinate to reflect.
HexCoord	center	The pivot the reflection axis passes through.

Returns

Type	Description
HexCoord	The coordinate reflected across the R axis through center.

See Also

ReflectR(HexCoord)

ReflectS(HexCoord)

Reflects a coordinate across the S axis by swapping Q and R: (q, r, s) -> (r, q, s). In axial form this returns (r, q).

Declaration

public static HexCoord ReflectS(HexCoord coord)

Parameters

Type	Name	Description
HexCoord	coord	The coordinate to reflect.

Returns

Type	Description
HexCoord	The coordinate reflected across the S axis.

See Also

ReflectQ(HexCoord)

ReflectR(HexCoord)

ReflectS(HexCoord, HexCoord)

Reflects a coordinate across the S axis passing through center. Equivalent to translating so center is the origin, reflecting, then translating back.

Declaration

public static HexCoord ReflectS(HexCoord coord, HexCoord center)

Parameters

Type	Name	Description
HexCoord	coord	The coordinate to reflect.
HexCoord	center	The pivot the reflection axis passes through.

Returns

Type	Description
HexCoord	The coordinate reflected across the S axis through center.

See Also

ReflectS(HexCoord)

RotateCCW(HexCoord)

Rotates a coordinate 60 degrees counter-clockwise around the origin. Applies the cube-space rotation (q, r, s) -> (-s, -q, -r). Calling this method six times returns the original coordinate.

Declaration

public static HexCoord RotateCCW(HexCoord coord)

Parameters

Type	Name	Description
HexCoord	coord	The coordinate to rotate around the origin.

Returns

Type	Description
HexCoord	The coordinate rotated 60 degrees counter-clockwise.

See Also

RotateCW(HexCoord)

RotateCW(HexCoord)

Rotates a coordinate 60 degrees clockwise around the origin. Applies the cube-space rotation (q, r, s) -> (-r, -s, -q). Calling this method six times returns the original coordinate.

Declaration

public static HexCoord RotateCW(HexCoord coord)

Parameters

Type	Name	Description
HexCoord	coord	The coordinate to rotate around the origin.

Returns

Type	Description
HexCoord	The coordinate rotated 60 degrees clockwise.

See Also

RotateCCW(HexCoord)

ToString()

Returns a string representation of this coordinate.

Declaration

public override string ToString()

Returns

Type	Description
string	A string in the format "(Q, R)".

Overrides

ValueType.ToString()

Operators

operator +(HexCoord, HexCoord)

Adds two hex coordinates component-wise: (a.Q + b.Q, a.R + b.R). Used to translate a coordinate by a direction vector.

Declaration

public static HexCoord operator +(HexCoord a, HexCoord b)

Parameters

Type	Name	Description
HexCoord	a	The left operand.
HexCoord	b	The right operand (often a direction vector such as NE).

Returns

Type	Description
HexCoord	The component-wise sum.

operator ==(HexCoord, HexCoord)

Returns true if left and right have equal Q and R values.

Declaration

public static bool operator ==(HexCoord left, HexCoord right)

Parameters

Type	Name	Description
HexCoord	left	The left operand.
HexCoord	right	The right operand.

Returns

Type	Description
bool

operator !=(HexCoord, HexCoord)

Returns true if left and right have different Q or R values.

Declaration

public static bool operator !=(HexCoord left, HexCoord right)

Parameters

Type	Name	Description
HexCoord	left	The left operand.
HexCoord	right	The right operand.

Returns

Type	Description
bool

operator *(HexCoord, int)

Scales a hex coordinate by an integer scalar: (coord.Q * scalar, coord.R * scalar). Useful for computing ring or range offsets.

Declaration

public static HexCoord operator *(HexCoord coord, int scalar)

Parameters

Type	Name	Description
HexCoord	coord	The coordinate to scale.
int	scalar	The integer multiplier.

Returns

Type	Description
HexCoord	The scaled coordinate.

operator *(int, HexCoord)

Scales a hex coordinate by an integer scalar: (coord.Q * scalar, coord.R * scalar). Commutative overload of coord * scalar.

Declaration

public static HexCoord operator *(int scalar, HexCoord coord)

Parameters

Type	Name	Description
int	scalar	The integer multiplier.
HexCoord	coord	The coordinate to scale.

Returns

Type	Description
HexCoord	The scaled coordinate.

operator -(HexCoord, HexCoord)

Subtracts b from a component-wise: (a.Q - b.Q, a.R - b.R). The result is the displacement vector from b to a.

Declaration

public static HexCoord operator -(HexCoord a, HexCoord b)

Parameters

Type	Name	Description
HexCoord	a	The left operand.
HexCoord	b	The right operand.

Returns

Type	Description
HexCoord	The component-wise difference.

operator -(HexCoord)

Negates both components: (-coord.Q, -coord.R). Points to the hex diametrically opposite the given coordinate relative to the origin.

Declaration

public static HexCoord operator -(HexCoord coord)

Parameters

Type	Name	Description
HexCoord	coord	The coordinate to negate.

Returns

Type	Description
HexCoord	The negated coordinate.

Implements

IEquatable<T>