Why might we need to associate data with a tile? For multiple reasons. For example, suppose we’re using a Tilemap to build the map of a top-down perspective game. In that case, we might want to add a “movement resistance” value to different tiles so that our character moves slower on tiles representing a swamp, faster on tiles representing a path, and cannot cross tiles showing impassable rocks.
In a previous article, I explained how to associate this value with Tiles in Unity, but I realized I didn’t cover how to do it in Godot. Let’s solve that in this article.
Imagine having a scene created with several TileMapLayers. In the example screenshot, I used three TileMapLayers: one to define the scene boundaries (WallsTileMapLayer), another for interior obstacles (InteriorObstaclesMapLayer), and another for walkable areas (GroundTileMapLayer). In the walkable areas layer, I placed all the tiles my agents can roam on, although some tiles should have different transit costs than others.
 |
| My Example Scene |
To reflect the different tile costs, we can associate data with the Custom Data Layers of the TileSet used in the TileMaps.
First, you need to register the different data types within the TileSet. In the inspector of any TileMap, expand the TileSet resource. You’ll see a section called “Custom Data Layers.” Expanding it shows the data types associated with each tile, and you can add new ones using the “Add element” button. The screenshot shows the data I associated with my tiles.
 |
| Associating Custom Data to a TileSet |
You can see I associated two data types: a boolean defining whether the tile is an obstacle (though I didn’t use it in my example) and a float defining the cost of moving over the tile.
Once the custom data types are defined, we need to set their values for each tile.
When you select a TileMapLayer in the hierarchy, you’ll see a TileSet tab at the bottom of the editor. Selecting it shows three sections for configuring the TileSet: “Setup,” “Select,” and “Paint.” We can use the last two to assign values to custom data.
In the “Select” section, you can pick specific tiles. Doing so displays several configuration sections, one of which is “Custom Data.” Expanding it shows the different custom data fields, where you can assign values. Remember to press Enter in numeric and text fields to apply changes effectively.
 |
| Configuring Custom Data in the “Select” Section of the TileSet Tab |
You can do the same more conveniently from the “Paint” tab. Selecting it shows a dropdown to choose the data you want to assign. Once you pick the data type, enter the value in the text field. From that point on, any tile you select in the TileSet will adopt that value. This option is ideal for quickly applying the same value to multiple tiles.
 |
| Configuring Custom Data in the “Paint” Section of the TileSet Tab |
With this, tiles will carry these data values to the positions where you place them.
Next, as an example, here’s the method I used to retrieve the cost of the tile associated with a given position.
 |
| Method to Retrieve the Cost Value Associated with a Tile |
Every TileMapLayer has a LocalToMap() method that converts a position to the coordinates of the tile covering that position. I used this method in line 188. However, note that the position cannot be global; it must be relative to the TileMapLayer. That’s why I used ToLocal() in line 189 to convert a global position to one relative to the TileMapLayer.
With the coordinates returned by LocalToMap(), we can call GetCellTileData() (line 190) to retrieve the data associated with the tile at that position. The returned type (TileData) is a package containing all custom data. Therefore, to get the specific data we need, we call its GetCustomData() method and cast it to the expected type. Be careful because you need to pass the exact name of the data field, and it’s easy to mistype it.
And that’s it. Now you have everything you need to associate data with your tiles and retrieve it later depending on the tile at each position. What you do with that data afterward is up to you.
