hex-math

chaoming 的头像作者 chaoming

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

📖 中文导读: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". 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

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

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