:github_url: hide .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/4.2/doc/tools/make_rst.py. .. XML source: https://github.com/godotengine/godot/tree/4.2/doc/classes/TileMap.xml. .. _class_TileMap: TileMap ======= **继承：** :ref:`Node2D` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`Object` 基于 2D 图块的地图节点。 .. rst-class:: classref-introduction-group 描述 ---- 基于 2D 图块的地图节点。Tilemap（图块地图）使用 :ref:`TileSet`\ ，其中包含了图块的列表，用于创建基于栅格的地图。TileMap 可以有若干图层，可以将图块布局在彼此之上。 出于性能原因，所有 TileMap 更新都会在一帧结束时进行批处理。值得注意的是，这意味着 :ref:`TileSetScenesCollectionSource` 中的场景图块可能会在其父级之后初始化。 要提前强制更新，请调用 :ref:`update_internals`\ 。 .. rst-class:: classref-introduction-group 教程 ---- - :doc:`使用 Tilemap <../tutorials/2d/using_tilemaps>` - `2D 平台跳跃演示 `__ - `2D 等轴演示 `__ - `2D 六边形演示 `__ - `2D 导航 Astar 演示 `__ - `2D 角色扮演游戏演示 `__ - `2D 运动学角色演示 `__ .. rst-class:: classref-reftable-group 属性 ---- .. table:: :widths: auto +----------------------------------------------------+--------------------------------------------------------------------------------------+-----------+ | :ref:`bool` | :ref:`collision_animatable` | ``false`` | +----------------------------------------------------+--------------------------------------------------------------------------------------+-----------+ | :ref:`VisibilityMode` | :ref:`collision_visibility_mode` | ``0`` | +----------------------------------------------------+--------------------------------------------------------------------------------------+-----------+ | :ref:`VisibilityMode` | :ref:`navigation_visibility_mode` | ``0`` | +----------------------------------------------------+--------------------------------------------------------------------------------------+-----------+ | :ref:`int` | :ref:`rendering_quadrant_size` | ``16`` | +----------------------------------------------------+--------------------------------------------------------------------------------------+-----------+ | :ref:`TileSet` | :ref:`tile_set` | | +----------------------------------------------------+--------------------------------------------------------------------------------------+-----------+ .. rst-class:: classref-reftable-group 方法 ---- .. table:: :widths: auto +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`_tile_data_runtime_update` **(** :ref:`int` layer, :ref:`Vector2i` coords, :ref:`TileData` tile_data **)** |virtual| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`_use_tile_data_runtime_update` **(** :ref:`int` layer, :ref:`Vector2i` coords **)** |virtual| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`add_layer` **(** :ref:`int` to_position **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`clear` **(** **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`clear_layer` **(** :ref:`int` layer **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`erase_cell` **(** :ref:`int` layer, :ref:`Vector2i` coords **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`fix_invalid_tiles` **(** **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`force_update` **(** :ref:`int` layer=-1 **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_cell_alternative_tile` **(** :ref:`int` layer, :ref:`Vector2i` coords, :ref:`bool` use_proxies=false **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2i` | :ref:`get_cell_atlas_coords` **(** :ref:`int` layer, :ref:`Vector2i` coords, :ref:`bool` use_proxies=false **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_cell_source_id` **(** :ref:`int` layer, :ref:`Vector2i` coords, :ref:`bool` use_proxies=false **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`TileData` | :ref:`get_cell_tile_data` **(** :ref:`int` layer, :ref:`Vector2i` coords, :ref:`bool` use_proxies=false **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2i` | :ref:`get_coords_for_body_rid` **(** :ref:`RID` body **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_layer_for_body_rid` **(** :ref:`RID` body **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Color` | :ref:`get_layer_modulate` **(** :ref:`int` layer **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`get_layer_name` **(** :ref:`int` layer **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RID` | :ref:`get_layer_navigation_map` **(** :ref:`int` layer **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_layer_y_sort_origin` **(** :ref:`int` layer **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_layer_z_index` **(** :ref:`int` layer **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_layers_count` **(** **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`RID` | :ref:`get_navigation_map` **(** :ref:`int` layer **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2i` | :ref:`get_neighbor_cell` **(** :ref:`Vector2i` coords, :ref:`CellNeighbor` neighbor **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`TileMapPattern` | :ref:`get_pattern` **(** :ref:`int` layer, :ref:`Vector2i[]` coords_array **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2i[]` | :ref:`get_surrounding_cells` **(** :ref:`Vector2i` coords **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2i[]` | :ref:`get_used_cells` **(** :ref:`int` layer **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2i[]` | :ref:`get_used_cells_by_id` **(** :ref:`int` layer, :ref:`int` source_id=-1, :ref:`Vector2i` atlas_coords=Vector2i(-1, -1), :ref:`int` alternative_tile=-1 **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Rect2i` | :ref:`get_used_rect` **(** **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_layer_enabled` **(** :ref:`int` layer **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_layer_navigation_enabled` **(** :ref:`int` layer **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_layer_y_sort_enabled` **(** :ref:`int` layer **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2i` | :ref:`local_to_map` **(** :ref:`Vector2` local_position **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2i` | :ref:`map_pattern` **(** :ref:`Vector2i` position_in_tilemap, :ref:`Vector2i` coords_in_pattern, :ref:`TileMapPattern` pattern **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector2` | :ref:`map_to_local` **(** :ref:`Vector2i` map_position **)** |const| | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`move_layer` **(** :ref:`int` layer, :ref:`int` to_position **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`notify_runtime_tile_data_update` **(** :ref:`int` layer=-1 **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`remove_layer` **(** :ref:`int` layer **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_cell` **(** :ref:`int` layer, :ref:`Vector2i` coords, :ref:`int` source_id=-1, :ref:`Vector2i` atlas_coords=Vector2i(-1, -1), :ref:`int` alternative_tile=0 **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_cells_terrain_connect` **(** :ref:`int` layer, :ref:`Vector2i[]` cells, :ref:`int` terrain_set, :ref:`int` terrain, :ref:`bool` ignore_empty_terrains=true **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_cells_terrain_path` **(** :ref:`int` layer, :ref:`Vector2i[]` path, :ref:`int` terrain_set, :ref:`int` terrain, :ref:`bool` ignore_empty_terrains=true **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_layer_enabled` **(** :ref:`int` layer, :ref:`bool` enabled **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_layer_modulate` **(** :ref:`int` layer, :ref:`Color` modulate **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_layer_name` **(** :ref:`int` layer, :ref:`String` name **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_layer_navigation_enabled` **(** :ref:`int` layer, :ref:`bool` enabled **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_layer_navigation_map` **(** :ref:`int` layer, :ref:`RID` map **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_layer_y_sort_enabled` **(** :ref:`int` layer, :ref:`bool` y_sort_enabled **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_layer_y_sort_origin` **(** :ref:`int` layer, :ref:`int` y_sort_origin **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_layer_z_index` **(** :ref:`int` layer, :ref:`int` z_index **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_navigation_map` **(** :ref:`int` layer, :ref:`RID` map **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_pattern` **(** :ref:`int` layer, :ref:`Vector2i` position, :ref:`TileMapPattern` pattern **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`update_internals` **(** **)** | +---------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 信号 ---- .. _class_TileMap_signal_changed: .. rst-class:: classref-signal **changed** **(** **)** 该 TileMap 的 :ref:`TileSet` 发生改变时发出。 .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 枚举 ---- .. _enum_TileMap_VisibilityMode: .. rst-class:: classref-enumeration enum **VisibilityMode**: .. _class_TileMap_constant_VISIBILITY_MODE_DEFAULT: .. rst-class:: classref-enumeration-constant :ref:`VisibilityMode` **VISIBILITY_MODE_DEFAULT** = ``0`` 使用调试设置确定可见性。 .. _class_TileMap_constant_VISIBILITY_MODE_FORCE_HIDE: .. rst-class:: classref-enumeration-constant :ref:`VisibilityMode` **VISIBILITY_MODE_FORCE_HIDE** = ``2`` 始终隐藏。 .. _class_TileMap_constant_VISIBILITY_MODE_FORCE_SHOW: .. rst-class:: classref-enumeration-constant :ref:`VisibilityMode` **VISIBILITY_MODE_FORCE_SHOW** = ``1`` 始终显示。 .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 属性说明 -------- .. _class_TileMap_property_collision_animatable: .. rst-class:: classref-property :ref:`bool` **collision_animatable** = ``false`` .. rst-class:: classref-property-setget - void **set_collision_animatable** **(** :ref:`bool` value **)** - :ref:`bool` **is_collision_animatable** **(** **)** 如果启用，TileMap 将看到它的碰撞同步到物理周期并将其碰撞类型从静态更改为运动学。这是创建基于 TileMap 的移动的平台所必需的。 \ **注意：**\ 启用 :ref:`collision_animatable` 可能会对性能产生一个很小的影响，只有在该 TileMap 正在移动并且有碰撞的图块时才这样做。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_property_collision_visibility_mode: .. rst-class:: classref-property :ref:`VisibilityMode` **collision_visibility_mode** = ``0`` .. rst-class:: classref-property-setget - void **set_collision_visibility_mode** **(** :ref:`VisibilityMode` value **)** - :ref:`VisibilityMode` **get_collision_visibility_mode** **(** **)** 显示或隐藏该 TileMap 的碰撞形状。如果设置为 :ref:`VISIBILITY_MODE_DEFAULT`\ ，则取决于调试设置“显示碰撞”。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_property_navigation_visibility_mode: .. rst-class:: classref-property :ref:`VisibilityMode` **navigation_visibility_mode** = ``0`` .. rst-class:: classref-property-setget - void **set_navigation_visibility_mode** **(** :ref:`VisibilityMode` value **)** - :ref:`VisibilityMode` **get_navigation_visibility_mode** **(** **)** 显示或隐藏该 TileMap 的导航网格。如果设置为 :ref:`VISIBILITY_MODE_DEFAULT`\ ，则取决于调试设置“显示导航”。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_property_rendering_quadrant_size: .. rst-class:: classref-property :ref:`int` **rendering_quadrant_size** = ``16`` .. rst-class:: classref-property-setget - void **set_rendering_quadrant_size** **(** :ref:`int` value **)** - :ref:`int` **get_rendering_quadrant_size** **(** **)** TileMap 的象限大小。象限是在单个画布项上一起绘制的一组图块，用于优化。\ :ref:`rendering_quadrant_size` 定义的是形成象限的正方形的边长，使用地图坐标系。因此，默认象限大小将 ``16 * 16 = 256`` 个图块组合到了一起。 Y 排序的图层不使用象限大小，这种图层中的图块会按 Y 位置分组。 \ **注意：**\ 象限是根据地图坐标系创建的，“正方形”的象限在 TileMap 的局部坐标系中可能并不是正方形。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_property_tile_set: .. rst-class:: classref-property :ref:`TileSet` **tile_set** .. rst-class:: classref-property-setget - void **set_tileset** **(** :ref:`TileSet` value **)** - :ref:`TileSet` **get_tileset** **(** **)** 指定的 :ref:`TileSet` 图块集。 .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 方法说明 -------- .. _class_TileMap_private_method__tile_data_runtime_update: .. rst-class:: classref-method void **_tile_data_runtime_update** **(** :ref:`int` layer, :ref:`Vector2i` coords, :ref:`TileData` tile_data **)** |virtual| 会使用 TileMap 内部即将使用的 TileData 对象来调用，从而实现运行时修改。 这个方法被调用的前提是：实现了 :ref:`_use_tile_data_runtime_update`\ ，并且对给定的图块坐标 ``coords`` 和层 ``layer`` 返回 ``true`` 。 \ **警告：**\ 该 ``tile_data`` 对象的子资源和 TileSet 中的子资源是一样的。对它们进行修改可能会影响整个 TileSet。请确保制作这些资源的副本再进行修改。 \ **注意：**\ 如果 ``tile_data`` 对象的属性要随时间变化，请使用 :ref:`notify_runtime_tile_data_update` 来通知该 TileMap 它需要更新。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_private_method__use_tile_data_runtime_update: .. rst-class:: classref-method :ref:`bool` **_use_tile_data_runtime_update** **(** :ref:`int` layer, :ref:`Vector2i` coords **)** |virtual| 如果位于层 ``layer`` 坐标 ``coords`` 的图块需要运行时更新，则应返回 ``true``\ 。 \ **警告：**\ 请确保这个函数只在需要时返回 ``true``\ 。任何在没有需要的情况下在运行时处理的图块都将导致显著的性能损失。 \ **注意：**\ 如果该函数的结果发生变化，请使用 :ref:`notify_runtime_tile_data_update` 通知 TileMap 它需要更新。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_add_layer: .. rst-class:: classref-method void **add_layer** **(** :ref:`int` to_position **)** 在数组中的给定位置 ``to_position`` 添加层。如果 ``to_position`` 为负数，则位置从结尾处开始计数，\ ``-1`` 会把层添加在数组的末尾。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_clear: .. rst-class:: classref-method void **clear** **(** **)** 清除所有单元格。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_clear_layer: .. rst-class:: classref-method void **clear_layer** **(** :ref:`int` layer **)** 清除给定图层上的所有单元格。 如果 ``layer`` 为负，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_erase_cell: .. rst-class:: classref-method void **erase_cell** **(** :ref:`int` layer, :ref:`Vector2i` coords **)** 擦除图层 ``layer`` 上位于 ``coords`` 坐标的单元格。 如果 ``layer`` 为负，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_fix_invalid_tiles: .. rst-class:: classref-method void **fix_invalid_tiles** **(** **)** 清除图块集中不存在的单元格。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_force_update: .. rst-class:: classref-method void **force_update** **(** :ref:`int` layer=-1 **)** *已废弃。*\ 见 :ref:`notify_runtime_tile_data_update` 和 :ref:`update_internals`\ 。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_cell_alternative_tile: .. rst-class:: classref-method :ref:`int` **get_cell_alternative_tile** **(** :ref:`int` layer, :ref:`Vector2i` coords, :ref:`bool` use_proxies=false **)** |const| 返回 ``layer`` 层中位于坐标 ``coords`` 单元格的图块备选 ID。如果 ``use_proxies`` 为 ``false``\ ，则会忽略该 :ref:`TileSet` 的图块代理，返回原始的备选标识符。见 :ref:`TileSet.map_tile_proxy`\ 。 如果 ``layer`` 为负，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_cell_atlas_coords: .. rst-class:: classref-method :ref:`Vector2i` **get_cell_atlas_coords** **(** :ref:`int` layer, :ref:`Vector2i` coords, :ref:`bool` use_proxies=false **)** |const| 返回 ``layer`` 层中位于坐标 ``coords`` 单元格的图块图集坐标 ID。如果 ``use_proxies`` 为 ``false``\ ，则会忽略该 :ref:`TileSet` 的图块代理，返回原始的备选标识符。见 :ref:`TileSet.map_tile_proxy`\ 。 如果 ``layer`` 为负，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_cell_source_id: .. rst-class:: classref-method :ref:`int` **get_cell_source_id** **(** :ref:`int` layer, :ref:`Vector2i` coords, :ref:`bool` use_proxies=false **)** |const| 返回 ``layer`` 层中位于坐标 ``coords`` 单元格的图块源 ID。如果该单元格不存在，则返回 ``-1``\ 。 如果 ``use_proxies`` 为 ``false``\ ，则会忽略该 :ref:`TileSet` 的图块代理，返回原始的备选标识符。见 :ref:`TileSet.map_tile_proxy`\ 。 如果 ``layer`` 为负，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_cell_tile_data: .. rst-class:: classref-method :ref:`TileData` **get_cell_tile_data** **(** :ref:`int` layer, :ref:`Vector2i` coords, :ref:`bool` use_proxies=false **)** |const| 返回与给定单元格关联的 :ref:`TileData` 对象，如果单元格不存在或者不是 :ref:`TileSetAtlasSource` 则返回 ``null``\ 。 如果 ``layer`` 为负，则从最后一个图层开始访问。 如果 ``use_proxies`` 为 ``false``\ ，则会忽略 :ref:`TileSet` 的图块代理，返回原始的备选标识符。见 :ref:`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 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_coords_for_body_rid: .. rst-class:: classref-method :ref:`Vector2i` **get_coords_for_body_rid** **(** :ref:`RID` body **)** 返回给定物理物体 RID 对应图块的坐标。与图块发生碰撞时，可以通过 :ref:`KinematicCollision2D.get_collider_rid` 获取该 RID。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_layer_for_body_rid: .. rst-class:: classref-method :ref:`int` **get_layer_for_body_rid** **(** :ref:`RID` body **)** 返回给定物理物体 RID 对应图块的 TileMap 图层。与图块发生碰撞时，可以通过 :ref:`KinematicCollision2D.get_collider_rid` 获取该 RID。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_layer_modulate: .. rst-class:: classref-method :ref:`Color` **get_layer_modulate** **(** :ref:`int` layer **)** |const| 返回 TileMap 图层的调制颜色。 如果 ``layer`` 为负，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_layer_name: .. rst-class:: classref-method :ref:`String` **get_layer_name** **(** :ref:`int` layer **)** |const| 返回 TileMap 图层的名称。 如果 ``layer`` 为负，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_layer_navigation_map: .. rst-class:: classref-method :ref:`RID` **get_layer_navigation_map** **(** :ref:`int` layer **)** |const| 返回当前分配给指定 TileMap ``layer`` 的 :ref:`NavigationServer2D` 导航地图 :ref:`RID`\ 。 默认情况下，TileMap 为第一个 TileMap 层，使用默认的 :ref:`World2D` 导航地图。对于每个附加的 TileMap 层，都会为附加层创建一个新的导航地图。 为了使 :ref:`NavigationAgent2D` 在 TileMap 层导航地图之间切换，使用 :ref:`NavigationAgent2D.set_navigation_map` 和从 :ref:`get_navigation_map` 接收的导航地图。 如果 ``layer`` 为负，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_layer_y_sort_origin: .. rst-class:: classref-method :ref:`int` **get_layer_y_sort_origin** **(** :ref:`int` layer **)** |const| 返回 TileMap 图层的 Y 排序原点。 如果 ``layer`` 为负，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_layer_z_index: .. rst-class:: classref-method :ref:`int` **get_layer_z_index** **(** :ref:`int` layer **)** |const| 返回 TileMap 图层的 Z 索引值。 如果 ``layer`` 为负，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_layers_count: .. rst-class:: classref-method :ref:`int` **get_layers_count** **(** **)** |const| 返回 TileMap 图层的数量。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_navigation_map: .. rst-class:: classref-method :ref:`RID` **get_navigation_map** **(** :ref:`int` layer **)** |const| 见 :ref:`get_layer_navigation_map`\ 。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_neighbor_cell: .. rst-class:: classref-method :ref:`Vector2i` **get_neighbor_cell** **(** :ref:`Vector2i` coords, :ref:`CellNeighbor` neighbor **)** |const| 返回与位于坐标 ``coords`` 的单元格相邻的单元格，方向由 ``neighbor`` 表示。这个方法会考虑 TileMap 的不同布局。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_pattern: .. rst-class:: classref-method :ref:`TileMapPattern` **get_pattern** **(** :ref:`int` layer, :ref:`Vector2i[]` coords_array **)** 根据给定的图层和单元格新建 :ref:`TileMapPattern`\ 。 如果 ``layer`` 为负，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_surrounding_cells: .. rst-class:: classref-method :ref:`Vector2i[]` **get_surrounding_cells** **(** :ref:`Vector2i` coords **)** 返回与 ``coords`` 处的单元格相邻的所有单元格的列表。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_used_cells: .. rst-class:: classref-method :ref:`Vector2i[]` **get_used_cells** **(** :ref:`int` layer **)** |const| 返回 :ref:`Vector2i` 数组，其中存放的是给定图层中所有包含图块的单元格的位置。空单元格的源标识符等于 -1、图集坐标标识符为 ``Vector2(-1, -1)``\ 、备选标识符为 -1。 如果 ``layer`` 为负，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_used_cells_by_id: .. rst-class:: classref-method :ref:`Vector2i[]` **get_used_cells_by_id** **(** :ref:`int` layer, :ref:`int` source_id=-1, :ref:`Vector2i` atlas_coords=Vector2i(-1, -1), :ref:`int` alternative_tile=-1 **)** |const| 返回 :ref:`Vector2i` 数组，其中存放的是给定图层中所有包含图块的单元格的位置。可以根据源（\ ``source_id``\ ）、图集坐标（\ ``atlas_coords``\ ）、备选 ID（\ ``alternative_tile``\ ）进行过滤。 如果某个参数为默认值，则该参数不会用于单元格的过滤。因此，如果所有参数都使用默认值，则返回的结果与 :ref:`get_used_cells` 相同。 空单元格的源标识符等于 -1、图集坐标标识符为 ``Vector2(-1, -1)``\ 、备选标识符为 -1。 如果 ``layer`` 为负，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_get_used_rect: .. rst-class:: classref-method :ref:`Rect2i` **get_used_rect** **(** **)** |const| 返回该地图的包围矩形，包围所有图层中的已使用（非空）的图块。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_is_layer_enabled: .. rst-class:: classref-method :ref:`bool` **is_layer_enabled** **(** :ref:`int` layer **)** |const| 返回某个图层是否已启用。 如果 ``layer`` 为负，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_is_layer_navigation_enabled: .. rst-class:: classref-method :ref:`bool` **is_layer_navigation_enabled** **(** :ref:`int` layer **)** |const| 返回是否启用图层的内置导航区块生成。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_is_layer_y_sort_enabled: .. rst-class:: classref-method :ref:`bool` **is_layer_y_sort_enabled** **(** :ref:`int` layer **)** |const| 返回某个图层是否会对图块进行 Y 排序。 如果 ``layer`` 为负，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_local_to_map: .. rst-class:: classref-method :ref:`Vector2i` **local_to_map** **(** :ref:`Vector2` local_position **)** |const| 返回包含给定 ``local_position`` 的单元格地图坐标。如果 ``local_position`` 使用全局坐标，请考虑在传入这个方法前使用 :ref:`Node2D.to_local`\ 。另见 :ref:`map_to_local`\ 。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_map_pattern: .. rst-class:: classref-method :ref:`Vector2i` **map_pattern** **(** :ref:`Vector2i` position_in_tilemap, :ref:`Vector2i` coords_in_pattern, :ref:`TileMapPattern` pattern **)** 如果图案粘贴在 ``position_in_tilemap`` 坐标处（请参阅 :ref:`set_pattern`\ ），则返回 :ref:`TileMapPattern` 中给定坐标 ``coords_in_pattern`` 对应的单元格坐标。该映射是必需的，因为在半偏移图块形状中，映射可能无法通过计算 ``position_in_tile_map + coords_in_pattern`` 工作。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_map_to_local: .. rst-class:: classref-method :ref:`Vector2` **map_to_local** **(** :ref:`Vector2i` map_position **)** |const| 返回单元格的中心位置，使用 TileMap 的局部坐标。要将返回值转换为全局坐标，请使用 :ref:`Node2D.to_global`\ 。另见 :ref:`local_to_map`\ 。 \ **注意：**\ 可能与图块的可视位置没有对应关系，即忽略各个图块的 :ref:`TileData.texture_origin` 属性。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_move_layer: .. rst-class:: classref-method void **move_layer** **(** :ref:`int` layer, :ref:`int` to_position **)** 将索引 ``layer`` 处的图层移动到数组中给定的位置 ``to_position``\ 。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_notify_runtime_tile_data_update: .. rst-class:: classref-method void **notify_runtime_tile_data_update** **(** :ref:`int` layer=-1 **)** 通知 TileMap 节点调用 :ref:`_use_tile_data_runtime_update` 或 :ref:`_tile_data_runtime_update` 将导致不同的结果。这将因此触发 TileMap 更新。 如果提供了 ``layer``\ ，则仅通知给定层的更改。出于性能原因，通常首选提供 ``layer`` 参数（如果适用）。 \ **警告：**\ 更新 TileMap 的计算成本很高，并且可能会影响性能。尝试限制该函数的调用次数，以避免不必要的更新。 \ **注意：**\ 这不会触发 TileMap 的直接更新，该更新将照常在帧结束时完成（除非你调用 :ref:`update_internals`\ ）。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_remove_layer: .. rst-class:: classref-method void **remove_layer** **(** :ref:`int` layer **)** 移除索引为 ``layer`` 的层。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_set_cell: .. rst-class:: classref-method void **set_cell** **(** :ref:`int` layer, :ref:`Vector2i` coords, :ref:`int` source_id=-1, :ref:`Vector2i` atlas_coords=Vector2i(-1, -1), :ref:`int` alternative_tile=0 **)** 设置位于层 ``layer`` 坐标为 ``coords`` 的单元格的图块标识符。\ :ref:`TileSet` 中的每个图块都由三部分进行标识： - 源标识符 ``source_id`` 标识的是 :ref:`TileSetSource` 标识符。见 :ref:`TileSet.set_source_id`\ ， - 图集坐标标识符 ``atlas_coords`` 标识的是图集中的图块坐标（如果使用的是 :ref:`TileSetAtlasSource` 源）。如果使用的是 :ref:`TileSetScenesCollectionSource`\ ，应该始终为 ``Vector2i(0, 0)``\ ， - 备选图块标识符 ``alternative_tile`` 标识的是图集中的图块备选项（如果使用的是 :ref:`TileSetAtlasSource` 源），如果使用的是 :ref:`TileSetScenesCollectionSource` 则标识的是场景。 如果 ``source_id`` 为 ``-1``\ 、\ ``atlas_coords`` 为 ``Vector2i(-1, -1)`` 或 ``alternative_tile`` 为 ``-1``\ ，则会擦除该单元格。擦除后的单元格中，\ **所有**\ 标识符都会自动设为对应的无效值，即 ``-1``\ 、\ ``Vector2i(-1, -1)`` 和 ``-1``\ 。 如果 ``layer`` 为负数，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_set_cells_terrain_connect: .. rst-class:: classref-method void **set_cells_terrain_connect** **(** :ref:`int` layer, :ref:`Vector2i[]` cells, :ref:`int` terrain_set, :ref:`int` terrain, :ref:`bool` ignore_empty_terrains=true **)** 更新 ``cells`` 坐标数组中的所有单元格，以便它们将给定的 ``terrain`` 用于给定的 ``terrain_set``\ 。如果一个更新的单元格与其相邻单元格之一具有相同的地形，则该函数会尝试将两者连接起来。如果需要创建正确的地形过渡，该函数可能会更新相邻的图块。 如果 ``ignore_empty_terrains`` 为真，则在尝试为给定地形约束找到最合适的图块时，空地形将被忽略。 如果 ``layer`` 为负，则从最后一个图层开始访问。 \ **注意：**\ 要正常工作，这个方法需要 TileMap 的 TileSet 设置了具有所有必需地形组合的地形。否则，可能会产生意想不到的结果。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_set_cells_terrain_path: .. rst-class:: classref-method void **set_cells_terrain_path** **(** :ref:`int` layer, :ref:`Vector2i[]` path, :ref:`int` terrain_set, :ref:`int` terrain, :ref:`bool` ignore_empty_terrains=true **)** 更新 ``path`` 坐标数组中的所有单元格，以便它们将给定的 ``terrain`` 用于给定的 ``terrain_set``\ 。该函数还将连接路径中具有相同地形的两个连续单元格。如果需要创建正确的地形过渡，该函数可能会更新相邻的图块。 如果 ``ignore_empty_terrains`` 为真，则在尝试为给定地形约束找到最合适的图块时将忽略空地形。 如果 ``layer`` 为负，则从最后一个图层开始访问。 \ **注意：**\ 要正常工作，这个方法需要 TileMap 的 TileSet 设置了具有所有必需地形组合的地形。否则，可能会产生意想不到的结果。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_set_layer_enabled: .. rst-class:: classref-method void **set_layer_enabled** **(** :ref:`int` layer, :ref:`bool` enabled **)** 启用或禁用图层 ``layer``\ 。被禁用的图层根本不会被处理（没有渲染、物理等）。 如果 ``layer`` 为负数，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_set_layer_modulate: .. rst-class:: classref-method void **set_layer_modulate** **(** :ref:`int` layer, :ref:`Color` modulate **)** 设置图层的颜色。该颜色会与图块的颜色以及 TileMap 的调制色相乘。 如果 ``layer`` 为负，则逆序访问图层。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_set_layer_name: .. rst-class:: classref-method void **set_layer_name** **(** :ref:`int` layer, :ref:`String` name **)** 设置图层的名称。主要在编辑器中使用。 如果 ``layer`` 为负，则逆序访问图层。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_set_layer_navigation_enabled: .. rst-class:: classref-method void **set_layer_navigation_enabled** **(** :ref:`int` layer, :ref:`bool` enabled **)** 启用或禁用图层的内置导航区块生成。如果你需要使用 :ref:`NavigationRegion2D` 节点根据 TileMap 烘焙导航区块，请禁用此项。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_set_layer_navigation_map: .. rst-class:: classref-method void **set_layer_navigation_map** **(** :ref:`int` layer, :ref:`RID` map **)** 将 :ref:`NavigationServer2D` 导航地图 :ref:`RID` 分配给指定的 TileMap ``layer``\ 。 默认情况下，TileMap 为第一个 TileMap 层使用默认的 :ref:`World2D` 导航地图。对于每个附加的 TileMap 层，都会为附加层创建一个新的导航地图。 为了使 :ref:`NavigationAgent2D` 在 TileMap 层导航地图之间切换，使用 :ref:`NavigationAgent2D.set_navigation_map` 和从 :ref:`get_navigation_map` 接收的导航地图。 如果 ``layer`` 为负，则从最后一个图层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_set_layer_y_sort_enabled: .. rst-class:: classref-method void **set_layer_y_sort_enabled** **(** :ref:`int` layer, :ref:`bool` y_sort_enabled **)** 启用或禁用图层的 Y 排序。如果进行了 Y 排序，则该图层和 CanvasItem 节点的行为一致，会将其中的每个图块都进行 Y 排序。 Y 排序图层的 Z 索引一般应该和未 Y 排序的图层不同，否则未 Y 排序的图层会作为一个整体，和 Y 排序图层一起进行 Y 排序。通常不希望发生这样的行为。 如果 ``layer`` 为负，则逆序访问图层。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_set_layer_y_sort_origin: .. rst-class:: classref-method void **set_layer_y_sort_origin** **(** :ref:`int` layer, :ref:`int` y_sort_origin **)** 设置图层的 Y 排序原点。各个图块的 Y 排序原点值都会加上这个 Y 排序原点值。 用例是为图层冒充不同的高度级别。俯视角游戏比较有用。 如果 ``layer`` 为负，则逆序访问图层。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_set_layer_z_index: .. rst-class:: classref-method void **set_layer_z_index** **(** :ref:`int` layer, :ref:`int` z_index **)** 设置图层的 Z 索引值。各个图块的 Z 索引值都会加上这个 Z 索引。 如果 ``layer`` 为负，则逆序访问图层。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_set_navigation_map: .. rst-class:: classref-method void **set_navigation_map** **(** :ref:`int` layer, :ref:`RID` map **)** 见 :ref:`set_layer_navigation_map`\ 。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_set_pattern: .. rst-class:: classref-method void **set_pattern** **(** :ref:`int` layer, :ref:`Vector2i` position, :ref:`TileMapPattern` pattern **)** 将给定的 :ref:`TileMapPattern` 粘贴到图块地图中的 ``position`` 位置和 ``layer`` 层。 如果 ``layer`` 为负，则从最后一层开始访问。 .. rst-class:: classref-item-separator ---- .. _class_TileMap_method_update_internals: .. rst-class:: classref-method void **update_internals** **(** **)** 触发 TileMap 的更新。通常不需要调用这个函数，因为 TileMap 节点的属性发生修改后会自动更新。 但是出于性能原因，会对这些更新进行分批，延迟到该帧的末尾执行。调用这个函数会强制 TileMap 立即进行更新。 \ **警告：**\ 更新 TileMap 的计算量很大，可能会影响性能。请尽量限制更新的次数和受影响的图块。 .. |virtual| replace:: :abbr:`virtual (本方法通常需要用户覆盖才能生效。)` .. |const| replace:: :abbr:`const (本方法没有副作用。不会修改该实例的任何成员变量。)` .. |vararg| replace:: :abbr:`vararg (本方法除了在此处描述的参数外，还能够继续接受任意数量的参数。)` .. |constructor| replace:: :abbr:`constructor (本方法用于构造某个类型。)` .. |static| replace:: :abbr:`static (调用本方法无需实例，所以可以直接使用类名调用。)` .. |operator| replace:: :abbr:`operator (本方法描述的是使用本类型作为左操作数的有效操作符。)` .. |bitfield| replace:: :abbr:`BitField (这个值是由下列标志构成的位掩码整数。)`