Godot 瓦片地图

要解决的具体问题

在 Godot 4.3+ 中开发 2D 瓦片地图关卡时，开发者面临三个核心痛点：一是传统 TileMap 节点已被废弃，需迁移到多节点 TileMapLayer 架构；二是瓦片的碰撞、导航、自定义数据（如伤害值、梯子标记）和地形自动连接需要精细配置；三是运行时动态修改瓦片（如放置、擦除、遍历）涉及坐标转换、数据读取和类型校验等细节。这些操作分散在不同编辑器面板和代码中，缺乏统一指导容易导致碰撞失效、数据类型错误或地形连接异常。

技能如何工作

核心能力

• 多图层管理：每个 TileMapLayer 节点对应一个逻辑图层（背景、墙壁、前景），通过 collision_enabled 和 navigation_enabled 属性独立控制碰撞和导航。
• TileSet 配置：在 TileSet 编辑器中配置 atlas 源、物理层（碰撞多边形）、导航层、遮挡层和自定义数据层（支持 int、float、String 等类型）。
• 地形自动连接：定义地形集并通过 Connect/Path 模式绘画，自动匹配相邻瓦片的地形连接。
• 运行时操作：使用 local_to_map 转换坐标、set_cell 修改瓦片、get_cell_source_id 读取源 ID、get_cell_tile_data(...).get_custom_data(...) 获取自定义数据。

关键步骤

1. 添加 TileMapLayer 节点：每个视觉/逻辑图层一个节点，父节点为 Node2D。
2. 创建/分配 TileSet：保存为 .tres 文件以便多图层/关卡复用。
3. 配置瓦片数据：在 TileSet 编辑器中添加碰撞多边形、导航层、自定义数据层和地形集。
4. 绘画瓦片：使用 Paint/Line/Rectangle/Bucket 工具，地形连接用 Connect/Path 模式。
5. 代码读写：通过 local_to_map、set_cell、get_cell_tile_data 等 API 操作瓦片。

适用边界与注意点

• 适用场景：2D 瓦片网格关卡设计、TileSet 配置（碰撞/导航/自定义数据/地形）、代码读写瓦片、从 TileMap 迁移到 TileMapLayer。
• 不适用场景：玩家跨瓦片移动（→ godot-2d-movement）、通用物理体/射线（→ godot-physics）、程序化地图生成（→ procedural-gen）、关卡设计实践（→ level-design）。
• 关键注意点：

- TileMap 节点已废弃，必须使用 TileMapLayer（单图层单节点）。
- local_to_map 需要局部坐标，鼠标/全局坐标需先 to_local(...) 转换。
- get_cell_tile_data 对空单元格或非 atlas 源返回 null，需先判空再访问自定义数据。
- 自定义数据层类型严格（如 int 层返回 int），类型不匹配或引用不存在的层名会报错。
- 地形连接需定义所有可能的相邻组合，否则 set_cells_terrain_connect 结果异常。
- 运行时编辑批处理到帧末，立即读取需调用 update_internals()（高开销，避免循环中调用）。
- 碰撞失效时检查图层的 collision_enabled、瓦片物理层多边形、TileSet 物理层掩码与碰撞体匹配。