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

Стандартный курсор мыши — это скучно. В играх, особенно с определённой стилистикой, он может выбиваться из общего визуального ряда и снижать погружение. Phaser 3 предоставляет простой и эффективный API для замены курсора как для всего игрового поля, так и для отдельных интерактивных объектов. В этой статье мы разберём, как загрузить и назначить собственные изображения для курсора, превратив обычный указатель в часть игрового интерфейса.

Версия 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('box', 'assets/sprites/block.png');
    }

    create ()
    {
        this.input.setDefaultCursor('url(assets/input/cursors/vigyori/arrow.cur), pointer');

        //  Create some custom cursor boxes

        this.add.sprite(100, 300, 'box').setInteractive({ cursor: 'url(assets/input/cursors/vigyori/link.cur), pointer' });
        this.add.sprite(300, 300, 'box').setInteractive({ cursor: 'url(assets/input/cursors/vigyori/cross.cur), pointer' });
        this.add.sprite(500, 300, 'box').setInteractive({ cursor: 'url(assets/input/cursors/vigyori/help.cur), pointer' });
        this.add.sprite(700, 300, 'box').setInteractive({ cursor: 'url(assets/input/cursors/vigyori/no.cur), pointer' });
    }
}

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

const game = new Phaser.Game(config);

Установка курсора по умолчанию

Чтобы изменить вид курсора для всей сцены, используется метод setDefaultCursor() объекта this.input. Этот метод принимает строку в формате CSS-свойства cursor. Внутри строки указывается путь к файлу курсора и резервное значение на случай, если файл не загрузится.

this.input.setDefaultCursor('url(assets/input/cursors/vigyori/arrow.cur), pointer');

В этом примере игра попытается использовать пользовательский курсор из файла arrow.cur. Если по какой-то причине (например, неправильный путь или формат) загрузка не удастся, браузер автоматически откатится к стандартному курсору pointer (рука с указующим пальцем). Это важная практика для обеспечения отказоустойчивости.

Назначение курсора для отдельных объектов

Часто требуется, чтобы курсор менялся только при наведении на конкретные интерактивные элементы, например, на кнопки или предметы. Для этого в Phaser используется опция cursor при установке интерактивности через метод setInteractive().

this.add.sprite(100, 300, 'box').setInteractive({ cursor: 'url(assets/input/cursors/vigyori/link.cur), pointer' });

Здесь мы создаём спрайт и сразу делаем его интерактивным. При наведении курсора на этот спрайт он сменится на указанный в опции. Как и в случае с курсором по умолчанию, здесь также указано резервное значение pointer. Этот подход позволяет создавать разнообразную интерактивную среду: один курсор для кликабельных предметов, другой — для запрещённых действий, третий — для справки.

Подготовка и загрузка ассетов

Phaser не имеет встроенного менеджера для курсоров как отдельного типа ассетов. Файлы курсоров загружаются браузером в момент первого использования CSS-правилом url(). Поэтому критически важно, чтобы путь к файлу был корректным и файл был доступен.

this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
this.load.image('box', 'assets/sprites/block.png');

В примере задаётся базовый URL для загрузки. Обратите внимание, что сам файл курсора (например, link.cur) не загружается через this.load. Браузер запросит его самостоятельно, когда будет применять CSS-правило. Убедитесь, что ваш веб-сервер корректно отдаёт файлы с расширением .cur (или .png, если используете растровые изображения) и с правильными CORS-заголовками, если ресурсы лежат на другом домене.

Форматы файлов и ограничения

Работа с кастомными курсорами — это, по сути, работа с нативным CSS. Поэтому действуют все стандартные браузерные ограничения.

* **Форматы:** Наиболее широкую поддержку имеют статические файлы .cur (специфичный для Windows) и .png. Для анимированных курсоров можно использовать .ani или анимированный .gif, но поддержка этих форматов сильно варьируется от браузера к браузеру. * **Размер:** Стандарт CSS ограничивает размер курсора. Обычно безопасный максимум — 32x32 или 64x64 пикселя, в зависимости от браузера и ОС. Более крупные изображения могут быть проигнорированы или обрезаны. * **Точка привязки (hotspot):** В файле .cur можно задать точку привязки (координаты, которые соответствуют фактическому положению клика). В растровых форматах типа .png точкой привязки по умолчанию является левый верхний угол (0,0). Изменить её средствами CSS или Phaser нельзя — это задаётся при создании файла курсора.

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

Кастомизация курсора — это небольшой, но мощный штрих, который повышает полировку и уникальность вашей игры. Вы можете задать общую стилистику через курсор по умолчанию и добавлять контекстные подсказки через курсоры для отдельных объектов (меч для атаки, гаечный ключ для ремонта). Для экспериментов попробуйте создать набор тематических курсоров в графическом редакторе, использовать простую анимацию (смена двух кадров) или динамически менять курсор в зависимости от состояния игрока (например, прицел при взятии оружия).