技能介绍

解决的工程痛点

Godot 4.3 引入了 TileMapLayer 节点以取代旧版 TileMap，这导致大量旧项目面临迁移问题，同时新项目的多层瓦片管理也变得更碎片化。此外，仅靠编辑器绘制无法满足运行时动态生成或修改地图的需求，而直接操作瓦片数据常因 API 误用（如坐标系未转换、空指针）导致崩溃或逻辑错误。

核心工作流与能力

该技能围绕 Godot 4.3+ 的 TileMapLayer 构建，核心工作流如下：

节点与资源管理：为每个逻辑层创建独立的 TileMapLayer 节点，并将配置好的 TileSet 保存为 .tres 资源以供复用。
数据配置：在 TileSet 编辑器中配置物理碰撞多边形、导航层、遮挡以及自定义数据层（如伤害值、是否为梯子）。
地形与自动拼接：定义地形集（Terrain Set），使用 Connect/Path 模式实现自连接瓦片的无缝拼接。
运行时操作：通过 local_to_map、set_cell 和 get_cell_tile_data 等 API 在代码中动态读写瓦片。

适用边界与避坑指南

坐标转换：local_to_map 需要局部坐标，鼠标全局坐标必须先通过 to_local() 转换，否则会导致瓦片偏移。
空值与类型检查：get_cell_tile_data 对空格或非图集来源返回 null，调用 get_custom_data 前必须判空。自定义数据是强类型的，读取类型与声明不符会报错。
碰撞失效排查：若碰撞不生效，需检查图层的 collision_enabled 属性、瓦片是否包含物理多边形，以及 TileSet 物理层掩码是否与场景刚体匹配。
性能注意：运行时编辑是帧末批量提交的，若需立即读取更新后的内部状态需调用 update_internals()，但应避免在循环中频繁调用。
适用边界：本技能不涉及角色在瓦片上的移动逻辑或纯程序化地图生成算法，相关场景请参考 godot-2d-movement 与 procedural-gen。