Build and edit tile-based 2D levels in Godot 4.7 with TileMapLayer and TileSet: paint layers, set up collision/navigation/custom-data on tiles, autotile with terrain sets, and read/write cells from code (set_cell, get_cell_tile_data, local_to_map). Use when working with TileMapLayer nodes, .tres Til

Godot TileMap (4.7 TileMapLayer) Author tile based levels with TileMapLayer + TileSet , add per tile collision and custom data, autotile with terrains, and manipulate cells at runtime. Targets Godot 4.7 , where TileMapLayer replaces the now deprecated TileMap node. When to use Use when designing 2D levels from a tile grid, configuring a TileSet (collision, navigation, custom data, terrains), or reading/writing tiles from code. Use when migrating a TileMap node (single node, many layers) to multiple TileMapLayer nodes (one layer each). When not to use: moving the player across the tiles → godot 2d movement ; general physics bodies/raycasts → godot physics ; procedural map generation algorithms → procedural gen ; level design practice → level design . Core workflow 1. Add a TileMapLayer node (one per visual/logical layer: background, walls, foreground). Each holds exactly one layer of tiles. 2. Create or assign a TileSet on the layer's tile set property. Add an atlas source (a texture sliced into tiles) in the TileSet editor. Save the TileSet as an external .tres so multiple layers/levels reuse it. 3. Add tile data in the TileSet editor: physics layers (collision polygons), navigation layers, occlusion, and custom data layers (typed per tile values like damage or is ladder ). 4. Paint in the TileMap bottom panel (Paint/Line/Rectangle/Bucket). For self connecting tiles, define a terrain set and paint with Connect/Path mode. 5. Enable per layer collision/navigation via the layer's collision enabled / navigation enabled properties. 6. Read/write from code with local to map , set cell , get cell source id , and get cell tile data(...).get custom data(...) . Patterns 1. Convert mouse position to a cell and read its custom data 2. Place and erase tiles at runtime 3. Autotiling a region with a terrain set 4. Iterate placed tiles (e.g. find all spawn tiles) Pitfalls TileMap node is deprecated in 4.3. Use TileMapLayer nodes (one layer per node); group them under a parent Node2D . Old TileMap calls that took a layer argument ( set cell(layer, ...) ) do not apply to TileMapLayer . local to map needs layer local coordinates. A world position needs to local(...) first. A mouse event's position is in viewport pixels, not world space, so it is wrong as soon as a Camera2D scrolls or zooms; convert it with make input local(event) (or poll get local mouse position() ) instead. get cell tile data returns null for empty cells or non atlas sources — always null check before get custom data . Custom data is typed. A layer declared as int returns int ; reading it as the wrong type or referencing a non existent layer name errors. Define the layer in the TileSet first. Terrains need every combination defined. set cells terrain connect produces odd results if the TileSet's terrain bitmask peering is incomplete. Runtime edits are batched to end of frame. If you must read updated internals immediately after set cell , call update internals() (expensive — avoid in loops). Collision not working? Check the layer's collision enabled , that the tile has a physics layer with a polygon, and that the TileSet's physics layer mask matches your bodies. References For TileSet setup (atlas sources, physics/navigation/custom data layers, terrain bitmasks), scene tiles, Y sorting, and runtime tile data overrides ( use tile data runtime update ), read references/tileset and terrains.md . Related skills godot 2d movement — characters that walk on these tiles. godot physics — collision layers/masks the tile collisions participate in. procedural gen — generating tilemaps from noise/RNG. level design / roguelike — design practice and grid based genres.

godot-tilemap