Godot 4 TileMapLayer Tutorial: Build a 2D World

Hand-placing hundreds of sprites to build a level is misery. Tilemaps let you paint a world out of reusable tiles instead, like a coloring book made of Lego. In Godot 4.3 and later the workflow changed a bit, so if you've followed an older tutorial and gotten confused, this is probably why.

Older Godot used a single TileMap node with layers stacked inside it. As of 4.3 that node is deprecated, and each layer is now its own TileMapLayer node. It's a better setup: layers are just nodes in your scene tree, so you can show, hide, move, and script them independently.

So you'll typically have a few TileMapLayer nodes side by side:

• Ground (grass, dirt, floors)
• Walls (the stuff you collide with)
• Details (decoration on top)

A TileSet is the palette of tiles a layer paints from. Add a TileMapLayer node, then in the Inspector create a new TileSet on its Tile Set property. Open the TileSet panel at the bottom of the editor and drag your tilesheet image in as an atlas. Godot offers to slice it into tiles automatically based on the size you set, usually 16x16 or 32x32.

That's the setup. Now you have a palette to paint with.

Select the layer, open the TileMap panel, pick tiles from the palette, and draw straight onto the scene. Rectangle and bucket-fill tools are there for blocking out large areas fast. Painting a screen of terrain takes seconds instead of the afternoon it would take placing sprites by hand.

Right now your walls are just a picture. To make the player actually bump into them, you add a physics layer to the TileSet, not to every tile in the scene.

In the TileSet panel, add a Physics Layer. Then select the wall tiles and paint a collision polygon onto them (the panel gives you a little editor for this). Every wall tile placed anywhere in your level now has collision automatically. One setup, applied everywhere. This is the part that makes tilemaps worth it.

Make sure your player's collision mask includes the layer your wall tiles use, or they'll still walk through.

Drawing each grass-to-dirt edge tile by hand is tedious. Terrains (Godot's autotiling) fix it. You tell the TileSet which tiles are "grass" and how they connect, and then as you paint, Godot picks the right edge and corner tiles for you. Draw a rough blob of grass and it cleans up the borders on its own.

It takes a bit of setup to define a terrain set, but for any game with organic terrain it pays for itself almost immediately. For a first project with simple square rooms, you can skip it and just paint manually.

You can query and edit the map at runtime, which is how you do destructible terrain, fog of war on a grid, or checking what tile the player is standing on:

@onready var ground: TileMapLayer = $Ground
​
func _ready() -> void:
    # Convert a world position to a tile coordinate
    var cell := ground.local_to_map(get_global_mouse_position())
    var data := ground.get_cell_tile_data(cell)
    print("Tile at ", cell, ": ", data)

Tilemaps are how you go from a single test room to an actual explorable map. Our Tile-Based World and Map Building quest takes this from a blank TileSet to a connected world with collision, layered terrain, and the structure to drop a player and enemies into. It's part of the 2D RPG campaign, where the tile world becomes the stage everything else plays out on.

What's the difference between TileMap and TileMapLayer in Godot 4?

TileMap is the old single node that held all layers internally, and it's deprecated as of Godot 4.3. TileMapLayer replaces it, with each layer as its own node in the scene tree. The new setup makes layers easier to show, hide, and script independently.

How do I add collision to tiles in Godot 4?

Add a Physics Layer to the TileSet, then paint a collision polygon onto the tiles that should be solid using the TileSet editor. Every placed copy of those tiles gets collision automatically. You don't add collision to tiles one by one in the scene.

What is autotiling in Godot?

Autotiling, handled by Terrains in Godot 4, automatically picks the correct edge and corner tiles as you paint, so grass meets dirt cleanly without placing each transition tile by hand. You define which tiles belong to a terrain and how they connect, then paint freely.