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 🔗

代表单元格的水平翻转标志。应该直接对 TileMap 使用，修改放置图块的备选 ID，将其进行翻转。

var alternate_id = $TileMap.get_cell_alternative_tile(0, Vector2i(2, 2))
if not alternate_id & TileSetAtlasSource.TRANSFORM_FLIP_H:
    # 如果没有翻转过就进行翻转。
    $TileMap.set_cell(0, 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)