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...

TileMap

已弃用： Use multiple TileMapLayer nodes instead. To convert a TileMap to a set of TileMapLayer nodes, open the TileMap bottom panel with the node selected, click the toolbox icon in the top-right corner and choose 'Extract TileMap layers as individual TileMapLayer nodes'.

继承： Node2D < CanvasItem < Node < Object

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

描述

基于 2D 图块的地图节点。Tilemap（图块地图）使用 TileSet，其中包含了图块的列表，用于创建基于栅格的地图。TileMap 可以有若干图层，可以将图块布局在彼此之上。

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

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

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

教程

属性

bool	collision_animatable	`false`
VisibilityMode	collision_visibility_mode	`0`
VisibilityMode	navigation_visibility_mode	`0`
int	rendering_quadrant_size	`16`
TileSet	tile_set

方法

void	_tile_data_runtime_update(layer: int, coords: Vector2i, tile_data: TileData) virtual
bool	_use_tile_data_runtime_update(layer: int, coords: Vector2i) virtual
void	add_layer(to_position: int)
void	clear()
void	clear_layer(layer: int)
void	erase_cell(layer: int, coords: Vector2i)
void	fix_invalid_tiles()
void	force_update(layer: int = -1)
int	get_cell_alternative_tile(layer: int, coords: Vector2i, use_proxies: bool = false) const
Vector2i	get_cell_atlas_coords(layer: int, coords: Vector2i, use_proxies: bool = false) const
int	get_cell_source_id(layer: int, coords: Vector2i, use_proxies: bool = false) const
TileData	get_cell_tile_data(layer: int, coords: Vector2i, use_proxies: bool = false) const
Vector2i	get_coords_for_body_rid(body: RID)
int	get_layer_for_body_rid(body: RID)
Color	get_layer_modulate(layer: int) const
String	get_layer_name(layer: int) const
RID	get_layer_navigation_map(layer: int) const
int	get_layer_y_sort_origin(layer: int) const
int	get_layer_z_index(layer: int) const
int	get_layers_count() const
RID	get_navigation_map(layer: int) const
Vector2i	get_neighbor_cell(coords: Vector2i, neighbor: CellNeighbor) const
TileMapPattern	get_pattern(layer: int, coords_array: Array[Vector2i])
Array[Vector2i]	get_surrounding_cells(coords: Vector2i)
Array[Vector2i]	get_used_cells(layer: int) const
Array[Vector2i]	get_used_cells_by_id(layer: int, source_id: int = -1, atlas_coords: Vector2i = Vector2i(-1, -1), alternative_tile: int = -1) const
Rect2i	get_used_rect() const
bool	is_cell_flipped_h(layer: int, coords: Vector2i, use_proxies: bool = false) const
bool	is_cell_flipped_v(layer: int, coords: Vector2i, use_proxies: bool = false) const
bool	is_cell_transposed(layer: int, coords: Vector2i, use_proxies: bool = false) const
bool	is_layer_enabled(layer: int) const
bool	is_layer_navigation_enabled(layer: int) const
bool	is_layer_y_sort_enabled(layer: int) 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	move_layer(layer: int, to_position: int)
void	notify_runtime_tile_data_update(layer: int = -1)
void	remove_layer(layer: int)
void	set_cell(layer: int, coords: Vector2i, source_id: int = -1, atlas_coords: Vector2i = Vector2i(-1, -1), alternative_tile: int = 0)
void	set_cells_terrain_connect(layer: int, cells: Array[Vector2i], terrain_set: int, terrain: int, ignore_empty_terrains: bool = true)
void	set_cells_terrain_path(layer: int, path: Array[Vector2i], terrain_set: int, terrain: int, ignore_empty_terrains: bool = true)
void	set_layer_enabled(layer: int, enabled: bool)
void	set_layer_modulate(layer: int, modulate: Color)
void	set_layer_name(layer: int, name: String)
void	set_layer_navigation_enabled(layer: int, enabled: bool)
void	set_layer_navigation_map(layer: int, map: RID)
void	set_layer_y_sort_enabled(layer: int, y_sort_enabled: bool)
void	set_layer_y_sort_origin(layer: int, y_sort_origin: int)
void	set_layer_z_index(layer: int, z_index: int)
void	set_navigation_map(layer: int, map: RID)
void	set_pattern(layer: int, position: Vector2i, pattern: TileMapPattern)
void	update_internals()

信号

changed() 🔗

该 TileMap 的 TileSet 发生改变时发出。

枚举

enum VisibilityMode: 🔗

VisibilityMode VISIBILITY_MODE_DEFAULT = 0

使用调试设置确定可见性。

VisibilityMode VISIBILITY_MODE_FORCE_HIDE = 2

始终隐藏。

VisibilityMode VISIBILITY_MODE_FORCE_SHOW = 1

始终显示。

属性说明

bool collision_animatable = false 🔗

void set_collision_animatable(value: bool)
bool is_collision_animatable()

如果启用，TileMap 将看到它的碰撞同步到物理周期并将其碰撞类型从静态更改为运动学。这是创建基于 TileMap 的移动的平台所必需的。

注意：启用 collision_animatable 可能会对性能产生一个很小的影响，只有在该 TileMap 正在移动并且有碰撞的图块时才这样做。

VisibilityMode collision_visibility_mode = 0 🔗

void set_collision_visibility_mode(value: VisibilityMode)
VisibilityMode get_collision_visibility_mode()

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

VisibilityMode navigation_visibility_mode = 0 🔗

void set_navigation_visibility_mode(value: VisibilityMode)
VisibilityMode get_navigation_visibility_mode()

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

int rendering_quadrant_size = 16 🔗

void set_rendering_quadrant_size(value: int)
int get_rendering_quadrant_size()

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

Y 排序的图层不使用象限大小，这种图层中的图块会按 Y 位置分组。

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

TileSet tile_set 🔗

void set_tileset(value: TileSet)
TileSet get_tileset()

该 TileMap 所使用的 TileSet。所有可用图块的纹理、碰撞以及其他额外行为都存储在这里。

方法说明

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

会使用 TileMap 内部即将使用的 TileData 对象来调用，从而实现运行时修改。

这个方法被调用的前提是：实现了 _use_tile_data_runtime_update()，并且对给定的图块坐标 coords 和层 layer 返回 true 。

警告：该 tile_data 对象的子资源和 TileSet 中的子资源是一样的。对它们进行修改可能会影响整个 TileSet。请确保制作这些资源的副本再进行修改。

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

bool _use_tile_data_runtime_update(layer: int, coords: Vector2i) virtual 🔗

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

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

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

void add_layer(to_position: int) 🔗

在数组中的给定位置 to_position 添加层。如果 to_position 为负数，则位置从结尾处开始计数，-1 会把层添加在数组的末尾。

void clear() 🔗

清除所有单元格。

void clear_layer(layer: int) 🔗

清除给定图层上的所有单元格。

如果 layer 为负，则从最后一个图层开始访问。

void erase_cell(layer: int, coords: Vector2i) 🔗

擦除图层 layer 上位于 coords 坐标的单元格。

如果 layer 为负，则从最后一个图层开始访问。

void fix_invalid_tiles() 🔗

清除图块集中不存在的单元格。

void force_update(layer: int = -1) 🔗

已弃用： Use notify_runtime_tile_data_update() and/or update_internals() instead.

强制更新 TileMap 和图层 layer。

int get_cell_alternative_tile(layer: int, coords: Vector2i, use_proxies: bool = false) const 🔗

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

如果 use_proxies 为 false，则会忽略该 TileSet 的图块代理，返回原始的备选标识符。见 TileSet.map_tile_proxy()。

如果 layer 为负，则从最后一个图层开始访问。

Vector2i get_cell_atlas_coords(layer: int, coords: Vector2i, use_proxies: bool = false) const 🔗

返回图层 layer 上坐标 coords 处单元格的图块地图集坐标 ID。如果单元格不存在，则返回 Vector2i(-1, -1)。

如果 use_proxies 为 false，则忽略 TileSet 的图块代理，返回原始图集坐标标识符。请参阅 TileSet.map_tile_proxy()。

如果 layer 为负，则从最后一个图层开始访问。

int get_cell_source_id(layer: int, coords: Vector2i, use_proxies: bool = false) const 🔗

返回坐标 coords 处图层 layer 上单元格的图块源 ID。如果单元格不存在，则返回 -1。

如果 use_proxies 为 false，则忽略 TileSet 的图块代理，返回原始源标识符。请参阅 TileSet.map_tile_proxy()。

如果 layer 为负，则从最后一个图层开始访问。

TileData get_cell_tile_data(layer: int, coords: Vector2i, use_proxies: bool = false) const 🔗

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

如果 layer 为负，则从最后一个图层开始访问。

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

如果 use_proxies 为 false，则会忽略 TileSet 的图块代理。见 TileSet.map_tile_proxy()。

Vector2i get_coords_for_body_rid(body: RID) 🔗

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

int get_layer_for_body_rid(body: RID) 🔗

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

Color get_layer_modulate(layer: int) const 🔗

返回 TileMap 图层的调制颜色。

如果 layer 为负，则从最后一个图层开始访问。

String get_layer_name(layer: int) const 🔗

返回 TileMap 图层的名称。

如果 layer 为负，则从最后一个图层开始访问。

返回分配给指定 TileMap 图层 layer 的 NavigationServer2D 导航地图的 RID。

默认情况下，TileMap 为第一个 TileMap 层，使用默认的 World2D 导航地图。对于每个附加的 TileMap 层，都会为附加层创建一个新的导航地图。

为了使 NavigationAgent2D 在 TileMap 层导航地图之间切换，使用 NavigationAgent2D.set_navigation_map() 和从 get_navigation_map() 接收的导航地图。

如果 layer 为负，则从最后一个图层开始访问。

int get_layer_y_sort_origin(layer: int) const 🔗

返回 TileMap 图层的 Y 排序原点。

如果 layer 为负，则从最后一个图层开始访问。

int get_layer_z_index(layer: int) const 🔗

返回 TileMap 图层的 Z 索引值。

如果 layer 为负，则从最后一个图层开始访问。

int get_layers_count() const 🔗

返回 TileMap 图层的数量。

已弃用： Use get_layer_navigation_map() instead.

返回分配给指定 TileMap 图层 layer 的 NavigationServer2D 导航地图的 RID。

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

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

TileMapPattern get_pattern(layer: int, coords_array: Array[Vector2i]) 🔗

根据给定的图层和单元格新建 TileMapPattern。

如果 layer 为负，则从最后一个图层开始访问。

Array[Vector2i] get_surrounding_cells(coords: Vector2i) 🔗

返回与 coords 处的单元格相邻的所有单元格的列表。

Array[Vector2i] get_used_cells(layer: int) const 🔗

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

如果 layer 为负，则从最后一个图层开始访问。

Array[Vector2i] get_used_cells_by_id(layer: int, 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。

如果 layer 为负，则从最后一个图层开始访问。

Rect2i get_used_rect() const 🔗

返回该地图的包围矩形，包围所有图层中的已使用（非空）的图块。

bool is_cell_flipped_h(layer: int, coords: Vector2i, use_proxies: bool = false) const 🔗

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

bool is_cell_flipped_v(layer: int, coords: Vector2i, use_proxies: bool = false) const 🔗

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

bool is_cell_transposed(layer: int, coords: Vector2i, use_proxies: bool = false) const 🔗

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

bool is_layer_enabled(layer: int) const 🔗

返回某个图层是否已启用。

如果 layer 为负，则从最后一个图层开始访问。

返回是否启用图层的内置导航区块生成。

bool is_layer_y_sort_enabled(layer: int) const 🔗

返回某个图层是否会对图块进行 Y 排序。

如果 layer 为负，则从最后一个图层开始访问。

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 🔗

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

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

void move_layer(layer: int, to_position: int) 🔗

将索引 layer 处的图层移动到数组中给定的位置 to_position。

void notify_runtime_tile_data_update(layer: int = -1) 🔗

通知 TileMap 节点调用 _use_tile_data_runtime_update() 或 _tile_data_runtime_update() 将导致不同的结果。这将因此触发 TileMap 更新。

如果提供了 layer，则仅通知给定层的更改。出于性能原因，通常首选提供 layer 参数（如果适用）。

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

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

void remove_layer(layer: int) 🔗

移除索引为 layer 的层。

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

设置位于层 layer 坐标为 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。

如果 layer 为负数，则从最后一个图层开始访问。

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

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

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

如果 layer 为负，则从最后一个图层开始访问。

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

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

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

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

如果 layer 为负，则从最后一个图层开始访问。

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

void set_layer_enabled(layer: int, enabled: bool) 🔗

启用或禁用图层 layer。被禁用的图层根本不会被处理（没有渲染、物理等）。

如果 layer 为负数，则从最后一个图层开始访问。

void set_layer_modulate(layer: int, modulate: Color) 🔗

设置图层的颜色。该颜色会与图块的颜色以及 TileMap 的调制色相乘。

如果 layer 为负，则逆序访问图层。

void set_layer_name(layer: int, name: String) 🔗

设置图层的名称。主要在编辑器中使用。

如果 layer 为负，则逆序访问图层。

启用或禁用图层的内置导航区块生成。如果你需要使用 NavigationRegion2D 节点根据 TileMap 烘焙导航区块，请禁用此项。

将 map 分配给指定 TileMap 图层 layer 的 NavigationServer2D 导航地图。

默认情况下，TileMap 为第一个 TileMap 层使用默认的 World2D 导航地图。对于每个附加的 TileMap 层，都会为附加层创建一个新的导航地图。

为了使 NavigationAgent2D 在 TileMap 层导航地图之间切换，使用 NavigationAgent2D.set_navigation_map() 和从 get_navigation_map() 接收的导航地图。

如果 layer 为负，则从最后一个图层开始访问。

void set_layer_y_sort_enabled(layer: int, y_sort_enabled: bool) 🔗

启用或禁用图层的 Y 排序。如果进行了 Y 排序，则该图层和 CanvasItem 节点的行为一致，会将其中的每个图块都进行 Y 排序。

Y 排序图层的 Z 索引一般应该和未 Y 排序的图层不同，否则未 Y 排序的图层会作为一个整体，和 Y 排序图层一起进行 Y 排序。通常不希望发生这样的行为。

如果 layer 为负，则逆序访问图层。

void set_layer_y_sort_origin(layer: int, y_sort_origin: int) 🔗

设置图层的 Y 排序原点。各个图块的 Y 排序原点值都会加上这个 Y 排序原点值。

用例是为图层冒充不同的高度级别。俯视角游戏比较有用。

如果 layer 为负，则逆序访问图层。

void set_layer_z_index(layer: int, z_index: int) 🔗

设置图层的 Z 索引值。各个图块的 Z 索引值都会加上这个 Z 索引。

如果 layer 为负，则逆序访问图层。

已弃用： Use set_layer_navigation_map() instead.

将 map 分配为指定 TileMap 层 layer 的 NavigationServer2D 导航地图。

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

将给定的 TileMapPattern 粘贴到图块地图中的 position 位置和 layer 层。

如果 layer 为负，则从最后一层开始访问。

void update_internals() 🔗

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

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

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