Godot TileMapLayer Tutorial: Setup & Example Project
Godot Tutorial

Godot TileMapLayer Tutorial: Setup & Example Project

By Ziva.sh • Updated November 10, 2026 • 11 min read

Download the working TileMapLayer example project (ZIP, 4 KB). It includes a configured TileSet, two layers, original tile art, and a Space-key paint/erase example. No account or Ziva installation is needed. The cover image shows this project running in Godot 4.7.2, the version used for verification.

Extract the ZIP, import project.godot, open main.tscn, and press F6. Ground and Details share tileset.tres; the atlas source ID is 7. Press Space to toggle the gold tile at map cell (3, 5). Read the example instructions and troubleshooting before adapting it. This is a layer/API example, not a finished platformer: it has no player, collisions, or terrain-autotiling rules.

To set up a Godot TileMapLayer, add the node, assign a TileSet, create atlas tiles, and paint cells. Use one TileMapLayer per map layer. In GDScript, set_cell(cell_position, source_id, atlas_coords) paints a cell without a layer index.

TileMapLayer is available from Godot 4.3, released August 15, 2024. The older TileMap node is deprecated, not removed. Start with the new-project setup below; use the migration section only if you already have an existing TileMap.

Set up a TileMapLayer in a new project

For Godot 4.3 or later, add a TileMapLayer node, assign a TileSet, and add a TileSet atlas source using your tile texture. Create the tiles in that atlas before painting cells. Add another TileMapLayer for each layer you need; they can share the same TileSet. The official tilemap tutorial walks through the editor controls.

To paint from code, attach this script to a TileMapLayer with its TileSet already assigned:

extends TileMapLayer

@export var source_id: int = 0
@export var atlas_coords: Vector2i = Vector2i(0, 0)

func _ready() -> void:
    set_cell(Vector2i(3, 5), source_id, atlas_coords)
    erase_cell(Vector2i(4, 5))

Set source_id to the ID of your actual atlas source and atlas_coords to an existing tile. (3, 5) is the cell position in the map, not a pixel position. Unlike the old TileMap.set_cell(), TileMapLayer's method takes no layer index: the node itself is the layer. Passing an invalid source or atlas coordinate can erase a cell rather than place a visible tile.

If you already have a deprecated TileMap, use the migration steps below instead of rebuilding the map. The setup and API were checked against the official class reference on October 3, 2026.

TL;DR / Key Takeaways
  • TileMap is deprecated, not removed. Existing scenes still load and play. New projects should start with TileMapLayer because every Godot 4 tilemap tutorial after mid-2024 assumes it.

  • The editor's one-click converter only works on scenes you can open directly. Tilemaps stored inside .tres resources or instanced scenes require a manual workaround that's caught more than one developer for a day.

  • Godot 4's terrain matching is less reliable than Godot 3's autotiles. If your game procedurally paints terrain at runtime (a Dome Keeper, a farming sim, a base-builder), read the terrain section before committing.

01 / What Changed in Godot 4.3

One node per layer, not one node with hidden layers

The old TileMap held layers internally. You added them in the inspector, then clicked a tab at the bottom of the editor to switch which layer your brush painted. The Godot 4.3 release notes state plainly: the old design "was not in line with Godot Engine's design philosophy in general."

TileMapLayer is exactly what the name says. Each layer is a scene node. Order is set by position in the tree. Layers share a TileSet resource via a property on each node. You select a layer by clicking its node, not a tab.

The practical upshot:

CapabilityTileMap (deprecated)TileMapLayer
Layer countStored as arrayOne per node
Per-layer collision toggleNocollision_enabled
Per-layer navigation toggleNonavigation_enabled
Per-layer occlusionNoocclusion_enabled
Per-layer z-index orderingManualNode tree order
Y-sort originPer layer (hidden)y_sort_origin property
Per-layer custom shaderAwkwardStandard CanvasItem material
Coordinate range16-bit signed16-bit signed (unchanged)

The 16-bit coordinate limit, documented on the class page, is unchanged: X and Y clamp between -32768 and 32767. Larger worlds chunk across multiple TileMapLayer nodes anyway, so the limit rarely bites.


02 / Migrating an Existing TileMap

The one-click path

For an existing deprecated TileMap, select that TileMap node and open the bottom TileMap panel. Click the toolbox icon in the top-right, then choose Extract TileMap layers as individual TileMapLayer nodes. These are migration steps, not the setup for a new TileMapLayer. The TileMap becomes a parent Node2D with one TileMapLayer child per former layer, each carrying its own tile_map_data PackedByteArray.

The case the editor cannot fix

Reddit user greenflySAU described the painful version migrating their game tankies to 4.3. Their scenarios stored tile data as PackedInt32Array blobs inside .tres files; the editor converter only operates on visible scenes. For each resource they had to revert the parent scene, copy the array into the scene as a text edit, open in Godot, run the converter, then copy the resulting PackedByteArray back into the resource. Per scenario, no scriptable workaround. Lesson: store tile data outside scene files and plan the migration before ship week.

The wire format

The new format is a base64 PackedByteArray packing source ID, atlas coordinates, alternative tile, and physics layer into 12 bytes per cell. It is opaque by design. Never hand-edit it. Use set_cell(), get_cell_source_id(), get_cell_atlas_coords(), and clear() for everything.


03 / Per-Layer Properties and Physics Quadrants

Quadrants are the performance knob you'll forget about

TileMapLayer batches rendering and physics into quadrants. The default size is 16, so a 16×16 square is one canvas item and one physics body group. You only touch it when:

  • Setting physics_quadrant_size = 1 for precise cell coords from get_coords_for_body_rid(). Required when AI agents need to know which tile they hit.
  • Raising rendering_quadrant_size to 32 or 64 for large outdoor maps; fewer, larger canvas items mean fewer draw calls.
  • Dropping it to 4 if you toggle layer visibility on small regions often.

The docs note that bumping physics_quadrant_size reduces get_coords_for_body_rid() precision. Real tradeoff.


04 / The Terrain Matching Catch

Godot 3's autotiles were more reliable

If you paint terrain in the editor and ship the result, Godot 4 is fine. If you paint terrain procedurally at runtime (building roads, tilling soil, destroying walls), read godot-proposals#7670 first.

The proposal author, dandeliondino, points out that Godot 4's terrain algorithm "isn't built to handle the complexity of the underlying system" and has high failure rates picking tiles from peering bits. They note that Dome Keeper, shipped on Godot 3, "would not currently be possible using Godot 4 terrains."

That statement still holds in 2026 with caveats. The community plugin Better Terrain closes the gap for most cases with a 3×3 minimal-style algorithm matching Godot 3's reliability. It is the first thing to install if your game does anything procedural with terrains.


05 / Four Approaches by Game Scale

Pick by map size, not by tutorial popularity

Four ways to build a tile-based world in Godot 4

Pick by map scale, not by tutorial popularity

ApproachBest forLearning curveScale
TileMapLayer (built-in)Most 2D games, multi-layer scenesMedium - terrains require peering-bits thinkingGood up to ~200×200 single layer
Better Terrain (plugin)Complex autotiling, 3x3 minimal styleLow - paints like Godot 3 autotilesSame as built-in; pure editor sugar
Chunked TileMapLayersLarge open worlds, infinite mapsHigh - write your own load/unloadScales beyond editor's comfort zone
Custom drawing (MultiMesh)Millions of tiles, no per-cell physicsHigh - manual culling and collisionFastest; you control everything

For most 2D games (platformers, top-down RPGs, procedural roguelikes, small open-world projects), the built-in node is enough. Halls of Torment, a survivors-like shipped on Godot, uses standard TileMapLayer with hand-painted art. Survivors-like maps are not the bottleneck; spawn logic is.

For a town-builder or farming sim where the player edits terrain, install Better Terrain.

For a continuous world larger than ~500×500 tiles, write a chunk loader. The Jackie Codes GodotFest 2025 talk on tilemaps covers serialization and the underused Scene Tiles feature in 50 minutes.


06 / Five Pitfalls That Cost a Day Each

Five pitfalls that eat a day each

Cause and fix for the issues that drive every “godot tilemap not working” forum thread

SymptomCauseFix
Collision disappears after migrationPhysics layer bitmask reset to defaults when extracting layersRe-set physics layers on the TileSet resource after running 'Extract'
set_cell() changes don't update physicsCollision shapes only rebuild on the next physics tick after a notifyCall tile_layer.notify_runtime_tile_data_update() once per batch
Terrains paint the wrong cornersPeering bits set on the wrong terrain or missing tile variantsOpen the Terrains tab, paint peering bits for every neighbor combination you have art for
Editor freezes on a large mapSingle TileMapLayer past ~500×500 cells, brush previews recompute every frameSplit into chunked layers, or reduce viewport zoom while painting
Physics body collides with tile seamsPer-tile collision polygons leave a hairline gap between adjacent cellsUse one-way collision OR snap player velocity to integer pixels

The first two hit hardest on day one of a migration. After running the converter, open the TileSet inspector and verify that physics, navigation, and occlusion layers are still set on each TileData entry. The "Extract" command preserves cell data but not always the per-layer enable flags on the TileSet itself.


07 / Editor Performance at Scale

Runtime is fast. The editor is the wall.

Editor brush stroke latency vs single TileMapLayer size

Approximate. 60 fps editing budget = ~16 ms. Past 500×500 the brush starts to drag.

50×502.0 ms
200×20018.0 ms
500×50095.0 ms
1000×1000420.0 ms
2000×20001700.0 ms

Runtime FPS holds up much better than editor latency. The editor lag is the practical limit, not the renderer.

These numbers vary by machine and TileSet complexity, but the curve is real: the editor's brush preview recomputes every frame while you paint, and past ~500×500 cells per layer it exceeds the 60 fps budget. The renderer itself is much happier; you can ship a 2000×2000 layer that runs at 144 fps, you just cannot edit it comfortably.

The fix is structural. Chunk the world. Eight 250×250 layers feel snappy in the editor and batch the same at runtime.


08 / TileMapLayer Collision, by Hand and with AI

Add collision to a TileMapLayer

A TileMapLayer has no collision until its TileSet has a physics layer and the solid tiles have collision polygons. The steps, from the official TileSet tutorial:

  1. Select the TileMapLayer, click its TileSet property in the inspector, unfold Physics Layers and choose Add Element.
  2. Open the TileSet editor at the bottom, select a solid tile and open its Physics Layer 0 section. Press F for a full-tile rectangle, or draw a polygon.
  3. Repeat for every solid tile. Tiles without a polygon stay walk-through, which is what you want for water or decoration.
  4. Leave Collision Enabled on in the layer's inspector, and check that your player's collision mask includes the physics layer's collision layer (both default to layer 1).

ChatGPT and older tutorials often describe the deprecated TileMap node instead. A forum user adding collision put it plainly: "Even ChatGPT cant help me, because he only knows the old TileMap" (Godot Forum).

Tested: an AI adding collision to this example

We gave Ziva, an AI agent that runs inside the Godot editor, this page's downloadable example with this request: add collision to the Ground layer so a player can stand on the grass and stone tiles, keep the water tiles non-solid, add a CharacterBody2D player with gravity and arrow-key movement, and check that it lands instead of falling through.

What it did, from the run's tool log:

  1. Read the TileSet with its TileMapLayer tools: one atlas source with four tiles and no physics layers. It found that demo.gd paints the cells at runtime, so the saved layer has no tiles.
  2. Read the tile art to tell grass, stone, water and gold apart, then called its TileSet atlas tool with collision shapes turned on. The tool added the physics layer but skipped the shapes because the tiles already existed, while still reporting success. Ziva caught that by reading the scene file and added 16 x 16 collision polygons to grass and stone only. We have filed that tool behavior as a bug.
  3. Wrote player.gd and added the Player node. Godot's GDScript checker reported no problems.
  4. Ran its physics validator (the player's mask matches the tile layer) and then the scene. The player landed on a tile under the gold marker, so Ziva moved the spawn to plain grass and checked the result in code: resting on the grass, grass and stone with one polygon each, water and gold with none.

Ziva's screenshot of the example after the run: the pink player square standing on the grass row.

It took 2 minutes, 23 tool calls and $0.03 of Ziva usage on Ziva Smart, the default model. Our own check, a separate script run on the result, agreed: the player came to rest on the grass row, with grass and stone solid and water and gold without collision. In this map the water sits below the grass row, so the run shows the water has no collision shape rather than the player falling into it.

Ziva.sh makes Ziva and wrote this test. We ran it on 10 November 2026 with Godot 4.7.2 on Linux and a development build of Ziva. It is one project and one run, so treat it as an example, not a benchmark.

For procedural maps the same agent can write the set_cell(coords, source_id, atlas_coords) loops; every cell is reachable from GDScript. If the player still falls through after this, see our collision checklist.

For the art that feeds the TileSet, see our pixel art guide, or generate tiles with AI inside Godot.


09 / When to Skip Godot's Tilemap Entirely

Two cases warrant a different tool:

  1. External level editor. Tiled is the de facto 2D level editor across engines. The Tiled-to-Godot importer plugin targets TileMapLayer as of 2025. Useful when your level designer is not a programmer.
  2. Millions of tiles with no per-cell physics. A MultiMeshInstance2D draws thousands of identical sprites in one draw call. For a galaxy of stars or a particle-field overlay with no collision, MultiMesh beats any tilemap.

Neither replaces TileMapLayer for the 95% case. They are the corners.


10 / The Short Answer

For a new Godot 4 project in 2026, start with TileMapLayer. One node per visual layer, one TileSet shared between them, quadrant size left alone unless the renderer or get_coords_for_body_rid() precision says otherwise. If you paint terrain at runtime, install Better Terrain. If you came from Godot 3, the GDScript vs C# comparison and the 2D engine landscape cover what else changed.

The deprecated TileMap will not break tomorrow. But every tutorial written in the last 18 months assumes the new node, and so does every plugin worth installing. Migrate on a quiet afternoon, not the week you ship.

Frequently asked questions

How do I add collision to a TileMapLayer in Godot 4?
Select the TileMapLayer, edit its TileSet in the inspector, unfold Physics Layers and choose Add Element. Then open the TileSet editor, select each solid tile and draw its collision polygon (press F for a full-tile rectangle). Leave the layer's collision enabled, and make sure your player's collision mask includes the physics layer's collision layer.
Can an AI add collision to a Godot TileMapLayer?
We tested Ziva, an AI agent inside the Godot editor, on this page's example project. Asked to make the grass and stone tiles solid and add a player, it added a physics layer and full-tile collision polygons to those two tiles only, wrote the player script, checked the layers with its physics validator and ran the scene. The player landed on the grass. It took 2 minutes and $0.03 of Ziva usage on the default model. One of its TileSet tools silently skipped the collision shapes, and Ziva noticed by reading the scene file.