Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

TileMapLayer

继承： Node2D < CanvasItem < Node < Object

基于 2D 图块的地图节点。

描述

基于 2D 图块的地图节点。TileMapLayer 即图块地图层，需要使用包含了图块列表的 TileSet，用于创建基于栅格的地图。与已经废弃的 TileMap 节点不同，TileMapLayer 只包含一个图块层。可以使用多个 TileMapLayer 实现和 TileMap 节点相同的效果。

出于性能原因，所有 TileMap 更新都会在一帧结束时进行批处理。值得注意的是，这意味着 TileSetScenesCollectionSource 中的场景图块可能会在其父级之后初始化。仅当在场景树内时才会排队。

要提前强制更新，请调用 update_internals()。

注意：考虑到性能和兼容性，TileMapLayer 所序列化的坐标限制为 16 位带符号整数，即 X、Y 坐标的范围在 -32768 到 32767 之间。保存图块数据时，该范围之外的图块会发生环绕。

教程

属性

bool	collision_enabled	`true`
DebugVisibilityMode	collision_visibility_mode	`0`
bool	enabled	`true`
bool	navigation_enabled	`true`
DebugVisibilityMode	navigation_visibility_mode	`0`
bool	occlusion_enabled	`true`
int	rendering_quadrant_size	`16`
PackedByteArray	tile_map_data	`PackedByteArray()`
TileSet	tile_set
bool	use_kinematic_bodies	`false`
bool	x_draw_order_reversed	`false`
int	y_sort_origin	`0`

方法

void	_tile_data_runtime_update(coords: Vector2i, tile_data: TileData) virtual
void	_update_cells(coords: Array[Vector2i], forced_cleanup: bool) virtual
bool	_use_tile_data_runtime_update(coords: Vector2i) virtual
void	clear()
void	erase_cell(coords: Vector2i)
void	fix_invalid_tiles()
int	get_cell_alternative_tile(coords: Vector2i) const
Vector2i	get_cell_atlas_coords(coords: Vector2i) const
int	get_cell_source_id(coords: Vector2i) const
TileData	get_cell_tile_data(coords: Vector2i) const
Vector2i	get_coords_for_body_rid(body: RID) const
RID	get_navigation_map() const
Vector2i	get_neighbor_cell(coords: Vector2i, neighbor: CellNeighbor) const
TileMapPattern	get_pattern(coords_array: Array[Vector2i])
Array[Vector2i]	get_surrounding_cells(coords: Vector2i)
Array[Vector2i]	get_used_cells() const
Array[Vector2i]	get_used_cells_by_id(source_id: int = -1, atlas_coords: Vector2i = Vector2i(-1, -1), alternative_tile: int = -1) const
Rect2i	get_used_rect() const
bool	has_body_rid(body: RID) const
bool	is_cell_flipped_h(coords: Vector2i) const
bool	is_cell_flipped_v(coords: Vector2i) const
bool	is_cell_transposed(coords: Vector2i) const
Vector2i	local_to_map(local_position: Vector2) const
Vector2i	map_pattern(position_in_tilemap: Vector2i, coords_in_pattern: Vector2i, pattern: TileMapPattern)
Vector2	map_to_local(map_position: Vector2i) const
void	notify_runtime_tile_data_update()
void	set_cell(coords: Vector2i, source_id: int = -1, atlas_coords: Vector2i = Vector2i(-1, -1), alternative_tile: int = 0)
void	set_cells_terrain_connect(cells: Array[Vector2i], terrain_set: int, terrain: int, ignore_empty_terrains: bool = true)
void	set_cells_terrain_path(path: Array[Vector2i], terrain_set: int, terrain: int, ignore_empty_terrains: bool = true)
void	set_navigation_map(map: RID)
void	set_pattern(position: Vector2i, pattern: TileMapPattern)
void	update_internals()

信号

changed() 🔗

TileMapLayer 的属性发生改变时发出。包括对单元格和属性的修改以及对所分配的 TileSet 的修改。

注意：批量修改 TileMapLayer 时可能频繁发出该信号。请勿在连接的函数中执行复杂的处理，建议延迟到帧末尾再进行这些操作（即调用 Object.call_deferred()）。

枚举

enum DebugVisibilityMode: 🔗

DebugVisibilityMode DEBUG_VISIBILITY_MODE_DEFAULT = 0

在编辑器中隐藏碰撞和导航调试形状，使用调试设置决定游戏中的可见性（即 SceneTree.debug_collisions_hint 和 SceneTree.debug_navigation_hint）。

DebugVisibilityMode DEBUG_VISIBILITY_MODE_FORCE_HIDE = 2

始终隐藏碰撞和导航调试形状。

DebugVisibilityMode DEBUG_VISIBILITY_MODE_FORCE_SHOW = 1

始终显示碰撞和导航调试形状。

属性说明

bool collision_enabled = true 🔗

void set_collision_enabled(value: bool)
bool is_collision_enabled()

启用或禁用碰撞。

DebugVisibilityMode collision_visibility_mode = 0 🔗

void set_collision_visibility_mode(value: DebugVisibilityMode)
DebugVisibilityMode get_collision_visibility_mode()

显示或隐藏 TileMapLayer 的碰撞形状。如果设置为 DEBUG_VISIBILITY_MODE_DEFAULT，则取决于调试设置“显示碰撞”。

bool enabled = true 🔗

void set_enabled(value: bool)
bool is_enabled()

如果为 false，则会完全禁用该 TileMapLayer（渲染、碰撞、导航、场景图块等）。

bool navigation_enabled = true 🔗

void set_navigation_enabled(value: bool)
bool is_navigation_enabled()

如果为 true，则启用导航区块。

DebugVisibilityMode navigation_visibility_mode = 0 🔗

void set_navigation_visibility_mode(value: DebugVisibilityMode)
DebugVisibilityMode get_navigation_visibility_mode()

显示或隐藏 TileMapLayer 的导航网格。如果设置为 DEBUG_VISIBILITY_MODE_DEFAULT，则取决于调试设置“显示导航”。

bool occlusion_enabled = true 🔗

void set_occlusion_enabled(value: bool)
bool is_occlusion_enabled()

启用或禁用光线遮蔽。

int rendering_quadrant_size = 16 🔗

void set_rendering_quadrant_size(value: int)
int get_rendering_quadrant_size()

TileMapLayer 的象限大小。象限是在单个画布项上一起绘制的一组图块，用于优化。rendering_quadrant_size 定义的是形成象限的正方形的边长，使用地图坐标系。因此，默认象限大小将 16 * 16 = 256 个图块组合到了一起。

象限大小不适用于 Y 排序的 TileMapLayer，因为在这种情况下图块按 Y 位置分组。

注意：象限是根据地图坐标系创建的，“正方形”的象限在 TileMapLayer 的局部坐标系中可能并不是正方形。

PackedByteArray tile_map_data = PackedByteArray() 🔗

void set_tile_map_data_from_array(value: PackedByteArray)
PackedByteArray get_tile_map_data_as_array()

字节数组形式的图块地图原始数据。

Note: The returned array is copied and any changes to it will not update the original property value. See PackedByteArray for more details.

TileSet tile_set 🔗

void set_tile_set(value: TileSet)
TileSet get_tile_set()

该图层使用的 TileSet。存储的是所有可用图块的纹理、碰撞以及额外的行为。

bool use_kinematic_bodies = false 🔗

void set_use_kinematic_bodies(value: bool)
bool is_using_kinematic_bodies()

如果为 true，则该 TileMapLayer 碰撞形状将被实例化为运动体。这对于移动 TileMapLayer 节点（即移动平台）可能是必要的。

bool x_draw_order_reversed = false 🔗

void set_x_draw_order_reversed(value: bool)
bool is_x_draw_order_reversed()

如果启用了 CanvasItem.y_sort_enabled，则将其设置为 true 将反转在 X 轴上绘制图块的顺序。

int y_sort_origin = 0 🔗

void set_y_sort_origin(value: int)
int get_y_sort_origin()

各个图块的 Y 排序原点值都会加上这个 Y 排序原点值。用例是为图层冒充其他高度级别。在俯视角游戏中比较有用。

方法说明

void _tile_data_runtime_update(coords: Vector2i, tile_data: TileData) virtual 🔗

使用即将由 TileMapLayer 内部使用的 TileData 对象来调用，从而允许在运行时对其进行修改。

仅当 _use_tile_data_runtime_update() 已实现，且它为给定的图块 coords 返回 true 时，才会调用该方法。

警告：tile_data 对象的子资源与 TileSet 中的子资源相同。修改它们可能会影响整个 TileSet。请确保复制这些资源再进行修改。

注意：如果 tile_data 对象的属性应随时间发生变化，请使用 notify_runtime_tile_data_update() 来通知 TileMapLayer 它需要更新。

void _update_cells(coords: Array[Vector2i], forced_cleanup: bool) virtual 🔗

TileMapLayer 的单元格需要内部更新时调用。更新可能由某个单元格的修改触发，也可能由 tile_set 的更改触发（所有单元格都会排队更新）。首次调用该函数始终为对 TileMapLayer 单元格的初始化。coords 包含所有已修改单元格的坐标，大致按照修改顺序排列。应当完全清理 TileMapLayer 的内部数据时 forced_cleanup 为 true。触发条件为：

层禁用；
层不可见；
tile_set 设为 null；
节点从场景树移除；
释放节点；

请注意，满足以上任一条件时进行的内部更新都视为“清理”。另见 update_internals()。

警告：实现该方法可能降低 TileMapLayer 的性能。

bool _use_tile_data_runtime_update(coords: Vector2i) virtual 🔗

如果位于坐标 coords 的图块需要运行时更新，则应返回 true。

警告：请确保这个函数只在需要时返回 true。任何在没有需要的情况下在运行时处理的图块都将导致显著的性能损失。

注意：如果该函数的结果发生变化，请使用 notify_runtime_tile_data_update() 通知 TileMapLayer 它需要更新。

void clear() 🔗

清除所有单元格。

void erase_cell(coords: Vector2i) 🔗

擦除位于坐标 coords 的单元格。

void fix_invalid_tiles() 🔗

清空包含不存在于 tile_set 中的图块的单元格。

int get_cell_alternative_tile(coords: Vector2i) const 🔗

返回位于坐标 coords 的单元格的图块备选 ID。

Vector2i get_cell_atlas_coords(coords: Vector2i) const 🔗

返回位于坐标 coords 的单元格的图块图集坐标 ID。如果单元格不存在则返回 Vector2i(-1, -1)。

int get_cell_source_id(coords: Vector2i) const 🔗

返回位于坐标 coords 的单元格的图块源 ID。如果单元格不存在则返回 -1。

TileData get_cell_tile_data(coords: Vector2i) const 🔗

返回与给定单元格关联的 TileData 对象，如果单元格不存在或者不是 TileSetAtlasSource 则返回 null。

func get_clicked_tile_power():
    var clicked_cell = tile_map_layer.local_to_map(tile_map_layer.get_local_mouse_position())
    var data = tile_map_layer.get_cell_tile_data(clicked_cell)
    if data:
        return data.get_custom_data("power")
    else:
        return 0

Vector2i get_coords_for_body_rid(body: RID) const 🔗

返回给定物理物体 RID 对应图块的坐标。与图块发生碰撞时，可以通过 KinematicCollision2D.get_collider_rid() 获取该 RID。

返回该 TileMapLayer 所使用的 NavigationServer2D 导航 RID。

默认情况下返回的是默认 World2D 导航地图，除非通过 set_navigation_map() 提供了自定义地图。

Vector2i get_neighbor_cell(coords: Vector2i, neighbor: CellNeighbor) const 🔗

返回与位于坐标 coords 的单元格相邻的单元格，方向由 neighbor 表示。这个方法会考虑 TileMap 的不同布局。

TileMapPattern get_pattern(coords_array: Array[Vector2i]) 🔗

根据给定的单元格数组新建 TileMapPattern 并将其返回。另见 set_pattern()。

Array[Vector2i] get_surrounding_cells(coords: Vector2i) 🔗

返回与位于 coords 的单元格相邻的所有单元格的列表。相邻单元格指存在相接边的单元格，因此正方形单元格会返回 4 个单元格，六边形单元格会返回 6 个单元格。

Array[Vector2i] get_used_cells() const 🔗

返回 Vector2i 数组，其中存放的是所有包含图块的单元格的位置。空单元格的源标识符等于 -1、图集坐标标识符为 Vector2(-1, -1)、备选标识符为 -1。

Array[Vector2i] get_used_cells_by_id(source_id: int = -1, atlas_coords: Vector2i = Vector2i(-1, -1), alternative_tile: int = -1) const 🔗

返回 Vector2i 数组，其中存放的是给定图层中所有包含图块的单元格的位置。可以根据源（source_id）、图集坐标（atlas_coords）、备选 ID（alternative_tile）进行过滤。

如果某个参数为默认值，则该参数不会用于单元格的过滤。因此，如果所有参数都使用默认值，则返回的结果与 get_used_cells() 相同。

空单元格的源标识符等于 -1、图集坐标标识符为 Vector2(-1, -1)、备选标识符为 -1。

Rect2i get_used_rect() const 🔗

返回地图的包围矩形，包围已使用（非空）的图块。

bool has_body_rid(body: RID) const 🔗

返回给定的 body RID 属于该 TileMapLayer 中的某个单元格。

bool is_cell_flipped_h(coords: Vector2i) const 🔗

如果位于坐标 coords 的单元格发生了水平翻转，则返回 true。结果仅对图集源有效。

bool is_cell_flipped_v(coords: Vector2i) const 🔗

如果位于坐标 coords 的单元格发生了垂直翻转，则返回 true。结果仅对图集源有效。

bool is_cell_transposed(coords: Vector2i) const 🔗

如果位于坐标 coords 的单元格发生了转置，则返回 true。结果仅对图集源有效。

Vector2i local_to_map(local_position: Vector2) const 🔗

返回包含给定 local_position 的单元格地图坐标。如果 local_position 使用全局坐标，请考虑在传入这个方法前使用 Node2D.to_local()。另见 map_to_local()。

Vector2i map_pattern(position_in_tilemap: Vector2i, coords_in_pattern: Vector2i, pattern: TileMapPattern) 🔗

如果图案粘贴在 position_in_tilemap 坐标处（请参阅 set_pattern()），则返回 TileMapPattern 中给定坐标 coords_in_pattern 对应的单元格坐标。该映射是必需的，因为在半偏移图块形状中，映射可能无法通过计算 position_in_tile_map + coords_in_pattern 工作。

Vector2 map_to_local(map_position: Vector2i) const 🔗

返回单元格的中心位置，使用 TileMapLayer 的局部坐标。要将返回值转换为全局坐标，请使用 Node2D.to_global()。另见 local_to_map()。

注意：可能与图块的可视位置没有对应关系，即忽略各个图块的 TileData.texture_origin 属性。

void notify_runtime_tile_data_update() 🔗

通知 TileMapLayer 节点调用 _use_tile_data_runtime_update() 或 _tile_data_runtime_update() 会得到不同的结果，继而触发 TileMapLayer 的更新。

警告：更新 TileMapLayer 的计算成本很高，并且可能会影响性能。尝试限制该函数的调用次数，以避免不必要的更新。

注意：这不会触发 TileMapLayer 的直接更新，该更新将照常在帧结束时完成（除非你调用 update_internals()）。

void set_cell(coords: Vector2i, source_id: int = -1, atlas_coords: Vector2i = Vector2i(-1, -1), alternative_tile: int = 0) 🔗

设置坐标为 coords 的单元格的图块标识符。TileSet 中的每个图块都由三部分进行标识：

源标识符 source_id 标识的是 TileSetSource 标识符。见 TileSet.set_source_id()，
图集坐标标识符 atlas_coords 标识的是图集中的图块坐标（如果使用的是 TileSetAtlasSource 源）。如果使用的是 TileSetScenesCollectionSource，应该始终为 Vector2i(0, 0)，
备选图块标识符 alternative_tile 标识的是图集中的图块备选项（如果使用的是 TileSetAtlasSource 源），如果使用的是 TileSetScenesCollectionSource 则标识的是场景。

如果 source_id 为 -1、atlas_coords 为 Vector2i(-1, -1) 或 alternative_tile 为 -1，则会擦除该单元格。擦除后的单元格中，所有标识符都会自动设为对应的无效值，即 -1、Vector2i(-1, -1) 和 -1。

void set_cells_terrain_connect(cells: Array[Vector2i], terrain_set: int, terrain: int, ignore_empty_terrains: bool = true) 🔗

更新 cells 坐标数组中的所有单元格，以便它们将给定的 terrain 用于给定的 terrain_set。如果一个更新的单元格与其相邻单元格之一具有相同的地形，则该函数会尝试将两者连接起来。如果需要创建正确的地形过渡，该函数可能会更新相邻的图块。

如果 ignore_empty_terrains 为 true，则在尝试为给定地形约束找到最合适的图块时，空地形将被忽略。

注意：要正常工作，这个方法需要 TileMap 的 TileSet 设置了具有所有必需地形组合的地形。否则，可能会产生意想不到的结果。

void set_cells_terrain_path(path: Array[Vector2i], terrain_set: int, terrain: int, ignore_empty_terrains: bool = true) 🔗

更新 path 坐标数组中的所有单元格，以便它们将给定的 terrain 用于给定的 terrain_set。该函数还将连接路径中具有相同地形的两个连续单元格。如果需要创建正确的地形过渡，该函数可能会更新相邻的图块。

如果 ignore_empty_terrains 为 true，则在尝试为给定地形约束找到最合适的图块时将忽略空地形。

注意：要正常工作，这个方法需要 TileMap 的 TileSet 设置了具有所有必需地形组合的地形。否则，可能会产生意想不到的结果。

将自定义 map 设置为 NavigationServer2D 导航地图。如果未设置，则改用默认的 World2D 导航地图。

void set_pattern(position: Vector2i, pattern: TileMapPattern) 🔗

将给定的 TileMapPattern 粘贴到图块地图中的 position 位置。另见 get_pattern()。

void update_internals() 🔗

触发 TileMapLayer 的更新。通常不需要调用这个函数，因为 TileMapLayer 节点的属性发生修改后会自动更新。

但是出于性能原因，会对这些更新进行分批，延迟到该帧的末尾执行。调用这个函数会强制 TileMapLayer 立即进行更新。

警告：更新 TileMapLayer 的计算量很大，可能会影响性能。请尽量限制更新的次数和受影响的图块。