hex-math
Reference for hexagonal grid algorithms and coordinate systems. Use when implementing movement, pathfinding, range calculations, or line of sight. Triggers on "hex", "hexagon", "grid", "coordinates", "pathfinding", "neighbors".
When & Why to Use This Skill
This Claude skill serves as a comprehensive technical reference for hexagonal grid mathematics and algorithms. It solves the complexity of spatial logic in game development and data visualization by providing optimized formulas for coordinate systems (Cube and Offset), pathfinding, distance calculations, and line-of-sight, enabling developers to implement robust hex-based mechanics quickly and accurately.
Use Cases
- Game Development: Implementing movement, pathfinding, and tactical range calculations for hex-based strategy or board games.
- Coordinate Conversion: Seamlessly transforming between Cube, Offset, and Pixel coordinates to bridge the gap between mathematical logic and UI rendering.
- Spatial Queries: Calculating line-of-sight, field-of-view, and area-of-effect (AOE) patterns within a hexagonal grid environment.
- Interactive Maps: Mapping user input (pixel-based clicks) to specific grid cells for interactive map editors or data dashboards.
| name | hex-math |
|---|---|
| description | Reference for hexagonal grid algorithms and coordinate systems. Use when implementing movement, pathfinding, range calculations, or line of sight. Triggers on "hex", "hexagon", "grid", "coordinates", "pathfinding", "neighbors". |
| allowed-tools | Read |
Hex Grid Mathematics Reference
Coordinate Systems
Cube Coordinates (Recommended)
- Three axes: q, r, s where q + r + s = 0
- Best for algorithms and math
- Easy neighbor calculation, distance, rotation
Offset Coordinates
- Two axes: col, row
- Better for storage and display
- Odd-q or even-q offset for pointy-top hexes
Key Algorithms
Cube to Offset (odd-q)
int col = q;
int row = r + (q - (q & 1)) ~/ 2;
Offset to Cube (odd-q)
int q = col;
int r = row - (col - (col & 1)) ~/ 2;
int s = -q - r;
Distance
int distance(Hex a, Hex b) {
return (abs(a.q - b.q) + abs(a.r - b.r) + abs(a.s - b.s)) ~/ 2;
}
Neighbors (6 directions)
const directions = [
Hex(1, -1, 0), Hex(1, 0, -1), Hex(0, 1, -1),
Hex(-1, 1, 0), Hex(-1, 0, 1), Hex(0, -1, 1),
];
List<Hex> neighbors(Hex h) {
return directions.map((d) => Hex(h.q + d.q, h.r + d.r, h.s + d.s)).toList();
}
Hex to Pixel (pointy-top)
double x = size * (sqrt(3) * q + sqrt(3)/2 * r);
double y = size * (3/2 * r);
Pixel to Hex
double q = (sqrt(3)/3 * x - 1/3 * y) / size;
double r = (2/3 * y) / size;
// Then round to nearest hex
Line Drawing (for line of sight)
List<Hex> lineDraw(Hex a, Hex b) {
int n = distance(a, b);
List<Hex> results = [];
for (int i = 0; i <= n; i++) {
results.add(hexRound(hexLerp(a, b, i / max(n, 1))));
}
return results;
}
Range (all hexes within N)
List<Hex> hexesInRange(Hex center, int range) {
List<Hex> results = [];
for (int q = -range; q <= range; q++) {
for (int r = max(-range, -q - range); r <= min(range, -q + range); r++) {
int s = -q - r;
results.add(Hex(center.q + q, center.r + r, center.s + s));
}
}
return results;
}
Reference
Full guide: https://www.redblobgames.com/grids/hexagons/