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

В разработке игр загрузка ресурсов — критически важный этап. Но что, если файл изображения или аудио не найден на сервере? Жесткий сбой? К счастью, Phaser предоставляет гибкий механизм обработки таких ошибок. Эта статья покажет, как движок ведет себя при 404 ошибках, почему это полезно для отладки и как можно построить отказоустойчивую систему загрузки, чтобы игра не падала из-за одного отсутствующего спрайта.

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

Живой запуск

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

Исходный код


class Example extends Phaser.Scene
{
    preload ()
    {
        this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
        //  The URLs are incorrect on purpose to test 404 handling
        this.load.image('taikodrummaster', 'assets/tribbles/taikodrummaster.jpg');
        this.load.image('sukasuka-chtholly', 'assets/tribbles/sukasuka-chtholly.png');
    }

    create ()
    {
        this.add.image(400, 300, 'taikodrummaster');
        this.add.image(400, 500, 'sukasuka-chtholly');

        this.add.text(10, 10, 'Load complete, both files 404d', { font: '16px Courier', fill: '#00ff00' });
    }
}

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

const game = new Phaser.Game(config);

Суть примера: преднамеренные ошибки

В представленном примере демонстрируется ключевое поведение Phaser Loader. Автор сознательно задает неверные URL-адреса для загружаемых изображений. Это позволяет наглядно увидеть, как движок реагирует на HTTP-статус 404 (Not Found) и продолжает работу.

this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
//  The URLs are incorrect on purpose to test 404 handling
this.load.image('taikodrummaster', 'assets/tribbles/taikodrummaster.jpg');
this.load.image('sukasuka-chtholly', 'assets/tribbles/sukasuka-chtholly.png');

Метод setBaseURL устанавливает базовый путь для всех последующих загрузок. Ключевой момент: пути к файлам (assets/tribbles/...) не существуют в указанном репозитории, что гарантированно приводит к ошибкам загрузки.

Поведение загрузчика (Loader)

Когда Phaser Loader пытается загрузить ресурс и получает в ответ ошибку 404, он не останавливает весь процесс загрузки и не крашит игру. Вместо этого он помечает этот конкретный ассет как не загруженный, но продолжает обработку очереди.

Важно понимать, что событие 'complete' для сцены (create) все равно будет вызвано после попытки загрузки всех файлов из очереди preload, независимо от их успешности. Это позволяет сцене инициализироваться и перехватить управление, даже если часть ресурсов отсутствует.

Создание сцены с "битыми" текстурами

В методе create происходит попытка отобразить изображения по их ключам, которые были зарегистрированы в preload.

this.add.image(400, 300, 'taikodrummaster');
this.add.image(400, 500, 'sukasuka-chtholly');

Поскольку загрузка не удалась, в кеше текстур (this.textures) нет данных для ключей 'taikodrummaster' и 'sukasuka-chtholly'. В таком случае Phaser создает и использует специальную текстуру-заглушку — небольшое изображение, которое явно указывает на проблему (часто это шахматная доска или пиксель определенного цвета). Игровой объект (Image) будет создан, но отрисуется этой заглушкой.

this.add.text(10, 10, 'Load complete, both files 404d', { font: '16px Courier', fill: '#00ff00' });

Текст на сцене подтверждает, что жизненный цикл сцены (preload -> create) завершился, несмотря на ошибки.

Практическая польза и отладка

Такое поведение невероятно полезно на этапе разработки и прототипирования.

1. **Быстрая итерация:** Вы можете начать писать логику игры, используя временные или даже несуществующие ключи текстур, а позже заменить их настоящими ассетами. Игра не будет падать на этапе загрузки. 2. **Визуальная индикация ошибок:** Заглушка мгновенно показывает, какой спрайт или изображение не загрузилось, что ускоряет отладку. 3. **Отказоустойчивость:** В продакшене это позволяет игре запуститься и, например, показать пользователю сообщение об ошибке, даже если какой-то второстепенный ресурс на CDN недоступен.

Для более тонкого контроля за процессом загрузки используйте события Loader'а, такие как 'filecomplete', 'loaderror' и 'complete'.

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

Phaser по умолчанию обрабатывает ошибки загрузки ресурсов максимально мягко, позволяя игре продолжить выполнение. Это дизайнерское решение ускоряет разработку и повышает отказоустойчивость. Для экспериментов попробуйте: добавить обработчик события 'loaderror', чтобы логировать проблемные URL; реализовать систему повторных попыток загрузки для критически важных ассетов; или создать кастомную, более информативную текстуру-заглушку для своего проекта.