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

Управление с клавиатуры — фундамент большинства игр. Phaser предлагает несколько способов реагировать на действия игрока, от простых одноразовых событий до полноценных объектов `Key`. В этой статье разберем базовый пример, который поможет быстро добавить управление в ваш прототип, и объясним, когда стоит использовать тот или иной подход. Вы научитесь подписываться на события конкретных клавиш, обрабатывать все нажатия подряд и узнаете о методе `addCapture`, который может решить проблему "захвата" ввода браузером. Это полезно для создания быстрых демо, меню и простых механик.

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

Живой запуск

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

Исходный код


class Example extends Phaser.Scene
{
    create ()
    {

        //  Listen for a specific key (in this case the A key.)
        //  This works without creating a new Key object, and is especially useful for 'once' calls.
        //  For game input (i.e. player controls) you should use Key objects instead.

        this.input.keyboard.on('keydown-A', event =>
        {
            console.log('Hello from the A Key!');
        });

        this.input.keyboard.on(Phaser.Events, event =>
        {
            console.log(event.key);
        });

        this.input.keyboard.on('keydown-SPACE', event =>
        {
            console.log('Hello from the Space Bar!');
        });

        this.input.keyboard.addCapture('SPACE');
        this.add.text(10, 10, 'Press any button and see the console', {fontSize: '20px'});
    }
}

const config = {
    type: Phaser.CANVAS,
    parent: 'phaser-example',
    scene: Example
};

const game = new Phaser.Game(config);

Подписка на конкретную клавишу с `keydown-CODE`

Самый быстрый способ отреагировать на нажатие определенной клавиши — использовать именованные события вида keydown-CODE, где CODE — это код клавиши.

Phaser генерирует такие события автоматически. Этот подход идеален для разовых действий, например, для кнопки паузы, скриншота или активации чита в процессе отладки.

this.input.keyboard.on('keydown-A', event => {
    console.log('Hello from the A Key!');
});

В этом коде метод this.input.keyboard.on устанавливает слушатель события. При нажатии клавиши `Aв консоль выведется сообщение. Обратите внимание, что код клавиши указывается после дефиса и в верхнем регистре (A,SPACE,ENTER`).

Обработка всех событий клавиатуры

Если вам нужно логировать или обрабатывать нажатия всех клавиш, можно подписаться на глобальное событие Phaser.Events. Это событие срабатывает при любом действии на клавиатуре.

this.input.keyboard.on(Phaser.Events, event => {
    console.log(event.key);
});

Внутри функции-обработчика параметр event — это нативное браузерное событие KeyboardEvent. Свойство event.key содержит строковое представление нажатой клавиши (например, 'a', 'ArrowUp', ' '). Этот метод полезен для отладки или создания экранных клавиатур.

Захват ввода с помощью `addCapture`

В браузерах некоторые клавиши имеют стандартное поведение. Например, пробел (SPACE) часто прокручивает страницу вниз. Это может мешать игровому процессу.

Метод addCapture библиотеки Phaser предотвращает это поведение по умолчанию для указанных клавиш, "захватывая" событие в рамках игры.

this.input.keyboard.addCapture('SPACE');

this.input.keyboard.on('keydown-SPACE', event => {
    console.log('Hello from the Space Bar!');
});

В примере выше вызов addCapture('SPACE') отменяет прокрутку страницы при нажатии пробела. Теперь событие полностью обрабатывается вашим игровым кодом. Важно вызывать addCapture до того, как вы начнете слушать соответствующую клавишу.

Когда использовать `Key` объекты, а когда события

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

// Для разовых действий или прототипов подойдет:
this.input.keyboard.on('keydown-W', event => { /* двигаться вверх */ });

// Для постоянного игрового контроля лучше так:
this.cursors = this.input.keyboard.createCursorKeys();
// или
this.keyW = this.input.keyboard.addKey(Phaser.Input.Keyboard.KeyCodes.W);

Почему? Объекты Key имеют удобные свойства для проверки состояния (isDown, isUp), что идеально для непрерывного движения в игровом цикле update. События же (on) лучше подходят для дискретных, одноразовых действий (прыжок, выстрел, выбор в меню).

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

Обработка клавиатурного ввода в Phaser начинается с простых событий keydown-CODE, которые отлично подходят для прототипирования и простых действий. Используйте addCapture, чтобы отключить стандартное поведение браузера для таких клавиш, как пробел или стрелки. Для экспериментов попробуйте

  1. Создать простой демо-контроллер, который выводит в консоль код любой нажатой клавиши
  2. Сделать кнопку "перезапуска сцены" по нажатию `R`, используя событие
  3. Реализовать плавное движение персонажа с помощью createCursorKeys() в методе update и сравнить с обработкой через события