Godot Tilemap Mastery Agent Skill

Godot 4.7 Baseline

• Expert patterns in this skill target Godot 4.7+ (stable, 2026-06-18).
• Consult the Godot 4.7 migration guide when upgrading projects from 4.6.
• NEVER assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.

TileMap Mastery

TileMapLayer routing + trade-offs — not TileSet editor Steps 1–3 tutorials (see Official Docs).

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