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

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

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

Живой запуск

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

Исходный код


var config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    backgroundColor: '#2d2d2d',
    parent: 'phaser-example',
    scene: {
        preload: preload,
        create: create
    }
};

var game = new Phaser.Game(config);

function preload ()
{
        this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
    this.load.video('tokyo', 'assets/bugs/tokyo.mp4', true);
}

function create ()
{
    var vid = this.add.video(400, 300, 'tokyo');

    vid.play();
}

Настройка базовой конфигурации игры

Первым шагом всегда является создание конфигурационного объекта для экземпляра Phaser.Game. В нем мы определяем основные параметры, такие как размеры холста, цвет фона и привязку к элементу DOM. Ключевой момент — указание функций сцены в свойстве scene. В нашем примере используются только preload и create, что типично для простых демонстраций.

var config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    backgroundColor: '#2d2d2d',
    parent: 'phaser-example',
    scene: {
        preload: preload,
        create: create
    }
};

var game = new Phaser.Game(config);

После объявления конфигурации создается экземпляр игры new Phaser.Game(config). Это инициализирует игровой цикл и подготавливает систему к загрузке ресурсов.

Загрузка видеофайла в `preload`

Функция `preload` выполняется автоматически движком перед созданием сцены. Её предназначение — загрузка всех необходимых ресурсов (изображений, звуков, видео). Для работы с загрузчиком используется объект `this.load`. В примере выполняются две операции:
1.  Установка базового URL для всех загружаемых файлов с помощью `this.load.setBaseURL()`. Это удобно, если ваши ресурсы лежат в одной корневой директории.
2.  Непосредственная загрузка видеофайла методом `this.load.video()`.
function preload ()
{
    this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
    this.load.video('tokyo', 'assets/bugs/tokyo.mp4', true);
}

Метод load.video принимает три аргумента: - 'tokyo' — уникальный строковый ключ, по которому видео будет доступно в кэше. - 'assets/bugs/tokyo.mp4' — путь к файлу относительно базового URL. - true — необязательный флаг, указывающий, что видео должно загрузиться с поддержкой кросс-доменных запросов (CORS). Его установка важна для корректной работы при загрузке с других доменов.

Создание и воспроизведение видео в `create`

Как только все ресурсы загружены, Phaser вызывает функцию create. Здесь происходит построение сцены. Чтобы добавить видео на сцену, используется фабрика this.add.video(), которая создает и возвращает объект типа VideoGameObject.

function create ()
{
    var vid = this.add.video(400, 300, 'tokyo');
    vid.play();
}

Метод this.add.video() принимает следующие параметры: - 400 — координата X (по горизонтали) для центра видео на игровом холсте. - 300 — координата Y (по вертикали) для центра видео. - 'tokyo' — ключ видео, указанный при загрузке в preload.

Созданный объект vid сохраняется в переменную для дальнейшего управления. Чтобы запустить воспроизведение, сразу же вызывается его метод vid.play(). После этого видео начнет проигрываться на сцене в указанных координатах.

Важные нюансы и практические советы

Хотя пример минимален, в реальных проектах стоит учитывать несколько моментов:

- **Автовоспроизведение в браузерах**: Современные браузеры блокируют автовоспроизведение видео со звуком без предварительного взаимодействия пользователя с сайтом (клика, касания). Если ваше видео содержит звуковую дорожку, метод play() может быть отклонен с ошибкой. Решением может быть воспроизведение без звука по умолчанию или запуск видео по действию игрока. - **Управление объектом VideoGameObject**: Объект vid предоставляет множество методов для контроля: vid.pause(), vid.stop(), vid.setMute(), vid.setVolume(). Вы также можете изменять его свойства, как у любого игрового объекта: vid.setScale(), vid.setAlpha(), vid.setAngle(). - **Размер и отображение**: По умолчанию видео отображается в своем оригинальном разрешении. Вы можете задать собственный размер через vid.setDisplaySize(width, height). - **Базовый URL**: Использование setBaseURL в примере обусловлено тем, что ресурсы хранятся на GitHub. В вашем проекте, скорее всего, ресурсы будут локальными, и этот шаг может не потребоваться. Просто указывайте корректный относительный путь в load.video.

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

Как видно из примера, добавление видео в Phaser 3 — задача, решаемая буквально в несколько строк. Движок абстрагирует сложности работы с HTML5 Video, предоставляя чистый и понятный API. Для экспериментов попробуйте: 1. Изменить размер видео с помощью setDisplaySize и применить к нему физическое тело, чтобы создать «телевизор», падающий под действием гравитации. 2. Сделать видео интерактивным — приостанавливать и возобновлять воспроизведение по клику мыши. 3. Использовать видео в качестве текстуры для частиц или динамического фона меню. Этот базовый механизм служит надежным фундаментом для более сложных визуальных решений в ваших играх.