Introduction

A tilemap is a grid of tiles used to create a game's layout. There are severalbenefits to usingTileMapLayer nodes to design your levels.First, they make it possible to draw the layout by "painting" the tiles onto agrid, which is much faster than placing individualSprite2Dnodes one by one. Second, they allow for much larger levels because they areoptimized for drawing large numbers of tiles. Finally, you can add collision,occlusion, and navigation shapes to tiles, adding greater functionality tothe TileMap.

Specifying the TileSet in the TileMapLayer

If you've followed the previous page onUsing TileSets, you shouldhave a TileSet resource that is built into the TileMapLayer node. This is good forprototyping, but in a real world project, you will generally have multiplelevels reusing the same tileset.

The recommended way to reuse the same TileSet in several TileMapLayer nodes is to savethe TileSet to an external resource. To do so, click the dropdown next to the TileSetresource and chooseSave:

Multiple TileMapLayers and settings

When working with tilemaps it's generally advised that you use multiple TileMapLayernodes when appropriate. Using multiple layers can be advantageous, for example,this allows you to distinguish foreground tiles from background tiles for betterorganization. You can place one tile per layer at a given location, which allows youto overlap several tiles together if you have more than one layer.

Each TileMapLayer node has several properties you can adjust:

• Enabled: Iftrue, the layer is visible in the editor and when runningthe project.

• TileSet The tileset used by the TileMapLayer node.

Opening the TileMap editor

Select the TileMapLayer node, then open the TileMap panel at the bottomof the editor:

Selecting tiles to use for painting

First, if you've created additional layers above, make sure you've selected thelayer you wish to paint on:

You can skip the above step if you haven't created additional layers, as thefirst layer is automatically selected when entering the TileMap editor.

Before you can place tiles in the 2D editor, you must select one or more tilesin the TileMap panel located at the bottom of the editor. To do so, click a tilein the TileMap panel, or hold down the mouse button to select multiple tiles:

You can also hold downShift to append to the current selection. Whenselecting more than one tile, multiple tiles will be placed every time youperform a painting operation. This can be used to paint structures composed ofmultiple tiles in a single click (such as large platforms or trees).

The final selection does not have to be contiguous: if there is empty spacebetween selected tiles, it will be left empty in the pattern that will bepainted in the 2D editor.

If you've created alternative tiles in your TileSet, you can select them forpainting on the right of the base tiles:

Lastly, if you've created ascenes collection in the TileSet, you can place scene tiles in the TileMap:

Painting modes and tools

Using the toolbar at the top of the TileMap editor, you can choose betweenseveral painting modes and tools. These modes affect operation when clicking inthe 2D editor,not the TileMap panel itself.

From left to right, the painting modes and tools you can choose are:

Line

After selecting Line Paint mode, you can draw in a line that isalways 1 tile thick (no matter its orientation).

If you right-click while in Line Paint mode, you will erase in a line.

If you have selected multiple tiles in the TileMap or using the Selection tool,you can place them in a repeating pattern across the line.

You can toggle this mode temporarily while in Paint or Eraser mode by holdingShift then drawing.

Bucket Fill

After selecting Bucket Fill mode, you can choose whether painting should belimited to contiguous areas only by toggling theContiguous checkbox thatappears on the right of the toolbar.

If you enableContiguous (the default), only matching tiles that touch thecurrent selection will be replaced. This contiguous check is performedhorizontally and vertically, butnot diagonally.

If you disableContiguous, all tiles with the same ID in the entire TileMap willbe replaced by the currently selected tile. If selecting an empty tile withContiguous unchecked, all tiles in the rectangle that encompasses theTileMap's effective area will be replaced instead.

If you right-click while in Bucket Fill mode, you will replace matching tileswith empty tiles.

If you have selected multiple tiles in the TileMap or using the Selection tool,you can place them in a repeating pattern within the filled area.

Painting randomly using scattering

While painting, you can optionally enablerandomization. When enabled,a random tile will be chosen between all the currently selected tiles whenpainting. This is supported with the Paint, Line, Rectangle and Bucket Filltools. For effective paint randomization, you must select multiple tilesin the TileMap editor or use scattering (both approaches can be combined).

IfScattering is set to a value greater than 0, there is a chance that no tilewill be placed when painting. This can be used to add occasional, non-repeatingdetail to large areas (such as adding grass or crumbs on a large top-downTileMap).

Example when using Paint mode:

Example when using Bucket Fill mode:

Saving and loading premade tile placements using patterns

While you can copy and paste tiles while in Select mode, you may wish to savepremadepatterns of tiles to place together in a go. This can be done on aper-TileMap basis by choosing thePatterns tab of the TileMap editor.

To create a new pattern, switch to Select mode, perform a selection and pressCtrl+C. Click on empty space within the Patterns tab (a blue focusrectangle should appear around the empty space), then pressCtrl+V:

To use an existing pattern, click its image in thePatterns tab, switch toany painting mode, then left-click somewhere in the 2D editor:

Like multi-tile selections, patterns will be repeated if used with the Line,Rectangle or Bucket Fill painting modes.

Handling tile connections automatically using terrains

To use terrains, the TileMapLayer node must feature at least one terrain set and aterrain within this terrain set. SeeCreating terrain sets (autotiling) if you haven't created a terrainset for the TileSet yet.

There are 3 kinds of painting modes available for terrain connections:

• Connect, where tiles are connected to surrounding tiles on the sameTileMapLayer.

• Path, where tiles are connected to tiles painted in the same stroke (untilthe mouse button is released).

• Tile-specific overrides to resolve conflicts or handle situations not coveredby the terrain system.

The Connect mode is easier to use, but Path is more flexible as it allows formore artist control during painting. For instance, Path can allow roads to bedirectly adjacent to each other without being connected to each other, whileConnect will force both roads to be connected.

Lastly, you can select specific tiles from the terrain to resolve conflicts incertain situations:

Any tile that has at least one of its bits set to a value set to thecorresponding terrain ID will appear in the list of tiles to choose from.

Handling missing tiles

If you remove tiles in the TileSet that are referenced in a TileMap, the TileMapwill display a placeholder to indicate that an invalid tile ID is placed:

These placeholders arenot visible in the running project, but the tile datais still persisted to disk. This allows you to safely close and reopen suchscenes. Once you re-add a tile with the matching ID, the tiles will appear withthe new tile's appearance.