Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

TileSetAtlasSource

Inherits: TileSetSource < Resource < RefCounted < Object

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

Description

An atlas is a grid of tiles laid out on a texture. Each tile in the grid must be exposed using 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 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 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>").

Properties

Vector2i

margins

Vector2i(0, 0)

Vector2i

separation

Vector2i(0, 0)

Texture2D

texture

Vector2i

texture_region_size

Vector2i(16, 16)

bool

use_texture_padding

true

Methods

void

clear_tiles_outside_texture ( )

int

create_alternative_tile ( Vector2i atlas_coords, int alternative_id_override=-1 )

void

create_tile ( Vector2i atlas_coords, Vector2i size=Vector2i(1, 1) )

Vector2i

get_atlas_grid_size ( ) const

int

get_next_alternative_tile_id ( Vector2i atlas_coords ) const

Texture2D

get_runtime_texture ( ) const

Rect2i

get_runtime_tile_texture_region ( Vector2i atlas_coords, int frame ) const

int

get_tile_animation_columns ( Vector2i atlas_coords ) const

float

get_tile_animation_frame_duration ( Vector2i atlas_coords, int frame_index ) const

int

get_tile_animation_frames_count ( Vector2i atlas_coords ) const

TileAnimationMode

get_tile_animation_mode ( Vector2i atlas_coords ) const

Vector2i

get_tile_animation_separation ( Vector2i atlas_coords ) const

float

get_tile_animation_speed ( Vector2i atlas_coords ) const

float

get_tile_animation_total_duration ( Vector2i atlas_coords ) const

Vector2i

get_tile_at_coords ( Vector2i atlas_coords ) const

TileData

get_tile_data ( Vector2i atlas_coords, int alternative_tile ) const

Vector2i

get_tile_size_in_atlas ( Vector2i atlas_coords ) const

Rect2i

get_tile_texture_region ( Vector2i atlas_coords, int frame=0 ) const

PackedVector2Array

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

bool

has_room_for_tile ( Vector2i atlas_coords, Vector2i size, int animation_columns, Vector2i animation_separation, int frames_count, Vector2i ignored_tile=Vector2i(-1, -1) ) const

bool

has_tiles_outside_texture ( ) const

void

move_tile_in_atlas ( Vector2i atlas_coords, Vector2i new_atlas_coords=Vector2i(-1, -1), Vector2i new_size=Vector2i(-1, -1) )

void

remove_alternative_tile ( Vector2i atlas_coords, int alternative_tile )

void

remove_tile ( Vector2i atlas_coords )

void

set_alternative_tile_id ( Vector2i atlas_coords, int alternative_tile, int new_id )

void

set_tile_animation_columns ( Vector2i atlas_coords, int frame_columns )

void

set_tile_animation_frame_duration ( Vector2i atlas_coords, int frame_index, float duration )

void

set_tile_animation_frames_count ( Vector2i atlas_coords, int frames_count )

void

set_tile_animation_mode ( Vector2i atlas_coords, TileAnimationMode mode )

void

set_tile_animation_separation ( Vector2i atlas_coords, Vector2i separation )

void

set_tile_animation_speed ( Vector2i atlas_coords, float speed )


Enumerations

enum TileAnimationMode:

TileAnimationMode TILE_ANIMATION_MODE_DEFAULT = 0

Tile animations start at same time, looking identical.

TileAnimationMode TILE_ANIMATION_MODE_RANDOM_START_TIMES = 1

Tile animations start at random times, looking varied.

TileAnimationMode TILE_ANIMATION_MODE_MAX = 2

Represents the size of the TileAnimationMode enum.


Constants

TRANSFORM_FLIP_H = 4096

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)

TRANSFORM_FLIP_V = 8192

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

TRANSFORM_TRANSPOSE = 16384

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


Property Descriptions

Vector2i margins = Vector2i(0, 0)

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


Vector2i separation = Vector2i(0, 0)

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


Texture2D texture

The atlas texture.


Vector2i texture_region_size = Vector2i(16, 16)

  • void set_texture_region_size ( Vector2i value )

  • Vector2i get_texture_region_size ( )

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


bool use_texture_padding = true

  • void set_use_texture_padding ( bool value )

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


Method Descriptions

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


int create_alternative_tile ( Vector2i atlas_coords, int alternative_id_override=-1 )

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.


void create_tile ( Vector2i atlas_coords, Vector2i size=Vector2i(1, 1) )

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


Vector2i get_atlas_grid_size ( ) 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.


int get_next_alternative_tile_id ( Vector2i atlas_coords ) const

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


Texture2D get_runtime_texture ( ) const

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


Rect2i get_runtime_tile_texture_region ( Vector2i atlas_coords, int frame ) 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 get_tile_texture_region.


int get_tile_animation_columns ( Vector2i atlas_coords ) const

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


float get_tile_animation_frame_duration ( Vector2i atlas_coords, int frame_index ) const

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


int get_tile_animation_frames_count ( Vector2i atlas_coords ) const

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


TileAnimationMode get_tile_animation_mode ( Vector2i atlas_coords ) const

Returns the TileAnimationMode of the tile at atlas_coords. See also set_tile_animation_mode.