Пользовательская HTML-страница для Web-экспорта

Хотя шаблоны Web-экспорта предоставляют стандартную HTML-страницу, полностью подходящую для запуска проекта без дополнительной настройки, может быть полезно создать собственную HTML-страницу. Хотя самой игрой пока сложно управлять извне, такая страница позволяет настроить процесс инициализации движка.

Вот некоторые примеры использования, когда полезна настройка страницы по умолчанию:

Загрузка файлов из каталога, отличного от каталога страницы;
Загрузка файла .zip вместо файла .pck в качестве основного пакета;
Загрузка движка из каталога, отличного от основного файла пакета;
Добавление кнопки click-to-play ("кликни-и-воспроизведение"), позволяющей запускать игры в полноэкранном режиме;
Загрузка некоторых дополнительных файлов перед запуском движка, что делает их доступными в файловой системе проекта как можно скорее;
Передача пользовательских аргументов командной строки, например -s, для запуска скрипта MainLoop.

HTML-страница по умолчанию доступна в репозитории Godot Engine по адресу /misc/dist/html/full-size.html, но в качестве гораздо более простого примера можно использовать следующий шаблон:

<!DOCTYPE html>
<html>
    <head>
        <title>My Template</title>
        <meta charset="UTF-8">
    </head>
    <body>
        <canvas id="canvas"></canvas>
        <script src="$GODOT_URL"></script>
        <script>
            var engine = new Engine($GODOT_CONFIG);
            engine.startGame();
        </script>
    </body>
</html>

Настройка

Как показано в примере выше, это в основном обычный HTML-документ с несколькими заполнителями, которые необходимо заменить во время экспорта, HTML-элементом <canvas> и простым кодом JavaScript, который вызывает класс Engine().

Единственные необходимые заполнители:

$GODOT_URL: Имя основного файла JavaScript, который предоставляет класс Engine(), необходимый для запуска движка, и который должен быть включён в HTML как <script>. Имя генерируется из Пути экспорта в процессе экспорта.
$GODOT_CONFIG: объект JavaScript, содержащий параметры экспорта и который может быть переопределен позже. Полный список переопределений см. в EngineConfig.

Следующие необязательные заполнители позволят включить некоторые дополнительные функции в ваш HTML-шаблон.

$GODOT_PROJECT_NAME: Имя проекта, указанное в параметре Name в разделе Project Settings > Application > Config. Рекомендуется использовать его в качестве <title> в шаблоне.
$GODOT_HEAD_INCLUDE: Пользовательская строка для включения в HTML-документ непосредственно перед концом тега <head>. Она настраивается в опциях экспорта в разделе Html / Head Include. Хотя вы полностью контролируете создаваемую HTML-страницу, эта переменная может быть полезна для настройки частей HTML head элемента из редактора Godot Editor, например, для различных предварительных настроек веб-экспорта.
$GODOT_SPLASH: путь к изображению, используемому в качестве заставки загрузки, как определено в параметре Image в Project Settings > Application > Boot Splash.
$GODOT_SPLASH_COLOR Цвет фона экрана-заставки, определенный в параметре BG Color в Project Settings > Application > Boot Splash, преобразованный в шестнадцатеричный код цвета.
$GODOT_SPLASH_CLASSES: Этот плейсхолдер содержит строку имён настроек и их значений, влияющих на экран-заставку. Эта строка предназначена для использования в качестве набора имён CSS-классов, позволяющих стилизовать изображение-заставку на основе настроек проекта. Доступны следующие настройки из раздела Project Settings > Application > Boot Splash, представленные указанными ниже именами классов в зависимости от boolean значения параметра:
- Show Image: show-image--true, show-image--false
- Stretch Mode: fullsize--true (if not Disabled), fullsize--false
- Use Filter: use-filter--true, use-filter--false

Когда пользовательская страница будет готова, ее можно выбрать в параметрах экспорта в разделе Html / Custom Html Shell.

../../../_images/html5_export_options.png

Начало проекта

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

Полный список доступных методов и параметров см. в HTML5 shell class reference.

Сначала необходимо загрузить движок, затем его инициализировать, и только после этого проект можно запустить. Каждый из этих шагов можно выполнить вручную, обеспечивая полный контроль. Однако, в простейшем случае достаточно создать экземпляр класса Engine() с экспортированной конфигурацией, а затем вызвать метод engine.startGame, при необходимости переопределив параметры EngineConfig.

const engine = new Engine($GODOT_CONFIG);
engine.startGame({
    /* optional override configuration, eg. */
    // unloadAfterInit: false,
    // canvasResizePolicy: 0,
    // ...
});

Этот фрагмент кода автоматически загружает и инициализирует движок перед запуском игры. Он использует заданную конфигурацию для загрузки движка. Метод engine.startGame является асинхронным и возвращает Promise. Это позволяет управляющему коду отслеживать корректность загрузки игры, не блокируя выполнение и не полагаясь на опрос.

Если вашему проекту требуется особый контроль над стартовыми аргументами и файлами зависимостей, можно использовать метод engine.start. Обратите внимание, что этот метод не выполняет автоматическую предзагрузку файла pck, поэтому вам, вероятно, потребуется вручную загрузить его (и любой другой дополнительный файл) с помощью метода engine.preloadFile.

При желании вы также можете вручную выполнить engine.init для выполнения определенных действий после инициализации модуля, но до запуска движка.

Этот процесс немного сложнее, но он дает вам полный контроль над процессом запуска двигателя.

const myWasm = 'mygame.wasm';
const myPck = 'mygame.pck';
const engine = new Engine();
Promise.all([
    // Load and init the engine
    engine.init(myWasm),
    // And the pck concurrently
    engine.preloadFile(myPck),
]).then(() => {
    // Now start the engine.
    return engine.start({ args: ['--main-pack', myPck] });
}).then(() => {
    console.log('Engine has started!');
});

Для ручной загрузки движка необходимо вызвать статический метод Engine.load(). Поскольку этот метод статический, можно создать несколько экземпляров движка, если они используют один и тот же wasm.

Примечание

По умолчанию невозможно создать несколько экземпляров, так как движок сразу же выгружается после инициализации. Чтобы предотвратить это, используйте переопределение unloadAfterInit. После этого движок можно выгрузить вручную, вызвав статический метод Engine.unload(). Выгрузка движка освобождает память браузера, выгружая файлы, которые больше не нужны после инициализации экземпляра.

Настройка поведения

В Web-среде можно использовать несколько методов, чтобы гарантировать, что игра будет работать так, как задумано.

Если вы ориентируетесь на определённую версию WebGL или просто хотите проверить, доступен ли WebGL, вы можете вызвать метод Engine.isWebGLAvailable(). Он может принимать аргумент, позволяющий проверить наличие определённой основной версии WebGL.

Поскольку реальный исполняемый файл отсутствует в Web-среде, движок хранит только виртуальное имя файла, сформированное на основе базового имени загруженных файлов движка. Это значение влияет на результат метода OS.get_executable_path() и определяет имя автоматически запускаемого основного пакета. Для переопределения этого значения можно использовать параметр переопределения executable.

Настройка презентации

Для дальнейшей настройки внешнего вида и поведения игры на вашей странице можно использовать несколько параметров конфигурации.

По умолчанию для рендеринга используется первый элемент холста на странице. Чтобы использовать другой элемент холста, можно использовать переопределение canvas. Для этого требуется ссылка на сам элемент DOM.

const canvasElement = document.querySelector("#my-canvas-element");
engine.startGame({ canvas: canvasElement });

Способ изменения размера холста движком можно настроить с помощью параметра переопределения canvasResizePolicy.

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

function printProgress(current, total) {
    console.log("Loaded " + current + " of " + total + " bytes");
}
engine.startGame({ onProgress: printProgress });

Обратите внимание, что в некоторых случаях total может быть равен 0. Это означает, что его невозможно рассчитать.

Если ваша игра поддерживает несколько языков, можно использовать опцию переопределения locale для принудительного выбора определённой локали, при условии наличия корректной строки с кодом языка. Для определения предпочитаемых пользователем языков может быть полезно использовать серверную логику. В этом случае код языка можно получить из HTTP-заголовка Accept-Language или определить с помощью службы GeoIP.

Отладка

Для отладки экспортированных проектов может быть полезно читать стандартный вывод и потоки ошибок, генерируемые движком. Это похоже на вывод, отображаемый в окне консоли редактора. По умолчанию для вывода и потоков ошибок используются стандартные console.log и console.warn соответственно. Это поведение можно настроить, настроив собственные функции для обработки сообщений.

Используйте параметр переопределения onPrint, чтобы задать функцию обратного вызова для потока вывода, и параметр переопределения onPrintError, чтобы задать функцию обратного вызова для потока ошибок.

function print(text) {
    console.log(text);
}
function printError(text) {
    console.warn(text);
}
engine.startGame({ onPrint: print, onPrintError: printError });

При работе с выходными данными двигателя следует помнить, что их может быть нежелательно печатать в готовом изделии.