Isometric grid math
Skill 0xheycat/isometric-game-skills/skills/isometric-grid-math
Agent-ready toolkit for isometric games: ComfyUI art pipelines, seamless terrain, sprites, grid math, Canvas2D rendering, pathfinding, and asset automation.
npx -y skills add 0xheycat/isometric-game-skills --skill isometric-grid-mathAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Use when converting between grid coordinates and screen pixels in a 2:1 isometric projection, including screen-to-grid for mouse picking.
The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
2.0 KB, as published. Nobody here has run it
Isometric Grid Math
Overview
Every isometric bug eventually traces back to the coordinate transform. This skill gives the exact, tested grid<->screen formulas for a 2:1 projection so placement and picking are pixel-correct.
When to Use
- Tiles render in the wrong place or overlap.
- Mouse clicks select the wrong tile.
- You are starting a renderer and need the core transform.
Process
- Fix tile width W and height H (2:1 means W = 2*H).
- grid->screen: screenX = (col - row) * (W/2); screenY = (col + row) * (H/2).
- Add the world origin offset so (0,0) is where you want it on screen.
- screen->grid (for picking): invert the transform using W and H.
- Round screen->grid results to integer tile coords.
- Validate round-trip: grid -> screen -> grid returns the original tile.
- Document the anchor (tile top vs tile center) and stay consistent.
const screenX = (col - row) * (W / 2);
const screenY = (col + row) * (H / 2);
// inverse
const col = ((screenX / (W/2)) + (screenY / (H/2))) / 2;
const row = ((screenY / (H/2)) - (screenX / (W/2))) / 2;
Rationalizations (Stop Lying to Yourself)
| Excuse | Reality |
|---|---|
| "I will tweak offsets until it looks right" | Magic offsets break on resize/zoom. Derive the transform. |
| "Rounding does not matter" | Unrounded screen->grid selects the wrong tile near edges. Round it. |
Red Flags - STOP if you catch yourself:
- Hard-coded pixel offsets instead of a derived transform.
- No screen->grid inverse for picking.
- Round-trip grid->screen->grid does not return the same tile.
Verification
You are NOT done until every box is checked:
- grid->screen and screen->grid are both implemented.
- Round-trip conversion is exact for integer tiles.
- Anchor convention is documented and consistent.