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".

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

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.
namehex-math
descriptionReference 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-toolsRead

Hex Grid Mathematics Reference

Coordinate Systems

  • 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/