О чем этот пример

Работа с тайловыми картами — основа для создания уровней в 2D-играх. Часто возникает задача точечного размещения объектов: расставить монеты, разместить ключи или исправить "дыру" в готовой карте. Метод `putTileAt` в Phaser — это прямое решение для таких случаев. В этой статье мы детально разберем, как работает этот метод, чем отличаются его вызовы с разными параметрами и как избежать типичных ошибок. Вы получите практическое понимание, которое сразу можно применить в своих проектах.

Версия Phaser: код и демо в этой статье рассчитаны на Phaser 3.90.0.

Живой запуск

Ниже встроен рабочий билд примера. Оригинальный источник: GitHub.

Исходный код


class Example extends Phaser.Scene
{
    preload ()
    {
        this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
        this.load.image('tiles', 'assets/tilemaps/tiles/platformer_tiles.png');
    }

    create ()
    {
        const map = this.make.tilemap({ tileWidth: 16, tileHeight: 16, width: 25, height: 20 });

        const tiles = map.addTilesetImage('tiles');

        const layer = map.createBlankLayer('layer1', tiles);

        map.putTileAt(77, 1, 1);
        map.putTileAt(77, 2, 1, true, layer);
    }
}

const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    backgroundColor: '#00000',
    parent: 'phaser-example',
    pixelArt: true,
    scene: Example
};

const game = new Phaser.Game(config);

Создание каркаса: Tilemap и слой

Прежде чем размещать тайлы, нужно создать саму карту и слой для отрисовки. В примере это делается в методе create сцены.

Сначала создается объект тайловой карты (Tilemap). Его параметры задают базовые размеры: ширину и высоту карты в тайлах, а также размер одного тайла в пикселях.

Затем загруженное изображение с тайлами связывается с картой через метод addTilesetImage. После этого создается пустой слой, на котором и будут рисоваться наши тайлы.

const map = this.make.tilemap({ tileWidth: 16, tileHeight: 16, width: 25, height: 20 });
const tiles = map.addTilesetImage('tiles');
const layer = map.createBlankLayer('layer1', tiles);

Базовый вызов: map.putTileAt(index, x, y)

Самый простой способ разместить тайл — вызвать метод putTileAt непосредственно у объекта карты map. Первый аргумент — индекс тайла в наборе (tileset). Индексация начинается с 0. В нашем примере используется индекс 77.

Второй и третий аргументы — координаты `xиy` на тайловой карте, куда будет помещен тайл. Важно: это координаты в ячейках карты (тайн-координаты), а не в пикселях экрана. Координата (0,0) — это верхний левый угол карты.

Этот вызов автоматически разместит тайл на первом созданном слое карты.

map.putTileAt(77, 1, 1);

Явное указание слоя: map.putTileAt(index, x, y, recalculate, layer)

Часто у карты несколько слоев (например, фон, земля, объекты). Чтобы точно указать, на какой слой положить тайл, используется расширенная форма метода.

Первые три аргумента остаются прежними. Четвертый аргумент — булевый флаг recalculate. Если передать true, Phaser пересчитает коллайдеры слоя после размещения тайла. Это важно, если на тайле есть физическое тело.

Пятый аргумент — целевой слой (layer). Это объект, который мы получили при создании слоя через createBlankLayer. Именно на этот слой и будет помещен тайл.

map.putTileAt(77, 2, 1, true, layer);

Почему важно указывать слой явно?

В примере показаны оба варианта вызова. Первый (map.putTileAt(77, 1, 1)) неявно работает с первым слоем карты. Второй (map.putTileAt(77, 2, 1, true, layer)) явно указывает слой layer.

Разница становится критичной, когда слоев больше одного. Если не указывать слой, тайл может попасть не на тот слой, который вы задумали, что приведет к визуальным багам (например, объект окажется под фоном) или проблемам с коллизиями.

Всегда явно передавайте слой в метод putTileAt, если в вашей сцене используется несколько слоев тайловой карты. Это делает код предсказуемым и защищенным от ошибок при его расширении.

Конфигурация игры и загрузка

Для корректной работы примера важна настройка игры (config) и предварительная загрузка ресурсов в preload.

Метод preload загружает изображение с тайлами из удаленного источника. Обратите внимание на флаг pixelArt: true в конфиге — он включает специальную фильтрацию для пиксельной графики, предотвращая размытие.

// В методе preload:
this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
this.load.image('tiles', 'assets/tilemaps/tiles/platformer_tiles.png');

// Конфигурация игры:
const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    backgroundColor: '#00000',
    parent: 'phaser-example',
    pixelArt: true,
    scene: Example
};

Что попробовать дальше

Метод putTileAt — это ваш точный инструмент для ручного редактирования тайловых карт в Phaser. Используйте его для размещения предметов, создания procedural content или исправления карт, сгенерированных алгоритмически. Для экспериментов попробуйте: 1. Создать несколько слоев и размещать тайлы на разных из них. 2. Использовать индекс 0 (обычно это "пустой" тайл) для удаления объектов с карты. 3. Размещать тайлы в цикле, чтобы создавать линии или простые геометрические фигуры на слое.