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

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

Создание точных и отзывчивых коллизий — основа геймплея в платформерах и других жанрах. Phaser предоставляет мощный инструмент `Tilemap.renderDebug()` для визуального анализа карты, что позволяет быстро проверить, какие тайлы считаются твёрдыми, и как движок определяет их границы. Эта статья покажет, как интегрировать и настраивать такую отладочную визуализацию в вашем проекте, экономя часы на поиск ошибок в физике уровней.

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

Живой запуск

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

Исходный код

class Example extends Phaser.Scene
{
    showCollidingTiles = true;
    showFaces = true;
    showTiles = true;
    helpText;
    map;
    debugGraphics;
    controls;

    preload ()
    {
        this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
        this.load.tilemapTiledJSON('map', 'assets/tilemaps/maps/super-mario.json');
        this.load.image('SuperMarioBros-World1-1', 'assets/tilemaps/tiles/super-mario.png');
        this.load.bitmapFont('gothic', 'assets/fonts/bitmap/gothic.png', 'assets/fonts/bitmap/gothic.xml');
    }

    create ()
    {
        this.map = this.make.tilemap({ key: 'map' });
        const tileset = this.map.addTilesetImage('SuperMarioBros-World1-1');
        const layer = this.map.createLayer('World1', tileset, 0, 0);
        layer.setScale(2);

        this.map.setCollision([ 14, 15, 16, 20, 21, 22, 23, 24, 25, 27, 28, 29, 33, 39, 40 ]);

        this.debugGraphics = this.add.graphics();

        this.input.keyboard.on('keydown-ONE', event =>
        {
            this.showTiles = !this.showTiles;
            this.drawDebug();
        });

        this.input.keyboard.on('keydown-TWO', event =>
        {
            this.showCollidingTiles = !this.showCollidingTiles;
            this.drawDebug();
        });

        this.input.keyboard.on('keydown-THREE', event =>
        {
            this.showFaces = !this.showFaces;
            this.drawDebug();
        });

        const cursors = this.input.keyboard.createCursorKeys();
        const controlConfig = {
            camera: this.cameras.main,
            left: cursors.left,
            right: cursors.right,
            speed: 0.5
        };

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

        this.helpText = this.add.text(16, 16, this.getHelpMessage(), {
            fontSize: '18px',
            padding: { x: 10, y: 5 },
            backgroundColor: '#000000',
            fill: '#ffffff'
        });
        this.helpText.setScrollFactor(0);

        this.drawDebug();
    }

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

    drawDebug ()
    {
        const tileColor = this.showTiles ? new Phaser.Display.Color(105, 210, 231, 200) : null;
        const colldingTileColor = this.showCollidingTiles ? new Phaser.Display.Color(243, 134, 48, 200) : null;
        const faceColor = this.showFaces ? new Phaser.Display.Color(40, 39, 37, 255) : null;

        this.debugGraphics.clear();

        // Pass in null for any of the style options to disable drawing that component
        this.map.renderDebug(this.debugGraphics, {
            tileColor: tileColor, // Non-colliding tiles
            collidingTileColor: colldingTileColor, // Colliding tiles
            faceColor: faceColor // Interesting faces, i.e. colliding edges
        });

        this.helpText.setText(this.getHelpMessage());
    }

    getHelpMessage ()
    {
        return `Press 1 to toggle tiles: ${this.showTiles ? 'on' : 'off'}\nPress 2 to toggle colliding tiles: ${this.showCollidingTiles ? 'on' : 'off'}\nPress 3 to toggle interesting faces: ${this.showFaces ? 'on' : 'off'}`;
    }
}

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

const game = new Phaser.Game(config);

Подготовка карты и настройка коллизий

В первую очередь загружаем карту и тайлсет, создаём слой и настраиваем коллизии. Ключевой метод setCollision помечает определённые индексы тайлов как твёрдые, с которыми смогут взаимодействовать физические тела.

this.map = this.make.tilemap({ key: 'map' });
const tileset = this.map.addTilesetImage('SuperMarioBros-World1-1');
const layer = this.map.createLayer('World1', tileset, 0, 0);
layer.setScale(2);

this.map.setCollision([ 14, 15, 16, 20, 21, 22, 23, 24, 25, 27, 28, 29, 33, 39, 40 ]);

Мы создаём графический объект debugGraphics, который будет использоваться для отрисовки отладочной информации поверх карты.

Отрисовка отладочной информации с помощью renderDebug

Сердце примера — метод drawDebug. Он очищает предыдущую отрисовку и вызывает this.map.renderDebug(), передавая ему стили для разных типов визуализации. Каждый стиль — это объект Phaser.Display.Color или null, если отрисовку этого элемента нужно отключить.

const tileColor = this.showTiles ? new Phaser.Display.Color(105, 210, 231, 200) : null;
const colldingTileColor = this.showCollidingTiles ? new Phaser.Display.Color(243, 134, 48, 200) : null;
const faceColor = this.showFaces ? new Phaser.Display.Color(40, 39, 37, 255) : null;

this.debugGraphics.clear();

this.map.renderDebug(this.debugGraphics, {
    tileColor: tileColor, // Цвет обычных (не сталкивающихся) тайлов
    collidingTileColor: colldingTileColor, // Цвет тайлов с коллизией
    faceColor: faceColor // Цвет «интересных» граней (краёв коллизии)
});

- tileColor: Подсвечивает контуры всех тайлов слоя. - collidingTileColor: Заливает тайлы, помеченные в setCollision, помогая убедиться, что нужные платформы и препятствия считаются твёрдыми. - faceColor: Рисует линии по краям (interesting faces) коллизионных тайлов. Это особенно полезно для понимания, где именно будет происходить соударение физического тела с препятствием.

Управление визуализацией «на лету»

Для удобства отладки реализовано переключение трёх режимов отрисовки с клавиатуры. Это позволяет изолированно смотреть на разные аспекты карты.

this.input.keyboard.on('keydown-ONE', event => {
    this.showTiles = !this.showTiles;
    this.drawDebug();
});

this.input.keyboard.on('keydown-TWO', event => {
    this.showCollidingTiles = !this.showCollidingTiles;
    this.drawDebug();
});

this.input.keyboard.on('keydown-THREE', event => {
    this.showFaces = !this.showFaces;
    this.drawDebug();
});

Состояние каждого флага выводится на экран через helpText. Метод getHelpMessage динамически формирует строку, отражающую текущие настройки. Текст зафиксирован на камере (setScrollFactor(0)), чтобы быть всегда видимым.

Движение камеры и финальная сборка

Чтобы исследовать большую карту, пример добавляет управление камерой с помощью Phaser.Cameras.Controls.FixedKeyControl. Камера привязывается к стрелкам клавиатуры.

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

В методе update каждый кадр вызывается this.controls.update(delta), обеспечивая плавное движение камеры. Конфигурация игры включает важный параметр pixelArt: true, который отключает сглаживание текстур, сохраняя чёткий пиксельный стиль.

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

Инструмент renderDebug — это ваш лучший помощник при отладке тайловых карт в Phaser. Он делает невидимые коллизии осязаемыми, мгновенно показывая, что именно движок считает препятствием. Для экспериментов попробуйте: изменить массив индексов в setCollision и понаблюдать за изменениями; создать разные слои с разными настройками коллизий и отлаживать их по отдельности; интегрировать эту визуализацию в редактор уровней для быстрой проверки дизайна.