TileSet

继承： Resource < RefCounted < Object

Tilemap 的图块库。

描述

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

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

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

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

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

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

教程

• 使用 Tilemap

• 2D 平台跳跃演示

• 2D 等轴演示

• 2D 六边形演示

• AStarGrid2D 的 2D 网格导航演示

• 2D 角色扮演游戏（RPG）演示

• 2D 运动学角色演示

属性

方法

枚举

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(value: TileLayout)

• TileLayout get_tile_layout()

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

TileOffsetAxis tile_offset_axis = 0 🔗

• void set_tile_offset_axis(value: TileOffsetAxis)

• TileOffsetAxis get_tile_offset_axis()

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

TileShape tile_shape = 0 🔗

• void set_tile_shape(value: TileShape)

• TileShape get_tile_shape()

图块的形状。

Vector2i tile_size = Vector2i(16, 16) 🔗

• void set_tile_size(value: Vector2i)

• Vector2i get_tile_size()

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

bool uv_clipping = false 🔗

• void set_uv_clipping(value: bool)

• bool is_uv_clipping()

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

方法说明

void add_custom_data_layer(to_position: int = -1) 🔗

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

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

void add_navigation_layer(to_position: int = -1) 🔗

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

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

void add_occlusion_layer(to_position: int = -1) 🔗

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

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

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

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

void add_physics_layer(to_position: int = -1) 🔗

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

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

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

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

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

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

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

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

void add_terrain_set(to_position: int = -1) 🔗

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

void cleanup_invalid_tile_proxies() 🔗

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

void clear_tile_proxies() 🔗

清除所有图块代理。

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

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

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

Array get_coords_level_tile_proxy(source_from: int, coords_from: Vector2i) 🔗

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

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

int get_custom_data_layer_by_name(layer_name: String) const 🔗

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

String get_custom_data_layer_name(layer_index: int) const 🔗

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

Variant.Type get_custom_data_layer_type(layer_index: int) const 🔗

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

int get_custom_data_layers_count() const 🔗

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

bool get_navigation_layer_layer_value(layer_index: int, layer_number: int) const 🔗

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

int get_navigation_layer_layers(layer_index: int) const 🔗

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

int get_navigation_layers_count() const 🔗

返回导航层的数量。

int get_next_source_id() const 🔗

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

int get_occlusion_layer_light_mask(layer_index: int) const 🔗

返回遮挡层的光照掩码。

bool get_occlusion_layer_sdf_collision(layer_index: int) const 🔗

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

int get_occlusion_layers_count() const 🔗

返回遮挡层的数量。

TileMapPattern get_pattern(index: int = -1) 🔗

返回给定 index 处的 TileMapPattern。

int get_patterns_count() 🔗

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

int get_physics_layer_collision_layer(layer_index: int) const 🔗

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

int get_physics_layer_collision_mask(layer_index: int) const 🔗

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

PhysicsMaterial get_physics_layer_physics_material(layer_index: int) const 🔗

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

int get_physics_layers_count() const 🔗

返回物理层的数量。

TileSetSource get_source(source_id: int) const 🔗

返回 ID 为 source_id 的 TileSetSource。

int get_source_count() const 🔗

返回该 TileSet 中 TileSetSource 的数量。

int get_source_id(index: int) const 🔗

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

int get_source_level_tile_proxy(source_from: int) 🔗

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

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

Color get_terrain_color(terrain_set: int, terrain_index: int) const 🔗

返回地形的颜色。

String get_terrain_name(terrain_set: int, terrain_index: int) const 🔗

返回地形的名称。

TerrainMode get_terrain_set_mode(terrain_set: int) const 🔗

返回地形集模式。

int get_terrain_sets_count() const 🔗

返回地形集的数量。

int get_terrains_count(terrain_set: int) const 🔗

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

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

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

bool has_coords_level_tile_proxy(source_from: int, coords_from: Vector2i) 🔗

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

bool has_source(source_id: int) const 🔗

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

bool has_source_level_tile_proxy(source_from: int) 🔗

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

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

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

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

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

void move_custom_data_layer(layer_index: int, to_position: int) 🔗

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

void move_navigation_layer(layer_index: int, to_position: int) 🔗

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

void move_occlusion_layer(layer_index: int, to_position: int) 🔗

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

void move_physics_layer(layer_index: int, to_position: int) 🔗

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

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

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

void move_terrain_set(terrain_set: int, to_position: int) 🔗

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

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

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

void remove_coords_level_tile_proxy(source_from: int, coords_from: Vector2i) 🔗

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

void remove_custom_data_layer(layer_index: int) 🔗

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

void remove_navigation_layer(layer_index: int) 🔗

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

void remove_occlusion_layer(layer_index: int) 🔗

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

void remove_pattern(index: int) 🔗

移除给定索引处的 TileMapPattern。

void remove_physics_layer(layer_index: int) 🔗

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

void remove_source(source_id: int) 🔗

移除具有给定源 ID 的源。

void remove_source_level_tile_proxy(source_from: int) 🔗

移除源级别的图块代理。

void remove_terrain(terrain_set: int, terrain_index: int) 🔗

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

void remove_terrain_set(terrain_set: int) 🔗

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

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

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

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

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

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

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

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

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

void set_custom_data_layer_name(layer_index: int, layer_name: String) 🔗

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

void set_custom_data_layer_type(layer_index: int, layer_type: Variant.Type) 🔗

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

void set_navigation_layer_layer_value(layer_index: int, layer_number: int, value: bool) 🔗

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

void set_navigation_layer_layers(layer_index: int, layers: int) 🔗

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

void set_occlusion_layer_light_mask(layer_index: int, light_mask: int) 🔗

设置给定 TileSet 遮挡层中遮挡器的遮挡层（渲染服务器中使用）。

void set_occlusion_layer_sdf_collision(layer_index: int, sdf_collision: bool) 🔗

启用或禁用给定 TileSet 遮挡层中遮挡器的 SDF 碰撞。

void set_physics_layer_collision_layer(layer_index: int, layer: int) 🔗

设置给定 TileSet 物理层中物体的物理层（物理服务器中使用）。

void set_physics_layer_collision_mask(layer_index: int, mask: int) 🔗

设置给定 TileSet 物理层中物体的物理层（物理服务器中使用）。

void set_physics_layer_physics_material(layer_index: int, physics_material: PhysicsMaterial) 🔗

设置给定 TileSet 物理层中物体的物理材质。

void set_source_id(source_id: int, new_source_id: int) 🔗

更改源的 ID。

void set_source_level_tile_proxy(source_from: int, source_to: int) 🔗

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

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

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

void set_terrain_color(terrain_set: int, terrain_index: int, color: Color) 🔗

设置地形的颜色。该颜色用于在 TileSet 编辑器中区分不同的地形。

void set_terrain_name(terrain_set: int, terrain_index: int, name: String) 🔗

设置地形的名称。

void set_terrain_set_mode(terrain_set: int, mode: TerrainMode) 🔗

设置地形模式。每种模式决定了图块形状的哪一个位被用来匹配相邻图块的地形。