Using Multiple TileMapLayer Nodes in Godot 4

One TileMap for everything gets expensive fast

In a typical Godot 4 2D project, it is tempting to put floors, walls, props, and collision shapes inside a single TileMap node. The node works, but it couples everything together. Moving one decorative tile forces the engine to reconsider the whole tile map. Off-screen walls are culled as part of the same block, so the renderer cannot skip them independently. Worse, navigation agents treat every tile on the map with the same navigation properties, so a rug or a wall decal can block pathfinding the same way a solid wall does.

Godot 4 addresses this with TileMapLayer. A TileMapLayer is a node that holds one logical layer of tiles. It has its own TileSet resource, Z index, collision shapes, and navigation bitmask. You can stack several TileMapLayer nodes under a Node2D parent and let the engine handle each layer separately.

Worked example: floor, walls, and one-way platforms

Create a scene with this tree:

• LevelRoot (Node2D)
• Floor (TileMapLayer)
• Walls (TileMapLayer)
• Platforms (TileMapLayer)
• PlayerAgent (NavigationAgent2D)

Open the Inspector for each TileMapLayer and assign a TileSet. Set Floor to navigation layer 1, Walls to navigation layer 2, and Platforms to navigation layer 4. These numbers are bitmasks; the exact values matter less than making sure they match your navigation agent.

Attach this script to LevelRoot:

extends Node2D

func _ready():
    var walls = $Walls
    var agent = $PlayerAgent

    # Confirm the wall layer uses its own navigation bitmask.
    # Replace 2 with the bitmask you assigned in the Inspector.
    walls.navigation_layer = 2

    # The agent must include the same bitmask to pathfind across walkable tiles.
    # Replace 7 with the combination of bits your agent should use.
    agent.navigation_layers = 7

Where to run: Godot editor, attached to the LevelRoot node in your scene. No special permissions are required. Expected check: selecting Walls shows Navigation Layer in the Inspector, and changing agent.navigation_layers changes which tiles the agent can traverse. Risk: if the agent bitmask omits the floor bit, pathfinding fails silently; the agent simply will not find a route.

Rendering, collision, and navigation trade-offs

Because each TileMapLayer is its own canvas item, Godot can cull layers independently. If the player cannot see the Walls layer, the renderer can skip it without skipping Floor. Batching also improves when layers share texture atlases; layers using different atlases may produce separate draw calls.

Collision works per layer too. You can give Walls solid collision shapes while leaving Floor as a navigation surface only. NavigationLayer bitmasks let agents ignore decorative tiles entirely. The catch is configuration: NavigationLayer values on TileMapLayer must overlap with NavigationAgent2D.navigation_layers, or the agent will not see those tiles as walkable.

Too many layers add scene-tree depth. If every prop gets its own TileMapLayer, you gain isolation but lose simplicity. Combine related tiles into shared TileSets when possible, and add layers only when you need separate rendering, collision, or navigation behavior.

Verify before you rely on it

• Open Editor > About in Godot and confirm you are running Godot 4. TileMapLayer does not exist in Godot 3.
• Select a TileMapLayer and confirm the Inspector shows TileSet, Layer, Navigation Layer, and Z Index.
• Move one layer off-screen and watch the Visible Canvas Items monitor in the debugger to confirm per-layer culling.
• Compare agent paths with and without the matching navigation bitmask to confirm pathfinding respects your layers.

Adding TileMapLayer nodes does not destroy existing data, but if you are replacing a monolithic TileMap, duplicate the scene first so you can roll back the tile layout.

Start with two layers—ground and walls—and add more only when a layer needs different rendering or navigation rules. Verify your engine version and bitmasks before shipping.