TileMap (2D) — модульные 2D-уровни

Эта энциклопедия про 3D, но Godot имеет первоклассный 2D-pipeline, и TileMap — главный инструмент для модульных уровней (платформеры, top-down RPG, dungeon crawlers, city builders).

Архитектура TileMap в Godot 4.x

С Godot 4.3 произошло важное изменение: классический TileMap-узел deprecated в пользу TileMapLayer-узлов.

В новом проекте используйте TileMapLayer. Один узел = один слой (например, фон → детали → объекты).

Главные понятия

• TileSet — Resource со списком всех доступных тайлов (sprite + collision + nav-data).
• TileMapLayer — Node2D, который рисует тайлы из TileSet на координатной сетке.
• Tile — ячейка TileSet’а: sprite-источник + collision-shape + custom data layers.
• TileSetAtlasSource — источник тайлов из одной картинки (atlas-style).
• TileSetScenesCollectionSource — источник тайлов из PackedScene (анимированные / сложные).

Создание TileSet

1. В FileSystem → New Resource → TileSet.
2. Двойной клик — открывается TileSet editor (bottom panel).
3. Кликаете + → New Atlas Source → выбираете texture (sprite-atlas с тайлами).
4. Редактор автоматически режет атлас на ячейки (по умолчанию 16×16). Каждая клетка — отдельный tile.
5. Для каждого tile настраиваете:
   • Physics layer — collision shape (выберите Physics Layer 0, нарисуйте полигон).
   • Navigation layer — для NavigationAgent2D.
   • Custom data layers — произвольные свойства (например, “damage_per_tick” для лавы).

TileMapLayer в работе

World
├── TileMapLayer_Background
│   tile_set: floor.tres
│   y_sort_enabled: false
├── TileMapLayer_Walls
│   tile_set: floor.tres  # тот же TileSet
│   y_sort_enabled: false
└── TileMapLayer_Objects
    tile_set: objects.tres
    y_sort_enabled: true   # для top-down с глубиной

В Scene View выберите слой → TileMap Editor (bottom panel) → выбираете tile из палитры → рисуете.

Программное управление

extends TileMapLayer

func _ready() -> void:
    # Координаты в TileMap — Vector2i (целые)
    set_cell(Vector2i(0, 0), 0, Vector2i(0, 0))  # source_id, atlas_coords
    # source_id — индекс источника в TileSet
    # atlas_coords — позиция тайла в атласе

    # Стереть тайл
    erase_cell(Vector2i(0, 0))

    # Получить tile data
    var tile_data := get_cell_tile_data(Vector2i(0, 0))
    if tile_data:
        var dmg = tile_data.get_custom_data("damage_per_tick")
        print(dmg)

    # Конвертация world ↔ map координат
    var map_pos := local_to_map(Vector2(64, 32))
    var world_pos := map_to_local(Vector2i(2, 1))

Terrains — авто-соединение тайлов

Главная фича для красивых уровней. Вы рисуете зону (трава, вода, дорога), и движок сам подбирает правильный tile для каждой ячейки на основе соседей.

1. В TileSet editor → выберите Terrains tab.
2. Добавьте Terrain Set → новый Terrain (“Grass”).
3. На каждом tile в Atlas выделите, какие его углы относятся к terrain “Grass”.
4. В TileMap editor переключите режим на Terrains → выбираете Grass → “красите” большой областью.
5. Godot для каждой клетки автоматически выбирает tile из набора, у которого углы совпадают с соседями.

Это terrain matching по углам и/или сторонам — классический “auto-tile”. Можно нарисовать кривую границу травы по карте, и стыковка с дорогой / водой будет идеальной.

Navigation на TileMap

Если хотите, чтобы NavigationAgent2D ходил по вашей карте:

1. В TileSet → Physics Layers НЕ хватит — это collision, не nav.
2. В TileSet → Navigation Layers → добавьте слой.
3. На каждом proходимом tile → нарисуйте navigation polygon (обычно совпадает с границей tile’а).
4. На TileMapLayer узле → Navigation Layers → отметьте используемый.
5. Godot автоматически собирает navmesh из всех проходимых tile’ов.

Анимированные тайлы

В TileSet Atlas Source → выберите tile → в Inspector → Animation Frames Count > 1. Указываете длительность каждого фрейма. Movement / textures animation работает без скриптов — TileMapLayer обновляет автоматически.

Применение: текущая вода, факелы, мерцающие cristals.

Подводные камни

1. Tile size в TileSet vs TileMapLayer — должны совпадать. Если поменяли в TileSet → перерисуйте слои.
2. Physics не работают по умолчанию — Physics Layer должна быть включена и tile должен иметь collision polygon. Часто забывают.
3. Y-sort на одном слое не дружит с tile-collision — для top-down с правильной сортировкой персонажа за деревом используйте Object Layer (Y-sort) отдельно от ground layers.
4. Custom data layers — мощно, но запоминайте имена. Опечатка "damage_per_tick" vs "damagePerTick" — silent fail.

Когда TileMap — НЕ выбор

• 3D-сцена — это 2D-узлы; в 3D используйте GridMap (см. главу 21).
• Hex grid — TileMap поддерживает hex layout (Inspector → tile_shape = HALF_OFFSET_*), но редактор удобнее под orthogonal. Для серьёзного hex-проекта смотрите community-плагины.
• Voxel-style 3D — это уже совсем другая задача; TileMap не подходит.