Getting Started With Godot Tile Maps: TileMapLayer, TileSet, Collisions, and Codex

Sat, 20 Jun 2026 11:21:07 +0800

A Godot tile map is a way to take a sprite sheet containing small images such as grass, roads, walls, and water, split it into regular grid cells, and then paint a level with those tiles.

In Godot 4.x, especially for new projects after 4.3, use TileMapLayer. The old TileMap node is deprecated. The current recommendation is to use one TileMapLayer for each map layer. This makes the node tree clearer and fits Godot’s node-based workflow better.

The official documentation also states that TileMapLayer is a node for 2D tile-based maps, and that it uses a TileSet to create grid maps. If you need multiple layers, use multiple TileMapLayer nodes.

Official docs:

https://docs.godotengine.org/en/stable/classes/class_tilemaplayer.html

https://docs.godotengine.org/en/latest/tutorials/2d/using_tilemaps.html

Two Core Concepts

Tile maps revolve around two things:

TileSet
TileMapLayer

TileSet is the tile library. It stores:

Grass, dirt, walls, water, roads, and other tiles.
Collision shapes for individual tiles.
Terrain auto-connection rules.
Navigation, occlusion, and custom data.

TileMapLayer is the canvas. It uses tiles from the TileSet to draw the map.

Start with a structure like this:

World (Node2D)
├─ Ground (TileMapLayer)       # Grass, roads, floors
├─ Decoration (TileMapLayer)   # Flowers, cracks, shadows
├─ Walls (TileMapLayer)        # Walls and obstacles
├─ Objects (Node2D)            # Chests, doors, NPCs, coins
└─ Player (CharacterBody2D)

Layering has several advantages:

Ground and walls do not get mixed together.
Display order is easier to control.
You can hide a single layer.
Only the wall layer needs collision; the ground layer can stay simple.
Codex gets a clearer node structure when writing scripts later.

Create Your First Tile Map

Prepare a tile image first, for example:

`1`	`tileset.png`

Every cell inside the image should use the same size. Common sizes are:

1
2
3

16 × 16
32 × 32
64 × 64

If each tile in the source art is 32 × 32, the Tile Size in your TileSet should also be 32 × 32.

Add a TileMapLayer

Add this to the scene:

1
2

Node2D
└─ TileMapLayer

Rename the TileMapLayer to:

Ground

Select Ground, then find this in the Inspector:

`1`	`Tile Set`

Click:

1
2

<empty>
→ New TileSet

Then open the new TileSet resource and set Tile Size to the source tile size, for example:

32 × 32

Add the Tile Image

After selecting Ground, the TileMap / TileSet editor panel appears at the bottom.

Drag tileset.png into the TileSet panel and choose automatic tile creation. Godot will split the image into tiles according to Tile Size.

After this step, the TileSet contains drawable tiles, and the Ground TileMapLayer can use them to paint the map.

Paint the Map

Switch to the TileMap panel at the bottom:

Pick a grass tile.
Paint with the pencil tool.
Delete with the eraser.
Use the rectangle tool to fill a region quickly.
Use the fill tool to fill a connected area.

Do not start with a huge map. Draw a small 20 × 15 map first, with only grass, walls, and a player spawn point.

Add Collision to Walls

Do not add collision to every ground tile. Usually only non-walkable tiles need collision:

Walls.
Rocks.
Fences.
Water boundaries.
Cliffs.

Select the TileSet resource and find:

`1`	`Physics Layers`

Click:

`1`	`Add Element`

A common setup is:

1
2

Collision Layer: 1
Collision Mask: 1

Then in the bottom TileSet panel:

Switch to the collision or physics painting tools.
Select a wall tile.
Draw a rectangular or polygon collision shape over the wall area.

This lets different tiles in the same TileSet have different collision shapes.

Make the Player Collide With Tile Walls

A basic player scene can look like this:

1
2
3

Player (CharacterBody2D)
├─ Sprite2D
└─ CollisionShape2D

Start with a minimal movement script:

extends CharacterBody2D

@export var speed: float = 200.0


func _physics_process(_delta: float) -> void:
	var direction := Input.get_vector(
		"move_left",
		"move_right",
		"move_up",
		"move_down"
	)

	velocity = direction * speed
	move_and_slide()

As long as the Player collision layer and mask match the physics layer in the TileSet, the player will be blocked by wall tiles.

While running the game, enable:

1
2

Debug
→ Visible Collision Shapes

This shows the player and wall collision shapes directly, which makes debugging much easier.

Use Three Map Layers

For a first project, use three layers:

World
├─ Ground
├─ Walls
└─ Decoration

Each node is an independent TileMapLayer.

Put these in Ground:

Grass.
Dirt.
Roads.
Floors.

Usually there is no collision.

Put these in Walls:

Walls.
Cliffs.
Water boundaries.
Non-walkable rocks.

Usually this layer has collision.

Put these in Decoration:

Flowers.
Grass blades.
Ground cracks.
Shadows.

Usually there is no collision.

You can use z_index for a simple draw order:

Ground: 0
Walls: 1
Decoration: 2
Player: 3

If you have trees, roofs, or bridge openings that should cover the player, handle that later with Y Sort or by splitting objects into upper and lower parts. Your first map does not need a complex occlusion system.

Use Terrain to Auto-Connect Roads and Walls

If you want the editor to automatically create edges and corners, such as:

Grass connecting to dirt edges.
Roads generating corners automatically.
Walls choosing the correct tile based on neighbors.
Water generating shorelines.

Use Godot’s Terrain Set.

The basic process is:

Add a Terrain Set in the TileSet.
Choose a matching mode, such as matching by sides and corners.
Create terrains, such as Grass, Dirt, and Water.
Mark the terrain connection positions for each tile.
Switch the TileMapLayer to Terrains painting mode.
Paint the map with the Connect or Path tool.

Godot will choose straight, corner, and edge tiles based on nearby cells. The official docs also mention two Terrain painting modes: Connect, which is easier to start with, and Path, which gives more manual control for roads and paths.

You do not need Terrain immediately. First draw a small map manually and understand TileSet, TileMapLayer, and collisions. Then learn auto-connection.

Edit Tiles From Code

Assume this scene structure:

1
2

World
└─ Ground

You can reference Ground from the World script:

extends Node2D

@onready var ground: TileMapLayer = $Ground

const SOURCE_ID: int = 0
const GRASS_TILE: Vector2i = Vector2i(0, 0)


func place_grass(cell: Vector2i) -> void:
	ground.set_cell(
		cell,
		SOURCE_ID,
		GRASS_TILE
	)

Here, cell is a tile map cell coordinate. For example:

`1`	`place_grass(Vector2i(5, 3))`

This places a grass tile at column 5, row 3.

Important: SOURCE_ID and the atlas coordinates in GRASS_TILE must match your actual TileSet. Do not copy the sample values blindly.

Convert Between World Coordinates and Cell Coordinates

Mouse positions are world coordinates, while tile maps use cell coordinates. Usually you first convert to the layer’s local coordinates, then convert to a map cell.

World position to cell coordinate:

1
2

var local_position := ground.to_local(get_global_mouse_position())
var cell := ground.local_to_map(local_position)

Cell coordinate back to map position:

`1`	`var position_in_layer := ground.map_to_local(cell)`

To place a tile with a mouse click:

extends Node2D

@onready var ground: TileMapLayer = $Ground

const SOURCE_ID: int = 0
const GRASS_TILE: Vector2i = Vector2i(0, 0)


func _unhandled_input(event: InputEvent) -> void:
	if event is InputEventMouseButton:
		if event.button_index == MOUSE_BUTTON_LEFT and event.pressed:
			var local_position := ground.to_local(
				get_global_mouse_position()
			)
			var cell := ground.local_to_map(local_position)

			ground.set_cell(
				cell,
				SOURCE_ID,
				GRASS_TILE
			)

To support right-click deletion, use:

`1`	`ground.erase_cell(cell)`

set_cell(), erase_cell(), local_to_map(), and map_to_local() are common TileMapLayer APIs.

Do Not Make Every Chest, Door, or Coin a Plain Tile

These objects are usually not good as plain image tiles:

Coins.
Chests.
Doors that can open.
NPCs.
Enemies.
Teleport points.
Traps.
Breakable boxes.

They have scripts, animations, collisions, and signals, so they are usually better as separate scenes.

For example, a coin:

1
2
3

Coin (Area2D)
├─ Sprite2D
└─ CollisionShape2D

Place it under:

1
2

World
└─ Objects

Plain tiles are best for static maps. Objects with behavior are better as independent Scene files. Godot also supports Scene Collection tiles, but for beginners, manually placing independent scenes is easier to understand and debug.

What Codex Can Help With

Codex is good at:

Writing player movement scripts.
Reading map cells.
Procedurally generating maps.
Randomly painting ground tiles.
Placing and deleting tiles with the mouse.
Finding spawn points.
Reading custom tile data.
Checking TileMapLayer API usage.
Implementing coins, doors, and chests.

You can prompt Codex like this:

This is a Godot 4.x project.

Scene structure:

World: Node2D
├─ Ground: TileMapLayer
├─ Walls: TileMapLayer
├─ Objects: Node2D
└─ Player: CharacterBody2D

Please write a script for World:

1. Convert the mouse world position to Ground cell coordinates;
2. Left-click places a grass tile;
3. Right-click clears a tile;
4. SOURCE_ID and atlas coordinates should use @export configuration;
5. Use Godot 4.x TileMapLayer API;
6. Use static types;
7. Do not modify the TileSet or scene node names.

Codex is less suitable for:

Determining the tile size of the source art.
Visually painting an entire map.
Fine-tuning Terrain bitmasks.
Guessing source_id.
Guessing atlas coordinates.
Hand-writing large .tscn map data.

A better workflow is: you create the TileSet, configure collisions, and paint the map in the Godot editor; Codex writes the map interaction, generation logic, and gameplay scripts around the real node structure.

First Practice Project

For the first exercise, make only a 20 × 15 map:

Paint grass on Ground.
Draw a wall border on Walls.
Add collision to wall tiles.
Place a Player.
Make the player collide with the walls.
Add a Coin scene afterward.

After finishing this exercise, you will understand the basic Godot tile map workflow:

TileSet stores tile art and rules
TileMapLayer draws one map layer
Collision is configured on tiles inside the TileSet
Objects with behavior should be independent scenes
Codex writes scripts around the real node structure

Get this minimal map working first. Then move on to Terrain, Y Sort, procedural generation, and large map loading.

TileMapLayer on KnightLi Blog