TileMapLayer

Наследует: Node2D < CanvasItem < Node < Object

Узел для 2D-карт на основе плиток.

Описание

Узел для 2D-карт на основе тайлов. TileMapLayer использует TileSet, содержащий список плиток, которые используются для создания карт на основе сетки. В отличие от узла TileMap, который устарел, TileMapLayer имеет только один слой плиток. Вы можете использовать несколько TileMapLayer для достижения того же результата, что и узел TileMap.

Из соображений производительности все обновления TileMap группируются в конце кадра. Это означает, что тайлы сцены из TileSetScenesCollectionSource инициализируются после своего родительского элемента. Они ставятся в очередь только внутри дерева сцены.

Чтобы принудительно выполнить обновление раньше, вызовите update_internals().

Примечание: Для повышения производительности и совместимости координаты, сериализуемые TileMapLayer, ограничены 16-битными знаковыми целыми числами, то есть диапазон координат X и Y составляет от -32768 до 32767. При сохранении данных, тайлы, выходящие за этот диапазон, переносятся.

Обучающие материалы

Свойства

bool	collision_enabled	`true`
DebugVisibilityMode	collision_visibility_mode	`0`
bool	enabled	`true`
bool	navigation_enabled	`true`
DebugVisibilityMode	navigation_visibility_mode	`0`
bool	occlusion_enabled	`true`
int	physics_quadrant_size	`16`
int	rendering_quadrant_size	`16`
PackedByteArray	tile_map_data	`PackedByteArray()`
TileSet	tile_set
bool	use_kinematic_bodies	`false`
bool	x_draw_order_reversed	`false`
int	y_sort_origin	`0`

Методы

void	_tile_data_runtime_update(coords: Vector2i, tile_data: TileData) virtual
void	_update_cells(coords: Array[Vector2i], forced_cleanup: bool) virtual
bool	_use_tile_data_runtime_update(coords: Vector2i) virtual
void	clear()
void	erase_cell(coords: Vector2i)
void	fix_invalid_tiles()
int	get_cell_alternative_tile(coords: Vector2i) const
Vector2i	get_cell_atlas_coords(coords: Vector2i) const
int	get_cell_source_id(coords: Vector2i) const
TileData	get_cell_tile_data(coords: Vector2i) const
Vector2i	get_coords_for_body_rid(body: RID) const
RID	get_navigation_map() const
Vector2i	get_neighbor_cell(coords: Vector2i, neighbor: CellNeighbor) const
TileMapPattern	get_pattern(coords_array: Array[Vector2i])
Array[Vector2i]	get_surrounding_cells(coords: Vector2i)
Array[Vector2i]	get_used_cells() const
Array[Vector2i]	get_used_cells_by_id(source_id: int = -1, atlas_coords: Vector2i = Vector2i(-1, -1), alternative_tile: int = -1) const
Rect2i	get_used_rect() const
bool	has_body_rid(body: RID) const
bool	is_cell_flipped_h(coords: Vector2i) const
bool	is_cell_flipped_v(coords: Vector2i) const
bool	is_cell_transposed(coords: Vector2i) const
Vector2i	local_to_map(local_position: Vector2) const
Vector2i	map_pattern(position_in_tilemap: Vector2i, coords_in_pattern: Vector2i, pattern: TileMapPattern)
Vector2	map_to_local(map_position: Vector2i) const
void	notify_runtime_tile_data_update()
void	set_cell(coords: Vector2i, source_id: int = -1, atlas_coords: Vector2i = Vector2i(-1, -1), alternative_tile: int = 0)
void	set_cells_terrain_connect(cells: Array[Vector2i], terrain_set: int, terrain: int, ignore_empty_terrains: bool = true)
void	set_cells_terrain_path(path: Array[Vector2i], terrain_set: int, terrain: int, ignore_empty_terrains: bool = true)
void	set_navigation_map(map: RID)
void	set_pattern(position: Vector2i, pattern: TileMapPattern)
void	update_internals()

Сигналы

changed() 🔗

Выдается при изменении свойств этого TileMapLayer. Сюда входят измененные ячейки, свойства или изменения, внесенные в назначенный ему TileSet.

Примечание: Этот сигнал может выдаваться очень часто при пакетном изменении TileMapLayer. Избегайте выполнения сложной обработки в подключенной функции и рассмотрите возможность отсрочки ее до конца кадра (т. е. вызова Object.call_deferred()).

Перечисления

enum DebugVisibilityMode: 🔗

DebugVisibilityMode DEBUG_VISIBILITY_MODE_DEFAULT = 0

Скройте формы отладки столкновений или навигации в редакторе и используйте настройки отладки, чтобы определить их видимость в игре (например, SceneTree.debug_collisions_hint или SceneTree.debug_navigation_hint).

DebugVisibilityMode DEBUG_VISIBILITY_MODE_FORCE_HIDE = 2

Всегда скрывайте формы отладки столкновений или навигации.

DebugVisibilityMode DEBUG_VISIBILITY_MODE_FORCE_SHOW = 1

Всегда показывать формы отладки столкновений или навигации.

Описания свойств

bool collision_enabled = true 🔗

void set_collision_enabled(value: bool)
bool is_collision_enabled()

Включить или отключить столкновения.

DebugVisibilityMode collision_visibility_mode = 0 🔗

void set_collision_visibility_mode(value: DebugVisibilityMode)
DebugVisibilityMode get_collision_visibility_mode()

Показать или скрыть формы столкновений TileMapLayer. Если установлено значение DEBUG_VISIBILITY_MODE_DEFAULT, это зависит от настроек отладки столкновений.

bool enabled = true 🔗

void set_enabled(value: bool)
bool is_enabled()

Если false, полностью отключает этот TileMapLayer (рендеринг, столкновения, навигацию, тайлы сцены и т. д.)

bool navigation_enabled = true 🔗

void set_navigation_enabled(value: bool)
bool is_navigation_enabled()

Если true, области навигации включены.

DebugVisibilityMode navigation_visibility_mode = 0 🔗

void set_navigation_visibility_mode(value: DebugVisibilityMode)
DebugVisibilityMode get_navigation_visibility_mode()

Показать или скрыть навигационные сетки TileMapLayer. Если установлено значение DEBUG_VISIBILITY_MODE_DEFAULT, это зависит от настроек отладки навигации показа.

bool occlusion_enabled = true 🔗

void set_occlusion_enabled(value: bool)
bool is_occlusion_enabled()

Включить или отключить окклюзию света.

int physics_quadrant_size = 16 🔗

void set_physics_quadrant_size(value: int)
int get_physics_quadrant_size()

The TileMapLayer's physics quadrant size. Within a physics quadrant, cells with similar physics properties are grouped together and their collision shapes get merged. physics_quadrant_size defines the length of a square's side, in the map's coordinate system, that forms the quadrant. Thus, the default quadrant size groups together 16 * 16 = 256 tiles.

Note: As quadrants are created according to the map's coordinate system, the quadrant's "square shape" might not look like square in the TileMapLayer's local coordinate system.

Note: This impacts the value returned by get_coords_for_body_rid(). Higher values will make that function less precise. To get the exact cell coordinates, you need to set physics_quadrant_size to 1, which disables physics chunking.

int rendering_quadrant_size = 16 🔗

void set_rendering_quadrant_size(value: int)
int get_rendering_quadrant_size()

Размер квадранта рендеринга TileMapLayer. Квадрант — это группа тайлов, которые нужно нарисовать вместе на одном элементе холста в целях оптимизации. rendering_quadrant_size определяет длину стороны квадрата в системе координат карты, которая образует квадрант. Таким образом, размер квадранта по умолчанию группирует вместе 16 * 16 = 256 тайлов.

Размер квадранта не применяется к отсортированному по Y TileMapLayer, так как в этом случае тайлы группируются по положению Y.

Примечание: Поскольку квадранты создаются в соответствии с системой координат карты, «квадратная форма» квадранта может не выглядеть как квадрат в локальной системе координат TileMapLayer.

PackedByteArray tile_map_data = PackedByteArray() 🔗

void set_tile_map_data_from_array(value: PackedByteArray)
PackedByteArray get_tile_map_data_as_array()

Необработанные данные карты плиток в виде массива байтов.

Note: The returned array is copied and any changes to it will not update the original property value. See PackedByteArray for more details.

TileSet tile_set 🔗

void set_tile_set(value: TileSet)
TileSet get_tile_set()

TileSet, используемый этим слоем. Текстуры, столкновения и дополнительное поведение всех доступных плиток хранятся здесь.

bool use_kinematic_bodies = false 🔗

void set_use_kinematic_bodies(value: bool)
bool is_using_kinematic_bodies()

Если true, то формы столкновений TileMapLayer будут инстанцированы как кинематические тела. Это может понадобиться для перемещения узлов TileMapLayer (т. е. перемещения платформ).

bool x_draw_order_reversed = false 🔗

void set_x_draw_order_reversed(value: bool)
bool is_x_draw_order_reversed()

Если CanvasItem.y_sort_enabled включен, установка этого параметра в true изменит порядок отрисовки плиток на оси X на обратный.

int y_sort_origin = 0 🔗

void set_y_sort_origin(value: int)
int get_y_sort_origin()

Это значение Y-sort origin добавляется к значению Y-sort origin каждого тайла. Это позволяет, например, подделать другой уровень высоты. Это может быть полезно для игр с видом сверху вниз.

Описания метода

void _tile_data_runtime_update(coords: Vector2i, tile_data: TileData) virtual 🔗

Вызывается с объектом TileData, который будет использоваться внутри TileMapLayer, что позволяет изменять его во время выполнения.

Этот метод вызывается только в том случае, если реализован _use_tile_data_runtime_update() и возвращает true для заданного тайла coords.

Предупреждение: Подресурсы объекта tile_data такие же, как в TileSet. Их изменение может повлиять на весь TileSet. Вместо этого обязательно дублируйте эти ресурсы.

Примечание: Если свойства объекта tile_data должны со временем измениться, используйте notify_runtime_tile_data_update(), чтобы уведомить TileMapLayer, что ему нужно обновление.

void _update_cells(coords: Array[Vector2i], forced_cleanup: bool) virtual 🔗

Вызывается, когда ячейки этого TileMapLayer нуждаются во внутреннем обновлении. Это обновление может быть вызвано изменением отдельных ячеек или изменением в tile_set (что приводит к тому, что все ячейки ставятся в очередь на обновление). Первый вызов этой функции всегда предназначен для инициализации всех ячеек TileMapLayer. coords содержит координаты всех измененных ячеек, примерно в том порядке, в котором они были изменены. force_cleanup имеет значение true, когда внутренние данные TileMapLayer должны быть полностью очищены. Это происходит, когда:

Слой отключен;
Слой не виден;
tile_set имеет значение null;
Узел удален из дерева;
Узел освобожден.

Обратите внимание, что любое внутреннее обновление, происходящее при проверке одного из этих условий, считается «очисткой». См. также update_internals().

Предупреждение: Реализация этого метода может ухудшить производительность TileMapLayer.

bool _use_tile_data_runtime_update(coords: Vector2i) virtual 🔗

Должен возвращать true, если тайл по координатам coords требует обновления во время выполнения.

Предупреждение: Убедитесь, что эта функция возвращает true только при необходимости. Обработка любого тайла во время выполнения без необходимости приведёт к значительному снижению производительности.

Примечание: Если результат этой функции должен измениться, используйте notify_runtime_tile_data_update(), чтобы уведомить TileMapLayer о необходимости обновления.

void clear() 🔗

Очистка всех ячеек.

void erase_cell(coords: Vector2i) 🔗

Стирает ячейку с координатами coords.

void fix_invalid_tiles() 🔗

Очищает ячейки, содержащие тайлы, которые не существуют в tile_set.

int get_cell_alternative_tile(coords: Vector2i) const 🔗

Возвращает идентификатор альтернативного тайла ячейки по координатам coords.

Vector2i get_cell_atlas_coords(coords: Vector2i) const 🔗

Возвращает идентификатор координат атласа тайла ячейки с координатами coords. Возвращает Vector2i(-1, -1), если ячейка не существует.

int get_cell_source_id(coords: Vector2i) const 🔗

Возвращает идентификатор источника тайла ячейки с координатами coords. Возвращает -1, если ячейка не существует.

TileData get_cell_tile_data(coords: Vector2i) const 🔗

Возвращает объект TileData, связанный с заданной ячейкой, или null, если ячейка не существует или не является TileSetAtlasSource.

func get_clicked_tile_power():
    var clicked_cell = tile_map_layer.local_to_map(tile_map_layer.get_local_mouse_position())
    var data = tile_map_layer.get_cell_tile_data(clicked_cell)
    if data:
        return data.get_custom_data("power")
    else:
        return 0

Vector2i get_coords_for_body_rid(body: RID) const 🔗

Returns the coordinates of the physics quadrant (see physics_quadrant_size) for given physics body RID. Such an RID can be retrieved from KinematicCollision2D.get_collider_rid(), when colliding with a tile.

Note: Higher values of physics_quadrant_size will make this function less precise. To get the exact cell coordinates, you need to set physics_quadrant_size to 1, which disables physics chunking.

Возвращает RID навигации NavigationServer2D, используемой этим TileMapLayer.

По умолчанию возвращается карта навигации World2D по умолчанию, если только пользовательская карта не была предоставлена с помощью set_navigation_map().

Vector2i get_neighbor_cell(coords: Vector2i, neighbor: CellNeighbor) const 🔗

Возвращает соседнюю ячейку к ячейке с координатами coords, идентифицированной направлением neighbor. Этот метод учитывает различные макеты, которые может принимать TileMap.

TileMapPattern get_pattern(coords_array: Array[Vector2i]) 🔗

Создает и возвращает новый TileMapPattern из указанного массива ячеек. См. также set_pattern().

Array[Vector2i] get_surrounding_cells(coords: Vector2i) 🔗

Возвращает список всех соседних ячеек для ячейки с coords. Любая соседняя ячейка — это та, которая касается краев, поэтому для квадратной ячейки будет возвращено 4 ячейки, для шестиугольника — 6 ячеек.

Array[Vector2i] get_used_cells() const 🔗

Возвращает массив Vector2i с позициями всех ячеек, содержащих тайл. Ячейка считается пустой, если ее исходный идентификатор равен -1, ее идентификатор координат атласа равен Vector2(-1, -1), а ее альтернативный идентификатор равен -1.

Array[Vector2i] get_used_cells_by_id(source_id: int = -1, atlas_coords: Vector2i = Vector2i(-1, -1), alternative_tile: int = -1) const 🔗

Возвращает массив Vector2i с позициями всех ячеек, содержащих тайл. Тайлы могут быть отфильтрованы по их источнику (source_id), координатам атласа (atlas_coords) или альтернативному идентификатору (alternative_tile).

Если параметр имеет значение по умолчанию, он не используется для фильтрации ячеек. Таким образом, если все параметры имеют свои значения по умолчанию, этот метод возвращает тот же результат, что и get_used_cells().

Ячейка считается пустой, если её идентификатор источника равен -1, координаты атласа — Vector2(-1, -1), а альтернативный идентификатор — -1.

Rect2i get_used_rect() const 🔗

Возвращает прямоугольник, охватывающий использованные (непустые) тайлы карты.

bool has_body_rid(body: RID) const 🔗

Возвращает, принадлежит ли предоставленный body RID одной из ячеек TileMapLayer.

bool is_cell_flipped_h(coords: Vector2i) const 🔗

Возвращает true, если ячейка с координатами coords перевернута по горизонтали. Результат действителен только для источников атласа.

bool is_cell_flipped_v(coords: Vector2i) const 🔗

Возвращает true, если ячейка с координатами coords перевернута вертикально. Результат действителен только для источников атласа.

bool is_cell_transposed(coords: Vector2i) const 🔗

Возвращает true, если ячейка с координатами coords транспонирована. Результат действителен только для источников атласа.

Vector2i local_to_map(local_position: Vector2) const 🔗

Возвращает координаты карты ячейки, содержащей заданный local_position. Если local_position находится в глобальных координатах, рассмотрите возможность использования Node2D.to_local() перед передачей его этому методу. См. также map_to_local().

Vector2i map_pattern(position_in_tilemap: Vector2i, coords_in_pattern: Vector2i, pattern: TileMapPattern) 🔗

Возвращает соответствующие координаты ячейки для заданных координат coords_in_pattern в TileMapPattern, если шаблон был вставлен по координатам position_in_tilemap (см. set_pattern()). Это сопоставление необходимо, потому что для фигур тайлов со смещением на половину простое вычисление position_in_tile_map + coords_in_pattern может не сработать.

Vector2 map_to_local(map_position: Vector2i) const 🔗

Возвращает центрированную позицию ячейки в локальном координатном пространстве TileMapLayer. Чтобы преобразовать возвращаемое значение в глобальные координаты, используйте Node2D.to_global(). См. также local_to_map().

Примечание: Это может не соответствовать визуальной позиции тайла, т. е. игнорирует свойство TileData.texture_origin отдельных тайлов.

void notify_runtime_tile_data_update() 🔗

Уведомляет узел TileMapLayer, что вызовы _use_tile_data_runtime_update() или _tile_data_runtime_update() приведут к разным результатам. Таким образом, это вызовет обновление TileMapLayer.

Предупреждение: Обновление TileMapLayer требует больших вычислительных затрат и может повлиять на производительность. Постарайтесь ограничить количество вызовов этой функции, чтобы избежать ненужного обновления.

Примечание: Это не запускает прямое обновление TileMapLayer, обновление будет выполнено в конце кадра, как обычно (если только вы не вызовете update_internals()).

void set_cell(coords: Vector2i, source_id: int = -1, atlas_coords: Vector2i = Vector2i(-1, -1), alternative_tile: int = 0) 🔗

Устанавливает идентификаторы тайла для ячейки с координатами coords. Каждый тайл TileSet идентифицируется с помощью трех частей:

Идентификатор источника source_id идентифицирует идентификатор TileSetSource. См. TileSet.set_source_id(),
Идентификатор координат атласа atlas_coords идентифицирует координаты тайла в атласе (если источником является TileSetAtlasSource). Для TileSetScenesCollectionSource это всегда должно быть Vector2i(0, 0),
Идентификатор альтернативного тайла alternative_tile идентифицирует альтернативный тайл в атласе (если источником является TileSetAtlasSource), а для TileSetScenesCollectionSource — сцену.

Если source_id установлен на -1, atlas_coords на Vector2i(-1, -1) или alternative_tile на -1, ячейка будет стерта. Стертая ячейка получает все ее идентификаторы, автоматически установленные на соответствующие недействительные значения, а именно -1, Vector2i(-1, -1) и -1.

void set_cells_terrain_connect(cells: Array[Vector2i], terrain_set: int, terrain: int, ignore_empty_terrains: bool = true) 🔗

Обновить все ячейки в массиве координат cells так, чтобы они использовали заданный terrain для заданного terrain_set. Если обновленная ячейка имеет тот же рельеф, что и одна из соседних ячеек, эта функция пытается объединить две. Эта функция может обновить соседние тайлы, если это необходимо для создания правильных переходов рельефа.

Если ignore_empty_terrains имеет значение true, пустые ландшафты будут игнорироваться при попытке найти наиболее подходящий тайл для заданных ограничений рельефа.

Примечание: Для корректной работы этот метод требует, чтобы TileSet TileMapLayer имел ландшафты (terrain), настроенные со всеми требуемыми комбинациями рельефа. В противном случае это может привести к неожиданным результатам.

void set_cells_terrain_path(path: Array[Vector2i], terrain_set: int, terrain: int, ignore_empty_terrains: bool = true) 🔗

Обновите все ячейки в массиве координат path, чтобы они использовали заданный terrain для заданного terrain_set. Функция также соединит две последовательные ячейки на пути с тем же рельефом. Эта функция может обновить соседние тайлы, если необходимо создать правильные переходы рельефа.

Если ignore_empty_terrains имеет значение true, пустые ландшафты будут игнорироваться при попытке найти наиболее подходящий тайл для заданных ограничений рельефа.

Примечание: Для корректной работы этот метод требует, чтобы TileSet TileMapLayer имел ландшафты, настроенные со всеми требуемыми комбинациями рельефа. В противном случае это может привести к неожиданным результатам.

Устанавливает пользовательскую map как навигационную карту NavigationServer2D. Если не установлено, вместо этого используется навигационная карта по умолчанию World2D.

void set_pattern(position: Vector2i, pattern: TileMapPattern) 🔗

Вставляет TileMapPattern в указанную position на карте тайлов. См. также get_pattern().

void update_internals() 🔗

Запускает прямое обновление TileMapLayer. Обычно вызов этой функции не требуется, так как узел TileMapLayer обновляется автоматически при изменении одного из его свойств или ячеек.

Однако по соображениям производительности эти обновления пакетируются и задерживаются до конца кадра. Вызов этой функции заставит TileMapLayer обновиться немедленно.

Предупреждение: Обновление TileMapLayer требует больших вычислительных затрат и может повлиять на производительность. Попробуйте ограничить количество обновлений и количество плиток, на которые они влияют.