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 圖塊的地圖節點。
說明
Node for 2D tile-based maps. Tilemaps use a TileSet which contain a list of tiles which are used to create grid-based maps. A TileMap may have several layers, layouting tiles on top of each other.
For performance reasons, all TileMap updates are batched at the end of a frame. Notably, this means that scene tiles from a TileSetScenesCollectionSource may be initialized after their parent. This is only queued when inside the scene tree.
To force an update earlier on, call update_internals().
Note: For performance and compatibility reasons, the coordinates serialized by TileMap are limited to 16-bit signed integers, i.e. the range for X and Y coordinates is from -32768 to 32767. When saving tile data, tiles outside this range are wrapped.
教學
屬性
|
||
|
||
|
||
|
||
方法
void |
_tile_data_runtime_update(layer: int, coords: Vector2i, tile_data: TileData) virtual |
_use_tile_data_runtime_update(layer: int, coords: Vector2i) virtual |
|
void |
|
void |
clear() |
void |
clear_layer(layer: int) |
void |
erase_cell(layer: int, coords: Vector2i) |
void |
|
void |
force_update(layer: int = -1) |
get_cell_alternative_tile(layer: int, coords: Vector2i, use_proxies: bool = false) const |
|
get_cell_atlas_coords(layer: int, coords: Vector2i, use_proxies: bool = false) const |
|
get_cell_source_id(layer: int, coords: Vector2i, use_proxies: bool = false) const |
|
get_cell_tile_data(layer: int, coords: Vector2i, use_proxies: bool = false) const |
|
get_coords_for_body_rid(body: RID) |
|
get_layer_for_body_rid(body: RID) |
|
get_layer_modulate(layer: int) const |
|
get_layer_name(layer: int) const |
|
get_layer_navigation_map(layer: int) const |
|
get_layer_y_sort_origin(layer: int) const |
|
get_layer_z_index(layer: int) const |
|
get_layers_count() const |
|
get_navigation_map(layer: int) const |
|
get_neighbor_cell(coords: Vector2i, neighbor: CellNeighbor) const |
|
get_pattern(layer: int, coords_array: Array[Vector2i]) |
|
get_surrounding_cells(coords: Vector2i) |
|
get_used_cells(layer: int) const |
|
get_used_cells_by_id(layer: int, source_id: int = -1, atlas_coords: Vector2i = Vector2i(-1, -1), alternative_tile: int = -1) const |
|
get_used_rect() const |
|
is_cell_flipped_h(layer: int, coords: Vector2i, use_proxies: bool = false) const |
|
is_cell_flipped_v(layer: int, coords: Vector2i, use_proxies: bool = false) const |
|
is_cell_transposed(layer: int, coords: Vector2i, use_proxies: bool = false) const |
|
is_layer_enabled(layer: int) const |
|
is_layer_navigation_enabled(layer: int) const |
|
is_layer_y_sort_enabled(layer: int) const |
|
local_to_map(local_position: Vector2) const |
|
map_pattern(position_in_tilemap: Vector2i, coords_in_pattern: Vector2i, pattern: TileMapPattern) |
|
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 |
訊號
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 🔗
如果啟用，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，則取決於除錯設定“顯示碰撞”。
void set_navigation_visibility_mode(value: VisibilityMode)
VisibilityMode get_navigation_visibility_mode()
顯示或隱藏該 TileMap 的導覽網格。如果設定為 VISIBILITY_MODE_DEFAULT，則取決於除錯設定“顯示導覽”。
int rendering_quadrant_size = 16 🔗
The TileMap's quadrant size. A quadrant is a group of tiles to be drawn together on a single canvas item, for optimization purposes. rendering_quadrant_size defines the length of a square's side, in the map's coordinate system, that forms the quadrant. Thus, the default quadrant size groups together 16 * 16 = 256 tiles.
The quadrant size does not apply on Y-sorted layers, as tiles are grouped by Y position instead in that case.
Note: As quadrants are created according to the map's coordinate system, the quadrant's "square shape" might not look like square in the TileMap's local coordinate system.
The TileSet used by this TileMap. The textures, collisions, and additional behavior of all available tiles are stored here.
方法說明
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 物件的屬性要隨時間變化，請使用 force_update() 來觸發 TileMap 更新。
bool _use_tile_data_runtime_update(layer: int, coords: Vector2i) virtual 🔗
如果位於層 layer 座標 coords 的圖塊需要運作時更新，則應返回 true。
警告：請確保這個函式只在需要時返回 true。任何在沒有需要的情況下在運作時處理的圖塊都將導致顯著的性能損失。
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) 🔗
Erases the cell on layer layer at coordinates coords.
If layer is negative, the layers are accessed from the last one.
void fix_invalid_tiles() 🔗
清除圖塊集中不存在的儲存格。
void force_update(layer: int = -1) 🔗
已棄用： Use notify_runtime_tile_data_update() and/or update_internals() instead.
Forces the TileMap and the layer layer to update.
int get_cell_alternative_tile(layer: int, coords: Vector2i, use_proxies: bool = false) const 🔗
Returns the tile alternative ID of the cell on layer layer at coords.
If use_proxies is false, ignores the TileSet's tile proxies, returning the raw alternative identifier. See TileSet.map_tile_proxy().
If layer is negative, the layers are accessed from the last one.
Vector2i get_cell_atlas_coords(layer: int, coords: Vector2i, use_proxies: bool = false) const 🔗
Returns the tile atlas coordinates ID of the cell on layer layer at coordinates coords. Returns Vector2i(-1, -1) if the cell does not exist.
If use_proxies is false, ignores the TileSet's tile proxies, returning the raw atlas coordinate identifier. See TileSet.map_tile_proxy().
If layer is negative, the layers are accessed from the last one.
int get_cell_source_id(layer: int, coords: Vector2i, use_proxies: bool = false) const 🔗
Returns the tile source ID of the cell on layer layer at coordinates coords. Returns -1 if the cell does not exist.
If use_proxies is false, ignores the TileSet's tile proxies, returning the raw source identifier. See TileSet.map_tile_proxy().
If layer is negative, the layers are accessed from the last one.
TileData get_cell_tile_data(layer: int, coords: Vector2i, use_proxies: bool = false) const 🔗
Returns the TileData object associated with the given cell, or null if the cell does not exist or is not a TileSetAtlasSource.
If layer is negative, the layers are accessed from the last one.
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
If use_proxies is false, ignores the TileSet's tile proxies. See 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 🔗
設定圖層的名稱。主要在編輯器中使用。
如果 layer 為負，則逆序存取圖層。
String get_layer_name(layer: int) const 🔗
設定圖層的名稱。主要在編輯器中使用。
如果 layer 為負，則逆序存取圖層。
Returns the RID of the NavigationServer2D navigation map assigned to the specified TileMap layer layer.
By default the TileMap uses the default World2D navigation map for the first TileMap layer. For each additional TileMap layer a new navigation map is created for the additional layer.
In order to make NavigationAgent2D switch between TileMap layer navigation maps use NavigationAgent2D.set_navigation_map() with the navigation map received from get_layer_navigation_map().
If layer is negative, the layers are accessed from the last one.
int get_layer_y_sort_origin(layer: int) const 🔗
設定圖層的名稱。主要在編輯器中使用。
如果 layer 為負，則逆序存取圖層。
int get_layer_z_index(layer: int) const 🔗
設定圖層的 Z 索引值。各個圖塊的 Z 索引值都會加上這個 Z 索引。
如果 layer 為負，則逆序存取圖層。
int get_layers_count() const 🔗
返回 TileMap 圖層的數量。
已棄用： Use get_layer_navigation_map() instead.
Returns the RID of the NavigationServer2D navigation map assigned to the specified TileMap layer layer.
Vector2i get_neighbor_cell(coords: Vector2i, neighbor: CellNeighbor) const 🔗
返回與位於座標 coords 的儲存格相鄰的儲存格，方向由 neighbor 表示。這個方法會考慮 TileMap 的不同佈局。
TileMapPattern get_pattern(layer: int, coords_array: Array[Vector2i]) 🔗
Creates a new TileMapPattern from the given layer and set of cells.
If layer is negative, the layers are accessed from the last one.
Array[Vector2i] get_surrounding_cells(coords: Vector2i) 🔗
返回與 coords 處的儲存格相鄰的所有儲存格的列表。
Array[Vector2i] get_used_cells(layer: int) const 🔗
Returns a Vector2i array with the positions of all cells containing a tile in the given layer. A cell is considered empty if its source identifier equals -1, its atlas coordinates identifiers is Vector2(-1, -1) and its alternative identifier is -1.
If layer is negative, the layers are accessed from the last one.
Array[Vector2i] get_used_cells_by_id(layer: int, source_id: int = -1, atlas_coords: Vector2i = Vector2i(-1, -1), alternative_tile: int = -1) const 🔗
Returns a Vector2i array with the positions of all cells containing a tile in the given layer. Tiles may be filtered according to their source (source_id), their atlas coordinates (atlas_coords) or alternative id (alternative_tile).
If a parameter has its value set to the default one, this parameter is not used to filter a cell. Thus, if all parameters have their respective default value, this method returns the same result as get_used_cells().
A cell is considered empty if its source identifier equals -1, its atlas coordinates identifiers is Vector2(-1, -1) and its alternative identifier is -1.
If layer is negative, the layers are accessed from the last one.
Rect2i get_used_rect() const 🔗
返回該地圖的包圍矩形，包圍所有圖層中的已使用（非空）的圖塊。
bool is_cell_flipped_h(layer: int, coords: Vector2i, use_proxies: bool = false) const 🔗
Returns true if the cell on layer layer at coordinates coords is flipped horizontally. The result is valid only for atlas sources.
bool is_cell_flipped_v(layer: int, coords: Vector2i, use_proxies: bool = false) const 🔗
Returns true if the cell on layer layer at coordinates coords is flipped vertically. The result is valid only for atlas sources.
bool is_cell_transposed(layer: int, coords: Vector2i, use_proxies: bool = false) const 🔗
Returns true if the cell on layer layer at coordinates coords is transposed. The result is valid only for atlas sources.
bool is_layer_enabled(layer: int) const 🔗
設定圖層的名稱。主要在編輯器中使用。
如果 layer 為負，則逆序存取圖層。
Returns if a layer's built-in navigation regions generation is enabled.
bool is_layer_y_sort_enabled(layer: int) const 🔗
設定圖層的名稱。主要在編輯器中使用。
如果 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) 🔗
通知呼叫_use_tile_data_runtime_update()或_tile_data_runtime_update()的TileMap節點將導致不同的結果。這將因此觸發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) 🔗
Update all the cells in the cells coordinates array so that they use the given terrain for the given terrain_set. If an updated cell has the same terrain as one of its neighboring cells, this function tries to join the two. This function might update neighboring tiles if needed to create correct terrain transitions.
If ignore_empty_terrains is true, empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints.
If layer is negative, the layers are accessed from the last one.
Note: To work correctly, this method requires the TileMap's TileSet to have terrains set up with all required terrain combinations. Otherwise, it may produce unexpected results.
void set_cells_terrain_path(layer: int, path: Array[Vector2i], terrain_set: int, terrain: int, ignore_empty_terrains: bool = true) 🔗
Update all the cells in the path coordinates array so that they use the given terrain for the given terrain_set. The function will also connect two successive cell in the path with the same terrain. This function might update neighboring tiles if needed to create correct terrain transitions.
If ignore_empty_terrains is true, empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints.
If layer is negative, the layers are accessed from the last one.
Note: To work correctly, this method requires the TileMap's TileSet to have terrains set up with all required terrain combinations. Otherwise, it may produce unexpected results.
void set_layer_enabled(layer: int, enabled: bool) 🔗
Enables or disables the layer layer. A disabled layer is not processed at all (no rendering, no physics, etc.).
If layer is negative, the layers are accessed from the last one.
void set_layer_modulate(layer: int, modulate: Color) 🔗
設定圖層的顏色。該顏色會與圖塊的顏色以及 TileMap 的調變色相乘。
如果 layer 為負，則逆序存取圖層。
void set_layer_name(layer: int, name: String) 🔗
設定圖層的名稱。主要在編輯器中使用。
如果 layer 為負，則逆序存取圖層。
Enables or disables a layer's built-in navigation regions generation. Disable this if you need to bake navigation regions from a TileMap using a NavigationRegion2D node.
Assigns map as a NavigationServer2D navigation map for the specified TileMap layer layer.
By default the TileMap uses the default World2D navigation map for the first TileMap layer. For each additional TileMap layer a new navigation map is created for the additional layer.
In order to make NavigationAgent2D switch between TileMap layer navigation maps use NavigationAgent2D.set_navigation_map() with the navigation map received from get_layer_navigation_map().
If layer is negative, the layers are accessed from the last one.
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.
Assigns map as a NavigationServer2D navigation map for the specified TileMap layer layer.
void set_pattern(layer: int, position: Vector2i, pattern: TileMapPattern) 🔗
將給定的 TileMapPattern 貼上到圖塊地圖中的 position 位置和 layer 層。
如果 layer 為負，則從最後一層開始存取。
void update_internals() 🔗
Triggers a direct update of the TileMap. Usually, calling this function is not needed, as TileMap node updates automatically when one of its properties or cells is modified.
However, for performance reasons, those updates are batched and delayed to the end of the frame. Calling this function will force the TileMap to update right away instead.
Warning: Updating the TileMap is computationally expensive and may impact performance. Try to limit the number of updates and how many tiles they impact.