TileMap¶
Inherits: Node2D < CanvasItem < Node < Object
Node for 2D tile-based maps.
Description¶
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.
Tutorials¶
Properties¶
|
||
|
||
|
||
|
||
Methods¶
void |
_tile_data_runtime_update ( int layer, Vector2i coords, TileData tile_data ) virtual |
_use_tile_data_runtime_update ( int layer, Vector2i coords ) virtual |
|
void |
|
void |
clear ( ) |
void |
clear_layer ( int layer ) |
void |
erase_cell ( int layer, Vector2i coords ) |
void |
|
void |
force_update ( int layer=-1 ) |
get_cell_alternative_tile ( int layer, Vector2i coords, bool use_proxies ) const |
|
get_cell_atlas_coords ( int layer, Vector2i coords, bool use_proxies ) const |
|
get_cell_source_id ( int layer, Vector2i coords, bool use_proxies ) const |
|
get_coords_for_body_rid ( RID body ) |
|
get_layer_modulate ( int layer ) const |
|
get_layer_name ( int layer ) const |
|
get_layer_y_sort_origin ( int layer ) const |
|
get_layer_z_index ( int layer ) const |
|
get_layers_count ( ) const |
|
get_neighbor_cell ( Vector2i coords, CellNeighbor neighbor ) const |
|
get_pattern ( int layer, Vector2i[] coords_array ) |
|
get_surrounding_tiles ( Vector2i coords ) |
|
get_used_cells ( int layer ) const |
|
get_used_rect ( ) |
|
is_layer_enabled ( int layer ) const |
|
is_layer_y_sort_enabled ( int layer ) const |
|
map_pattern ( Vector2i position_in_tilemap, Vector2i coords_in_pattern, TileMapPattern pattern ) |
|
map_to_world ( Vector2i map_position ) const |
|
void |
move_layer ( int layer, int to_position ) |
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_from_surrounding_terrains ( int layer, Vector2i[] cells, int terrain_set, bool ignore_empty_terrains=true ) |
void |
set_layer_enabled ( int layer, bool enabled ) |
void |
set_layer_modulate ( int layer, Color enabled ) |
void |
set_layer_name ( int layer, String name ) |
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_pattern ( int layer, Vector2i position, TileMapPattern pattern ) |
world_to_map ( Vector2 world_position ) const |
Signals¶
changed ( )
Emitted when the TileSet of this TileMap changes.
Enumerations¶
enum VisibilityMode:
VISIBILITY_MODE_DEFAULT = 0 --- Use the debug settings to determine visibility.
VISIBILITY_MODE_FORCE_HIDE = 2 --- Always hide.
VISIBILITY_MODE_FORCE_SHOW = 1 --- Always show.
Property Descriptions¶
int cell_quadrant_size
Default |
|
Setter |
set_quadrant_size(value) |
Getter |
get_quadrant_size() |
The TileMap's quadrant size. Optimizes drawing by batching, using chunks of this size.
bool collision_animatable
Default |
|
Setter |
set_collision_animatable(value) |
Getter |
is_collision_animatable() |
If enabled, the TileMap will see its collisions synced to the physics tick and change its collision type from static to kinematic. This is required to create TileMap-based moving platform.
Note: Enabling collision_animatable
may have a small performance impact, only do it if the TileMap is moving and has colliding tiles.
VisibilityMode collision_visibility_mode
Default |
|
Setter |
set_collision_visibility_mode(value) |
Getter |
get_collision_visibility_mode() |
Show or hide the TileMap's collision shapes. If set to VISIBILITY_MODE_DEFAULT
, this depends on the show collision debug settings.
Default |
|
Setter |
set_navigation_visibility_mode(value) |
Getter |
get_navigation_visibility_mode() |
Show or hide the TileMap's collision shapes. If set to VISIBILITY_MODE_DEFAULT
, this depends on the show navigation debug settings.
TileSet tile_set
Setter |
set_tileset(value) |
Getter |
get_tileset() |
The assigned TileSet.
Method Descriptions¶
Called with a TileData object about to be used internally by the TileMap, allowing its modification at runtime.
This method is only called if _use_tile_data_runtime_update is implemented and returns true
for the given tile coords[/coords] and [code]layer
.
Warning: The tile_data
object's sub-resources are the same as the one in the TileSet. Modifying them might impact the whole TileSet. Instead, make sure to duplicate those resources.
Note: If the properties of tile_data
object should change over time, use force_update to trigger a TileMap update.
Should return true
if the tile at coordinates coords[/coords] on layer [code]layer
requires a runtime update.
Warning: Make sure this function only return true
when needed. Any tile processed at runtime without a need for it will imply a significant performance penalty.
void add_layer ( int to_position )
Adds a layer at the given position to_position
in the array. If to_position
is -1, adds it at the end of the array.
void clear ( )
Clears all cells.
void clear_layer ( int layer )
Clears all cells on the given layer.
Erases the cell on layer layer
at coordinates coords
.
void fix_invalid_tiles ( )
Clears cells that do not exist in the tileset.
void force_update ( int layer=-1 )
Triggers an update of the TileMap. If layer
is provided, only updates the given layer.
Note: The TileMap node updates automatically when one of its properties is modified. A manual update is only needed if runtime modifications (implemented in _tile_data_runtime_update) need to be applied.
Warning: Updating the TileMap is a performance demanding task. Limit occurrences of those updates to the minimum and limit the amount tiles they impact (by segregating tiles updated often to a dedicated layer for example).
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.
Returns the tile atlas coordinates ID of the cell on layer layer
at coordinates coords
. If use_proxies
is false
, ignores the TileSet's tile proxies, returning the raw alternative identifier. See TileSet.map_tile_proxy.
Returns the tile source ID of the cell on layer layer
at coordinates coords
. If use_proxies
is false
, ignores the TileSet's tile proxies, returning the raw alternative identifier. See TileSet.map_tile_proxy.
Returns the coordinates of the tile for given physics body RID. Such RID can be retrieved from KinematicCollision2D.get_collider_rid, when colliding with a tile.
Returns a TileMap layer's modulate.
Returns a TileMap layer's name.
Returns a TileMap layer's Y sort origin.
Returns a TileMap layer's Z-index value.
int get_layers_count ( ) const
Vector2i get_neighbor_cell ( Vector2i coords, CellNeighbor neighbor ) const
Returns the neighboring cell to the one at coordinates coords
, identified by the neighbor
direction. This method takes into account the different layouts a TileMap can take.
TileMapPattern get_pattern ( int layer, Vector2i[] coords_array )
Creates a new TileMapPattern from the given layer and set of cells.
Vector2i[] get_surrounding_tiles ( Vector2i coords )
Returns the list of all neighbourings cells to the one at coords
Vector2i[] get_used_cells ( int layer ) const
Returns a Vector2 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.
Rect2 get_used_rect ( )
Returns a rectangle enclosing the used (non-empty) tiles of the map, including all layers.
Returns if a layer is enabled.
Returns if a layer Y-sorts its tiles.
Vector2i map_pattern ( Vector2i position_in_tilemap, Vector2i coords_in_pattern, TileMapPattern pattern )
Returns for the given coordinate coords_in_pattern
in a TileMapPattern the corresponding cell coordinates if the pattern was pasted at the position_in_tilemap
coordinates (see set_pattern). This mapping is required as in half-offset tile shapes, the mapping might not work by calculating position_in_tile_map + coords_in_pattern
Returns a local position of the center of the cell at the given tilemap (grid-based) coordinates.
Note: This doesn't correspond to the visual position of the tile, i.e. it ignores the TileData.texture_offset property of individual tiles.
Moves the layer at index layer_index
to the given position to_position
in the array.
void remove_layer ( int layer )
Removes the layer at index layer
.
void set_cell ( int layer, Vector2i coords, int source_id=-1, Vector2i atlas_coords=Vector2i(-1, -1), int alternative_tile=0 )
Sets the tile indentifiers for the cell on layer layer
at coordinates coords
. Each tile of the TileSet is identified using three parts:
The source identifier
source_id
identifies a TileSetSource identifier. See TileSet.set_source_id,The atlas coordinates identifier
atlas_coords
identifies a tile coordinates in the atlas (if the source is a TileSetAtlasSource. For TileSetScenesCollectionSource it should be 0),The alternative tile identifier
alternative_tile
identifies a tile alternative the source is a TileSetAtlasSource, and the scene for a TileSetScenesCollectionSource.
void set_cells_from_surrounding_terrains ( int layer, Vector2i[] cells, int terrain_set, bool ignore_empty_terrains=true )
Updates all the cells in the cells
coordinates array and replace them by tiles that matches the surrounding cells terrains. Only cells form the given terrain_set
are considered.
If ignore_empty_terrains
is true, zones with no terrain defined are ignored to select the tiles.
Enables or disables the layer layer
. A disabled layer is not processed at all (no rendering, no physics, etc...).
Sets a layer's color. It will be multiplied by tile's color and TileMap's modulate.
Sets a layer's name. This is mostly useful in the editor.
Enables or disables a layer's Y-sorting. If a layer is Y-sorted, the layer will behave as a CanvasItem node where each of its tile gets Y-sorted.
Y-sorted layers should usually be on different Z-index values than not Y-sorted layers, otherwise, each of those layer will be Y-sorted as whole with the Y-sorted one. This is usually an undesired behvaior.
Sets a layer's Y-sort origin value. This Y-sort origin value is added to each tile's Y-sort origin value.
This allows, for example, to fake a different height level on each layer. This can be useful for top-down view games.
Sets a layers Z-index value. This Z-index is added to each tile's Z-index value.
void set_pattern ( int layer, Vector2i position, TileMapPattern pattern )
Paste the given TileMapPattern at the given position
and layer
in the tile map.
Returns the tilemap (grid-based) coordinates corresponding to the given local position.