Struct HexGridLayout

Defines the spatial layout for a hexagonal grid, providing conversion between axial hex coordinates and world-space positions. Supports both flat-top and pointy-top orientations. Uses precomputed 2x2 forward and inverse matrices for efficient O(1) conversion.

Implements

IEquatable<HexGridLayout>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.Core.Structures

Assembly: ScyllaCore.dll

Syntax

public readonly struct HexGridLayout : IEquatable<HexGridLayout>

Remarks

A HexGridLayout is a lightweight value type that encodes five parameters: Size (the X circumradius, aliased as SizeX), SizeY (the Y circumradius, equal to Size for uniform layouts), Orientation, and the world-space origin (OriginX, OriginY). All conversion logic is precomputed into two 2x2 matrices stored in eight private fields (_f0.._f3 forward, _b0.._b3 inverse).

Grid-to-world conversion (GridToWorld(HexCoord)) applies the forward matrix, scaling X by Size and Y by SizeY, then adds the origin offset. World-to-grid conversion (WorldToGrid(Vector2)) subtracts the origin, divides X by Size and Y by SizeY, applies the inverse matrix, and rounds via Round().

Use GetCornerOffset(int) to compute individual vertex positions for rendering hex cell outlines or placing geometry at corners.

Equality comparison uses exact floating-point equality. Two layouts created with identical parameters compare equal.

Constructors

HexGridLayout(float, HexOrientation, float, float)

Creates a new hex grid layout with the specified size, orientation, and world-space origin. Precomputes the forward and inverse transformation matrices for efficient runtime conversion.

Declaration

public HexGridLayout(float size, HexOrientation orientation, float originX = 0, float originY = 0)

Parameters

Type	Name	Description
float	size	The hex circumradius (distance from center to vertex) in world units. Must be a finite number greater than zero.
HexOrientation	orientation	The hex orientation (PointyTop or FlatTop). Determines which precomputed matrix values are stored.
float	originX	The X world-space position of the hex at axial coordinate (0, 0). Defaults to 0. Must be a finite number.
float	originY	The Y world-space position of the hex at axial coordinate (0, 0). Defaults to 0. Must be a finite number.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown when `size` is not a finite positive number, or when `originX` or `originY` is NaN or infinite.

HexGridLayout(float, float, HexOrientation, float, float)

Creates a new hex grid layout with independent X and Y circumradii, allowing squashed or stretched (non-uniform) hexes. Precomputes the forward and inverse transformation matrices.

Declaration

public HexGridLayout(float sizeX, float sizeY, HexOrientation orientation, float originX = 0, float originY = 0)

Parameters

Type	Name	Description
float	sizeX	The hex circumradius along X in world units. Must be a finite number greater than zero.
float	sizeY	The hex circumradius along Y in world units. Must be a finite number greater than zero.
HexOrientation	orientation	The hex orientation (PointyTop or FlatTop).
float	originX	The X world-space position of the hex at axial coordinate (0, 0). Defaults to 0.
float	originY	The Y world-space position of the hex at axial coordinate (0, 0). Defaults to 0.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown when `sizeX` or `sizeY` is not a finite positive number, or when `originX` or `originY` is NaN or infinite.

Fields

Orientation

The hex orientation (flat-top or pointy-top). Determines the forward and inverse transformation matrices stored in this layout.

Declaration

public readonly HexOrientation Orientation

Field Value

Type	Description
HexOrientation

OriginX

The X position of the grid origin in world space. Added to every grid-to-world result; subtracted before every world-to-grid conversion.

Declaration

public readonly float OriginX

Field Value

Type	Description
float

OriginY

The Y position of the grid origin in world space. Added to every grid-to-world result; subtracted before every world-to-grid conversion.

Declaration

public readonly float OriginY

Field Value

Type	Description
float

Size

The hex circumradius along the X axis: the horizontal distance in world units from a hex center to a vertex. For uniform layouts this equals SizeY and the hex side length. Must be a finite positive number greater than zero. Equivalent to SizeX.

Declaration

public readonly float Size

Field Value

Type	Description
float

SizeY

The hex circumradius along the Y axis. Equals Size for uniform layouts; differs for squashed or stretched layouts created with the non-uniform constructor. Must be a finite positive number greater than zero.

Declaration

public readonly float SizeY

Field Value

Type	Description
float

Properties

SizeX

The hex circumradius along the X axis. Alias for Size, provided to pair naturally with SizeY.

Declaration

public float SizeX { get; }

Property Value

Type	Description
float

Methods

Equals(HexGridLayout)

Determines whether this layout equals another layout using exact floating-point comparison. Two layouts are equal when Size, SizeY, Orientation, OriginX, and OriginY are all identical.

Declaration

public bool Equals(HexGridLayout other)

Parameters

Type	Name	Description
HexGridLayout	other	The layout to compare with.

Returns

Type	Description
bool	true if all five layout parameters are exactly equal; false otherwise.

Equals(object)

Determines whether this layout 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 HexGridLayout with equal values.

Overrides

ValueType.Equals(object)

GetCornerOffset(int)

Computes the world-space offset of the specified corner vertex relative to the center of any hex in this layout.

Declaration

public Vector2 GetCornerOffset(int corner)

Parameters

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

Returns

Type	Description
Vector2	The 2D offset vector from the hex center to the specified corner vertex.

Remarks

Corners are indexed 0-5 in counter-clockwise order starting from the start angle determined by Orientation:

PointyTop: corner 0 is at 30 degrees (upper-right vertex).
FlatTop: corner 0 is at 0 degrees (right vertex).

For uniform layouts the returned offset has magnitude equal to Size (the circumradius). For non-uniform layouts (when Size differs from SizeY) the corners trace an ellipse: the X component is scaled by Size and the Y component by SizeY, so the magnitude varies with the angle. To get the absolute world position of a corner, add the result to the hex center obtained from GridToWorld(HexCoord). Values outside 0-5 are wrapped using modular arithmetic.

GetHashCode()

Returns a hash code for this layout.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	A hash code based on all layout parameters.

Overrides

ValueType.GetHashCode()

GridToWorld(HexCoord)

Converts an axial hex coordinate to the world-space position of the hex center. Applies the precomputed forward matrix scaled by Size, then adds the origin offset.

Declaration

public Vector2 GridToWorld(HexCoord coord)

Parameters

Type	Name	Description
HexCoord	coord	The axial hex coordinate to convert.

Returns

Type	Description
Vector2	The world-space 2D position of the center of the hex at `coord`. For Zero this always returns `(OriginX, OriginY)`.

ToString()

Returns a string representation of this layout.

Declaration

public override string ToString()

Returns

Type	Description
string	A string describing the size, orientation, and origin.

Overrides

ValueType.ToString()

WorldToGrid(Vector2)

Converts a world-space position to the nearest integer hex coordinate. Subtracts the origin, divides X by Size and Y by SizeY, applies the precomputed inverse matrix to produce a FractionalHexCoord, then rounds to the nearest hex using the cube rounding algorithm.

Declaration

public HexCoord WorldToGrid(Vector2 worldPos)

Parameters

Type	Name	Description
Vector2	worldPos	The world-space 2D position to snap to the grid.

Returns

Type	Description
HexCoord	The HexCoord whose center is closest to `worldPos`.

Operators

operator ==(HexGridLayout, HexGridLayout)

Returns true if left and right have identical size, orientation, and origin values.

Declaration

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

Parameters

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

Returns

Type	Description
bool

operator !=(HexGridLayout, HexGridLayout)

Returns true if left and right differ in size, orientation, or origin.

Declaration

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

Parameters

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

Returns

Type	Description
bool

Implements

IEquatable<T>