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

Експорт 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 version

Depending on your choice of renderer, Godot can target WebGL 1.0 (GLES2) or WebGL 2.0 (GLES3).

WebGL 1.0 is the recommended option if you want your project to be supported on all browsers with the best performance.

Godot's GLES3 renderer targets high end devices, and the performance using WebGL 2.0 can be subpar. Some features are also not supported in WebGL 2.0 specifically.

Additionally, while most browsers support WebGL 2.0, this is not yet the case for Safari. WebGL 2.0 support is coming in Safari 15 for macOS, and is not available yet for any iOS browser (all WebKit-based like Safari). See Can I use WebGL 2.0 for details.

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

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

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

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

  • Threads: will require the browser to support SharedArrayBuffer. See Can I use SharedArrayBuffer for details.

  • 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).

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

Типи експорту, всі, крім Regular, ще не підтримуються версією C#.

Обмеження

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

Важливо

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

Порада

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

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

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

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

Потоки

Як зазначалося вище, багатопоточність доступна лише в тому випадку, якщо встановлено відповідний 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 export templates may be built without support for the singleton to improve security. With such templates, and on platforms other than HTML5, calling JavaScript.eval will also return null. The availability of the singleton can be checked with the JavaScript feature tag:

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)