Up to date

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

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

枚举¶

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)

TRANSFORM_FLIP_V = 8192

代表单元格的垂直翻转标志。用法见 TRANSFORM_FLIP_H。

TRANSFORM_TRANSPOSE = 16384

代表单元格的转置标志。用法见 TRANSFORM_FLIP_H。

属性说明¶

Vector2i margins = Vector2i(0, 0)

void set_margins ( Vector2i value )
Vector2i get_margins ( )

边距，单位为像素，用于偏移纹理中栅格的原点。

Vector2i separation = Vector2i(0, 0)

void set_separation ( Vector2i value )
Vector2i get_separation ( )

间隔，单位为像素，是栅格的纹理区域中图块之间的间距。

Texture2D texture

void set_texture ( Texture2D value )
Texture2D get_texture ( )

图集纹理。

Vector2i texture_region_size = Vector2i(16, 16)

void set_texture_region_size ( Vector2i value )
Vector2i get_texture_region_size ( )

纹理中的基础图块大小（以像素为单位）。该大小必须大于该 TileSet 中的 tile_size 值。

bool use_texture_padding = true

void set_use_texture_padding ( bool value )
bool get_use_texture_padding ( )

如果为 true，则生成一个内部纹理，每个图块周围有一个额外的单像素填充。纹理填充避免了图块之间出现线条状的常见伪像。

禁用该设置可能会导致性能略有提高，因为在 TileSetAtlasSource 资源被修改时，生成内部纹理需要内存和处理时间。

方法说明¶

void clear_tiles_outside_texture ( )

移除所有位于可用纹理区域之外的图块。这个方法会遍历所有源的图块，因此建议先使用 has_tiles_outside_texture。

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

为坐标为 atlas_coords 的图块创建备选图块。如果 alternative_id_override 为 -1，则会给予自动生成的唯一 ID，否则使用给定的 ID 赋值。

返回新的备选标识符，如果无法使用提供的 alternative_id_override 创建则返回 -1。

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

在坐标 atlas_coords 处新建给定大小 size 的图块。

Vector2i get_atlas_grid_size ( ) const

返回图集栅格大小，这取决于纹理中可以容纳多少个图块。因此，它取决于 texture 的大小，该图集的 margins、和该图块的 texture_region_size。

int get_next_alternative_tile_id ( Vector2i atlas_coords ) const

返回后续调用 create_alternative_tile 时将返回的备选 ID。

Texture2D get_runtime_texture ( ) const

如果 use_texture_padding 为 false，则返回 texture。否则，创建并返回包含内边距的内部 ImageTexture。

Rect2i get_runtime_tile_texture_region ( Vector2i atlas_coords, int frame ) const

返回由 get_runtime_texture 返回的纹理内给定 frame 的坐标 atlas_coords 处的图块区块。

注意：如果 use_texture_padding 为 false，则返回与 get_tile_texture_region 相同的结果。

int get_tile_animation_columns ( Vector2i atlas_coords ) const

返回位于坐标 atlas_coords 的图块的动画布局中有多少列。

float get_tile_animation_frame_duration ( Vector2i atlas_coords, int frame_index ) const

返回位于坐标 atlas_coords 的图块的第 frame_index 帧的动画帧时长。

int get_tile_animation_frames_count ( Vector2i atlas_coords ) const

返回位于坐标 atlas_coords 的图块有多少动画帧。

TileAnimationMode get_tile_animation_mode ( Vector2i atlas_coords ) const

返回图集坐标为 atlas_coords 的图块的 TileAnimationMode。另见 set_tile_animation_mode。

Vector2i get_tile_animation_separation ( Vector2i atlas_coords ) const

返回位于坐标 atlas_coords 的图块的帧与帧之间（在图集网格中）的间隔。

float get_tile_animation_speed ( Vector2i atlas_coords ) const

返回位于坐标 atlas_coords 的图块的动画速度。

float get_tile_animation_total_duration ( Vector2i atlas_coords ) const

返回坐标 atlas_coords 处的图块的帧持续时间的总和。这个值需要除以动画速度才能得到实际的动画循环持续时间。

Vector2i get_tile_at_coords ( Vector2i atlas_coords ) const

如果有覆盖 atlas_coords 坐标的图块，则返回该图块左上角的坐标（即它的坐标 ID）。否则返回 Vector2i(-1, -1)。

TileData get_tile_data ( Vector2i atlas_coords, int alternative_tile ) const

返回给定图集坐标和备选 ID 对应的 TileData 对象。

Vector2i get_tile_size_in_atlas ( Vector2i atlas_coords ) const

返回位于坐标 atlas_coords 的图块的大小（使用栅格坐标系）。

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

返回某个图块在图集纹理中的纹理区域。对于动画图块，可以提供 frame 参数来获取动画中不同的帧对应的区域。

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

返回修改以下任意属性时将会自动移除的图块坐标 ID 的数组：texture、margins、separation、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

返回图集中是否有足够的空间来使用给定的属性创建/修改图块。如果提供了 ignored_tile，则判断时会和给定的图块在图集中不存在一样。可以在想要修改某个图块的属性时使用。

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

将 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 ( Vector2i atlas_coords, int alternative_tile )

移除备选 ID 为 alternative_tile 的备选图块。

使用为 0 的 alternative_tile 调用这个函数会失败，因为基础图块备选项无法被移除。

void remove_tile ( Vector2i atlas_coords )

移除位于坐标 atlas_coords 的图块及其备选项。

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

将图块的备选 ID 从 alternative_tile 改为 new_id。

调用这个函数时将 new_id 设为 0 会导致失败，因为基础图块备选项无法移动。

void set_tile_animation_columns ( Vector2i atlas_coords, int frame_columns )

设置位于坐标 atlas_coords 的图块的动画布局中的列数。如果设置为 0，则动画帧在图集中水平排列。

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

设置位于坐标 atlas_coords 的图块动画帧 frame_index 的持续时间 duration。

void set_tile_animation_frames_count ( Vector2i atlas_coords, int frames_count )

设置位于坐标 atlas_coords 的图块有多少动画帧。

void set_tile_animation_mode ( Vector2i atlas_coords, TileAnimationMode mode )

将图集坐标为 atlas_coords 的图块的 TileAnimationMode 设置为 mode。另见 get_tile_animation_mode。

void set_tile_animation_separation ( Vector2i atlas_coords, Vector2i separation )

设置位于坐标 atlas_coords 的图块的动画布局中，图块的间距（单位为栅格图块）。

void set_tile_animation_speed ( Vector2i atlas_coords, float speed )

设置位于坐标 atlas_coords 的图块的动画速度。