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>") 设置。

属性

方法

枚举

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) 🔗

将图块的备选 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 的图块的动画速度。