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.

Methods

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

fix_invalid_tiles ( )

void

force_update ( int layer=-1 )

int

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

Vector2i

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

int

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

Vector2i

get_coords_for_body_rid ( RID body )

Color

get_layer_modulate ( int layer ) const

String

get_layer_name ( 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

Vector2i

get_neighbor_cell ( Vector2i coords, CellNeighbor neighbor ) const

TileMapPattern

get_pattern ( int layer, Vector2i[] coords_array )

Vector2i[]

get_surrounding_tiles ( Vector2i coords )

Vector2i[]

get_used_cells ( int layer ) const

Rect2

get_used_rect ( )

bool

is_layer_enabled ( int layer ) const

bool

is_layer_y_sort_enabled ( int layer ) const

Vector2i

map_pattern ( Vector2i position_in_tilemap, Vector2i coords_in_pattern, TileMapPattern pattern )

Vector2

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=-1 )

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 )

Vector2i

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

16

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

false

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.


Default

0

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

0

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.


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.


  • bool _use_tile_data_runtime_update ( int layer, Vector2i coords ) virtual

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.


  • 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 occurences 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 coodinates of the tile for given physics body RID. Such RID can be retrieved from KinematicCollision2D.get_collider_rid, when colliding with a tile.


  • Color get_layer_modulate ( int layer ) const

Returns a TileMap layer's modulate.


Returns a TileMap layer's name.


  • int get_layer_y_sort_origin ( int layer ) const

Returns a TileMap layer's Y sort origin.


  • int get_layer_z_index ( int layer ) const

Returns a TileMap layer's Z-index value.


  • int get_layers_count ( ) const


Returns the neighboring cell to the one at coordinates coords, indentified by the neighbor direction. This method takes into account the different layouts a TileMap can take.


Creates a new TileMapPattern from the given layer and set of cells.


Returns the list of all neighbourings cells to the one at coords


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.


  • bool is_layer_enabled ( int layer ) const

Returns if a layer is enabled.


  • bool is_layer_y_sort_enabled ( int layer ) const

Returns if a layer Y-sorts its tiles.


Returns for the given coodinate 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 the local position corresponding to the given tilemap (grid-based) coordinates.


  • void move_layer ( int layer, int to_position )

Moves the layer at index layer_index to the given position to_position in the array.


  • void remove_layer ( int layer )

Moves the layer at index layer_index to the given position to_position in the array.


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

Sets the tile indentifiers for the cell on layer layer at coordinates coords. Each tile of the TileSet is identified using three parts:


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


  • void set_layer_enabled ( int layer, bool enabled )

Enables or disables the layer layer. A disabled layer is not processed at all (no rendering, no physics, etc...).


  • void set_layer_modulate ( int layer, Color enabled )

Sets a layer's color. It will be multiplied by tile's color and TileMap's modulate.


  • void set_layer_name ( int layer, String name )

Sets a layer's name. This is mostly useful in the editor.


  • void set_layer_y_sort_enabled ( int layer, bool y_sort_enabled )

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.


  • void set_layer_y_sort_origin ( int layer, int y_sort_origin )

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.


  • void set_layer_z_index ( int layer, int z_index )

Sets a layers Z-index value. This Z-index is added to each tile's Z-index value.


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.