Skip to main content
skill CX Codex

hex-grid-spatial — Claude Code skill: hex grid distances and neighbours

hex-grid-spatial is a Claude Code skill that calculates neighbours, hex distance, and radius cells on odd-r offset maps for movement or area-of-effect logic.

Apache-2.0 1 installs ★ 1,933 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add benchflow-ai/skillsbench --skill hex-grid-spatial -a claude-code
Open on GitHub

What hex-grid-spatial does

The skill hands the agent three Python helpers for a hex map. Coordinates follow the odd-r offset scheme: rows with an odd index sit half a tile further right, counting starts at the bottom-left tile, columns grow rightward and rows upward.

Neighbours come from a six-entry direction table. On odd rows four of those entries shift by one column compared with even rows, while east and west stay put. Get the parity wrong and the neighbour list lands on the wrong column, so a map stored in another layout has to be converted to odd-r first.

Distance converts both tiles to cube coordinates and returns the step count between them. The radius helper scans a square around the centre and keeps only tiles that pass the distance check, which gets costly on large radii.

What it helps with

  • list the six tiles touching a hex
  • measure how many steps separate two tiles
  • collect every tile within a radius of a city
  • test whether two tiles share an edge
  • convert offset coordinates to cube form for distance math

Example prompts for the agent

  • List the six neighbours of tile (21, 13) on the hex map
  • How many hexes between (21, 13) and (24, 13)? Use the hex distance helper
  • Give me every tile within 3 of (21, 13), centre excluded

How to install hex-grid-spatial

1Skills CLI (Vercel)

npx skills add benchflow-ai/skillsbench --skill hex-grid-spatial -a claude-code

2Manually: put the files in place

~/.claude/skills/hex-grid-spatial/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/hex-grid-spatial/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about hex-grid-spatial

How do I install hex-grid-spatial in Claude Code?

Run npx skills add benchflow-ai/skillsbench --skill hex-grid-spatial -a claude-code. The skill file lands at ~/.claude/skills/hex-grid-spatial/SKILL.md.

What does hex-grid-spatial do?

It gives the agent helpers for a hex map: the six neighbours of a tile, the distance between two tiles, and every tile inside a radius. Coordinates are odd-r offset.

Which grid layout does it support?

Odd-r offset only, where odd rows are shifted right. On any other layout the neighbours and distances come out wrong, so the map has to be converted first.

Source text

SKILL.md · Apache-2.0
---
name: hex-grid-spatial
description: Hex grid spatial utilities for offset coordinate systems. Use when working with hexagonal grids, calculating distances, finding neighbors, or spatial queries on hex maps.
---

# Hex Grid Spatial Utilities

Utilities for hexagonal grid coordinate systems using **odd-r offset coordinates** (odd rows shifted right).

## Coordinate System

- Tile 0 is at bottom-left
- X increases rightward (columns)
- Y increases upward (rows)
- Odd rows (y % 2 == 1) are shifted right by half a hex

## Direction Indices

```
     2   1
      \ /
   3 - * - 0
      / \
     4   5

0=East, 1=NE, 2=NW, 3=West, 4=SW, 5=SE
```

## Core Functions

### Get Neighbors

```python
def get_neighbors(x: int, y: int) -> List[Tuple[int, int]]:
    """Get all 6 neighboring hex coordinates."""
    if y % 2 == 0:  # even row
        directions = [(1,0), (0,-1), (-1,-1), (-1,0), (-1,1), (0,1)]
    else:  # odd row - shifted right
        directions = [(1,0), (1,-1), (0,-1), (-1,0), (0,1), (1,1)]
    return [(x + dx, y + dy) for dx, dy in directions]
```

### Hex Distance

```python
def hex_distance(x1: int, y1: int, x2: int, y2: int) -> int:
    """Calculate hex distance using cube coordinate conversion."""
    def offset_to_cube(col, row):
        cx = col - (row - (row & 1)) // 2
        cz = row
        cy = -cx - cz
        return cx, cy, cz

    cx1, cy1, cz1 = offset_to_cube(x1, y1)
    cx2, cy2, cz2 = offset_to_cube(x2, y2)
    return (abs(cx1-cx2) + abs(cy1-cy2) + abs(cz1-cz2)) // 2
```

### Tiles in Range

```python
def get_tiles_in_range(x: int, y: int, radius: int) -> List[Tuple[int, int]]:
    """Get all tiles within radius (excluding center)."""
    tiles = []
    for dx in range(-radius, radius + 1):
        for dy in range(-radius, radius + 1):
            nx, ny = x + dx, y + dy
            if (nx, ny) != (x, y) and hex_distance(x, y, nx, ny) <= radius:
                tiles.append((nx, ny))
    return tiles
```

## Usage Examples

```python
# Find neighbors of tile (21, 13)
neighbors = get_neighbors(21, 13)
# For odd row: [(22,13), (22,12), (21,12), (20,13), (21,14), (22,14)]

# Calculate distance
dist = hex_distance(21, 13, 24, 13)  # Returns 3

# Check adjacency
is_adj = hex_distance(21, 13, 21, 14) == 1  # True

# Get all tiles within 3 of city center
workable = get_tiles_in_range(21, 13, 3)
```

## Key Insight: Even vs Odd Row

The critical difference is in directions 1, 2, 4, 5 (the diagonal directions):

| Direction | Even Row (y%2==0) | Odd Row (y%2==1) |
|-----------|-------------------|------------------|
| NE (1) | (0, -1) | (1, -1) |
| NW (2) | (-1, -1) | (0, -1) |
| SW (4) | (-1, +1) | (0, +1) |
| SE (5) | (0, +1) | (1, +1) |

East (0) and West (3) are always (1, 0) and (-1, 0).

© benchflow-ai · Apache-2.0 · benchflow-ai/skillsbench

Similar skills

All skills for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set22

The whole set →
meteorology-driver-classification meteorology-driver-classification sorts the columns of an environmental dataset into heat, flow, wind and human drivers, so an attribution run can treat each group as one factor. CX Codex +1 2installs scipy-curve-fit scipy-curve-fit guides coding agents to estimate nonlinear model parameters from experimental data with scipy.optimize.curve_fit. CX Codex +1 2installs python-scala-idioms python-scala-idioms guides AI agents to translate Python into idiomatic Scala. Enforces immutability, pattern matching, sealed domain traits, and type-safe error handling. CX Codex +1 1installs first-order-model-fitting The first-order-model-fitting skill fits first-order models to experimental step responses and returns K and tau. Use it when you need a compact model of thermal, electrical, or mechanical behavior. CX Codex +1 1installs python-scala-syntax-mapping python-scala-syntax-mapping is a Claude Code skill that maps Python syntax to Scala for coding assistants translating variables, comprehensions, and control structures. CX Codex +1 1installs image-ocr Use this skill to read text in images with Tesseract OCR through Python. It fits scans, screenshots, and batches of image files. CX Codex +1 1installs audiobook Turns a web article or a text file into an audiobook: pulls the content, cleans it up, and voices it through ElevenLabs, OpenAI TTS or gTTS. CX Codex +1 1installs nanogpt-training nanogpt-training is a Claude Code skill with guidance for training 124M-parameter GPT-2 scale models on a single GPU using Muon, bfloat16, and tokenized dataset shards. CX Codex +1 1installs

Project sponsors

Companies that keep this analytics open