godot-tilemap

Godot TileMap（4.7 TileMapLayer）

使用 TileMapLayer + TileSet 创建基于瓦片的关卡，为每个瓦片添加碰撞和自定义数据，使用地形自动拼接瓦片，并在运行时操作单元格。面向 Godot 4.7；在此版本中，TileMapLayer 取代了现已弃用的 TileMap 节点。

适用场景

• 需要使用瓦片网格设计 2D 关卡、配置 TileSet（碰撞、导航、自定义数据、地形），或通过代码读取/写入瓦片时。
• 需要将 TileMap 节点（单个节点包含多个图层）迁移为多个 TileMapLayer 节点（每个节点一个图层）时。

不适用场景： 控制玩家在瓦片上移动 → godot-2d-movement；通用物理实体/射线检测 → godot-physics；程序化地图生成算法 → procedural-gen；关卡设计实践 → level-design。

核心工作流

1. 添加一个 TileMapLayer 节点（每个视觉/逻辑图层各一个：背景、墙壁、前景）。每个节点只包含一个瓦片图层。
2. 在图层的 tile_set 属性中创建或指定 TileSet。在 TileSet 编辑器中添加图集源（将纹理切分为瓦片）。将 TileSet 保存为外部 .tres 文件，供多个图层/关卡重复使用。
3. 在 TileSet 编辑器中添加瓦片数据： 物理图层（碰撞多边形）、导航图层、遮挡，以及自定义数据图层（每个瓦片的类型化值，例如 damage 或 is_ladder）。
4. 在 TileMap 底部面板中绘制（Paint/Line/Rectangle/Bucket）。对于可自动连接的瓦片，定义一个地形集，并使用 Connect/Path 模式绘制。
5. 通过图层的 collision_enabled / navigation_enabled 属性启用每个图层的碰撞/导航。
6. 使用 local_to_map、set_cell、get_cell_source_id 和 get_cell_tile_data(...).get_custom_data(...) 通过代码读取/写入。

常见模式

1. 将鼠标位置转换为单元格并读取其自定义数据

extends TileMapLayer

func _unhandled_input(event: InputEvent) -> void:
    if event is InputEventMouseButton and event.pressed:
        # local_to_map expects local coords; convert from global first.
        var cell := local_to_map(to_local(event.position))
        var data := get_cell_tile_data(cell)   # TileData or null
        if data:
            var dmg: int = data.get_custom_data("damage")  # custom data layer
            print("Cell %s deals %d damage" % [cell, dmg])

2. 在运行时放置和擦除瓦片

# set_cell(coords, source_id, atlas_coords, alternative_tile = 0)
func place_wall(cell: Vector2i) -> void:
    set_cell(cell, 0, Vector2i(2, 1))   # source 0, atlas tile at column 2, row 1

func dig(cell: Vector2i) -> void:
    erase_cell(cell)                    # same as set_cell(cell, -1)

func clear_level() -> void:
    clear()                             # remove every tile on this layer

3. 使用地形集自动拼接区域

# Paint a filled area with terrain `terrain` of terrain set `terrain_set`;
# Godot picks the correct edge/corner tiles to connect them.
func fill_with_grass(cells: Array[Vector2i]) -> void:
    var terrain_set := 0
    var grass_terrain := 0
    set_cells_terrain_connect(cells, terrain_set, grass_terrain, true)

4. 遍历已放置的瓦片（例如查找所有出生点瓦片）

func find_spawns() -> Array[Vector2i]:
    var spawns: Array[Vector2i] = []
    for cell in get_used_cells():
        var data := get_cell_tile_data(cell)
        if data and data.get_custom_data("is_spawn"):
            spawns.append(cell)
    return spawns

注意事项

• TileMap 节点在 4.3 中已弃用。 请使用 TileMapLayer 节点（每个节点一个图层），并将它们归到父级 Node2D 下。旧版 TileMap 中接受 layer 参数的调用（set_cell(layer, ...)）不适用于 TileMapLayer。
• local_to_map 需要局部坐标。 必须先使用 to_local(...) 转换鼠标/全局位置，否则单元格位置会出现偏移。
• get_cell_tile_data 对空单元格或非图集源会返回 null——调用 get_custom_data 前务必检查是否为 null。
• 自定义数据有类型。 声明为 int 的图层会返回 int；以错误类型读取或引用不存在的图层名称都会报错。请先在 TileSet 中定义该图层。
• 地形需要定义所有组合。 如果 TileSet 的地形位掩码邻接关系不完整，set_cells_terrain_connect 会产生异常结果。
• 运行时编辑会批量处理到帧末。如果必须在调用 set_cell 后立即读取更新后的内部数据，请调用 update_internals()（开销较大——避免在循环中调用）。
• 碰撞不起作用？ 检查图层的 collision_enabled、瓦片是否拥有带多边形的物理图层，以及 TileSet 的物理图层掩码是否与物理实体匹配。

参考资料

• 有关 TileSet 设置（图集源、物理/导航/自定义数据图层、地形位掩码）、场景瓦片、Y 轴排序，以及运行时瓦片数据覆盖（_use_tile_data_runtime_update），请阅读 references/tileset-and-terrains.md。

相关技能

• godot-2d-movement — 在这些瓦片上行走的角色。
• godot-physics — 瓦片碰撞所参与的碰撞图层/掩码。
• procedural-gen — 使用噪声/RNG 生成瓦片地图。
• level-design / roguelike — 关卡设计实践和网格类游戏。