Table of Contents

Class TileMapLayer

Namespace
Godot
Assembly
GodotSharp.dll

Node for 2D tile-based maps. A TileMapLayer uses a TileSet which contain a list of tiles which are used to create grid-based maps. Unlike the TileMap node, which is deprecated, TileMapLayer has only one layer of tiles. You can use several TileMapLayer to achieve the same result as a TileMap node.

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

public class TileMapLayer : Node2D, IDisposable
Inheritance
TileMapLayer
Implements
Inherited Members

Constructors

TileMapLayer() 

public TileMapLayer()

Properties

CollisionEnabled

Enable or disable collisions.

public bool CollisionEnabled { get; set; }

Property Value

bool

CollisionVisibilityMode

Show or hide the TileMapLayer's collision shapes. If set to Default, this depends on the show collision debug settings.

public TileMapLayer.DebugVisibilityMode CollisionVisibilityMode { get; set; }

Property Value

TileMapLayer.DebugVisibilityMode

Enabled

If false, disables this TileMapLayer completely (rendering, collision, navigation, scene tiles, etc.)

public bool Enabled { get; set; }

Property Value

bool

NavigationEnabled

If true, navigation regions are enabled.

public bool NavigationEnabled { get; set; }

Property Value

bool

NavigationVisibilityMode

Show or hide the TileMapLayer's navigation meshes. If set to Default, this depends on the show navigation debug settings.

public TileMapLayer.DebugVisibilityMode NavigationVisibilityMode { get; set; }

Property Value

TileMapLayer.DebugVisibilityMode

RenderingQuadrantSize

The TileMapLayer's quadrant size. A quadrant is a group of tiles to be drawn together on a single canvas item, for optimization purposes. RenderingQuadrantSize 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 a Y-sorted TileMapLayer, 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 TileMapLayer's local coordinate system.

public int RenderingQuadrantSize { get; set; }

Property Value

int

TileMapData

The raw tile map data as a byte array.

public byte[] TileMapData { get; set; }

Property Value

byte[]

TileSet

The TileSet used by this layer. The textures, collisions, and additional behavior of all available tiles are stored here.

public TileSet TileSet { get; set; }

Property Value

TileSet

UseKinematicBodies

If true, this TileMapLayer collision shapes will be instantiated as kinematic bodies. This can be needed for moving TileMapLayer nodes (i.e. moving platforms).

public bool UseKinematicBodies { get; set; }

Property Value

bool

XDrawOrderReversed

If YSortEnabled is enabled, setting this to true will reverse the order the tiles are drawn on the X-axis.

public bool XDrawOrderReversed { get; set; }

Property Value

bool

YSortOrigin

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. This can be useful for top-down view games.

public int YSortOrigin { get; set; }

Property Value

int

Methods

Clear()

Clears all cells.

public void Clear()

EraseCell(Vector2I)

Erases the cell at coordinates coords.

public void EraseCell(Vector2I coords)

Parameters

coords Vector2I

FixInvalidTiles()

Clears cells containing tiles that do not exist in the TileSet.

public void FixInvalidTiles()

GetCellAlternativeTile(Vector2I)

Returns the tile alternative ID of the cell at coordinates coords.

public int GetCellAlternativeTile(Vector2I coords)

Parameters

coords Vector2I

Returns

int

GetCellAtlasCoords(Vector2I)

Returns the tile atlas coordinates ID of the cell at coordinates coords. Returns Vector2i(-1, -1) if the cell does not exist.

public Vector2I GetCellAtlasCoords(Vector2I coords)

Parameters

coords Vector2I

Returns

Vector2I

GetCellSourceId(Vector2I)

Returns the tile source ID of the cell at coordinates coords. Returns -1 if the cell does not exist.

public int GetCellSourceId(Vector2I coords)

Parameters

coords Vector2I

Returns

int

GetCellTileData(Vector2I)

Returns the TileData object associated with the given cell, or null if the cell does not exist or is not a TileSetAtlasSource.

func get_clicked_tile_power():
      var clicked_cell = tile_map_layer.local_to_map(tile_map_layer.get_local_mouse_position())
      var data = tile_map_layer.get_cell_tile_data(clicked_cell)
      if data:
          return data.get_custom_data("power")
      else:
          return 0
public TileData GetCellTileData(Vector2I coords)

Parameters

coords Vector2I

Returns

TileData

GetCoordsForBodyRid(Rid)

Returns the coordinates of the tile for given physics body Rid. Such an Rid can be retrieved from GetColliderRid(), when colliding with a tile.

public Vector2I GetCoordsForBodyRid(Rid body)

Parameters

body Rid

Returns

Vector2I

GetNavigationMap()

Returns the Rid of the NavigationServer2D navigation used by this TileMapLayer.

By default this returns the default World2D navigation map, unless a custom map was provided using SetNavigationMap(Rid).

public Rid GetNavigationMap()

Returns

Rid

GetNeighborCell(Vector2I, CellNeighbor)

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.

public Vector2I GetNeighborCell(Vector2I coords, TileSet.CellNeighbor neighbor)

Parameters

coords Vector2I
neighbor TileSet.CellNeighbor

Returns

Vector2I

GetPattern(Array<Vector2I>)

Creates and returns a new TileMapPattern from the given array of cells. See also SetPattern(Vector2I, TileMapPattern).

public TileMapPattern GetPattern(Array<Vector2I> coordsArray)

Parameters

coordsArray Array<Vector2I>

Returns

TileMapPattern

GetSurroundingCells(Vector2I)

Returns the list of all neighboring cells to the one at coords.

public Array<Vector2I> GetSurroundingCells(Vector2I coords)

Parameters

coords Vector2I

Returns

Array<Vector2I>

GetUsedCells()

Returns a Vector2I array with the positions of all cells containing a tile. A cell is considered empty if its source identifier equals -1, its atlas coordinate identifier is Vector2(-1, -1) and its alternative identifier is -1.

public Array<Vector2I> GetUsedCells()

Returns

Array<Vector2I>

GetUsedCellsById(int, Vector2I?, int)

Returns a Vector2I array with the positions of all cells containing a tile. Tiles may be filtered according to their source (sourceId), their atlas coordinates (atlasCoords), or alternative id (alternativeTile).

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 values, this method returns the same result as GetUsedCells().

A cell is considered empty if its source identifier equals -1, its atlas coordinate identifier is Vector2(-1, -1) and its alternative identifier is -1.

public Array<Vector2I> GetUsedCellsById(int sourceId = -1, Vector2I? atlasCoords = null, int alternativeTile = -1)

Parameters

sourceId int
atlasCoords Vector2I?

If the parameter is null, then the default value is new Vector2I(-1, -1).

alternativeTile int

Returns

Array<Vector2I>

GetUsedRect()

Returns a rectangle enclosing the used (non-empty) tiles of the map.

public Rect2I GetUsedRect()

Returns

Rect2I

HasBodyRid(Rid)

Returns whether the provided bodyRid belongs to one of this TileMapLayer's cells.

public bool HasBodyRid(Rid body)

Parameters

body Rid

Returns

bool

HasGodotClassMethod(in godot_string_name)

Check if the type contains a method with the given name. This method is used by Godot to check if a method exists before invoking it. Do not call or override this method.

protected override bool HasGodotClassMethod(in godot_string_name method)

Parameters

method godot_string_name

Name of the method to check for.

Returns

bool

HasGodotClassSignal(in godot_string_name)

Check if the type contains a signal with the given name. This method is used by Godot to check if a signal exists before raising it. Do not call or override this method.

protected override bool HasGodotClassSignal(in godot_string_name signal)

Parameters

signal godot_string_name

Name of the signal to check for.

Returns

bool

InvokeGodotClassMethod(in godot_string_name, NativeVariantPtrArgs, out godot_variant)

Invokes the method with the given name, using the given arguments. This method is used by Godot to invoke methods from the engine side. Do not call or override this method.

protected override bool InvokeGodotClassMethod(in godot_string_name method, NativeVariantPtrArgs args, out godot_variant ret)

Parameters

method godot_string_name

Name of the method to invoke.

args NativeVariantPtrArgs

Arguments to use with the invoked method.

ret godot_variant

Value returned by the invoked method.

Returns

bool

LocalToMap(Vector2)

Returns the map coordinates of the cell containing the given localPosition. If localPosition is in global coordinates, consider using ToLocal(Vector2) before passing it to this method. See also MapToLocal(Vector2I).

public Vector2I LocalToMap(Vector2 localPosition)

Parameters

localPosition Vector2

Returns

Vector2I

MapPattern(Vector2I, Vector2I, TileMapPattern)

Returns for the given coordinates coordsInPattern in a TileMapPattern the corresponding cell coordinates if the pattern was pasted at the positionInTilemap coordinates (see SetPattern(Vector2I, TileMapPattern)). This mapping is required as in half-offset tile shapes, the mapping might not work by calculating position_in_tile_map + coords_in_pattern.

public Vector2I MapPattern(Vector2I positionInTilemap, Vector2I coordsInPattern, TileMapPattern pattern)

Parameters

positionInTilemap Vector2I
coordsInPattern Vector2I
pattern TileMapPattern

Returns

Vector2I

MapToLocal(Vector2I)

Returns the centered position of a cell in the TileMapLayer's local coordinate space. To convert the returned value into global coordinates, use ToGlobal(Vector2). See also LocalToMap(Vector2).

Note: This may not correspond to the visual position of the tile, i.e. it ignores the TextureOrigin property of individual tiles.

public Vector2 MapToLocal(Vector2I mapPosition)

Parameters

mapPosition Vector2I

Returns

Vector2

NotifyRuntimeTileDataUpdate()

Notifies the TileMapLayer node that calls to _UseTileDataRuntimeUpdate(Vector2I) or _TileDataRuntimeUpdate(Vector2I, TileData) will lead to different results. This will thus trigger a TileMapLayer update.

Warning: Updating the TileMapLayer is computationally expensive and may impact performance. Try to limit the number of calls to this function to avoid unnecessary update.

Note: This does not trigger a direct update of the TileMapLayer, the update will be done at the end of the frame as usual (unless you call UpdateInternals()).

public void NotifyRuntimeTileDataUpdate()

SetCell(Vector2I, int, Vector2I?, int)

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

- The source identifier sourceId identifies a TileSetSource identifier. See SetSourceId(int, int),

- The atlas coordinate identifier atlasCoords identifies a tile coordinates in the atlas (if the source is a TileSetAtlasSource). For TileSetScenesCollectionSource it should always be Vector2i(0, 0),

- The alternative tile identifier alternativeTile identifies a tile alternative in the atlas (if the source is a TileSetAtlasSource), and the scene for a TileSetScenesCollectionSource.

If sourceId is set to -1, atlasCoords to Vector2i(-1, -1), or alternativeTile to -1, the cell will be erased. An erased cell gets all its identifiers automatically set to their respective invalid values, namely -1, Vector2i(-1, -1) and -1.

public void SetCell(Vector2I coords, int sourceId = -1, Vector2I? atlasCoords = null, int alternativeTile = 0)

Parameters

coords Vector2I
sourceId int
atlasCoords Vector2I?

If the parameter is null, then the default value is new Vector2I(-1, -1).

alternativeTile int

SetCellsTerrainConnect(Array<Vector2I>, int, int, bool)

Update all the cells in the cells coordinates array so that they use the given terrain for the given terrainSet. 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 ignoreEmptyTerrains is true, empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints.

Note: To work correctly, this method requires the TileMapLayer's TileSet to have terrains set up with all required terrain combinations. Otherwise, it may produce unexpected results.

public void SetCellsTerrainConnect(Array<Vector2I> cells, int terrainSet, int terrain, bool ignoreEmptyTerrains = true)

Parameters

cells Array<Vector2I>
terrainSet int
terrain int
ignoreEmptyTerrains bool

SetCellsTerrainPath(Array<Vector2I>, int, int, bool)

Update all the cells in the path coordinates array so that they use the given terrain for the given terrainSet. 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 ignoreEmptyTerrains is true, empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints.

Note: To work correctly, this method requires the TileMapLayer's TileSet to have terrains set up with all required terrain combinations. Otherwise, it may produce unexpected results.

public void SetCellsTerrainPath(Array<Vector2I> path, int terrainSet, int terrain, bool ignoreEmptyTerrains = true)

Parameters

path Array<Vector2I>
terrainSet int
terrain int
ignoreEmptyTerrains bool

SetNavigationMap(Rid)

Sets a custom map as a NavigationServer2D navigation map. If not set, uses the default World2D navigation map instead.

public void SetNavigationMap(Rid map)

Parameters

map Rid

SetPattern(Vector2I, TileMapPattern)

Pastes the TileMapPattern at the given position in the tile map. See also GetPattern(Array<Vector2I>).

public void SetPattern(Vector2I position, TileMapPattern pattern)

Parameters

position Vector2I
pattern TileMapPattern

UpdateInternals()

Triggers a direct update of the TileMapLayer. Usually, calling this function is not needed, as TileMapLayer 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 TileMapLayer to update right away instead.

Warning: Updating the TileMapLayer is computationally expensive and may impact performance. Try to limit the number of updates and how many tiles they impact.

public void UpdateInternals()

_TileDataRuntimeUpdate(Vector2I, TileData)

Called with a TileData object about to be used internally by the TileMapLayer, allowing its modification at runtime.

This method is only called if _UseTileDataRuntimeUpdate(Vector2I) is implemented and returns true for the given tile coords.

Warning: The tileData 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 tileData object should change over time, use NotifyRuntimeTileDataUpdate() to notify the TileMapLayer it needs an update.

public virtual void _TileDataRuntimeUpdate(Vector2I coords, TileData tileData)

Parameters

coords Vector2I
tileData TileData

_UseTileDataRuntimeUpdate(Vector2I)

Should return true if the tile at coordinates coords requires a runtime update.

Warning: Make sure this function only returns true when needed. Any tile processed at runtime without a need for it will imply a significant performance penalty.

Note: If the result of this function should change, use NotifyRuntimeTileDataUpdate() to notify the TileMapLayer it needs an update.

public virtual bool _UseTileDataRuntimeUpdate(Vector2I coords)

Parameters

coords Vector2I

Returns

bool

Events

Changed

Emitted when this TileMapLayer's properties changes. This includes modified cells, properties, or changes made to its assigned TileSet.

Note: This signal may be emitted very often when batch-modifying a TileMapLayer. Avoid executing complex processing in a connected function, and consider delaying it to the end of the frame instead (i.e. calling CallDeferred(StringName, params Variant[])).

public event Action Changed

Event Type

Action
Edit this page