Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Експорт для Інтернету¶

Дивись також

На цій сторінці описано, як експортувати проект Godot на HTML5. Якщо ви хочете замість цього скомпілювати редактор, або експортувати бінарні шаблони з джерела, прочитайте Compiling for the Web.

HTML5 export allows publishing games made in Godot Engine to the browser. This requires support for WebAssembly, WebGL and SharedArrayBuffer in the user's browser.

Увага

Projects written in C# using Godot 4 currently cannot be exported to the web. To use C# on web platforms, use Godot 3 instead.

Порада

Use the browser-integrated developer console, usually opened with F12 (Cmd + Option + I on macOS), to view debug information like JavaScript, engine, and WebGL errors.

Увага

Godot 4's HTML5 exports currently cannot run on macOS and iOS due to upstream bugs with SharedArrayBuffer and WebGL 2.0. We recommend using macOS and iOS native export functionality instead, as it will also result in better performance.

Godot 3's HTML5 exports are more compatible with various browsers in general, especially when using the GLES2 rendering backend (which only requires WebGL 1.0).

Версії WebGL¶

Godot 4.0 and later can only target WebGL 2.0 (using the Compatibility rendering method). There is no stable way to run Vulkan applications on the web yet.

See Can I use WebGL 2.0 for a list of browser versions supporting WebGL 2.0. Note that Safari has several issues with WebGL 2.0 support that other browsers don't have, so we recommend using a Chromium-based browser or Firefox if possible.

Параметри експортування¶

Якщо доступний робочий шаблон вебекспорту, у редакторі з’являється кнопка між кнопками Зупинити сцену та Відтворити відредаговану сцену, щоб швидко відкрити гру у браузері за замовчуванням для тестування.

If you plan to use VRAM compression make sure that Vram Texture Compression is enabled for the targeted platforms (enabling both For Desktop and For Mobile will result in a bigger, but more compatible export).

Якщо вказано шлях до файлу Custom HTML shell (користувацької оболонки HTML), то він буде використаний замість сторінки HTML за замовчуванням. Дивіться Custom HTML page for Web export.

Head Include додається до елемента <head> згенерованої HTML-сторінки. Це дозволяє, наприклад, завантажувати вебшрифти та сторонні JavaScript API, включати CSS, або запускати код JavaScript.

Важливо

Кожен проєкт повинен генерувати власний HTML-файл. При експорті декілька текстових заповнювачів замінюються у згенерованому файлі HTML спеціально для заданих параметрів експорту. Будь-які прямі зміни до цього файлу HTML будуть втрачені в майбутньому експорті. Щоб налаштувати згенерований файл, скористайтесь опцією Custom HTML shell (Користувацька оболонка HTML).

Обмеження¶

З міркувань безпеки та конфіденційності багато функцій, які без особливих зусиль працюють на власних платформах, на вебплатформі складніші. Далі наведено список обмежень, про які слід пам’ятати, при переносі гру Godot в Інтернет.

Важливо

Постачальники браузерів роблять все більше функціональних можливостей доступними лише в захищеному контексті, це означає, що такі функції доступні лише в тому випадку, якщо вебсторінка обслуговується через захищене з'єднання HTTPS (localhost зазвичай звільняється від такої вимоги).

Використання файлів cookie для збереження даних¶

Користувачі повинні дозволити файли cookie (зокрема IndexedDB), якщо бажаний доступ до файлу user://. Під час гри, в iframe, сторонні файли cookie також повинні бути включені. Режим перегляду інкогніто/приват також запобігає постійності.

Метод OS.is_userfs_persistent() для перевірки постійності файлової системи user://, але в деяких випадках може давати помилкові спрацьовування.

Фонова обробка¶

Проект буде призупинено браузером, коли вкладка більше не є активною вкладкою в браузері користувача. Це означає, що такі функції, як _process() і _physics_process() більше не будуть працювати, поки вкладка не буде знову активованою користувачем (коли він переключиться назад). Це може призвести до відключення мережевих ігор, якщо користувач перемикає вкладки протягом тривалого часу.

Це обмеження не застосовується до нефокусованих вікон браузера. Тому з боку користувача це можна опрацювати, запустивши проект в окремому вікні замість окремої вкладки.

Повний екран та захват мишки¶

Браузери не дозволяють довільно входити в повноекранний режим. Те саме стосується захоплення курсору. Натомість ці дії повинні відбуватися як відповідь на подію введення JavaScript. У Godot, перехід в повноекранний режим відбувається внаслідок натискання вхідної події зворотного виклику, такої як _input або _unhandled_input. Запиту синглтона Input недостатньо, відповідна подія введення має бути активною.

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

Аудіо¶

Some browsers restrict autoplay for audio on websites. The easiest way around this limitation is to request the player to click, tap or press a key/button to enable audio, for instance when displaying a splash screen at the start of your game.

Дивись також

Google пропонує додаткову інформацію про їх `політику автоматичного відтворення Web Audio<https://sites.google.com/a/chromium.org/dev/audio-video/autoplay>`__.

Apple's Safari team also posted additional information about their Auto-Play Policy Changes for macOS.

Попередження

Доступ до мікрофона вимагає захищеного контексту.

Робота у мережі¶

Мережі низького рівня не реалізовані через відсутність підтримки у браузерах.

В даний час підтримуються лише HTTP клієнт, HTTP запити, WebSocket (клієнт) і WebRTC.

Класи HTTP також мають кілька обмежень щодо платформи HTML5:

Доступ або зміна StreamPeer неможлива

Потоковий/Блокуючий режими не доступні

Неможливі зміни більше одного разу за кадр, тому опитування в циклі зависне

Немає фрагментованих відповідей

Перевірку хосту не можна вимкнути

Підпорядковується `політиці того самого походження<https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy>`__

Буфер обміну¶

Синхронізація буфера обміну між движком та операційною системою вимагає браузера, що підтримує `API буфера обміну<https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API>`__, крім того, через асинхронний характер API може бути ненадійним при доступі з GDScript.

Попередження

Потрібен захищений контекст.

Геймпади¶

Геймпади не будуть виявлені, доки не буде натиснута одна з їхніх кнопок. Геймпади можуть мати неправильне відображення залежно від комбінації браузера/ОС/геймпада, на жаль `API Gamepad<https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API>`__ не забезпечує надійного способу виявлення інформації про геймпад, необхідної для їх повторного призначення на основі моделі/постачальника/ОС через міркування конфіденційності.

Попередження

Потрібен захищений контекст.

Заставка завантаження не відображається¶

Сторінка HTML за замовчуванням не відображає заставку завантаження під час завантаження. Однак зображення експортується як файл PNG, тому користувацькі HTML-сторінки можуть відображати його.

Обслуговування файлів¶

Експорт для Інтернету генерує декілька файлів, що подаються з вебсервера, включаючи сторінку HTML за замовчуванням для презентації. Можна використовувати власний HTML-файл, дивіться Custom HTML page for Web export.

Попередження

To ensure low audio latency and the ability to use Thread in web exports, Godot 4 web exports always use SharedArrayBuffer. This requires a secure context, while also requiring the following CORS headers to be set when serving the files:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

If you don't control the web server or are unable to add response headers, use coi-serviceworker as a workaround.

If the client doesn't receive the required response headers, the project will not run.

The generated .html file can be used as DirectoryIndex in Apache servers and can be renamed to e.g. index.html at any time. Its name is never depended on by default.

The HTML page draws the game at maximum size within the browser window. This way, it can be inserted into an <iframe> with the game's size, as is common on most web game hosting sites.

Інші експортовані файли подаються такими, якими вони є, поруч із файлом .html, без зміни назв. Файл .wasm представляє собою двійковий модуль WebAssembly реалізації движка. Файл .pck є основним пакетом Godot, що містить вашу гру. Файл .js містить стартовий код і використовується файлом .html для доступу до движка. Файл .png містить заставку завантаження. Він не використовується на HTML-сторінці за замовчуванням, але включений для користувацьких сторінок HTML.

Файл .pck є бінарним, і, як правило , поставляється з MIME-типом application/octet-stream. Файл .wasm поставляється в вигляді application/wasm.

Попередження

Постачання модуля WebAssembly (.wasm) з MIME-типом відмінним від application/wasm може запобігти деякій оптимізації запуску.

Delivering the files with server-side compression is recommended especially for the .pck and .wasm files, which are usually large in size. The WebAssembly module compresses particularly well, down to around a quarter of its original size with gzip compression. Consider using Brotli precompression if supported on your web server for further file size savings.

Хости, що забезпечують швидке стискання: GitHub Pages (gzip)

Хости, які не забезпечують швидке стискання: itch.io, GitLab Pages (`підтримує ручне попереднє стиснення<https://webd97.de/post/gitlab-pages-compression/>`__)

Порада

The Godot repository includes a Python script to host a local web server. This script is intended for testing the web editor, but it can also be used to test exported projects.

Save the linked script to a file called serve.py, move this file to the folder containing the exported project's index.html, then run the following command in a command prompt within the same folder:

# You may need to replace `python` with `python3` on some platforms.
python serve.py --root .

On Windows, you can open a command prompt in the current folder by holding Shift and right-clicking on empty space in Windows Explorer, then choosing Open PowerShell window here.

This will serve the contents of the current folder and open the default web browser automatically.

Note that for production use cases, this Python-based web server should not be used. Instead, you should use an established web server such as Apache or nginx.

Виклик JavaScript із скрипта¶

In web builds, the JavaScriptBridge singleton is implemented. It offers a single method called eval that works similarly to the JavaScript function of the same name. It takes a string as an argument and executes it as JavaScript code. This allows interacting with the browser in ways not possible with script languages integrated into Godot.

func my_func():
    JavaScriptBridge.eval("alert('Calling JavaScript per GDScript!');")

private void MyFunc()
{
    JavaScriptBridge.Eval("alert('Calling JavaScript per C#!');")
}

Значення останнього оператора JavaScript перетворюється у значення GDScript і повертається eval() за певних обставин:

JavaScript number is returned as float

JavaScript boolean is returned as bool

JavaScript string is returned as String

JavaScript ArrayBuffer, TypedArray and DataView are returned as PackedByteArray

func my_func2():
    var js_return = JavaScriptBridge.eval("var myNumber = 1; myNumber + 2;")
    print(js_return) # prints '3.0'

private void MyFunc2()
{
    var jsReturn = JavaScriptBridge.Eval("var myNumber = 1; myNumber + 2;");
    GD.Print(jsReturn); // prints '3.0'
}

Будь-яке інше значення JavaScript повертається як null.

HTML5 export templates may be built without support for the singleton to improve security. With such templates, and on platforms other than HTML5, calling JavaScriptBridge.eval will also return null. The availability of the singleton can be checked with the web feature tag:

func my_func3():
    if OS.has_feature('web'):
        JavaScriptBridge.eval("""
            console.log('The JavaScriptBridge singleton is available')
        """)
    else:
        print("The JavaScriptBridge singleton is NOT available")

private void MyFunc3()
{
    if (OS.HasFeature("web"))
    {
        JavaScriptBridge.Eval("console.log('The JavaScriptBridge singleton is available')");
    }
    else
    {
        GD.Print("The JavaScriptBridge singleton is NOT available");
    }
}

Порада

Багаторядні рядки GDScript, оточені 3 лапками, """ як зазначено вище в my_func3(), корисні для збереження коду JavaScript читабельним.

The eval method also accepts a second, optional Boolean argument, which specifies whether to execute the code in the global execution context, defaulting to false to prevent polluting the global namespace:

func my_func4():
    # execute in global execution context,
    # thus adding a new JavaScript global variable `SomeGlobal`
    JavaScriptBridge.eval("var SomeGlobal = {};", true)

private void MyFunc4()
{
    // execute in global execution context,
    // thus adding a new JavaScript global variable `SomeGlobal`
    JavaScriptBridge.Eval("var SomeGlobal = {};", true);
}

Змінні середовища¶

You can use the following environment variables to set export options outside of the editor. During the export process, these override the values that you set in the export menu.

HTML5 export environment variables¶
Export option	Environment variable
Encryption / Encryption Key	`GODOT_SCRIPT_ENCRYPTION_KEY`