Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

TileMap

继承: Node2D < CanvasItem < Node < Object

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

描述

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

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

要提前强制更新,请调用 update_internals

教程

属性

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 ( int layer, Vector2i coords, TileData tile_data ) virtual

bool

_use_tile_data_runtime_update ( int layer, Vector2i coords ) virtual

void

add_layer ( int to_position )

void

clear ( )

void

clear_layer ( int layer )

void

erase_cell ( int layer, Vector2i coords )

void

fix_invalid_tiles ( )

void

force_update ( int layer=-1 )

int

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

Vector2i

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

int

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

TileData

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

Vector2i

get_coords_for_body_rid ( RID body )

int

get_layer_for_body_rid ( RID body )

Color

get_layer_modulate ( int layer ) const

String

get_layer_name ( int layer ) const

RID

get_layer_navigation_map ( int layer ) const

int

get_layer_y_sort_origin ( int layer ) const

int

get_layer_z_index ( int layer ) const

int

get_layers_count ( ) const

RID

get_navigation_map ( int layer ) const

Vector2i

get_neighbor_cell ( Vector2i coords, CellNeighbor neighbor ) const

TileMapPattern

get_pattern ( int layer, Vector2i[] coords_array )

Vector2i[]

get_surrounding_cells ( Vector2i coords )

Vector2i[]

get_used_cells ( int layer ) const

Vector2i[]

get_used_cells_by_id ( int layer, int source_id=-1, Vector2i atlas_coords=Vector2i(-1, -1), int alternative_tile=-1 ) const

Rect2i

get_used_rect ( ) const

bool

is_layer_enabled ( int layer ) const

bool

is_layer_navigation_enabled ( int layer ) const

bool

is_layer_y_sort_enabled ( int layer ) const

Vector2i

local_to_map ( Vector2 local_position ) const

Vector2i

map_pattern ( Vector2i position_in_tilemap, Vector2i coords_in_pattern, TileMapPattern pattern )

Vector2

map_to_local ( Vector2i map_position ) const

void

move_layer ( int layer, int to_position )

void

notify_runtime_tile_data_update ( int layer=-1 )

void

remove_layer ( int layer )

void

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

void

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

void

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

void

set_layer_enabled ( int layer, bool enabled )

void

set_layer_modulate ( int layer, Color modulate )

void

set_layer_name ( int layer, String name )

void

set_layer_navigation_enabled ( int layer, bool enabled )

void

set_layer_navigation_map ( int layer, RID map )

void

set_layer_y_sort_enabled ( int layer, bool y_sort_enabled )

void

set_layer_y_sort_origin ( int layer, int y_sort_origin )

void

set_layer_z_index ( int layer, int z_index )

void

set_navigation_map ( int layer, RID map )

void

set_pattern ( int layer, Vector2i position, TileMapPattern pattern )

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 ( bool value )

  • bool is_collision_animatable ( )

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

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


VisibilityMode collision_visibility_mode = 0

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


VisibilityMode navigation_visibility_mode = 0

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


int rendering_quadrant_size = 16

  • void set_rendering_quadrant_size ( int value )

  • int get_rendering_quadrant_size ( )

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

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

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


TileSet tile_set

指定的 TileSet 图块集。


方法说明

void _tile_data_runtime_update ( int layer, Vector2i coords, TileData tile_data ) 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 ( int layer, Vector2i coords ) virtual

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

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

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


void add_layer ( int to_position )

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


void clear ( )

清除所有单元格。


void clear_layer ( int layer )

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

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


void erase_cell ( int layer, Vector2i coords )

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

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


void fix_invalid_tiles ( )

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


void force_update ( int layer=-1 )

已废弃。notify_runtime_tile_data_updateupdate_internals


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

返回 layer 层中位于坐标 coords 单元格的图块备选 ID。如果 use_proxiesfalse,则会忽略该 TileSet 的图块代理,返回原始的备选标识符。见 TileSet.map_tile_proxy

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


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

返回 layer 层中位于坐标 coords 单元格的图块图集坐标 ID。如果 use_proxiesfalse,则会忽略该 TileSet 的图块代理,返回原始的备选标识符。见 TileSet.map_tile_proxy

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


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

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

如果 use_proxiesfalse,则会忽略该 TileSet 的图块代理,返回原始的备选标识符。见 TileSet.map_tile_proxy

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


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

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

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

如果 use_proxiesfalse,则会忽略 TileSet 的图块代理,返回原始的备选标识符。见 TileSet.map_tile_proxy

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

Vector2i get_coords_for_body_rid ( RID body )

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


int get_layer_for_body_rid ( RID body )

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


Color get_layer_modulate ( int layer ) const

返回 TileMap 图层的调制颜色。

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


String get_layer_name ( int layer ) const

返回 TileMap 图层的名称。

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


RID get_layer_navigation_map ( int layer ) const

返回当前分配给指定 TileMap layerNavigationServer2D 导航地图 RID

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

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

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


int get_layer_y_sort_origin ( int layer ) const

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

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


int get_layer_z_index ( int layer ) const

返回 TileMap 图层的 Z 索引值。

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


int get_layers_count ( ) const

返回 TileMap 图层的数量。


RID get_navigation_map ( int layer ) const

get_layer_navigation_map


Vector2i get_neighbor_cell ( Vector2i coords, CellNeighbor neighbor ) const

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


TileMapPattern get_pattern ( int layer, Vector2i[] coords_array )

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

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


Vector2i[] get_surrounding_cells ( Vector2i coords )

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


Vector2i[] get_used_cells ( int layer ) const

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

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


Vector2i[] get_used_cells_by_id ( int layer, int source_id=-1, Vector2i atlas_coords=Vector2i(-1, -1), int alternative_tile=-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_layer_enabled ( int layer ) const

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

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


bool is_layer_navigation_enabled ( int layer ) const

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


bool is_layer_y_sort_enabled ( int layer ) const

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

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


Vector2i local_to_map ( Vector2 local_position ) const

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


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

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


Vector2 map_to_local ( Vector2i map_position ) const

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

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


void move_layer ( int layer, int to_position )

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


void notify_runtime_tile_data_update ( int layer=-1 )

通知 TileMap 节点调用 _use_tile_data_runtime_update_tile_data_runtime_update 将导致不同的结果。这将因此触发 TileMap 更新。

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

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

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


void remove_layer ( int layer )

移除索引为 layer 的层。


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

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

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

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


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

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

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

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

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


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

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

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

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

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


void set_layer_enabled ( int layer, bool enabled )

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

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


void set_layer_modulate ( int layer, Color modulate )

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

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


void set_layer_name ( int layer, String name )

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

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


void set_layer_navigation_enabled ( int layer, bool enabled )

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


void set_layer_navigation_map ( int layer, RID map )

NavigationServer2D 导航地图 RID 分配给指定的 TileMap layer

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

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

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


void set_layer_y_sort_enabled ( int layer, bool y_sort_enabled )

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

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

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


void set_layer_y_sort_origin ( int layer, int y_sort_origin )

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

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

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


void set_layer_z_index ( int layer, int z_index )

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

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


void set_navigation_map ( int layer, RID map )

set_layer_navigation_map


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

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

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


void update_internals ( )

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

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

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