Using TileSets

Introduction

A tilemap is a grid of tiles used to create a game's layout. There are several benefits to using TileMap nodes to design your levels. First, they let you draw a layout by "painting" tiles onto a grid, which is much faster than placing individual Sprite2D nodes one by one. Second, they allow for larger levels because they are optimized for drawing large numbers of tiles. Finally, they allow you to add greater functionality to your tiles with collision, occlusion, and navigation shapes.

To use tilemaps, you will need to create a TileSet first. A TileSet is a collection of tiles that can be placed in a TileMap node. After creating a TileSet, you will be able to place them using the TileMap editor.

To follow this guide, you will need an image containing your tiles where every tile has the same size (large objects can be split into several tiles). This image is called a tilesheet. Tiles do not have to be square: they can be rectangular, hexagonal, or isometric (pseudo-3D perspective).

Creating a new TileSet

Using a tilesheet

This demonstration will use the following tiles taken from Kenney's "Abstract Platformer" pack. We'll use this particular tilesheet from the set:

Tilesheet with 64×64 tiles. Credit: Kenney

Create a new TileMap node, then select it and create a new TileSet resource in the inspector:

Creating a new TileSet resource within the TileMap node

After creating the TileSet resource, click the value to unfold it in the inspector. The default tile shape is Square, but you can also choose Isometric, Half-Offset Square or Hexagon (depending on the shape of your tile images). If using a tile shape other than Square, you may also need to adjust the Tile Layout and Tile Offset Axis properties. Lastly, enabling the Rendering > UV Clipping property may be useful if you wish tiles to be clipped by their tile coordinates. This ensures tiles cannot draw outside their allocated area on the tilesheet.

Set the tile size to 64×64 in the inspector to match the example tilesheet:

Setting the tile size to 64×64 to match the example tilesheet

If relying on automatic tiles creation (like we're about to do here), you must set the tile size before creating the atlas. The atlas will determine which tiles from the tilesheet can be added to a TileMap node (as not every part of the image may be a valid tile).

Open the TileSet panel at the bottom of the editor, then click the "+" icon in the bottom-left corner to add a new atlas:

Creating a new atlas in a TileSet resource using the bottom panel

After creating an atlas, you must assign a tilesheet texture to it. This can be done by choosing it on the left column of the bottom panel, then clicking the value of the Texture property and choosing Quick Load (or Load). Specify the path to the image file using the file dialog that appears.

Loading a tilesheet image in the newly created TileSet atlas

After specifying a valid image, you will be asked whether to create tiles automatically. Answer Yes:

Automatically creating tiles based on tilesheet image content

This will automatically create tiles according to the tile size you specified earlier in the TileSet resource. This greatly speeds up initial tile setup.

Note

When using automatic tile generation based on image contents, parts of the tilesheet that are fully transparent will not have tiles generated.

If there are tiles from the tilesheet you do not wish to be present in atlas, choose the Eraser tool at the top of the tileset preview, then click the tiles you wish to remove:

Using the Eraser tool to remove unwanted tiles from the TileSet atlas

You can also right-click a tile and choose Delete, as an alternative to the Eraser tool.

Tip

Like in the 2D and TileMap editors, you can pan across the TileSet panel using the middle or right mouse buttons, and zoom using the mouse wheel or buttons in the top-left corner.

If you wish to source tiles from several tilesheet images for a single TileSet, create additional atlases and assign textures to each of them before continuing. It is also possible to use one image per tile this way (although using tilesheets is recommended for better usability).

You can adjust properties for the atlas in the middle column:

Adjusting TileSet atlas properties in the dedicated inspector (part of the TileSet panel)

The following properties can be adjusted on the atlas:

• ID: The identifier (unique within this TileSet), used for sorting.

• Name: The human-readable name for the atlas. Use a descriptive name here for organizational purposes (such as "terrain", "decoration", etc).

• Margins: The margins on the image's edges that should not be selectable as tiles (in pixels). Increasing this can be useful if you download a tilesheet image that has margins on the edges (e.g. for attribution).

• Separation: The separation between each tile on the atlas in pixels. Increasing this can be useful if the tilesheet image you're using contains guides (such as outlines between every tile).

• Texture Region Size: The size of each tile on the atlas in pixels. In most cases, this should match the tile size defined in the TileMap property (although this is not strictly necessary).

• Use Texture Padding: If checked, adds a 1-pixel transparent edge around each tile to prevent texture bleeding when filtering is enabled. It's recommended to leave this enabled unless you're running into rendering issues due to texture padding.

Note that changing texture margin, separation and region size may cause tiles to be lost (as some of them would be located outside the atlas image's coordinates). To regenerate tiles automatically from the tilesheet, use the three vertical dots menu button at the top of the TileSet editor and choose Create Tiles in Non-Transparent Texture Regions:

Recreating tiles automatically after changing atlas properties

Using a collection of scenes

Since Godot 4.0, you can place actual scenes as tiles. This allows you to use any collection of nodes as a tile. For example, you could use scene tiles to place gameplay elements, such as shops the player may be able to interact with. You could also use scene tiles to place AudioStreamPlayer2Ds (for ambient sounds), particle effects, and more.

Warning

Scene tiles come with a greater performance overhead compared to atlases, as every scene is instanced individually for every placed tile.

It's recommended to use only scene tiles when necessary. To draw sprites in a tile without any kind of advanced manipulation, use atlases instead.

For this example, we'll create a scene containing a CPUParticles2D root node. Save this scene to a scene file (separate from the scene containing the TileMap), then switch to the scene containing the TileMap node. Open the TileSet editor, and create a new Scenes Collection in the left column:

Creating a scenes collection in the TileSet editor

After creating a scenes collection, you can enter a descriptive name for the scenes collection in the middle column if you wish. Select this scenes collection then create a new scene slot:

Creating a scene tile after selecting the scenes collection in the TileSet editor

Select this scene slot in the right column, then use Quick Load (or Load) to load the scene file containing the particles:

Creating a scene slot, then loading a scene file into it in the TileSet editor

You now have a scene tile in your TileSet. Once you switch to the TileMap editor, you'll be able to select it from the scenes collection and paint it like any other tile.

Merging several atlases into a single atlas

Using multiple atlases within a single TileSet resource can sometimes be useful, but it can also be cumbersome in certain situations (especially if you're using one image per tile). Godot allows you to merge several atlases into a single atlas for easier organization.

To do so, you must have more than one atlas created in the TileSet resource. Use the "three vertical dots" menu button located at the bottom of the list of atlases, then choose Open Atlas Merging Tool:

Opening the atlas merging tool after creating multiple atlases

This will open a dialog, in which you can select several atlases by holding Shift or Ctrl then clicking on multiple elements:

Using the atlas merging tool dialog

Choose Merge to merge the selected atlases into a single atlas image (which translates to a single atlas within the TileSet). The unmerged atlases will be removed within the TileSet, but the original tilesheet images will be kept on the filesystem. If you don't want the unmerged atlases to be removed from the TileSet resource, choose Merge (Keep Original Atlases) instead.

Tip

TileSet features a system of tile