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

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

Поки OpenGL ES 3 не буде видалено з Godot на користь Vulkan, експорт HTML5 буде використовувати WebGL 2 при вибраному параметрі GLES3.

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

Використовувати WebGL 2 не рекомендується через очікуване видалення з Godot без заміни.

WebGL 2 підтримується не всіма браузерами. Firefox і Chromium (Chrome, Opera) найпопулярніші браузери, що підтримують його, натомість Safari та Edge не працюють з ним. На iOS, всі браузери засновані на WebKit (тобто Safari), тому вони теж не працюють з WebGL 2.

Рендер Godot WebGL 2 має проблеми з 3D і більше не підтримується.

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

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

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

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

  • Threads (Потоковий): вимагає від браузера підтримки 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).

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

Типи експорту, всі, крім 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)