godot-tilemap-mastery

TileMaps 中绝对不要做的事

• 绝对不要在未批处理的情况下，在大型循环中调用 set_cell() — 优先使用地形连接、图案或区块批处理器。
• 绝对不要忘记在 set_cell 中填写 source_id — 使用错误的重载 → 崩溃或静默失败。
• 绝对不要混用世界坐标和图块坐标 — 始终使用 local_to_map / map_to_local。
• 绝对不要在存在地形功能时手动绘制有机形状的区域 — 使用地形集 + set_cells_terrain_connect。
• 绝对不要将动态角色放入 TileMap — 敌人/拾取物是节点；图块用于几何结构/可破坏单元格。
• 绝对不要在每个物理帧都频繁调用 get_cell_tile_data() — 缓存元数据（fast_metadata_cache.gd）。

---

决策树：如何写入单元格

目标	首选方案	脚本	权衡
有机地面 / 道路 / 河流	地形自动拼接	terrain_autotile.gd / terrain_path_painter.gd	TileSet 的设置成本；设计师迭代最快
预制房间 / 房屋 / 印章	TileMapPattern	tile_pattern_stamper.gd	非常适合程序化生成的部件；按单元格调整的灵活性较低
稀疏 / 精确编辑	set_cell	—	少量单元格时没问题；每帧数千个则不适用
大型流式世界	区块	tilemap_chunking.gd / procedural_chunk_batcher.gd / tilemap_data_manager.gd	增加间接层 + 加载边界
可破坏式挖掘/破坏	自定义数据 HP	destructible_tile_logic.gd	编辑后必须刷新导航/物理
游戏玩法查询（摩擦力/危险）	自定义数据 + 缓存	gameplay_data_query.gd / fast_metadata_cache.gd	调用 set_cell 时需要使缓存失效
编辑后的导航	运行时导航修复	nav_mesh_teleport_fix.gd	每个单元格都处理的话成本高；应批量重建
单向 / 物理层	TileSet 物理	physics_shape_interaction.gd	与 CharacterBody 碰撞掩码对齐
等距 / 多楼层排序	Y-sort 层	sorting_Z_layering.gd	父节点和所有层都需要启用 y_sort
旧版 TileMap → 图层	迁移	tilemap_layer_v43_upgrade.gd	一次性升级辅助工具

编辑器图集/物理绘制设置：请参阅 Reference 中的官方文档 — 不要从此技能正文重新加载步骤 1–3 / flood_fill 教程。

可用脚本（单一索引 + 强制触发条件）

任务	强制使用的脚本
序列化 / 大型世界数据	tilemap_data_manager.gd
运行时地形路径	terrain_path_painter.gd / terrain_autotile.gd
可破坏图块	destructible_tile_logic.gd
自定义数据的游戏玩法读取	gameplay_data_query.gd（如果频繁调用，则使用 fast_metadata_cache.gd）
程序化批量放置	procedural_chunk_batcher.gd
区块流式加载/卸载	tilemap_chunking.gd
图案印章预制件	tile_pattern_stamper.gd
编辑后的导航修复	nav_mesh_teleport_fix.gd
单向 / 物理层操作	physics_shape_interaction.gd
Y-sort / Z 分层	sorting_Z_layering.gd
4.3+ 多图层升级	tilemap_layer_v43_upgrade.gd

专家级权衡（仅路由）

• **等距 Y 排序：**在父节点和每个 TileMapLayer 上启用 y_sort_enabled；调整高大瓦片的 y_sort_origin — 参见 sorting_Z_layering.gd。
• **程序化生成：**盖印图案或批量处理地形；避免逐格调用 set_cell — tile_pattern_stamper.gd / procedural_chunk_batcher.gd。
• **差异 / 保存增量：**比较各图层之间 get_used_cells() 的 source_id/atlas；尽可能通过 tilemap_data_manager.gd 保存增量，而非保存完整地图。

深入指南（按需查阅）

LLM 无知规则：如果通用 Agent 在阅读前不会了解某项内容，就将其放在此处或 scripts/ 中 — 绝不要删除，只能移动。

主题	参考资料
TileSet 编辑器步骤	tileset-editor-setup.md
运行时 API + 洪泛 / 地形	runtime-tile-patterns.md
等距 / 图案 / 差异	expert-tilemap-architectures.md

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接；需要路由到相关领域时再加载相关技能 — 不要预先加载整个知识网络。

官方文档

• 使用 TileMaps — TileMapLayer 工作流、图层、运行时 set_cell / 地形绘制，以及多图层优于单个旧版 TileMap 的适用场景。
• 使用 TileSets — 图集源、地形，以及在 TileSet 编辑器中绘制的物理 / 导航 / 自定义数据图层。
• TileMapLayer — 单元格 API、地形连接、图案、坐标转换和运行时瓦片数据更新。
• TileSet — 由引用该资源的每个 TileMapLayer 共享的物理 / 地形 / 自定义数据图层定义。
• TileSetAtlasSource — 图集网格、替代项，以及用于驱动碰撞和元数据的逐瓦片 TileData。
• TileData — 查询时使用的自定义数据、物理多边形、导航多边形和 y_sort_origin。
• TileMapPattern — 捕获 / 盖印多瓦片预制件，无需逐格循环调用 set_cell。
• 碰撞形状（2D） — TileSet 物理图层向 CharacterBody2D 提供的形状选择和单向碰撞模式。
• 导航简介（2D） — 编辑后，瓦片导航多边形如何传递给 NavigationRegion2D / NavigationAgent2D。
• 画布图层 — 地面、装饰和屋顶 TileMapLayer 的 z-index / CanvasLayer 分离。
• 后台加载 — 用于流式加载区块 TileSets / 瓦片地图场景的多线程 ResourceLoader 模式，可避免卡顿尖峰。

相关技能

前置条件

• godot-project-foundations — 在创建 TileSet 图集和多层关卡场景前，了解场景树、资源和导入布局。
• godot-gdscript-mastery — 了解运行时瓦片管理器中使用的类型化 Vector2i API、缓存模式以及信号向上／调用向下的结构。
• godot-2d-physics — 了解 TileMapLayer 物理层所涉及的碰撞层／遮罩，以及等效于 StaticBody2D 的行为。

互补技能

• godot-version-migration — tilemap_layer_v43_upgrade 和 TileMap→TileMapLayer 属于 4.x 迁移路径；应用图层脚本前，请先通过迁移中心升级引擎。
• godot-characterbody-2d — 了解针对瓦片碰撞体调用 move_and_slide、单向平台，以及基于 TileMapLayer 几何体进行地板／墙面查询。
• godot-navigation-pathfinding — 当可破坏或程序生成的瓦片改变可行走多边形时，更新 NavigationAgent2D／区域。
• godot-camera-systems — 了解用于驱动玩家周围区块加载／卸载的 Camera2D 边界和跟随半径。
• godot-adapt-3d-to-2d — 了解与 TILE_SHAPE_ISOMETRIC 和多楼层 TileMapLayers 配合使用的等距视角／Y 轴排序深度技巧。
• godot-scene-management — 了解区块场景的打包和切换，确保大型瓦片世界流式加载时不会留下孤立图层。
• godot-performance-optimization — 当 set_cell／自定义数据查询占用大量帧时间时，了解批处理、缓存预算和性能分析器检查。

下游／使用方

• godot-procedural-generation — 使用地形连接、图案或区块批处理器写入单元格的噪声／BSP／WFC 生成器。
• godot-genre-platformer — 使用 TileSet 物理、单向平台和危险物自定义数据构建的精准平台跳跃关卡。
• godot-genre-metroidvania — 基于 TileMapLayer 区块构建的互连房间网格、能力门和地图揭示机制。
• godot-genre-sandbox — 将 TileMapLayer 视为可编辑地形后端的可挖掘／可建造 2D 世界。
• godot-monte-carlo-balancer — 发布地图前，模拟瓦片自定义数据中编码的危险物密度、可破坏物耐久值和移动成本。

主入口

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。