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

Интеграция геймпадов — мощный способ повысить вовлечённость в игре. Однако отладка их работы может превратиться в угадайку: какой сигнал сейчас приходит и правильно ли он обрабатывается? В этой статье разберём готовый пример из официального репозитория Phaser, который выводит полный дамп состояния всех подключенных контроллеров прямо на игровой экран. Этот инструмент незаменим для настройки управления, калибровки осей и проверки корректности работы кнопок.

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

Живой запуск

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

Исходный код


class Example extends Phaser.Scene
{
    text;

    preload ()
    {
        this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
        this.load.image('sky', 'assets/skies/lightblue.png');
    }

    create ()
    {
        this.add.image(0, 0, 'sky').setOrigin(0);

        this.text = this.add.text(10, 30, '', { font: '16px Courier', fill: '#ffffff' });
    }

    update ()
    {
        if (this.input.gamepad.total === 0)
        {
            return;
        }

        const debug = [];
        const pads = this.input.gamepad.gamepads;

        // var pads = this.input.gamepad.getAll();
        // var pads = navigator.getGamepads();

        for (let i = 0; i < pads.length; i++)
        {
            const pad = pads[i];

            if (!pad)
            {
                continue;
            }

            //  Timestamp, index. ID
            debug.push(pad.id);
            debug.push(`Index: ${pad.index} Timestamp: ${pad.timestamp}`);

            //  Buttons

            let buttons = '';

            for (let b = 0; b < pad.buttons.length; b++)
            {
                const button = pad.buttons[b];

                buttons = buttons.concat(`B${button.index}: ${button.value}  `);

                // buttons = buttons.concat('B' + b + ': ' + button.value + '  ');

                if (b === 8)
                {
                    debug.push(buttons);
                    buttons = '';
                }
            }
            
            debug.push(buttons);

            //  Axis

            let axes = '';

            for (let a = 0; a < pad.axes.length; a++)
            {
                const axis = pad.axes[a];

                axes = axes.concat(`A${axis.index}: ${axis.getValue()}  `);

                // axes = axes.concat('A' + a + ': ' + axis + '  ');

                if (a === 1)
                {
                    debug.push(axes);
                    axes = '';
                }
            }
            
            debug.push(axes);
            debug.push('');
        }
        
        this.text.setText(debug);
    }
}

const config = {
    type: Phaser.WEBGL,
    parent: 'phaser-example',
    width: 800,
    height: 600,
    input: {
        gamepad: true
    },
    scene: Example
};

const game = new Phaser.Game(config);

Подготовка сцены и включение геймпадов

Всё начинается с базовой настройки. В методе preload загружается фон для визуального контекста.

Ключевой момент — конфигурация игры. Чтобы система ввода Phaser начала отслеживать геймпады, необходимо явно указать это в настройках input.

const config = {
    type: Phaser.WEBGL,
    parent: 'phaser-example',
    width: 800,
    height: 600,
    input: {
        gamepad: true // Включаем поддержку геймпадов
    },
    scene: Example
};

В методе create создаётся текстовый объект с моноширинным шрифтом. Он будет использоваться как консоль для вывода всех данных. Важно использовать шрифт вроде Courier, где все символы имеют одинаковую ширину, чтобы столбцы с данными выровнялись корректно.

create ()
{
    this.add.image(0, 0, 'sky').setOrigin(0);
    this.text = this.add.text(10, 30, '', { font: '16px Courier', fill: '#ffffff' });
}

Получение списка контроллеров в основном цикле

Логика сбора данных работает в методе update, который вызывается каждый кадр. Первым делом проверяется, подключён ли хотя бы один геймпад через свойство this.input.gamepad.total. Если нет — функция завершается, чтобы не тратить ресурсы.

if (this.input.gamepad.total === 0)
{
    return;
}

Для получения массива всех геймпадов в примере используется свойство this.input.gamepad.gamepads. Это обёртка Phaser над нативным API. В комментариях показаны альтернативные способы: метод this.input.gamepad.getAll() или прямой вызов navigator.getGamepads().

const pads = this.input.gamepad.gamepads;
// var pads = this.input.gamepad.getAll();
// var pads = navigator.getGamepads();

Цикл перебирает этот массив. Элемент может быть null (если слот для контроллера есть, но устройство отключено), поэтому выполняется проверка if (!pad).

Сбор информации: идентификатор, кнопки и оси

Для каждого активного геймпада собирается три блока данных, которые помещаются в массив debug.

1. **Идентификатор и метаданные:** Свойства id, index и timestamp предоставляются браузером и помогают определить модель контроллера и время последнего ввода.

debug.push(pad.id);
    debug.push(`Index: ${pad.index} Timestamp: ${pad.timestamp}`);

2. **Состояние кнопок:** Цикл проходит по массиву pad.buttons. Каждый элемент — объект с полями value (степень нажатия от 0 до 1) и index. Значение полезно для триггеров (R2/L2). Данные форматируются в строку, и для читаемости после каждых 9 кнопок (b === 8) делается перенос строки.

for (let b = 0; b < pad.buttons.length; b++)
    {
        const button = pad.buttons[b];
        buttons = buttons.concat(`B${button.index}: ${button.value}  `);
        if (b === 8)
        {
            debug.push(buttons);
            buttons = '';
        }
    }
    debug.push(buttons);

3. **Состояние осей (стиков, крестовины):** Аналогично обрабатывается массив pad.axes. Значение оси — число от -1 до 1. Для удобства чтения данные по двум основным осям (X и Y) выводятся на одной строке (a === 1).

for (let a = 0; a < pad.axes.length; a++)
    {
        const axis = pad.axes[a];
        axes = axes.concat(`A${axis.index}: ${axis.getValue()}  `);
        if (a === 1)
        {
            debug.push(axes);
            axes = '';
        }
    }
    debug.push(axes);

После сбора данных по всем контроллерам массив строк debug передаётся в метод setText нашего текстового объекта, и информация отображается на экране.

Практическое применение для разработки

Этот скрипт — больше чем пример. Его можно адаптировать под конкретные задачи разработки.

* **Поиск «мёртвых зон»:** Запустите пример и медленно отклоняйте стик. Наблюдайте за значениями осей A0 и A1. Если в центре значения не возвращаются к нулю или меняются скачками, это указывает на проблему, которую нужно компенсировать в коде калибровкой или мёртвой зоной. * **Определение индексов кнопок:** Нажимайте кнопки на контроллере и смотрите, какой индекс B0...B17 и значение value реагируют. Это нужно для корректной привязки действий в игре (if (pad.B12.value === 1) { player.jump(); }). * **Тестирование поддержки нескольких геймпадов:** Подключите два контроллера и убедитесь, что данные по ним выводятся в отдельных блоках с правильными индексами. Это основа для реализации мультиплеера на одном экране. Используйте этот код как отправную точку для создания собственного визуального инструмента отладки управления в вашем проекте.

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

Готовый пример предоставляет прямой и наглядный способ диагностики геймпадов в Phaser, избавляя от слепой работы с API. Для экспериментов попробуйте

  1. Добавить цветовое выдечение для нажатых кнопок (например, значение value > 0 выводить зелёным)
  2. Реализовать простой визуализатор осей в виде движущегося круга, который будет отклоняться в зависимости от значений A0 и A1
  3. Сохранять «снимок» состояния кнопок (какие были нажаты в момент события) для отладки сложных комбинаций