Godot4 Isometric Tilemap

Godot 4 Isometric TileMap

Overview

Godot 4 supports isometric natively, but the defaults fight you: wrong tile shape, broken draw order, and magic pixel offsets that look fine until something moves. This skill maps the repo's tested concepts (grid math, depth sorting) onto Godot's TileMapLayer + Y-sort so it is correct the first time.

When to Use

• Starting an isometric scene in Godot 4 (4.3+, TileMapLayer).
• Characters draw in front of / behind tiles they should not.
• Tiles overlap, or mouse picking selects the wrong cell.

Process

1. TileSet: set Tile Shape = Isometric, Tile Layout = Diamond Down, and Tile Size to your 2:1 footprint (e.g. 64x32).
2. Put ground on a TileMapLayer. For anything that must sort against characters, enable Y Sort Enabled on the layer and its parent node.
3. Set each movable sprite's y_sort_origin to the tile's feet/anchor (not its top). This is Godot's version of the depth = col + row rule (see depth-sorting-occlusion).
4. Convert coordinates with the built-ins local_to_map() / map_to_local() instead of hand-rolled offsets (mirrors isometric-grid-math).
5. Mouse picking: local_to_map(get_local_mouse_position()) to get the cell, then map_to_local() to snap a highlight (see tile-picking-interaction).
6. Keep ONE tile size and anchor convention across every layer and scene.

# grid  world: let Godot do the iso math
var cell: Vector2i = ground.local_to_map(ground.get_local_mouse_position())
var world: Vector2 = ground.map_to_local(cell)  # center of that tile

Rationalizations (Stop Lying to Yourself)

| Excuse | Reality | |---|---| | "I'll nudge sprite offsets until it lines up" | Manual offsets break under Y-sort and zoom. Set y_sort_origin to the anchor. | | "I'll write the iso math myself" | local_to_map / map_to_local are exact and tested. Use them. |

Red Flags - STOP if you catch yourself:

• Y Sort disabled, or y_sort_origin left at the default (0,0).
• Hand-written screengrid math instead of the TileMapLayer API.
• Mixed tile sizes or anchors across layers.

Verification

You are NOT done until every box is checked:

• [ ] TileSet shape = Isometric, layout = Diamond Down, 2:1 tile size.
• [ ] Y Sort on; a character sorts correctly walking around a tall object.
• [ ] Picking via local_to_map selects the cell under the cursor.
• [ ] Round-trip local_to_map(map_to_local(cell)) returns the same cell.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 0xheycat
• Source: 0xheycat/isometric-game-skills
• License: MIT
• Homepage: https://0xheycat.github.io/isometric-game-skills/demo/

Install and usage instructions live in the source repository linked above.