Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

TileSetAtlasSource

繼承： TileSetSource < Resource < RefCounted < Object

以一組圖塊的形式向 TileSet 資源暴露 2D 合集紋理。

說明

合集是在紋理上鋪設的圖塊柵格。柵格中的每個圖塊都必須使用 create_tile() 公開。然後使用它們在柵格中的座標，對這些圖塊進行索引。

每個圖塊也可以在柵格座標中有一個大小，使其在地合集中的儲存格更多或更少。

可以使用 create_alternative_tile() 建立圖塊的替代版本，然後使用替代 ID 對其進行索引。主圖塊（柵格中的那個）使用一個等於 0 的替代 ID 進行存取。

每個圖塊替代品都有一組由源的 TileSet 圖層定義的屬性。這些屬性儲存在 TileData 物件中，該物件可以使用 get_tile_data() 來存取和修改。

由於 TileData 屬性直接儲存在 TileSetAtlasSource 資源中，它們的屬性也可以使用 TileSetAtlasSource.set("<coords_x>:<coords_y>/<alternative_id>/<tile_data_property>") 設定。

屬性

Vector2i	margins	`Vector2i(0, 0)`
Vector2i	separation	`Vector2i(0, 0)`
Texture2D	texture
Vector2i	texture_region_size	`Vector2i(16, 16)`
bool	use_texture_padding	`true`

方法

void	clear_tiles_outside_texture()
int	create_alternative_tile(atlas_coords: Vector2i, alternative_id_override: int = -1)
void	create_tile(atlas_coords: Vector2i, size: Vector2i = Vector2i(1, 1))
Vector2i	get_atlas_grid_size() const
int	get_next_alternative_tile_id(atlas_coords: Vector2i) const
Texture2D	get_runtime_texture() const
Rect2i	get_runtime_tile_texture_region(atlas_coords: Vector2i, frame: int) const
int	get_tile_animation_columns(atlas_coords: Vector2i) const
float	get_tile_animation_frame_duration(atlas_coords: Vector2i, frame_index: int) const
int	get_tile_animation_frames_count(atlas_coords: Vector2i) const
TileAnimationMode	get_tile_animation_mode(atlas_coords: Vector2i) const
Vector2i	get_tile_animation_separation(atlas_coords: Vector2i) const
float	get_tile_animation_speed(atlas_coords: Vector2i) const
float	get_tile_animation_total_duration(atlas_coords: Vector2i) const
Vector2i	get_tile_at_coords(atlas_coords: Vector2i) const
TileData	get_tile_data(atlas_coords: Vector2i, alternative_tile: int) const
Vector2i	get_tile_size_in_atlas(atlas_coords: Vector2i) const
Rect2i	get_tile_texture_region(atlas_coords: Vector2i, frame: int = 0) const
PackedVector2Array	get_tiles_to_be_removed_on_change(texture: Texture2D, margins: Vector2i, separation: Vector2i, texture_region_size: Vector2i)
bool	has_room_for_tile(atlas_coords: Vector2i, size: Vector2i, animation_columns: int, animation_separation: Vector2i, frames_count: int, ignored_tile: Vector2i = Vector2i(-1, -1)) const
bool	has_tiles_outside_texture() const
void	move_tile_in_atlas(atlas_coords: Vector2i, new_atlas_coords: Vector2i = Vector2i(-1, -1), new_size: Vector2i = Vector2i(-1, -1))
void	remove_alternative_tile(atlas_coords: Vector2i, alternative_tile: int)
void	remove_tile(atlas_coords: Vector2i)
void	set_alternative_tile_id(atlas_coords: Vector2i, alternative_tile: int, new_id: int)
void	set_tile_animation_columns(atlas_coords: Vector2i, frame_columns: int)
void	set_tile_animation_frame_duration(atlas_coords: Vector2i, frame_index: int, duration: float)
void	set_tile_animation_frames_count(atlas_coords: Vector2i, frames_count: int)
void	set_tile_animation_mode(atlas_coords: Vector2i, mode: TileAnimationMode)
void	set_tile_animation_separation(atlas_coords: Vector2i, separation: Vector2i)
void	set_tile_animation_speed(atlas_coords: Vector2i, speed: float)

列舉

enum TileAnimationMode: 🔗

TileAnimationMode TILE_ANIMATION_MODE_DEFAULT = 0

平鋪動畫同時開始，看起來相同。

TileAnimationMode TILE_ANIMATION_MODE_RANDOM_START_TIMES = 1

平鋪動畫隨機開始，看起來多種多樣。

TileAnimationMode TILE_ANIMATION_MODE_MAX = 2

代表 TileAnimationMode 列舉的大小。

常數

TRANSFORM_FLIP_H = 4096 🔗

代表單元格的水平翻轉標誌。應該直接對 TileMapLayer 使用，修改放置圖塊的備選 ID，將其進行翻轉。

var alternate_id = $TileMapLayer.get_cell_alternative_tile(Vector2i(2, 2))
if not alternate_id & TileSetAtlasSource.TRANSFORM_FLIP_H:
    # 如果沒有翻轉過就進行翻轉。
    $TileMapLayer.set_cell(Vector2i(2, 2), source_id, atlas_coords, alternate_id | TileSetAtlasSource.TRANSFORM_FLIP_H)

注意：可以將這些變換進行組合，從而實現 0、90、180、270 度旋轉，範例如下：

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,
}

TRANSFORM_FLIP_V = 8192 🔗

表示儲存格的垂直翻轉旗標。用法請參閱 TRANSFORM_FLIP_H。

TRANSFORM_TRANSPOSE = 16384 🔗

表示儲存格的轉置旗標。用法請參閱 TRANSFORM_FLIP_H。

屬性說明

Vector2i margins = Vector2i(0, 0) 🔗

void set_margins(value: Vector2i)
Vector2i get_margins()

邊距，單位為圖元，用於偏移紋理中柵格的原點。

Vector2i separation = Vector2i(0, 0) 🔗

void set_separation(value: Vector2i)
Vector2i get_separation()

間隔，單位為圖元，是柵格的紋理區域中圖塊之間的間距。

Texture2D texture 🔗

void set_texture(value: Texture2D)
Texture2D get_texture()

合集紋理。

Vector2i texture_region_size = Vector2i(16, 16) 🔗

void set_texture_region_size(value: Vector2i)
Vector2i get_texture_region_size()

紋理中的基礎圖塊大小（以像素為單位）。該大小必須大於等於 TileSet 中的 tile_size 值。

bool use_texture_padding = true 🔗

void set_use_texture_padding(value: bool)
bool get_use_texture_padding()

如果為 true，則生成一個內部紋理，每個圖塊周圍有一個額外的單圖元填充。紋理填充避免了圖塊之間出現線條狀的常見偽像。

停用該設定可能會導致效能略有提高，因為在 TileSetAtlasSource 資源被修改時，生成內部紋理需要記憶體和處理時間。

方法說明

void clear_tiles_outside_texture() 🔗

刪除所有不適合可用紋理區域的圖塊。此方法會迭代所有來源的圖塊，因此建議事先使用 has_tiles_outside_texture()。

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

為座標為 atlas_coords 的圖塊建立備選圖塊。如果 alternative_id_override 為 -1，則會給予自動生成的唯一 ID，否則使用給定的 ID 賦值。

返回新的備選識別字，如果無法使用提供的 alternative_id_override 建立則返回 -1。

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

在座標 atlas_coords 處新建給定大小 size 的圖塊。

Vector2i get_atlas_grid_size() const 🔗

回傳圖集柵格大小，這取決於紋理中可以容納多少個圖塊。因此，它取決於 texture 的大小，該圖集的 margins 和該圖塊的 texture_region_size。

int get_next_alternative_tile_id(atlas_coords: Vector2i) const 🔗

返回後續呼叫 create_alternative_tile() 時將返回的備選 ID。

Texture2D get_runtime_texture() const 🔗

如果 use_texture_padding 為 false，則回傳 texture。否則，建立並回傳包含內邊距的內部 ImageTexture。

Rect2i get_runtime_tile_texture_region(atlas_coords: Vector2i, frame: int) const 🔗

返回由 get_runtime_texture() 返回的紋理內給定 frame 的座標 atlas_coords 處的圖塊區塊。

注意：如果 use_texture_padding 為 false，則返回與 get_tile_texture_region() 相同的結果。

int get_tile_animation_columns(atlas_coords: Vector2i) const 🔗

返回位於座標 atlas_coords 的圖塊的動畫布局中有多少列。

float get_tile_animation_frame_duration(atlas_coords: Vector2i, frame_index: int) const 🔗

返回位於座標 atlas_coords 的圖塊的第 frame_index 影格的動畫影格時長。

int get_tile_animation_frames_count(atlas_coords: Vector2i) const 🔗

返回位於座標 atlas_coords 的圖塊有多少動畫影格。

TileAnimationMode get_tile_animation_mode(atlas_coords: Vector2i) const 🔗

回傳 atlas_coords 處圖塊的圖塊動畫模式。另見 set_tile_animation_mode()。

Vector2i get_tile_animation_separation(atlas_coords: Vector2i) const 🔗

返回位於座標 atlas_coords 的圖塊的影格與影格之間（在合集網格中）的間隔。

float get_tile_animation_speed(atlas_coords: Vector2i) const 🔗

返回位於座標 atlas_coords 的圖塊的動畫速度。

float get_tile_animation_total_duration(atlas_coords: Vector2i) const 🔗

返回座標 atlas_coords 處的圖塊的影格持續時間的總和。這個值需要除以動畫速度才能得到實際的動畫迴圈持續時間。

Vector2i get_tile_at_coords(atlas_coords: Vector2i) const 🔗

如果有覆蓋 atlas_coords 座標的圖塊，則返回該圖塊左上角的座標（即它的座標 ID）。否則返回 Vector2i(-1, -1)。

TileData get_tile_data(atlas_coords: Vector2i, alternative_tile: int) const 🔗

返回給定合集座標和備選 ID 對應的 TileData 對象。

Vector2i get_tile_size_in_atlas(atlas_coords: Vector2i) const 🔗

返回位於座標 atlas_coords 的圖塊的大小（使用柵格座標系）。

Rect2i get_tile_texture_region(atlas_coords: Vector2i, frame: int = 0) const 🔗

返回某個圖塊在合集紋理中的紋理區域。對於動畫圖塊，可以提供 frame 參數來取得動畫中不同的影格對應的區域。

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

返回修改以下任意屬性時將會自動移除的圖塊座標 ID 的陣列：texture、margins、separation、texture_region_size。可以用來復原可能造成圖塊資料丟失的更改。

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

返回合集中是否有足夠的空間來使用給定的屬性建立/修改圖塊。如果提供了 ignored_tile，則判斷時會和給定的圖塊在合集中不存在一樣。可以在想要修改某個圖塊的屬性時使用。

bool has_tiles_outside_texture() const 🔗

檢查來源是否有任何不適合紋理區域（部分或完全）的圖塊。

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

將 atlas_coords 座標處的圖塊及其替代物移動到具有 new_size 大小的 new_atlas_coords 座標。如果給定區域中已經存在一個圖塊，則該函式將失敗。

如果 new_atlas_coords 為 Vector2i(-1, -1)，則保持圖塊的座標。如果 new_size 為 Vector2i(-1, -1)，則保持圖塊的大小。

為避免錯誤，請首先使用 has_room_for_tile() 來檢查移動是否可行。

void remove_alternative_tile(atlas_coords: Vector2i, alternative_tile: int) 🔗

移除備選 ID 為 alternative_tile 的備選圖塊。

使用為 0 的 alternative_tile 呼叫這個函式會失敗，因為基礎圖塊備選項無法被移除。

void remove_tile(atlas_coords: Vector2i) 🔗

移除位於座標 atlas_coords 的圖塊及其備選項。

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

將圖塊的備選 ID 從 alternative_tile 改為 new_id。

呼叫這個函式時將 new_id 設為 0 會導致失敗，因為基礎圖塊備選項無法移動。

void set_tile_animation_columns(atlas_coords: Vector2i, frame_columns: int) 🔗

設定位於座標 atlas_coords 的圖塊的動畫布局中的列數。如果設定為 0，則動畫影格在合集中水平排列。

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

設定位於座標 atlas_coords 的圖塊動畫影格 frame_index 的持續時間 duration。

void set_tile_animation_frames_count(atlas_coords: Vector2i, frames_count: int) 🔗

設定位於座標 atlas_coords 的圖塊有多少動畫影格。

void set_tile_animation_mode(atlas_coords: Vector2i, mode: TileAnimationMode) 🔗

將 atlas_coords 處的圖塊的圖塊動畫模式設定為 mode。另見 get_tile_animation_mode()。

void set_tile_animation_separation(atlas_coords: Vector2i, separation: Vector2i) 🔗

設定位於座標 atlas_coords 的圖塊的動畫布局中，圖塊的間距（單位為柵格圖塊）。

void set_tile_animation_speed(atlas_coords: Vector2i, speed: float) 🔗

設定位於座標 atlas_coords 的圖塊的動畫速度。