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¶

int	cell_quadrant_size	`16`
bool	collision_animatable	`false`
VisibilityMode	collision_visibility_mode	`0`
VisibilityMode	navigation_visibility_mode	`0`
TileSet	tile_set

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

VisibilityMode collision_visibility_mode

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.

TileSet tile_set

Setter	set_tileset(value)
Getter	get_tileset()

The assigned TileSet.

Method Descriptions¶

void _tile_data_runtime_update ( int layer, Vector2i coords, TileData tile_data ) virtual

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 erase_cell ( int layer, Vector2i coords )

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

int get_cell_alternative_tile ( int layer, Vector2i coords, bool use_proxies ) 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.

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

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.

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

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.

Vector2i get_coords_for_body_rid ( RID body )

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.

Color get_layer_modulate ( int layer ) const

Returns a TileMap layer's modulate.

String get_layer_name ( int layer ) const

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

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.

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.

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

Vector2 map_to_world ( Vector2i map_position ) const

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.

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 )

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.

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.

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

Paste the given TileMapPattern at the given position and layer in the tile map.

Vector2i world_to_map ( Vector2 world_position ) const

Returns the tilemap (grid-based) coordinates corresponding to the given local position.