Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/godot/godot-tilemap

godot-tilemap

Verified

Godot 4.7 tile maps with TileMapLayer and TileSet: atlas sources, data layers, terrain autotiling and set_cell or local_to_map at runtime. Use for 2D tile levels in Godot, tiles with no collision, a click on the wrong cell or porting a deprecated TileMap. Not for Unity (`unity-tilemap-2d`), tile art (`create-game-assets`) or generation (`procedural-gen`).

FileKindSize
SKILL.mdskill md8.9 KB
references/tileset-and-terrains.mdmarkdown4.0 KB

references/tileset-and-terrains.md

View on GitHub
# TileSet & terrains reference (Godot 4.7)

Depth companion to `godot-tilemap`.

## TileSet sources

A `TileSet` holds one or more **sources**, each with an integer `source_id`:

- **Atlas source** (`TileSetAtlasSource`) — a single texture sliced into a grid of tiles.
  Most common. Tiles are addressed by `atlas_coords: Vector2i` (column, row).
- **Scene collection source** (`TileSetScenesCollectionSource`) — places whole scenes as
  tiles (e.g. a tile that is a particle emitter). `atlas_coords` is always `Vector2i(0,0)`
  and the `alternative_tile` selects the scene.

In code, `set_cell(coords, source_id, atlas_coords, alternative_tile)` fully identifies a
tile. `alternative_tile` selects flips/rotations or alternative tiles you defined.

## Per-tile data layers

Configured in the TileSet editor; each layer applies to every tile you paint data onto:

- **Physics layers** — collision polygons per tile. The TileSet defines layer index +
  collision layer/mask; `TileMapLayer.collision_enabled` toggles them at the node level.
- **Navigation layers** — navigation polygons for pathfinding. Note the docs caution that
  built-in tile navigation has limits; consider baking a `NavigationRegion2D` for large
  maps.
- **Occlusion layers** — light occluder polygons per tile.
- **Custom data layers** — named, typed values (`String`, `int`, `bool`, `Vector2`, ...).
  Read with `tile_data.get_custom_data("name")`. Ideal for gameplay metadata
  (`is_ladder`, `friction`, `damage`, `is_spawn`).

## Terrains (autotiling)

1. In the TileSet, create a **terrain set** (choose a matching mode: Match Corners and
   Sides, Match Corners, or Match Sides).
2. Add one or more **terrains** to that set.
3. Paint terrain **peering bits** onto each tile's edges/corners so Godot knows how tiles
   connect.
4. In the TileMap panel's **Terrains** tab, paint with **Connect** (auto-connect to
   neighbors on the layer) or **Path** (connect only along the current stroke).

From code:

```gdscript
set_cells_terrain_connect(cells, terrain_set, terrain, ignore_empty_terrains)
set_cells_terrain_path(path_cells, terrain_set, terrain, ignore_empty_terrains)
```

Both require the TileSet to have all needed bit combinations defined; missing
combinations yield placeholder/odd tiles.

## Coordinate conversions

```gdscript
local_to_map(local_pos: Vector2) -> Vector2i   # pixel (local) -> cell
map_to_local(cell: Vector2i)     -> Vector2     # cell -> centered local pixel pos
get_neighbor_cell(cell, TileSet.CELL_NEIGHBOR_RIGHT_SIDE)
get_surrounding_cells(cell)                     # all edge neighbors
```

For global coordinates wrap with `to_local()` / `to_global()` (Node2D methods).

## Y-sorting (top-down depth)

Enable `CanvasItem.y_sort_enabled` on the `TileMapLayer` and set per-tile
`y_sort_origin` (and the layer's `y_sort_origin`) so taller tiles and characters overlap
correctly. The rendering quadrant optimization is bypassed for Y-sorted layers (tiles are
grouped by Y instead).

## Runtime tile-data overrides

To vary a tile's data at runtime without editing the shared TileSet, override on a
`TileMapLayer` subclass:

```gdscript
extends TileMapLayer

func _use_tile_data_runtime_update(coords: Vector2i) -> bool:
    return get_cell_atlas_coords(coords) == Vector2i(3, 0)   # only these tiles

func _tile_data_runtime_update(coords: Vector2i, tile_data: TileData) -> void:
    # Duplicate sub-resources before editing — they are shared with the TileSet!
    tile_data.modulate = Color(1, 0.6, 0.6)
```

Call `notify_runtime_tile_data_update()` when the result of `_use_tile_data_runtime_update`
should change. These updates are computationally expensive — restrict them to the few
tiles that need them.

## Migrating from the TileMap node

A deprecated `TileMap` node with N layers becomes N `TileMapLayer` nodes. Godot offers a
"Extract TileMap layers as individual TileMapLayer nodes" tool from the TileMap node's
toolbar. After extraction, update scripts: drop the leading `layer` argument from cell
calls and target the specific `TileMapLayer` node instead.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall