Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Спеціальна HTML-сторінка для веб-експорту

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

Деякі випадки використання, коли налаштування сторінки за замовчуванням є корисним, включають:

Завантаження файлів з каталогу, відмінного від сторінки;
Завантаження файлу .zip замість файлу .pck як основного пакета;
Завантаження механізму з каталогу, відмінного від основного файлу пакета;
Додавання кнопки для запуску ігор у повноекранному режимі;
Завантаження деяких додаткових файлів перед запуском двигуна, що робить їх доступними у файловій системі проекту якнайшвидше;
Передача спеціальних аргументів командного рядка, наприклад -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, наприклад. для різних попередніх налаштувань веб-експорту.
$GODOT_SPLASH: Шлях до зображення, яке використовується як завантажувальна заставка, як визначено в налаштуваннях Image у Налаштуваннях проекту > Програма > Завантажувальна заставка.
$GODOT_SPLASH_COLOR Колір фону екрану-заставки, як визначено в налаштуваннях BG Color у Project Settings > Application > Boot Splash, перетворений на шістнадцятковий код кольорів.
$GODOT_SPLASH_CLASSES: цей заповнювач надає рядок назв налаштувань та їх значень, які впливають на екран-заставку. Цей рядок призначений для використання як набору імен класів CSS, що дозволяє стилізувати заставку на основі налаштувань проекту заставки. Надаються такі параметри з Налаштування проекту > Програма > Завантажувальна програма, представлені назвами класів, показаними нижче, залежно від логічного значення параметра:
- Показати зображення: show-image--true, show-image--false
- Stretch Mode: fullsize--true (якщо не вимкнено), fullsize--false
- Використати фільтр: 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(). Розвантаження механізму звільняє пам’ять браузера шляхом вивантаження файлів, які більше не потрібні після ініціалізації екземпляра.

Налаштування поведінки

У веб-середовищі можна використовувати кілька методів, щоб гарантувати, що гра працюватиме належним чином.

Якщо ви націлюєтеся на певну версію WebGL або просто хочете перевірити, чи доступний WebGL взагалі, ви можете викликати метод Engine.isWebGLAvailable(). Він необов’язково приймає аргумент, який дозволяє перевірити конкретну основну версію WebGL.

Оскільки справжній виконуваний файл не існує в веб-середовищі, механізм зберігає лише віртуальне ім’я файлу, утворене з базового імені завантажених файлів механізму. Це значення впливає на вихід методу OS.get_executable_path() і визначає назву автоматично запущеного основного пакета. Параметр заміни executable можна використовувати для заміни цього значення.

Налаштування презентації

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

За замовчуванням для візуалізації використовується перший елемент canvas на сторінці. Щоб використовувати інший елемент canvas, можна використати параметр перевизначення 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 });

Майте на увазі, що в деяких випадках загальна може бути 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 });

Обробляючи вихідні дані двигуна, майте на увазі, що може бути небажаним друкувати їх у готовому продукті.