Up to date

This page is up to date for Godot 4.1. 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

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

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

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_separation ( Vector2i atlas_coords, Vector2i separation )

void

set_tile_animation_speed ( Vector2i atlas_coords, float speed )


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

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


Vector2i get_tile_animation_separation ( Vector2i atlas_coords ) const

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


float get_tile_animation_speed ( Vector2i atlas_coords ) const

Returns the animation speed of the tile at coordinates atlas_coords.


float get_tile_animation_total_duration ( Vector2i atlas_coords ) 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.


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


TileData get_tile_data ( Vector2i atlas_coords, int alternative_tile ) const

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


Vector2i get_tile_size_in_atlas ( Vector2i atlas_coords ) const

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


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


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

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.


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

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.


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

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


void remove_alternative_tile ( Vector2i atlas_coords, int alternative_tile )

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_tile ( Vector2i atlas_coords )

Remove a tile and its alternative at coordinates atlas_coords.


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

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_tile_animation_columns ( Vector2i atlas_coords, int frame_columns )

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_frame_duration ( Vector2i atlas_coords, int frame_index, float duration )

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


void set_tile_animation_frames_count ( Vector2i atlas_coords, int frames_count )

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


void set_tile_animation_separation ( Vector2i atlas_coords, Vector2i separation )

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_speed ( Vector2i atlas_coords, float speed )

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