Skill v1.0.2

version: "1.0.2" 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

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)

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.

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.