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

TileSet¶

继承： Resource < RefCounted < Object

Tilemap 的图块库。

描述¶

TileSet 是 TileMap 的图块库。TileSet 处理 TileSetSource 列表，每个表中存储一组图块。

图块既可以来自 TileSetAtlasSource，可以渲染纹理中的图块，支持物理、导航等功能，也可以来自 TileSetScenesCollectionSource，提供基于场景的图块。

图块通过使用三个 ID 来引用：源 ID、图集坐标 ID、备选图块 ID。

TileSet 可以配置图块暴露哪些属性。为了做到这一点，TileSet 资源使用了属性层，你可以根据需要进行添加和删除。

例如，添加物理层可以为瓷砖提供碰撞形状。不同的层都有不同的属性（物理层和遮罩），要实现不同类型的碰撞，你也可以添加多个 TileSet 物理层。

更多信息请参阅添加新层的函数。

教程¶

属性¶

TileLayout	tile_layout	`0`
TileOffsetAxis	tile_offset_axis	`0`
TileShape	tile_shape	`0`
Vector2i	tile_size	`Vector2i(16, 16)`
bool	uv_clipping	`false`

方法¶

void	add_custom_data_layer ( int to_position=-1 )
void	add_navigation_layer ( int to_position=-1 )
void	add_occlusion_layer ( int to_position=-1 )
int	add_pattern ( TileMapPattern pattern, int index=-1 )
void	add_physics_layer ( int to_position=-1 )
int	add_source ( TileSetSource source, int atlas_source_id_override=-1 )
void	add_terrain ( int terrain_set, int to_position=-1 )
void	add_terrain_set ( int to_position=-1 )
void	cleanup_invalid_tile_proxies ( )
void	clear_tile_proxies ( )
Array	get_alternative_level_tile_proxy ( int source_from, Vector2i coords_from, int alternative_from )
Array	get_coords_level_tile_proxy ( int source_from, Vector2i coords_from )
int	get_custom_data_layer_by_name ( String layer_name ) const
String	get_custom_data_layer_name ( int layer_index ) const
Variant.Type	get_custom_data_layer_type ( int layer_index ) const
int	get_custom_data_layers_count ( ) const
bool	get_navigation_layer_layer_value ( int layer_index, int layer_number ) const
int	get_navigation_layer_layers ( int layer_index ) const
int	get_navigation_layers_count ( ) const
int	get_next_source_id ( ) const
int	get_occlusion_layer_light_mask ( int layer_index ) const
bool	get_occlusion_layer_sdf_collision ( int layer_index ) const
int	get_occlusion_layers_count ( ) const
TileMapPattern	get_pattern ( int index=-1 )
int	get_patterns_count ( )
int	get_physics_layer_collision_layer ( int layer_index ) const
int	get_physics_layer_collision_mask ( int layer_index ) const
PhysicsMaterial	get_physics_layer_physics_material ( int layer_index ) const
int	get_physics_layers_count ( ) const
TileSetSource	get_source ( int source_id ) const
int	get_source_count ( ) const
int	get_source_id ( int index ) const
int	get_source_level_tile_proxy ( int source_from )
Color	get_terrain_color ( int terrain_set, int terrain_index ) const
String	get_terrain_name ( int terrain_set, int terrain_index ) const
TerrainMode	get_terrain_set_mode ( int terrain_set ) const
int	get_terrain_sets_count ( ) const
int	get_terrains_count ( int terrain_set ) const
bool	has_alternative_level_tile_proxy ( int source_from, Vector2i coords_from, int alternative_from )
bool	has_coords_level_tile_proxy ( int source_from, Vector2i coords_from )
bool	has_source ( int source_id ) const
bool	has_source_level_tile_proxy ( int source_from )
Array	map_tile_proxy ( int source_from, Vector2i coords_from, int alternative_from ) const
void	move_custom_data_layer ( int layer_index, int to_position )
void	move_navigation_layer ( int layer_index, int to_position )
void	move_occlusion_layer ( int layer_index, int to_position )
void	move_physics_layer ( int layer_index, int to_position )
void	move_terrain ( int terrain_set, int terrain_index, int to_position )
void	move_terrain_set ( int terrain_set, int to_position )
void	remove_alternative_level_tile_proxy ( int source_from, Vector2i coords_from, int alternative_from )
void	remove_coords_level_tile_proxy ( int source_from, Vector2i coords_from )
void	remove_custom_data_layer ( int layer_index )
void	remove_navigation_layer ( int layer_index )
void	remove_occlusion_layer ( int layer_index )
void	remove_pattern ( int index )
void	remove_physics_layer ( int layer_index )
void	remove_source ( int source_id )
void	remove_source_level_tile_proxy ( int source_from )
void	remove_terrain ( int terrain_set, int terrain_index )
void	remove_terrain_set ( int terrain_set )
void	set_alternative_level_tile_proxy ( int source_from, Vector2i coords_from, int alternative_from, int source_to, Vector2i coords_to, int alternative_to )
void	set_coords_level_tile_proxy ( int p_source_from, Vector2i coords_from, int source_to, Vector2i coords_to )
void	set_custom_data_layer_name ( int layer_index, String layer_name )
void	set_custom_data_layer_type ( int layer_index, Variant.Type layer_type )
void	set_navigation_layer_layer_value ( int layer_index, int layer_number, bool value )
void	set_navigation_layer_layers ( int layer_index, int layers )
void	set_occlusion_layer_light_mask ( int layer_index, int light_mask )
void	set_occlusion_layer_sdf_collision ( int layer_index, bool sdf_collision )
void	set_physics_layer_collision_layer ( int layer_index, int layer )
void	set_physics_layer_collision_mask ( int layer_index, int mask )
void	set_physics_layer_physics_material ( int layer_index, PhysicsMaterial physics_material )
void	set_source_id ( int source_id, int new_source_id )
void	set_source_level_tile_proxy ( int source_from, int source_to )
void	set_terrain_color ( int terrain_set, int terrain_index, Color color )
void	set_terrain_name ( int terrain_set, int terrain_index, String name )
void	set_terrain_set_mode ( int terrain_set, TerrainMode mode )

枚举¶

enum TileShape:

TileShape TILE_SHAPE_SQUARE = 0

矩形图块形状。

TileShape TILE_SHAPE_ISOMETRIC = 1

钻石图块形状（用于等轴外观）。

注意：等轴 TileSet 在 TileMap 及其所有图层都启用了Y 排序时效果最好。

TileShape TILE_SHAPE_HALF_OFFSET_SQUARE = 2

矩形图块形状，每隔一行/列偏移半个图块。

TileShape TILE_SHAPE_HEXAGON = 3

六边形图块形状。

enum TileLayout:

TileLayout TILE_LAYOUT_STACKED = 0

图块坐标布局，两个轴与对应的局部水平轴和垂直轴保持一致。

TileLayout TILE_LAYOUT_STACKED_OFFSET = 1

与 TILE_LAYOUT_STACKED 相同，但第一个半偏移偏向负方向，而不是正方向。

TileLayout TILE_LAYOUT_STAIRS_RIGHT = 2

图块坐标布局，水平轴保持水平，垂直轴朝向右下方。

TileLayout TILE_LAYOUT_STAIRS_DOWN = 3

图块坐标布局，垂直轴保持垂直，水平轴朝向右下方。

TileLayout TILE_LAYOUT_DIAMOND_RIGHT = 4

图块坐标布局，水平轴朝向右上方，垂直轴朝向右下方。

TileLayout TILE_LAYOUT_DIAMOND_DOWN = 5

图块坐标布局，水平轴朝向右下方，垂直轴朝向左下方。

enum TileOffsetAxis:

TileOffsetAxis TILE_OFFSET_AXIS_HORIZONTAL = 0

水平半偏移。

TileOffsetAxis TILE_OFFSET_AXIS_VERTICAL = 1

垂直半偏移。

enum CellNeighbor:

CellNeighbor CELL_NEIGHBOR_RIGHT_SIDE = 0

右侧相邻单元格。

CellNeighbor CELL_NEIGHBOR_RIGHT_CORNER = 1

右角相邻单元格。

CellNeighbor CELL_NEIGHBOR_BOTTOM_RIGHT_SIDE = 2

右下侧相邻单元格。

CellNeighbor CELL_NEIGHBOR_BOTTOM_RIGHT_CORNER = 3

右下角相邻单元格。

CellNeighbor CELL_NEIGHBOR_BOTTOM_SIDE = 4

下侧相邻单元格。

CellNeighbor CELL_NEIGHBOR_BOTTOM_CORNER = 5

下角相邻单元格。

CellNeighbor CELL_NEIGHBOR_BOTTOM_LEFT_SIDE = 6

左下侧相邻单元格。

CellNeighbor CELL_NEIGHBOR_BOTTOM_LEFT_CORNER = 7

左下角相邻单元格。

CellNeighbor CELL_NEIGHBOR_LEFT_SIDE = 8

左侧相邻单元格。

CellNeighbor CELL_NEIGHBOR_LEFT_CORNER = 9

左角相邻单元格。

CellNeighbor CELL_NEIGHBOR_TOP_LEFT_SIDE = 10

左上侧相邻单元格。

CellNeighbor CELL_NEIGHBOR_TOP_LEFT_CORNER = 11

左上角相邻单元格。

CellNeighbor CELL_NEIGHBOR_TOP_SIDE = 12

上侧相邻单元格。

CellNeighbor CELL_NEIGHBOR_TOP_CORNER = 13

上角相邻单元格。

CellNeighbor CELL_NEIGHBOR_TOP_RIGHT_SIDE = 14

右上侧相邻单元格。

CellNeighbor CELL_NEIGHBOR_TOP_RIGHT_CORNER = 15

右上角相邻单元格。

enum TerrainMode:

TerrainMode TERRAIN_MODE_MATCH_CORNERS_AND_SIDES = 0

要求与相邻图块地形的角和边都匹配。

TerrainMode TERRAIN_MODE_MATCH_CORNERS = 1

要求与相邻图块地形的角相匹配。

TerrainMode TERRAIN_MODE_MATCH_SIDES = 2

要求与相邻图块地形的边相匹配。

属性说明¶

TileLayout tile_layout = 0

void set_tile_layout ( TileLayout value )
TileLayout get_tile_layout ( )

对于所有半偏移形状（等轴、六边形和半偏移正方形），更改图块在 TileMap 栅格中的索引方式。

TileOffsetAxis tile_offset_axis = 0

void set_tile_offset_axis ( TileOffsetAxis value )
TileOffsetAxis get_tile_offset_axis ( )

对于所有半偏移形状（等轴、六边形和半偏移正方形），确定偏移轴。

TileShape tile_shape = 0

void set_tile_shape ( TileShape value )
TileShape get_tile_shape ( )

图块的形状。

Vector2i tile_size = Vector2i(16, 16)

void set_tile_size ( Vector2i value )
Vector2i get_tile_size ( )

图块的大小，单位为像素。无论图块是什么形状，这个大小对应的都是图块形状的包围矩形。因此，这是图集所需的最小单元格大小。

bool uv_clipping = false

void set_uv_clipping ( bool value )
bool is_uv_clipping ( )

渲染图块时启用/禁用 UV 裁剪。

方法说明¶

void add_custom_data_layer ( int to_position=-1 )

在 TileSet 中添加自定义数据层，放置到数组中的 to_position 位置。如果 to_position 为 -1，则会将其添加到数组的末尾。

自定义数据层能够为图集图块分配自定义属性。

在 TileSet 中添加导航层，放置到数组中的 to_position 位置。如果 to_position 为 -1，则会将其添加到数组的末尾。

导航层能够为图集图块分配导航区域。

void add_occlusion_layer ( int to_position=-1 )

在 TileSet 中添加遮挡层，放置到数组中的 to_position 位置。如果 to_position 为 -1，则会将其添加到数组的末尾。

遮挡层能够为图集图块分配遮挡多边形。

int add_pattern ( TileMapPattern pattern, int index=-1 )

添加存储在 TileSet 资源中的 TileMapPattern。如果提供了 index，则会插入到给定的位置。

void add_physics_layer ( int to_position=-1 )

在 TileSet 中添加物理层，放置到数组中的 to_position 位置。如果 to_position 为 -1，则会将其添加到数组的末尾。

物理层能够为图集图块分配碰撞多边形。

int add_source ( TileSetSource source, int atlas_source_id_override=-1 )

在 TileSet 中添加 TileSetSource。如果 atlas_source_id_override 不为 -1，则还会设置其源 ID。否则会自动生成唯一标识符。

函数返回添加的源 ID，如果无法添加源则返回 -1。

警告：同一个源不能同时属于两个 TileSet。如果添加的源已经附加到其他 TileSet，则会在该那个 TileSet 中移除。

void add_terrain ( int terrain_set, int to_position=-1 )

在 TileSet 的 terrain_set 地形集中添加新的地形，放置到数组中的 to_position 位置。如果 to_position 为 -1，则会将其添加到数组的末尾。

void add_terrain_set ( int to_position=-1 )

在 TileSet 添加新的地形集，放置到数组中的 to_position 位置。如果 to_position 为 -1，则会将其添加到数组的末尾。

void cleanup_invalid_tile_proxies ( )

清除指向无效图块的图块代理。

void clear_tile_proxies ( )

清除所有图块代理。

Array get_alternative_level_tile_proxy ( int source_from, Vector2i coords_from, int alternative_from )

返回给定标识符的备选级代理。返回的数组包含三个代理的目标标识符（源 ID、图集坐标 ID 和备选图块 ID）。

如果该 TileSet 没有给定标识符的代理，则返回空数组。

Array get_coords_level_tile_proxy ( int source_from, Vector2i coords_from )

返回给定标识符的坐标级代理。返回的数组包含代理的两个目标标识符（源 ID 和图集坐标 ID）。

如果该 TileSet 没有给定标识符的代理，则返回空数组。

int get_custom_data_layer_by_name ( String layer_name ) const

返回自定义数据层的索引，该自定义数据层由名称表示。

String get_custom_data_layer_name ( int layer_index ) const

返回自定义数据层的名称，该自定义数据层由索引表示。

Variant.Type get_custom_data_layer_type ( int layer_index ) const

返回自定义数据层的类型，该自定义数据层由索引表示。

int get_custom_data_layers_count ( ) const

返回自定义数据层的数量。

返回由给定的 layer_index 标识的 TileSet 导航数据层是否启用了指定的导航层，导航层 layer_number 在 1 和 32 之间。

返回给定 TileSet 导航层的（导航服务器中的）导航层。

返回导航层的数量。

int get_next_source_id ( ) const

返回新的未使用的源 ID。这个生成的 ID 与调用 add_source 将返回的 ID 相同。

int get_occlusion_layer_light_mask ( int layer_index ) const

返回遮挡层的光照掩码。

bool get_occlusion_layer_sdf_collision ( int layer_index ) const

返回这个层的遮挡器是否使用 sdf_collision。

int get_occlusion_layers_count ( ) const

返回遮挡层的数量。

TileMapPattern get_pattern ( int index=-1 )

返回给定 index 处的 TileMapPattern。

int get_patterns_count ( )

返回此图块集处理的 TileMapPattern 的数量。

int get_physics_layer_collision_layer ( int layer_index ) const

返回给定 TileSet 物理层中的物体所在的（物理服务器中的）碰撞层。

int get_physics_layer_collision_mask ( int layer_index ) const

返回给定 TileSet 物理层中物体的碰撞遮罩。

PhysicsMaterial get_physics_layer_physics_material ( int layer_index ) const

返回给定 TileSet 物理层中物体的碰撞材质。

int get_physics_layers_count ( ) const

返回物理层的数量。

TileSetSource get_source ( int source_id ) const

返回 ID 为 source_id 的 TileSetSource。

int get_source_count ( ) const

返回该 TileSet 中 TileSetSource 的数量。

int get_source_id ( int index ) const

返回索引为 index 的源的源 ID。

int get_source_level_tile_proxy ( int source_from )

返回给定源标识符的源级别代理。

如果 TileSet 没有给定标识符的代理，则返回 -1。

Color get_terrain_color ( int terrain_set, int terrain_index ) const

返回地形的颜色。

String get_terrain_name ( int terrain_set, int terrain_index ) const

返回地形的名称。

TerrainMode get_terrain_set_mode ( int terrain_set ) const

返回地形集模式。

int get_terrain_sets_count ( ) const

返回地形集的数量。

int get_terrains_count ( int terrain_set ) const

返回给定地形集中的地形数。

bool has_alternative_level_tile_proxy ( int source_from, Vector2i coords_from, int alternative_from )

返回给定的标识符是否存在备选级别的代理。

bool has_coords_level_tile_proxy ( int source_from, Vector2i coords_from )

返回给定的标识符是否存在坐标级别的代理。

bool has_source ( int source_id ) const

返回该 TileSet 中是否存在给定源 ID 的源。

bool has_source_level_tile_proxy ( int source_from )

返回给定的源 ID 是否存在源级别的代理。

Array map_tile_proxy ( int source_from, Vector2i coords_from, int alternative_from ) const

根据配置的代理，将提供的标识符映射到一组新的标识符。返回的是由源 ID、图集坐标 ID 和备选图块 ID 这三个元素构成的 Array。

这个函数首先查找匹配的备选级代理，然后是坐标级代理，然后是源级代理。

如果未找到与提供的标识符对应的代理，则返回与用作参数的值相同的值。

void move_custom_data_layer ( int layer_index, int to_position )

将索引为 layer_index 的自定义数据层移动到数组中给定的 to_position 位置。还会更新相应的图集图块。

将索引为 layer_index 的导航层移动到数组中给定的 to_position 位置。还会更新相应的图集图块。

void move_occlusion_layer ( int layer_index, int to_position )

将索引为 layer_index 的遮挡层移动到数组中给定的 to_position 位置。还会更新相应的图集图块。

void move_physics_layer ( int layer_index, int to_position )

将索引为 layer_index 的物理层移动到数组中给定的 to_position 位置。还会更新相应的图集图块。

void move_terrain ( int terrain_set, int terrain_index, int to_position )

将地形集 terrain_set 中索引为 terrain_index 的地形移动到数组中给定的 to_position 位置。还会更新相应的图集图块。

void move_terrain_set ( int terrain_set, int to_position )

将索引为 terrain_set 的地形集移动到数组中给定的 to_position 位置。还会更新相应的图集图块。

void remove_alternative_level_tile_proxy ( int source_from, Vector2i coords_from, int alternative_from )

移除具有给定标识符的备选级别代理。

void remove_coords_level_tile_proxy ( int source_from, Vector2i coords_from )

移除具有给定标识符的坐标级别代理。

void remove_custom_data_layer ( int layer_index )

移除索引为 layer_index 的自定义数据层。也会相应地更新图集中的图块。

移除索引为 layer_index 的导航层。也会相应地更新图集中的图块。

void remove_occlusion_layer ( int layer_index )

移除索引为 layer_index 的遮挡层。也会相应地更新图集中的图块。

void remove_pattern ( int index )

移除给定索引处的 TileMapPattern。

void remove_physics_layer ( int layer_index )

移除索引为 layer_index 的物理层。也会更新图集中的相应图块。

void remove_source ( int source_id )

移除具有给定源 ID 的源。

void remove_source_level_tile_proxy ( int source_from )

移除源级别的图块代理。

void remove_terrain ( int terrain_set, int terrain_index )

移除给定地形集 terrain_set 中索引为 terrain_index 的地形。也会相应地更新图集中的图块。

void remove_terrain_set ( int terrain_set )

移除索引为 terrain_set 的地形集。也会相应地更新图集中的图块。

void set_alternative_level_tile_proxy ( int source_from, Vector2i coords_from, int alternative_from, int source_to, Vector2i coords_to, int alternative_to )

为给定的标识符创建备选级代理。代理会将一组图块标识符映射到另一组标识符。

可以用来替换使用此 TileSet 的所有 TileMap 中的某个图块，因为 TileMap 节点将在目标图块可用时找到并使用代理的目标图块。

可以使用编辑器自动替换 TileMap 节点中的代理图块。

void set_coords_level_tile_proxy ( int p_source_from, Vector2i coords_from, int source_to, Vector2i coords_to )

为给定的标识符创建坐标级代理。代理会将一组图块标识符映射到另一组标识符。使用坐标级代理时，备选图块 ID 保持不变。

可以用来替换使用此 TileSet 的所有 TileMap 中的某个图块，因为 TileMap 节点将在目标图块可用时找到并使用代理的目标图块。

可以使用编辑器自动替换 TileMap 节点中的代理图块。

void set_custom_data_layer_name ( int layer_index, String layer_name )

设置由给定索引标识的自定义数据层的名称。名称是层的标识符，因此如果名称已被使用就会失败并报错。

void set_custom_data_layer_type ( int layer_index, Variant.Type layer_type )

设置自定义数据层的类型，该自定义数据层由索引表示。

根据 value，启用或禁用 TileSet 导航数据层中指定的导航层，导航数据层由给定的 layer_index 标识，给定的 layer_number 应在 1 和 32 之间。

设置给定 TileSet 导航层中导航区域的导航层（导航服务器中使用）。

void set_occlusion_layer_light_mask ( int layer_index, int light_mask