How does Y-sort work in Godot?

With y_sort_enabled, sibling Node2D children draw in order of their global Y position — lower Y draws first, higher Y draws on top. Y-sort must be enabled on the parent for it to affect children.

Why doesn't my TileMapLayer Y-sort with characters?

Both the TileMapLayer and the Node2D parent must have y_sort_enabled = true. Tiles also need a Y-Sort Origin set in the TileSet so the engine knows which point of each tile to compare. Without that origin, tiles use their cell center, which is wrong for isometric foot-of-tile sort.

What's Y-Sort Origin in the TileSet?

A per-tile offset that defines where on the tile to take the sort Y from. For an isometric character tile, set the origin near the feet so the character sorts based on where they stand rather than their visual center.

Fix: Godot TileMap Y-Sort Not Working on Isometric

Quick answer: Enable y_sort_enabled on both the TileMapLayer and its parent Node2D. Set Y-Sort Origin per tile in the TileSet so the engine sorts by foot position, not tile center.

An isometric town. Buildings should occlude the player when the player stands behind them and vice versa. Player walks behind a house; both render at full opacity but the player is drawn over the house. Y-sort is enabled but not working as expected.

Y-Sort Has Three Layers

For TileMap-and-character Y-sort:

The Node2D parent must have y_sort_enabled = true.
The TileMapLayer (child) must have y_sort_enabled = true.
Each tile in the TileSet must have a Y-Sort Origin set.

Miss any layer and Y-sort either doesn’t fire or sorts by the wrong reference point.

Set Y-Sort Origin per Tile

Open the TileSet. Select a tile (e.g., a building). In the right panel, find Rendering → Y Sort Origin. Set it to the bottom-center of the tile (the “foot” of the building):

Y Sort Origin: (0, 32)   # for a 64x64 tile, bottom-center is 32 below center

Tiles now sort based on their foot Y. A building’s base sorts against a character’s feet.

Character Y-Sort

For your player Sprite2D (or AnimatedSprite2D):

$Player.y_sort_enabled = true   # though only parent matters
# Position the sprite so its “feet” are at the node origin

The sort uses the node’s global Y position. To match foot-of-tile, the player Sprite2D’s pivot should be at the feet (set offset.y = -sprite_height/2 if the texture is centered).

Same Z-Index

Y-sort only orders within the same z_index. If your character is at z_index 1 and tiles are at z_index 0, the character always draws on top regardless of Y. Keep them at the same z_index for sort to take effect.

Debugging

Enable Debug → Show Sort Y in the editor (if available in your version) to visualize the sort Y per node. Otherwise add a debug print of get_global_transform_with_canvas().origin.y on the player and a sample tile — whichever has the higher value should draw on top.

Verifying

Walk the player up behind a building; player should be hidden. Walk down past the building’s base; player should appear in front. Both at the same Z. Working sort = the expected occlusion pattern.

“Three Y-sort flags + Y-Sort Origin per tile. Isometric sorting needs all four configured correctly.”

Add a project-wide convention for sprite pivots: feet at origin, no exceptions. Sort becomes predictable.