Phaser.js: всё об играх и разработке

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

Создание обширных игровых миров часто упирается в инструменты для их проектирования. Формат CSV (Comma-Separated Values) — это простой и понятный способ хранения тайловых карт, который можно редактировать даже в обычном табличном редакторе. В этой статье мы разберём пример загрузки CSV-карты в Phaser 3, настроим камеру для скроллинга по большому уровню и добавим визуальную панель для отладки. Этот подход отлично подходит для прототипирования или создания игр с процедурной генерацией уровней.

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

Живой запуск

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

Исходный код

class Example extends Phaser.Scene
{
    controls;

    preload ()
    {
        this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
        this.load.tilemapCSV('map', 'assets/tilemaps/csv/catastrophi_level2.csv');
        this.load.image('tiles', 'assets/tilemaps/tiles/catastrophi_tiles_16.png');
    }

    create ()
    {
        console.log(this.cache.tilemap.entries);

        // When loading a CSV map, make sure to specify the tileWidth and tileHeight
        const map = this.make.tilemap({ key: 'map', tileWidth: 16, tileHeight: 16 });
        const tileset = map.addTilesetImage('tiles');
        const layer = map.createLayer(0, tileset, 0, 0); // layer index, tileset, x, y
        layer.skipCull = true;

        this.cameras.main.setBounds(0, 0, map.widthInPixels, map.heightInPixels);

        const cursors = this.input.keyboard.createCursorKeys();

        const controlConfig = {
            camera: this.cameras.main,
            left: cursors.left,
            right: cursors.right,
            up: cursors.up,
            down: cursors.down,
            speed: 0.5
        };

        this.controls = new Phaser.Cameras.Controls.FixedKeyControl(controlConfig);

        const help = this.add.text(16, 16, 'Arrow keys to scroll', {
            fontSize: '18px',
            fill: '#ffffff'
        });

        help.setScrollFactor(0);

        const gui = new dat.GUI();

        const cam = this.cameras.main;

        cam.setBounds(0, 0, 4096, 4096);

        gui.addFolder('Camera');
        gui.add(cam, 'dirty').listen();
        gui.add(cam.midPoint, 'x').listen();
        gui.add(cam.midPoint, 'y').listen();
        gui.add(cam, 'scrollX').listen();
        gui.add(cam, 'scrollY').listen();
    }

    update (time, delta)
    {
        this.controls.update(delta);
    }
}

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

const game = new Phaser.Game(config);

Загрузка ресурсов: карта и тайлсет

В методе preload() загружаются два ключевых ресурса: CSV-файл с данными карты и изображение тайлсета. Обратите внимание, что для загрузки CSV используется специальный метод load.tilemapCSV(), который парсит файл и помещает результат в кеш тайловых карт.

this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
this.load.tilemapCSV('map', 'assets/tilemaps/csv/catastrophi_level2.csv');
this.load.image('tiles', 'assets/tilemaps/tiles/catastrophi_tiles_16.png');

Создание тайлового слоя из данных CSV

В методе create() мы извлекаем данные карты из кеша и создаём визуальный слой. Важный нюанс: при создании тайловой карты из CSV данных необходимо явно указать размер тайла через параметры tileWidth и tileHeight. Свойство layer.skipCull = true отключает оптимизацию, скрывающую тайлы за пределами экрана, что полезно для отладки больших карт.

const map = this.make.tilemap({ key: 'map', tileWidth: 16, tileHeight: 16 });
const tileset = map.addTilesetImage('tiles');
const layer = map.createLayer(0, tileset, 0, 0);
layer.skipCull = true;

Настройка камеры и управления

Чтобы игрок мог исследовать обширный уровень, камере задаются границы, соответствующие размерам карты в пикселях. Для управления камерой создаётся экземпляр Phaser.Cameras.Controls.FixedKeyControl, который привязывает стрелки клавиатуры к перемещению камеры с заданной скоростью. Текст с подсказкой имеет setScrollFactor(0), поэтому он остаётся на фиксированной позиции поверх экрана.

this.cameras.main.setBounds(0, 0, map.widthInPixels, map.heightInPixels);

const cursors = this.input.keyboard.createCursorKeys();
const controlConfig = {
    camera: this.cameras.main,
    left: cursors.left,
    right: cursors.right,
    up: cursors.up,
    down: cursors.down,
    speed: 0.5
};
this.controls = new Phaser.Cameras.Controls.FixedKeyControl(controlConfig);

Визуальная отладка с dat.GUI

Для наглядного отслеживания состояния камеры в реальном времени в примере используется библиотека dat.GUI. Она создаёт панель, которая отображает и позволяет слушать изменения ключевых свойств камеры, таких как её центральная точка (midPoint) и текущее смещение (scrollX, scrollY). Это бесценный инструмент при отладке скроллинга и проверки границ уровня.

const gui = new dat.GUI();
const cam = this.cameras.main;
gui.addFolder('Camera');
gui.add(cam, 'dirty').listen();
gui.add(cam.midPoint, 'x').listen();
gui.add(cam.midPoint, 'y').listen();
gui.add(cam, 'scrollX').listen();
gui.add(cam, 'scrollY').listen();

Обновление состояния управления

Класс FixedKeyControl требует, чтобы его метод update() вызывался каждый кадр игрового цикла. Именно это происходит в методе update() сцены. В него передаётся delta — время, прошедшее с предыдущего кадра, что обеспечивает плавное и независимое от частоты кадров движение камеры.

update (time, delta)
{
    this.controls.update(delta);
}

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

Использование CSV для хранения карт — это быстрый и минималистичный способ создать большой уровень для вашей игры на Phaser. Вы научились загружать такие данные, визуализировать их и давать игроку возможность исследовать мир с помощью движущейся камеры. Для экспериментов попробуйте: сгенерировать CSV-карту программно, чтобы создать процедурный уровень; добавить несколько слоёв тайлов для создания parallax-эффекта; или заменить FixedKeyControl на привязку камеры к спрайту игрока.