godot-tilemap-mastery

NEVER Do in TileMaps

• NEVER call set_cell() in huge loops without batching — Prefer terrain connect, patterns, or chunk batchers.
• NEVER forget source_id in set_cell — Wrong overload → crash or silent miss.
• NEVER mix world coords with tile coords — Always local_to_map / map_to_local.
• NEVER hand-paint organic blobs when terrains exist — Use terrain sets + set_cells_terrain_connect.
• NEVER put dynamic actors in the TileMap — Enemies/pickups are nodes; tiles are geometry / destructible cells.
• NEVER spam get_cell_tile_data() every physics frame — Cache metadata ([fast_metadata_cache.gd](scripts/fast_metadata_cache.gd)).

---

Decision Tree: How to Write Cells

| Goal | Prefer | Script | Trade-off |

|------|--------|--------|-----------|

| Organic ground / roads / rivers | Terrain autotile | [terrain_autotile.gd](scripts/terrain_autotile.gd) / [terrain_path_painter.gd](scripts/terrain_path_painter.gd) | Setup cost in TileSet; fastest designer iteration |

| Prefab rooms / houses / stamps | TileMapPattern | [tile_pattern_stamper.gd](scripts/tile_pattern_stamper.gd) | Great for procgen pieces; less flexible per-cell |

| Sparse / precise edits | set_cell | — | Fine for few cells; bad for thousands/frame |

| Huge streaming worlds | Chunks | [tilemap_chunking.gd](scripts/tilemap_chunking.gd) / [procedural_chunk_batcher.gd](scripts/procedural_chunk_batcher.gd) / [tilemap_data_manager.gd](scripts/tilemap_data_manager.gd) | Indirection + load boundaries |

| Destructible dig/break | Custom data HP | [destructible_tile_logic.gd](scripts/destructible_tile_logic.gd) | Must refresh nav/physics after edits |

| Gameplay queries (friction/hazard) | Custom data + cache | [gameplay_data_query.gd](scripts/gameplay_data_query.gd) / [fast_metadata_cache.gd](scripts/fast_metadata_cache.gd) | Cache invalidation on set_cell |

| Nav after edits | Runtime nav fix | [nav_mesh_teleport_fix.gd](scripts/nav_mesh_teleport_fix.gd) | Costly if every cell; batch rebuilds |

| One-way / physics layers | TileSet physics | [physics_shape_interaction.gd](scripts/physics_shape_interaction.gd) | Align with CharacterBody masks |

| Iso / multi-floor sort | Y-sort layers | [sorting_Z_layering.gd](scripts/sorting_Z_layering.gd) | Parent + all layers need y_sort |

| Legacy TileMap → layers | Migration | [tilemap_layer_v43_upgrade.gd](scripts/tilemap_layer_v43_upgrade.gd) | One-time upgrade aid |

Editor atlas/physics paint setup: Official Documentation in Reference — Do NOT reload Steps 1–3 / flood_fill tutorials from this skill body.

Available Scripts (single index + MANDATORY triggers)

| Task | MANDATORY script(s) |

|------|---------------------|

| Serialize / large world data | [tilemap_data_manager.gd](scripts/tilemap_data_manager.gd) |

| Runtime terrain paths | [terrain_path_painter.gd](scripts/terrain_path_painter.gd) / [terrain_autotile.gd](scripts/terrain_autotile.gd) |

| Destructible tiles | [destructible_tile_logic.gd](scripts/destructible_tile_logic.gd) |

| Custom data gameplay reads | [gameplay_data_query.gd](scripts/gameplay_data_query.gd) (+ [fast_metadata_cache.gd](scripts/fast_metadata_cache.gd) if hot) |

| Procedural bulk place | [procedural_chunk_batcher.gd](scripts/procedural_chunk_batcher.gd) |

| Chunk stream in/out | [tilemap_chunking.gd](scripts/tilemap_chunking.gd) |

| Pattern stamp prefabs | [tile_pattern_stamper.gd](scripts/tile_pattern_stamper.gd) |

| Nav repair after edits | [nav_mesh_teleport_fix.gd](scripts/nav_mesh_teleport_fix.gd) |

| One-way / physics layer ops | [physics_shape_interaction.gd](scripts/physics_shape_interaction.gd) |

| Y-sort / Z layering | [sorting_Z_layering.gd](scripts/sorting_Z_layering.gd) |

| 4.3+ multi-layer upgrade | [tilemap_layer_v43_upgrade.gd](scripts/tilemap_layer_v43_upgrade.gd) |

Expert Trade-offs (routing only)

• Isometric Y-sort: enable y_sort_enabled on parent and each TileMapLayer; tune y_sort_origin on tall tiles — see [sorting_Z_layering.gd](scripts/sorting_Z_layering.gd).
• Procgen: stamp patterns or batch terrain; avoid per-cell set_cell storms — [tile_pattern_stamper.gd](scripts/tile_pattern_stamper.gd) / [procedural_chunk_batcher.gd](scripts/procedural_chunk_batcher.gd).
• Diff / save deltas: compare get_used_cells() source_id/atlas between layers; persist deltas via [tilemap_data_manager.gd](scripts/tilemap_data_manager.gd) rather than full maps when possible.

Deep recipes (on demand)

> LLM-ignorance rule: if a general agent would not know it before reading, it lives here or in scripts/ — never delete, only move.

| Topic | Reference |

|-------|-----------|

| TileSet editor steps | [tileset-editor-setup.md](references/tileset-editor-setup.md) |

| Runtime APIs + flood/terrain | [runtime-tile-patterns.md](references/runtime-tile-patterns.md) |

| Iso / patterns / diff | [expert-tilemap-architectures.md](references/expert-tilemap-architectures.md) |

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Using TileMaps — TileMapLayer workflow, layers, runtime set_cell / terrain painting, and when multiple layers beat a single legacy TileMap.
• Using TileSets — atlas sources, terrains, physics/navigation/custom data layers painted in the TileSet editor.
• TileMapLayer — cell APIs, terrain connect, patterns, coordinate conversion, and runtime tile-data updates.
• TileSet — physics/terrain/custom-data layer definitions shared by every TileMapLayer that references the resource.
• TileSetAtlasSource — atlas grid, alternatives, and per-tile TileData that drive collision and metadata.
• TileData — custom data, physics polygons, navigation polygons, and y_sort_origin used at query time.
• TileMapPattern — capture/stamp multi-tile prefabs without per-cell set_cell loops.
• Collision shapes (2D) — shape choices and one-way collision patterns that TileSet physics layers expose to CharacterBody2D.
• Navigation introduction (2D) — how tile navigation polygons feed NavigationRegion2D / NavigationAgent2D after edits.
• Canvas layers — z-index / CanvasLayer separation for ground, decoration, and roof TileMapLayers.
• Background loading — threaded ResourceLoader patterns for streaming chunk TileSets / tilemap scenes without hitch spikes.

Related Skills

Prerequisites

• godot-project-foundations — scene tree, resources, and import layout before authoring TileSet atlases and multi-layer level scenes.
• godot-gdscript-mastery — typed Vector2i APIs, caching patterns, and signal-up/call-down structure used in runtime tile managers.
• godot-2d-physics — collision layers/masks and StaticBody2D-equivalent behavior that TileMapLayer physics layers participate in.

Complements

• godot-version-migration — tilemap_layer_v43_upgrade and TileMap→TileMapLayer sit on the 4.x hop path; run engine upgrades via the migration hub before applying layer scripts.
• godot-characterbody-2d — move_and_slide against tile colliders, one-way platforms, and floor/wall queries over TileMapLayer geometry.
• godot-navigation-pathfinding — NavigationAgent2D / region updates when destructible or procedural tiles change walkable polygons.
• godot-camera-systems — Camera2D limits and follow radii that drive chunk load/unload around the player.
• godot-adapt-3d-to-2d — isometric / Y-sort depth tricks that pair with TILE_SHAPE_ISOMETRIC and multi-floor TileMapLayers.
• godot-scene-management — packing and swapping chunk scenes so large tile worlds stream without orphaned layers.
• godot-performance-optimization — batching, cache budgets, and profiler checks when set_cell / custom-data queries dominate frame time.

Downstream / consumers

• godot-procedural-generation — noise/BSP/WFC generators that write cells via terrain connect, patterns, or chunk batchers.
• godot-genre-platformer — precision platformer levels built from TileSet physics, one-ways, and hazard custom data.
• godot-genre-metroidvania — interconnected room grids, ability gates, and map revelation layered on TileMapLayer chunks.
• godot-genre-sandbox — diggable/buildable 2D worlds that treat TileMapLayer as the editable terrain backend.
• godot-monte-carlo-balancer — simulate hazard density, destructible HP, and traversal cost encoded in tile custom data before shipping maps.

Master

• godot-master — library router and mirrored module entry for cross-skill discovery.