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

Дивись також

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

Експорт HTML5 дозволяє публікувати ігри, зроблені в Godot Engine, в браузері. Для цього потрібна підтримка WebAssembly і WebGL в браузері користувача.

Важливо

Використовуйте інтегровану у браузер консоль розробника, яку зазвичай відкривають з допомогою F12, щоб переглянути інформацію налагодження, таку як помилки JavaScript, редактора і WebGL.

Увага

Трапляється багато помилок при запуску проєктів HTML5 на iOS <https://github.com/godotengine/godot/issues?q=is:issue+is:open+label:platform:html5+ios>`__ (незалежно від браузера). Ми рекомендуємо використовувати рідну функцію експорту iOS, оскільки це також призведе до кращої продуктивності.

Версії WebGL

Залежно від вашого вибору рендерера, Godot може орієнтуватися наWebGL 1.0 (GLES2), або WebGL 2.0 (GLES3).

WebGL 1.0 є рекомендованим варіантом, якщо ви хочете, щоб ваш проект підтримувався у всіх браузерах з найкращою продуктивністю.

Рендерер GLES3 в Godot орієнтований на високоякісні пристрої, а продуктивність за допомогою WebGL 2.0 може бути нижчою. Деякі функції також не підтримуються конкретно в WebGL 2.0.

Крім того, хоча більшість браузерів підтримують WebGL 2.0, це ще не стосується Safari. Підтримка WebGL 2.0 поставляється в Safari 15 для macOS, і поки не доступна для будь-якого браузера iOS (все на основі WebKit, як Safari). Докладніше про це в Чи можу я використовувати WebGL 2.0.

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

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

Ви можете вибрати Тип експорту, щоб вибрати, які функції будуть доступні:

  • Regular (Звичайний): є найбільш сумісним із браузерами, не підтримує потоки, а також GDNative.

  • Threads (Потоковий): вимагає від браузера підтримки SharedArrayBuffer. Дивіться Чи можу я використовувати SharedArrayBuffer.

  • GDNative: включає підтримку GDNative, але робить двійковий файл більшим і повільнішим для завантаження.

Якщо ви плануєте використовувати стиснення VRAM, переконайтеся, що Vram Texture Compression увімкнено для цільових платформ (увімкнення For Desktop (для настільних) і For Mobile (для мобільних) призведе до більшого, але більш сумісного експорту).

Якщо вказано шлях до файлу 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).

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

Export types other than Regular are not yet supported by the C# version.

Обмеження

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

Важливо

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

Порада

Перевірте список відкритих проблем HTML5 на GitHub, щоб побачити, чи є серед них виявлена вами проблема. Якщо нема, відкрийте таку, щоб повідомити про свій інтерес.

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

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

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

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

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

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

Потоки

Як зазначалося вище, багатопоточність доступна лише в тому випадку, якщо встановлено відповідний Export Type (тип експорту) і підтримка його в браузерах все ще обмежена.

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

Потрібен захищений контекст. Браузери також починають вимагати, щоб вебсторінка обслуговувалась специфічними `заголовками ізоляції перехресного походження<https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy>`__.

GDNative

Як зазначалося вище, GDNative доступний лише за умови встановлення відповідного Export Type (типу експорту).

Експорт також скопіює необхідні GDNative файли .wasm у вихідну папку (і їх потрібно завантажити на ваш сервер разом із грою).

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

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

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

Аудіо

Chrome обмежує спосіб відтворення вебсайтами аудіо. Можливо, гравцю буде потрібно клацнути, торкнутися або натиснути клавішу, щоб увімкнути звук.

Дивись також

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

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

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

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

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

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

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

Буфер обміну

Синхронізація буфера обміну між движком та операційною системою вимагає браузера, що підтримує `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-сторінки можуть відображати його.

Обмеження мови шейдерів

При експорті проєкту GLES2 у HTML5 буде використовуватися WebGL 1.0. WebGL 1.0 не підтримує динамічні цикли, тому шейдери, що використовують їх, там не працюватимуть.

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

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

Створений файл .html можна використовувати як DirectoryIndex на серверах Apache, і його можна перейменовувати, наприклад, index.html у будь-який час, за замовчуванням його назва незалежна.

Сторінка HTML малює гру на максимальному розмірі у вікні браузера. Таким чином його можна вставити в <iframe> розмір гри, як це поширено на більшості вебсайтів хостингу вебігор.

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

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

Застереження

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

Передача файлів із стисненням на стороні сервера рекомендується, особливо для файлів .pck і .wasm, які зазвичай мають великий розмір. Модуль WebAssembly стискає особливо добре, приблизно до чверті свого початкового розміру за допомогою стиснення gzip.

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

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

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

У вебзбірках реалізовано синглтон JavaScript. Він пропонує єдиний метод із назвою eval, який працює подібно до однойменної функції JavaScript. Він приймає рядок як аргумент і виконує його як код JavaScript. Це дозволяє скриптовим мовам інтегрованим в Godot взаємодіяти з браузером неможливими шляхами.

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

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

  • number JavaScript повертається як float GDScript

  • boolean JavaScript повертається як bool GDScript

  • string JavaScript повертається як String GDScript

  • JavaScript ArrayBuffer, TypedArray і DataView повертаються як PoolByteArray GDScript

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

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

Шаблони експорту HTML5 можуть бути побудовані без підтримки синглтонів для покращення безпеки. З такими шаблонами та на платформах, відмінних від HTML5, виклик JavaScript.eval буде також повертати null. Наявність синглтона можна перевірити за допомогою тега функції JavaScript:

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

Порада

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

Метод eval також приймає другий, додатковий аргумент Boolean, який визначає , чи слід виконати код в глобальному контексті виконання, за замовчуванням false , щоб запобігти забрудненню глобального простору імен:

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