TileMap

Inherits: Node2D < CanvasItem < Node < Object

基于 2D 图块的地图节点。

描述

基于 2D 图块的地图节点。图块地图使用 TileSet，其中包含图块列表，纹理能加上可选的碰撞、导航和/或遮挡形状，用于创建基于网格的地图。

当对图块地图进行物理查询时，Physics2DDirectSpaceState.intersect_shape、Physics2DDirectBodyState.get_contact_collider_shape_metadata 等方法会返回检测到的碰撞形状，这些形状所处的单元格坐标会被编码为 metadata。

教程

• Using Tilemaps

• 2D Platformer Demo

• 2D Isometric Demo

• 2D Hexagonal Demo

• 2D Navigation Astar Demo

• 2D Role Playing Game Demo

• 2D Kinematic Character Demo

属性

方法

信号

• settings_changed ( )

当图块地图设置发生变化时触发。

枚举

enum Mode:

• MODE_SQUARE = 0 —- 正交定向模式。

• MODE_ISOMETRIC = 1 —- 等距定向模式。

• MODE_CUSTOM = 2 —- 自定义方向模式。

enum HalfOffset:

• HALF_OFFSET_X = 0 —- X坐标上的一半偏移。

• HALF_OFFSET_Y = 1 —- Y坐标上的一半偏移。

• HALF_OFFSET_DISABLED = 2 —- 禁用半偏移。

• HALF_OFFSET_NEGATIVE_X = 3 —- X坐标上的半偏移，负数。

• HALF_OFFSET_NEGATIVE_Y = 4 —- Y坐标上的半偏移，负数。

enum TileOrigin:

• TILE_ORIGIN_TOP_LEFT = 0 —- 图块原点在其左上角。

• TILE_ORIGIN_CENTER = 1 —- 图块原点在其中心。

• TILE_ORIGIN_BOTTOM_LEFT = 2 —- 图块原点在其左下角。

常量

• INVALID_CELL = -1 —- 当一个单元不存在时返回。

属性说明

• bool cell_clip_uv

如果true，单元格的UV将被剪裁。

• Transform2D cell_custom_transform

将应用到图块地图的，单元格的自定义Transform2D。

• HalfOffset cell_half_offset

依次排列的图块的偏移量。有关可能的值，参阅HalfOffset。

• int cell_quadrant_size

图块地图的象限大小。使用这个尺寸的图块，通过批处理优化绘制。

• Vector2 cell_size

图块地图的单元大小。

• TileOrigin cell_tile_origin

图块原点的坐标。有关可能的值，参阅TileOrigin。

• bool cell_y_sort

如果true，图块地图的直接子节点将按其Y坐标顺序绘制。

• bool centered_textures

如果true，纹理将被集中在每个图块的中间。这对某些等距或上帝视角的模式很有用，当纹理被做得比图块大或小时，例如，为了避免瓷砖边缘的闪烁。偏移量仍被应用，但从瓦片的中心开始。如果使用，compatibility_mode会被忽略。

如果false，纹理坐标从左上角开始，除非compatibility_mode被启用。

• float collision_bounce

静态体碰撞的反弹值，参阅collision_use_kinematic。

• float collision_friction

静态体碰撞的摩擦值，参阅collision_use_kinematic。

• int collision_layer

The collision layer(s) for all colliders in the TileMap. See Collision layers and masks in the documentation for more information.

• int collision_mask

The collision mask(s) for all colliders in the TileMap. See Collision layers and masks in the documentation for more information.

• bool collision_use_kinematic

如果true，图块地图的碰撞将被当作运动体处理。如果false，碰撞将被当作静态体来处理。

• bool collision_use_parent

如果true，这个图块地图的碰撞形状将被添加到父级的碰撞形状中。父级必须是一个CollisionObject2D。

• bool compatibility_mode

如果为true，则保持与Godot 3.1或更早版本的图块地图的兼容性，即当图块原点改变时，纹理会移动，如果纹理大小不均匀，则会旋转。这种模式对非同质等距图块（例如2:1）进行flip_h, flip_v 和 transpose 图块操作时，将出现问题，在这种情况下，纹理不能与碰撞重合，因此不推荐用于等距或非方形图块。

如果false，在进行flip_h、flip_v操作时，如果不使用偏移量，纹理不会移动，在改变图块原点时也是如此。

兼容性模式对centered_textures选项不起作用，因为用cell_tile_origin选项或不规则图块中的纹理进行替换时，与这些纹理的居中项没有关系。

• Mode mode

图块地图的方向模式。有关可能的值，参阅Mode。

• int occluder_light_mask

分配给图块地图中所有光遮挡器的光线遮罩。图块集的光遮挡器将只从具有相同光线遮挡的Light2D中投射阴影。

• bool show_collision

如果true，碰撞形状在编辑器中是可见的。不影响碰撞形状在运行时的可见性。要在运行时显示碰撞形状，请在调试菜单中启用可见的碰撞形状。

• TileSet tile_set

指定的TileSet图块集。

方法说明

• void clear ( )

清除所有单元格。

• void fix_invalid_tiles ( )

清除图块集中不存在的单元格。

• int get_cell ( int x, int y ) const

返回指定单元格的图块索引。如果单元格中没有图块，则返回 INVALID_CELL。

• Vector2 get_cell_autotile_coord ( int x, int y ) const

返回图块集中自动图块变化的坐标（子图块列和行）。如果单元格没有自动图块，则返回向量零。

• int get_cellv ( Vector2 position ) const

返回由 Vector2 指定的单元格的图块索引。如果单元格中没有图块，则返回 INVALID_CELL。

• bool get_collision_layer_bit ( int bit ) const

如果指定碰撞层的比特位被设置，返回 true。

• bool get_collision_mask_bit ( int bit ) const

如果指定碰撞遮罩比特位被设置，返回 true。

• Array get_used_cells ( ) const

返回一个Vector2数组，其中包含图块集中所有单元格的位置（图块索引非-1）。

• Array get_used_cells_by_id ( int id ) const

返回所有具有id中指定的图块索引的单元格的数组。

• Rect2 get_used_rect ( )

返回一个包围着地图中已使用非空图块的矩形。

• bool is_cell_transposed ( int x, int y ) const

如果指定单元格被转置，即X轴和Y轴互换，则返回true。

• bool is_cell_x_flipped ( int x, int y ) const

如果指定单元格在X轴上被翻转，则返回true。

• bool is_cell_y_flipped ( int x, int y ) const

如果指定单元格在Y轴上被翻转，则返回true。

• Vector2 map_to_world ( Vector2 map_position, bool ignore_half_ofs=false ) const

返回与指定的图块地图（基于网格）坐标相对应的单元格左上角的局部坐标。

要获得全局坐标，请使用Node2D.to_global。

var local_position = my_tilemap.map_to_world(map_position)
var global_position = my_tilemap.to_global(local_position)

可以选择忽略图块地图的半偏移。

• void set_cell ( int x, int y, int tile, bool flip_x=false, bool flip_y=false, bool transpose=false, Vector2 autotile_coord=Vector2( 0, 0 ) )

设置由Vector2给出的单元格的图块索引。

-1的索引将清除该单元。

也可以选择翻转、移位，或者指定自动图块坐标。自动图块坐标指的是子图块的列和行。

注意： 由于性能原因，导航多边形和碰撞形状等数据不会立即更新。

如果你需要这些被立即更新，你可以调用update_dirty_quadrants。

重写该方法会在内部重写它，允许在放置/移除图块时实现自定义逻辑。

func set_cell(x, y, tile, flip_x=false, flip_y=false, transpose=false, autotile_coord=Vector2()):
    # 在这里写下你的自定义逻辑。
    # 调用默认方法:
    .set_cell(x, y, tile, flip_x, flip_y, transpose, autotile_coord)

• void set_cellv ( Vector2 position, int tile, bool flip_x=false, bool flip_y=false, bool transpose=false )

设置给定单元格的瓦片索引。

索引-1会清除该单元。

也可以选择翻转或转置图块。

注意： 由于性能原因，导航多边形和碰撞形状等数据不会立即更新。

如果你需要立即更新这些数据，可以调用update_dirty_quadrants。

• void set_collision_layer_bit ( int bit, bool value )

设置指定碰撞层bit位。

• void set_collision_mask_bit ( int bit, bool value )

设置指定碰撞遮罩bit位。

• void update_bitmask_area ( Vector2 position )

对基于网格的X和Y坐标所引用的单元格，及其相邻单元格，应用自动平移规则。

• void update_bitmask_region ( Vector2 start=Vector2( 0, 0 ), Vector2 end=Vector2( 0, 0 ) )

对指定区域内的单元格应用自动平移规则，由基于网格的X和Y坐标指定。

用无效的或缺失的参数调用时，自动平铺规则应用于整个图块地图。

• void update_dirty_quadrants ( )

更新图块地图的象限，允许如导航和碰撞形状等内容，在修改后立即使用。

• Vector2 world_to_map ( Vector2 world_position ) const

返回与指定的局部坐标相对应的图块地图坐标，基于网格。

要使用这个全局坐标，首先要用Node2D.to_local确定局部坐标。

var local_position = my_tilemap.to_local(global_position)
var map_position = my_tilemap.world_to_map(local_position)