godot-tilemap-mastery

name	godot-tilemap-mastery
description	Expert blueprint for TileMapLayer and TileSet systems for efficient 2D level design. Covers terrain autotiling, physics layers, custom data, navigation integration, and runtime manipulation. Use when building grid-based levels OR implementing destructible tiles. Keywords TileMapLayer, TileSet, terrain, autotiling, atlas, physics layer, custom data.

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).

---

Decision Tree: How to Write Cells

Goal	Prefer	Script	Trade-off
Organic ground / roads / rivers	Terrain autotile	terrain_autotile.gd / terrain_path_painter.gd	Setup cost in TileSet; fastest designer iteration
Prefab rooms / houses / stamps	TileMapPattern	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 / procedural_chunk_batcher.gd / tilemap_data_manager.gd	Indirection + load boundaries
Destructible dig/break	Custom data HP	destructible_tile_logic.gd	Must refresh nav/physics after edits
Gameplay queries (friction/hazard)	Custom data + cache	gameplay_data_query.gd / fast_metadata_cache.gd	Cache invalidation on set_cell
Nav after edits	Runtime nav fix	nav_mesh_teleport_fix.gd	Costly if every cell; batch rebuilds
One-way / physics layers	TileSet physics	physics_shape_interaction.gd	Align with CharacterBody masks
Iso / multi-floor sort	Y-sort layers	sorting_Z_layering.gd	Parent + all layers need y_sort
Legacy TileMap → layers	Migration	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
Runtime terrain paths	terrain_path_painter.gd / terrain_autotile.gd
Destructible tiles	destructible_tile_logic.gd
Custom data gameplay reads	gameplay_data_query.gd (+ fast_metadata_cache.gd if hot)
Procedural bulk place	procedural_chunk_batcher.gd
Chunk stream in/out	tilemap_chunking.gd
Pattern stamp prefabs	tile_pattern_stamper.gd
Nav repair after edits	nav_mesh_teleport_fix.gd
One-way / physics layer ops	physics_shape_interaction.gd
Y-sort / Z layering	sorting_Z_layering.gd
4.3+ multi-layer upgrade	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.
• Procgen: stamp patterns or batch terrain; avoid per-cell set_cell storms — tile_pattern_stamper.gd / procedural_chunk_batcher.gd.
• Diff / save deltas: compare get_used_cells() source_id/atlas between layers; persist deltas via 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
Runtime APIs + flood/terrain	runtime-tile-patterns.md
Iso / patterns / diff	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.