Table of Contents

Class TileSetAtlasSource

Exposes a 2D atlas texture as a set of tiles for a TileSet resource.

Inheritance
TileSetAtlasSource

Remarks

An atlas is a grid of tiles laid out on a texture. Each tile in the grid must be exposed using TileSetAtlasSource.create_tile. Those tiles are then indexed using their coordinates in the grid.

Each tile can also have a size in the grid coordinates, making it more or less cells in the atlas.

Alternatives version of a tile can be created using TileSetAtlasSource.create_alternative_tile, which are then indexed using an alternative ID. The main tile (the one in the grid), is accessed with an alternative ID equal to 0.

Each tile alternate has a set of properties that is defined by the source's TileSet layers. Those properties are stored in a TileData object that can be accessed and modified using TileSetAtlasSource.get_tile_data.

As TileData properties are stored directly in the TileSetAtlasSource resource, their properties might also be set using TileSetAtlasSource.set("<coords_x>:<coords_y>/<alternative_id>/<tile_data_property>").

Fields

TRANSFORM_FLIP_H

Represents cell's horizontal flip flag. Should be used directly with TileMap to flip placed tiles by altering their alternative IDs.

var alternate_id = $TileMap.get_cell_alternative_tile(0, Vector2i(2, 2))
if not alternate_id & TileSetAtlasSource.TRANSFORM_FLIP_H:
    # If tile is not already flipped, flip it.
    $TileMap.set_cell(0, Vector2i(2, 2), source_id, atlas_coords, alternate_id | TileSetAtlasSource.TRANSFORM_FLIP_H)

Note: These transformations can be combined to do the equivalent of 0, 90, 180, and 270 degree rotations, as shown below:

enum TileTransform {
    ROTATE_0 = 0,
    ROTATE_90 = TileSetAtlasSource.TRANSFORM_TRANSPOSE | TileSetAtlasSource.TRANSFORM_FLIP_H,
    ROTATE_180 = TileSetAtlasSource.TRANSFORM_FLIP_H | TileSetAtlasSource.TRANSFORM_FLIP_V,
    ROTATE_270 = TileSetAtlasSource.TRANSFORM_TRANSPOSE | TileSetAtlasSource.TRANSFORM_FLIP_V,

}


const TRANSFORM_FLIP_H = 4096

TRANSFORM_FLIP_V

Represents cell's vertical flip flag. See TRANSFORM_FLIP_H for usage.

const TRANSFORM_FLIP_V = 8192

TRANSFORM_TRANSPOSE

Represents cell's transposed flag. See TRANSFORM_FLIP_H for usage.

const TRANSFORM_TRANSPOSE = 16384

Properties

margins

Margins, in pixels, to offset the origin of the grid in the texture.

var margins : Vector2i = Vector2i(0, 0)

Property Value

Vector2i

Remarks

separation

Separation, in pixels, between each tile texture region of the grid.

var separation : Vector2i = Vector2i(0, 0)

Property Value

Vector2i

Remarks

texture

The atlas texture.

var texture : Texture2D

Property Value

Texture2D

Remarks

texture_region_size

The base tile size in the texture (in pixel). This size must be bigger than or equal to the TileSet's tile_size value.

var texture_region_size : Vector2i = Vector2i(16, 16)

Property Value

Vector2i

Remarks

use_texture_padding

If true, generates an internal texture with an additional one pixel padding around each tile. Texture padding avoids a common artifact where lines appear between tiles.

Disabling this setting might lead a small performance improvement, as generating the internal texture requires both memory and processing time when the TileSetAtlasSource resource is modified.

var use_texture_padding : bool = true

Property Value

bool

Remarks

  • void set_use_texture_padding(bool value)
  • bool get_use_texture_padding

Methods

clear_tiles_outside_texture

Removes all tiles that don't fit the available texture area. This method iterates over all the source's tiles, so it's advised to use has_tiles_outside_texture beforehand.

void clear_tiles_outside_texture

create_alternative_tile(Vector2i, int)

Creates an alternative tile for the tile at coordinates atlas_coords. If alternative_id_override is -1, give it an automatically generated unique ID, or assigns it the given ID otherwise.

Returns the new alternative identifier, or -1 if the alternative could not be created with a provided alternative_id_override.

int create_alternative_tile(Vector2i atlas_coords, int alternative_id_override)

Parameters

atlas_coords Vector2i
alternative_id_override int

create_tile(Vector2i, Vector2i)

Creates a new tile at coordinates atlas_coords with the given size.

void create_tile(Vector2i atlas_coords, Vector2i size)

Parameters

atlas_coords Vector2i
size Vector2i

get_atlas_grid_size

Qualifiers: const

Returns the atlas grid size, which depends on how many tiles can fit in the texture. It thus depends on the texture's size, the atlas margins, and the tiles' texture_region_size.

Vector2i get_atlas_grid_size

get_next_alternative_tile_id(Vector2i)

Qualifiers: const

Returns the alternative ID a following call to TileSetAtlasSource.create_alternative_tile would return.

int get_next_alternative_tile_id(Vector2i atlas_coords)

Parameters

atlas_coords Vector2i

get_runtime_texture

Qualifiers: const

If use_texture_padding is false, returns texture. Otherwise, returns and internal ImageTexture created that includes the padding.

Texture2D get_runtime_texture

get_runtime_tile_texture_region(Vector2i, int)

Qualifiers: const

Returns the region of the tile at coordinates atlas_coords for the given frame inside the texture returned by get_runtime_texture.

Note: If use_texture_padding is false, returns the same as TileSetAtlasSource.get_tile_texture_region.

Rect2i get_runtime_tile_texture_region(Vector2i atlas_coords, int frame)

Parameters

atlas_coords Vector2i
frame int

get_tile_animation_columns(Vector2i)

Qualifiers: const

Returns how many columns the tile at atlas_coords has in its animation layout.

int get_tile_animation_columns(Vector2i atlas_coords)

Parameters

atlas_coords Vector2i

get_tile_animation_frame_duration(Vector2i, int)

Qualifiers: const

Returns the animation frame duration of frame frame_index for the tile at coordinates atlas_coords.

float get_tile_animation_frame_duration(Vector2i atlas_coords, int frame_index)

Parameters

atlas_coords Vector2i
frame_index int

get_tile_animation_frames_count(Vector2i)

Qualifiers: const

Returns how many animation frames has the tile at coordinates atlas_coords.

int get_tile_animation_frames_count(Vector2i atlas_coords)

Parameters

atlas_coords Vector2i

get_tile_animation_mode(Vector2i)

Qualifiers: const

Returns the tile animation mode of the tile at atlas_coords. See also TileSetAtlasSource.set_tile_animation_mode.

int get_tile_animation_mode(Vector2i atlas_coords)

Parameters

atlas_coords Vector2i

get_tile_animation_separation(Vector2i)

Qualifiers: const

Returns the separation (as in the atlas grid) between each frame of an animated tile at coordinates atlas_coords.

Vector2i get_tile_animation_separation(Vector2i atlas_coords)

Parameters

atlas_coords Vector2i

get_tile_animation_speed(Vector2i)

Qualifiers: const

Returns the animation speed of the tile at coordinates atlas_coords.

float get_tile_animation_speed(Vector2i atlas_coords)

Parameters

atlas_coords Vector2i

get_tile_animation_total_duration(Vector2i)

Qualifiers: const

Returns the sum of the sum of the frame durations of the tile at coordinates atlas_coords. This value needs to be divided by the animation speed to get the actual animation loop duration.

float get_tile_animation_total_duration(Vector2i atlas_coords)

Parameters

atlas_coords Vector2i

get_tile_at_coords(Vector2i)

Qualifiers: const

If there is a tile covering the atlas_coords coordinates, returns the top-left coordinates of the tile (thus its coordinate ID). Returns Vector2i(-1, -1) otherwise.

Vector2i get_tile_at_coords(Vector2i atlas_coords)

Parameters

atlas_coords Vector2i

get_tile_data(Vector2i, int)

Qualifiers: const

Returns the TileData object for the given atlas coordinates and alternative ID.

TileData get_tile_data(Vector2i atlas_coords, int alternative_tile)

Parameters

atlas_coords Vector2i
alternative_tile int

get_tile_size_in_atlas(Vector2i)

Qualifiers: const

Returns the size of the tile (in the grid coordinates system) at coordinates atlas_coords.

Vector2i get_tile_size_in_atlas(Vector2i atlas_coords)

Parameters

atlas_coords Vector2i

get_tile_texture_region(Vector2i, int)

Qualifiers: const

Returns a tile's texture region in the atlas texture. For animated tiles, a frame argument might be provided for the different frames of the animation.

Rect2i get_tile_texture_region(Vector2i atlas_coords, int frame)

Parameters

atlas_coords Vector2i
frame int

get_tiles_to_be_removed_on_change(Texture2D, Vector2i, Vector2i, Vector2i)

Returns an array of tiles coordinates ID that will be automatically removed when modifying one or several of those properties: texture, margins, separation or texture_region_size. This can be used to undo changes that would have caused tiles data loss.

PackedVector2Array get_tiles_to_be_removed_on_change(Texture2D texture, Vector2i margins, Vector2i separation, Vector2i texture_region_size)

Parameters

texture Texture2D
margins Vector2i
separation Vector2i
texture_region_size Vector2i

has_room_for_tile(Vector2i, Vector2i, int, Vector2i, int, Vector2i)

Qualifiers: const

Returns whether there is enough room in an atlas to create/modify a tile with the given properties. If ignored_tile is provided, act as is the given tile was not present in the atlas. This may be used when you want to modify a tile's properties.

bool has_room_for_tile(Vector2i atlas_coords, Vector2i size, int animation_columns, Vector2i animation_separation, int frames_count, Vector2i ignored_tile)

Parameters

atlas_coords Vector2i
size Vector2i
animation_columns int
animation_separation Vector2i
frames_count int
ignored_tile Vector2i

has_tiles_outside_texture

Qualifiers: const

Checks if the source has any tiles that don't fit the texture area (either partially or completely).

bool has_tiles_outside_texture

move_tile_in_atlas(Vector2i, Vector2i, Vector2i)

Move the tile and its alternatives at the atlas_coords coordinates to the new_atlas_coords coordinates with the new_size size. This functions will fail if a tile is already present in the given area.

If new_atlas_coords is Vector2i(-1, -1), keeps the tile's coordinates. If new_size is Vector2i(-1, -1), keeps the tile's size.

To avoid an error, first check if a move is possible using TileSetAtlasSource.has_room_for_tile.

void move_tile_in_atlas(Vector2i atlas_coords, Vector2i new_atlas_coords, Vector2i new_size)

Parameters

atlas_coords Vector2i
new_atlas_coords Vector2i
new_size Vector2i

remove_alternative_tile(Vector2i, int)

Remove a tile's alternative with alternative ID alternative_tile.

Calling this function with alternative_tile equals to 0 will fail, as the base tile alternative cannot be removed.

void remove_alternative_tile(Vector2i atlas_coords, int alternative_tile)

Parameters

atlas_coords Vector2i
alternative_tile int

remove_tile(Vector2i)

Remove a tile and its alternative at coordinates atlas_coords.

void remove_tile(Vector2i atlas_coords)

Parameters

atlas_coords Vector2i

set_alternative_tile_id(Vector2i, int, int)

Change a tile's alternative ID from alternative_tile to new_id.

Calling this function with new_id of 0 will fail, as the base tile alternative cannot be moved.

void set_alternative_tile_id(Vector2i atlas_coords, int alternative_tile, int new_id)

Parameters

atlas_coords Vector2i
alternative_tile int
new_id int

set_tile_animation_columns(Vector2i, int)

Sets the number of columns in the animation layout of the tile at coordinates atlas_coords. If set to 0, then the different frames of the animation are laid out as a single horizontal line in the atlas.

void set_tile_animation_columns(Vector2i atlas_coords, int frame_columns)

Parameters

atlas_coords Vector2i
frame_columns int

set_tile_animation_frame_duration(Vector2i, int, float)

Sets the animation frame duration of frame frame_index for the tile at coordinates atlas_coords.

void set_tile_animation_frame_duration(Vector2i atlas_coords, int frame_index, float duration)

Parameters

atlas_coords Vector2i
frame_index int
duration float

set_tile_animation_frames_count(Vector2i, int)

Sets how many animation frames the tile at coordinates atlas_coords has.

void set_tile_animation_frames_count(Vector2i atlas_coords, int frames_count)

Parameters

atlas_coords Vector2i
frames_count int

set_tile_animation_mode(Vector2i, int)

Sets the tile animation mode of the tile at atlas_coords to mode. See also TileSetAtlasSource.get_tile_animation_mode.

void set_tile_animation_mode(Vector2i atlas_coords, int mode)

Parameters

atlas_coords Vector2i
mode int

set_tile_animation_separation(Vector2i, Vector2i)

Sets the margin (in grid tiles) between each tile in the animation layout of the tile at coordinates atlas_coords has.

void set_tile_animation_separation(Vector2i atlas_coords, Vector2i separation)

Parameters

atlas_coords Vector2i
separation Vector2i

set_tile_animation_speed(Vector2i, float)

Sets the animation speed of the tile at coordinates atlas_coords has.

void set_tile_animation_speed(Vector2i atlas_coords, float speed)

Parameters

atlas_coords Vector2i
speed float