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...
Експорт для Інтернету
Дивись також
На цій сторінці описано, як експортувати проект Godot на HTML5. Якщо ви хочете замість цього скомпілювати редактор, або експортувати бінарні шаблони з джерела, прочитайте Компіляція для Інтернету.
Експорт HTML5 дозволяє публікувати ігри, створені на Godot Engine, у браузері. Для цього потрібна підтримка WebAssembly і WebGL 2.0 у браузері користувача.
Увага
Проекти, написані на C# з використанням Godot 4, наразі не можна експортувати в Інтернет. Перегляньте цю публікацію в блозі для отримання додаткової інформації.
Щоб використовувати C# на веб-платформах, замість цього використовуйте Godot 3.
Порада
Використовуйте інтегровану в браузер консоль розробника, яка зазвичай відкривається за допомогою F12 або Ctrl + Shift + I (Cmd + Option + I на macOS), щоб переглянути інформацію про налагодження, як-от помилки JavaScript, двигуна та WebGL.
Якщо ярлик не працює, це тому, що Godot фактично фіксує введення. Ви все ще можете відкрити консоль розробника, увійшовши в меню браузера.
Примітка
Через проблеми з безпекою SharedArrayBuffer через різноманітні експлойти, використання кількох потоків для веб-платформи має численні недоліки, включаючи потребу в спеціальних заголовках на стороні сервера та повну ізоляцію між джерелами (тобто відсутність реклами чи інтеграції сторонніх розробників на веб-сайті, на якому розміщена ваша гра).
Починаючи з Godot 4.3, Godot підтримує експорт вашої гри в одному потоці, що вирішує цю проблему. Хоча він має деякі недоліки сам по собі (він не може використовувати потоки та не такий продуктивний, як багатопотоковий експорт), він не вимагає стільки накладних витрат для встановлення. Він також загалом більш сумісний з магазинами, такими як itch.io або веб-видавцями, такими як Poki або CrazyGames. Однопотоковий експорт також дуже добре працює на macOS та iOS, де завжди виникали проблеми сумісності з експортом у кілька потоків.
З цих причин це найкращий і зараз стандартний спосіб експорту ваших ігор в Інтернеті.
Щоб отримати додаткові відомості, перегляньте цю публікацію в блозі про однопотоковий веб-експорт.
Дивись також
Перегляньте список відкритих проблем на GitHub, пов’язаних з веб-експортом, щоб переглянути список відомих помилок.
Ім'я файлу експорту
Ми пропонуємо користувачам експортувати свої веб-проекти з назвою файлу index.html. index.html зазвичай є файлом за умовчанням, який завантажується веб-серверами під час доступу до батьківського каталогу, зазвичай приховуючи назву цього файлу.
Увага
Експорт Godot 4 Web очікує, що деякі файли матимуть ті самі назви, що й ім’я, задане під час початкового експорту. Деякі проблеми можуть виникнути, якщо деякі експортовані файли перейменовано, зокрема основний файл HTML.
Версії WebGL
Godot 4 може працювати лише з WebGL 2.0 (використовуючи метод рендерингу сумісності). Forward+/Mobile не підтримуються на веб-платформі, оскільки ці методи рендерингу розроблені на основі сучасних низькорівневих графічних API. Godot наразі не підтримує WebGPU, що є необхідною умовою для роботи Forward+/Mobile на веб-платформі.
Перегляньте Чи можу я використовувати WebGL 2.0, щоб переглянути список версій браузера, що підтримують WebGL 2.0. Зауважте, що Safari має кілька проблем із підтримкою WebGL 2.0, яких немає в інших браузерах, тому ми рекомендуємо використовувати браузер на базі Chromium або Firefox, якщо це можливо.
Мобільні міркування
Веб-експорт може працювати на мобільних платформах із деякими застереженнями. У той час як нативний експорт Android і iOS завжди буде ефективнішим із значним відривом, веб-експорт дозволяє людям запускати ваш проект, не відвідуючи магазини програм.
Пам’ятайте, що під час роботи на мобільних пристроях продуктивність процесора та графічного процесора є високою. Це ще більш актуально під час запуску проекту, експортованого в Інтернет (оскільки це WebAssembly замість рідного коду). Перегляньте розділ Швидкодія документації, щоб отримати поради щодо оптимізації вашого проекту. Якщо ваш проект працює на платформах, відмінних від Web, ви можете використовувати Теги функцій, щоб застосувати параметри, орієнтовані на низький рівень під час запуску проекту, експортованого в Web.
Щоб пришвидшити час завантаження на мобільних пристроях, вам слід також compile an optimized export template з вимкненими невикористаними функціями. Залежно від функцій, які використовує ваш проект, це може значно зменшити розмір корисного навантаження WebAssembly, пришвидшивши його завантаження та ініціалізацію (навіть у кеш-пам’яті).
Відтворення аудіо
Починаючи з Godot 4.3, відтворення аудіо здійснюється за допомогою Web Audio API на веб-платформі. Цей режим відтворення Sample забезпечує низьку затримку, навіть якщо проект експортовано без підтримки потоку, але він має кілька обмежень:
AudioEffects не підтримуються.
Reverberation and doppler ефекти не підтримуються.
Процедурне створення аудіо не підтримується.
Позиційне аудіо може не завжди працювати належним чином залежно від властивостей вузла.
Щоб використовувати власну систему відтворення аудіо Godot на веб-платформі, ви можете змінити режим відтворення за замовчуванням за допомогою параметра проекту Audio > General > Default Playback Type.web або змінити властивість Playback Type на Stream на AudioStreamPlayer, AudioStreamPlayer2D або AudioStreamPlayer3D вузол. Це призводить до збільшення затримки (особливо, коли підтримку потоку вимкнено), але дозволяє працювати повному набору аудіофункцій Godot.
Параметри експортування
Якщо доступний робочий шаблон вебекспорту, у редакторі з’являється кнопка між кнопками Зупинити сцену та Відтворити відредаговану сцену, щоб швидко відкрити гру у браузері за замовчуванням для тестування.
Якщо ваш проєкт використовує GDExtension, необхідно ввімкнути Підтримку розширень.
Якщо ви плануєте використовувати VRAM compression, переконайтеся, що стиснення текстури VRAM увімкнено для цільових платформ (увімкнення для настільних комп’ютерів і для мобільних пристроїв призведе до більшого, але більш сумісного експорту).
Якщо вказано шлях до файлу користувацької HTML-оболонки, він буде використаний замість HTML-сторінки за замовчуванням. Див. Спеціальна HTML-сторінка для веб-експорту.
Head Include додається до елемента <head> згенерованої HTML-сторінки. Це дозволяє, наприклад, завантажувати вебшрифти та сторонні JavaScript API, включати CSS, або запускати код JavaScript.
Розмір вікна автоматично відповідатиме розміру вікна браузера за замовчуванням. Якщо ви хочете використовувати фіксований розмір незалежно від розміру вікна браузера, змініть Політику зміни розміру полотна на Немає. Це дозволить керувати розміром вікна за допомогою власного коду JavaScript в оболонці HTML. Ви також можете встановити значення Проєкт, щоб воно працювало ближче до нативного експорту, відповідно до project settings.
Важливо
Кожен проєкт має створювати власний HTML-файл. Під час експорту кілька текстових заповнювачів замінюються у згенерованому HTML-файлі спеціально для заданих параметрів експорту. Будь-які прямі зміни до цього HTML-файлу будуть втрачені під час майбутніх експортів. Щоб налаштувати згенерований файл, скористайтеся параметром Налаштування HTML-оболонки.
Підтримка потоків і розширень
Якщо Підтримка потоків увімкнено, експортований проект зможе make use of multithreading для підвищення продуктивності. Це також дозволяє відтворювати аудіо з низькою затримкою, коли для типу відтворення встановлено значення Потік (замість стандартного Зразка, який використовується в веб-експорті). Щоб увімкнути цю функцію, потрібно використовувати заголовки ізоляції між джерелами, які описано в розділі Обслуговування файлів нижче.
Якщо Підтримка розширень увімкнено, GDExtensions можна буде завантажити. Зверніть увагу, що для роботи веб-платформи GDExtensions все ще потрібно спеціально скомпільувати. Як і підтримка потоків, увімкнення цієї функції потребує використання ізольованих заголовків між джерелами.
Експорт як прогресивна веб-програма (PWA)
Якщо ввімкнено Progressive Web App > Enable, це матиме кілька наслідків:
Налаштуйте піктограми високої роздільної здатності, режим відображення та орієнтацію екрана. Вони налаштовуються в кінці розділу Progressive Web App у параметрах експорту. Ці параметри використовуються, якщо користувач додає проект на головний екран свого пристрою, що часто зустрічається на мобільних платформах. Це також підтримується на настільних платформах, хоча й у більш обмежених можливостях.
Дозволити завантажувати проект без підключення до Інтернету, якщо він був завантажений принаймні один раз. Це працює завдяки service worker, який встановлюється під час першого завантаження проекту в браузері користувача. Цей сервіс-воркер забезпечує локальний резервний варіант, коли немає підключення до Інтернету.
Зауважте, що веб-браузери можуть вибрати видалення кешованих даних, якщо користувачеві бракує місця на диску або якщо користувач деякий час не відкривав проект. Щоб дані зберігалися в кеш-пам’яті протягом тривалого часу, користувач може додати сторінку в закладки або, в ідеалі, додати її на головний екран свого пристрою.
Якщо офлайн-дані недоступні через те, що їх видалено з кешу, ви можете налаштувати Офлайн-сторінку, яка відображатиметься в цьому випадку. Сторінка має бути у форматі HTML і буде збережена на комп’ютері клієнта під час першого завантаження проекту.
Переконайтеся, що заголовки ізоляції між джерелами завжди присутні, навіть якщо веб-сервер не налаштовано для їх надсилання. Це дозволяє експорту з увімкненими потоками працювати, якщо розміщено на будь-якому веб-сайті, навіть якщо ви не можете контролювати заголовки, які він надсилає.
Цю поведінку можна вимкнути, знявши прапорець Увімкнути ізольовані заголовки між джерелами в розділі прогресивної веб-програми.
Обмеження
З міркувань безпеки та конфіденційності багато функцій, які без особливих зусиль працюють на власних платформах, на вебплатформі складніші. Далі наведено список обмежень, про які слід пам’ятати, при переносі гру Godot в Інтернет.
Важливо
Постачальники браузерів роблять все більше функціональних можливостей доступними лише в захищеному контексті, це означає, що такі функції доступні лише в тому випадку, якщо вебсторінка обслуговується через захищене з'єднання HTTPS (localhost зазвичай звільняється від такої вимоги).
Фонова обробка
Проект буде призупинено браузером, коли вкладка більше не є активною вкладкою в браузері користувача. Це означає, що такі функції, як _process() і _physics_process() більше не будуть працювати, поки вкладка не буде знову активованою користувачем (коли він переключиться назад). Це може призвести до відключення мережевих ігор, якщо користувач перемикає вкладки протягом тривалого часу.
Це обмеження не застосовується до нефокусованих вікон браузера. Тому з боку користувача це можна опрацювати, запустивши проект в окремому вікні замість окремої вкладки.
Повний екран та захват мишки
Браузери не дозволяють довільно входити в повноекранний режим. Те саме стосується захоплення курсору. Натомість ці дії повинні відбуватися як відповідь на подію введення JavaScript. У Godot, перехід в повноекранний режим відбувається внаслідок натискання вхідної події зворотного виклику, такої як _input або _unhandled_input. Запиту синглтона Input недостатньо, відповідна подія введення має бути активною.
З тієї ж причини налаштування проєкту на весь екран не працює, якщо движок не запускається з дійсного обробника вхідних подій. Це вимагає customization of the HTML page.
Аудіо
Деякі браузери обмежують автоматичне відтворення аудіо на веб-сайтах. Найпростіший спосіб обійти це обмеження — попросити гравця клацнути, торкнутися або натиснути клавішу/кнопку, щоб увімкнути аудіо, наприклад, коли відображається екран-заставка на початку вашої гри.
Дивись також
Google пропонує додаткову інформацію про свою політику автоматичного відтворення веб-аудіо. <https://www.chromium.org/audio-video/autoplay/>`__.
Команда Safari від Apple також опублікувала додаткову інформацію про свої Зміни в політиці автоматичного відтворення для macOS.
Попередження
Для доступу до мікрофона потрібен secure context.
Попередження
Починаючи з Godot 4.3, веб-експорт за замовчуванням використовуватиме семпли замість потоків для відтворення аудіо.
Це пов’язано з тим, як браузери віддають перевагу відтворенню аудіо, і недостатньою обчислювальною потужністю, доступною під час експорту веб-ігор із вимкненою опцією експорту Використовувати потоки.
Зауважте, що аудіоефекти ще не реалізовано для зразків.
Робота у мережі
Мережа низького рівня не реалізована через відсутність підтримки в браузерах.
Наразі підтримуються лише HTTP client, HTTP requests, WebSocket (client) та WebRTC.
Класи HTTP також мають кілька обмежень щодо платформи HTML5:
Доступ або зміна
StreamPeerнеможливаПотоковий/Блокуючий режими не доступні
Неможливі зміни більше одного разу за кадр, тому опитування в циклі зависне
Немає фрагментованих відповідей
Перевірку хосту не можна вимкнути
Підпорядковується політиці того самого походження
Буфер обміну
Синхронізація буфера обміну між движком та операційною системою вимагає браузера, що підтримує API буфера обміну, крім того, через асинхронний характер API може бути ненадійним при доступі з GDScript.
Попередження
Потрібен secure context.
Геймпади
Геймпади не будуть виявлені, доки не буде натиснута одна з їхніх кнопок. Геймпади можуть мати неправильне відображення залежно від комбінації браузера/ОС/геймпада, на жаль API Gamepad не забезпечує надійного способу виявлення інформації про геймпад, необхідної для їх повторного призначення на основі моделі/постачальника/ОС через міркування конфіденційності.
Попередження
Потрібен secure context.
Обслуговування файлів
Експорт для Інтернету генерує декілька файлів, що подаються з вебсервера, включаючи сторінку HTML за замовчуванням для презентації. Можна використовувати власний HTML-файл, дивіться Спеціальна HTML-сторінка для веб-експорту.
Попередження
Лише під час експорту за допомогою Використовувати потоки, щоб забезпечити низьку затримку аудіо та можливість використовувати class_Thread у веб-експорті, веб-експорт Godot 4 використовує SharedArrayBuffer. Для цього потрібен secure context, а також потрібно встановити наступні заголовки CORS під час обслуговування файлів:
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
Якщо ви не контролюєте веб-сервер або не можете додати заголовки відповідей, поставте прапорець Progressive Web App > Enable у параметрах експорту. Це застосовує обхідний шлях на основі Service Worker, який дозволяє запускати проект, імітуючи наявність цих заголовків відповіді. У цьому випадку все ще потрібен безпечний контекст.
Якщо клієнт не отримує необхідні заголовки відповіді або не застосовано обхідний шлях на основі Service Worker, проект не запускатиметься.
Згенерований файл .html можна використовувати як DirectoryIndex на серверах Apache і можна перейменувати, наприклад, на. index.html у будь-який час. Його назва ніколи не залежить від замовчуванням.
HTML-сторінка малює гру в максимальному розмірі у вікні браузера. Таким чином його можна вставити в <iframe> із розміром гри, як це зазвичай буває на більшості сайтів розміщення веб-ігор.
Інші експортовані файли подаються без змін, поруч із файлом .html. Файл .wasm — це бінарний модуль WebAssembly, який реалізує механізм. Файл .pck — це основний пакет Godot, який містить вашу гру. Файл .js містить код запуску та використовується файлом .html для доступу до системи. Файл .png містить початкове зображення завантаження.
Файл .pck є бінарним, і, як правило , поставляється з MIME-типом application/octet-stream. Файл .wasm поставляється в вигляді application/wasm.
Попередження
Постачання модуля WebAssembly (.wasm) з MIME-типом відмінним від application/wasm може запобігти деякій оптимізації запуску.
Рекомендується надсилати файли зі стисненням на стороні сервера, особливо для файлів .pck і .wasm, які зазвичай мають великий розмір. Модуль WebAssembly стискається особливо добре, приблизно до чверті початкового розміру за допомогою стиснення gzip. Розгляньте можливість використання попереднього стиснення Brotli, якщо воно підтримується на вашому веб-сервері, для додаткового заощадження розміру файлу.
Хости, що забезпечують швидке стискання: GitHub Pages (gzip)
Хости, що не забезпечують стиснення на льоту: itch.io, GitLab Pages (підтримує ручне попереднє стиснення gzip)
Порада
Репозиторій Godot містить «скрипт Python для розміщення локального веб-сервера <https://raw.githubusercontent.com/godotengine/godot/master/platform/web/serve.py>`__. Цей скрипт призначений для тестування веб-редактора, але його також можна використовувати для тестування експортованих проектів.
Збережіть пов’язаний скрипт у файл під назвою serve.py, перемістіть цей файл до папки, що містить index.html експортованого проекту, а потім виконайте таку команду в командному рядку в тій же папці:
# You may need to replace `python` with `python3` on some platforms.
python serve.py --root .
У Windows ви можете відкрити командний рядок у поточній папці, утримуючи Shift і клацнувши правою кнопкою миші порожнє місце в Провіднику Windows, а потім вибравши Відкрити тут вікно PowerShell.
Це призведе до обслуговування вмісту поточної папки та автоматичного відкриття веб-браузера за замовчуванням.
Зауважте, що для робочих випадків використання цього веб-сервера на основі Python не слід використовувати. Натомість вам слід використовувати встановлений веб-сервер, наприклад Apache або nginx.
Взаємодія з браузером і JavaScript
Перегляньте dedicated page про те, як взаємодіяти з JavaScript і отримати доступ до деяких унікальних функцій веб-браузера.
Змінні середовища
Ви можете використовувати такі змінні середовища, щоб налаштувати параметри експорту поза редактором. Під час процесу експорту вони замінюють значення, встановлені в меню експорту.
Варіант експорту |
Змінна середовища |
|---|---|
Шифрування / ключ шифрування |
|
Вирішення проблем
Під час локального експорту відображається інший проект
Якщо ви використовуєте розгортання одним клацанням у декількох проектах, ви можете помітити, що замість проекту, над яким ви зараз працюєте, відображається один із проектів, які ви розгорнули раніше. Це пов'язано з кешуванням сервісного працівника, якому наразі бракує механізму автоматичного очищення кешу.
Як тимчасове рішення, ви можете вручну скасувати реєстрацію поточного сервісного працівника, щоб скинути кеш. Це також дозволить зареєструвати нового сервісного працівника. У браузерах на базі Chromium відкрийте інструменти розробника, натиснувши F12 або Ctrl + Shift + I (Cmd + Option + I на macOS), а потім натисніть на вкладку «Додаток» в DevTools (вона може бути прихована за значком шеврона, якщо панель devtools вузька). Ви можете або встановити прапорець і перезавантажити сторінку, або натиснути поруч із сервісним працівником, який зараз зареєстрований, а потім перезавантажити сторінку.
Скасування реєстрації сервісного працівника в DevTools браузерів на базі Chromium
Процедура в Firefox аналогічна. Відкрийте інструменти розробника, натиснувши F12 або Ctrl + Shift + I (Cmd + Option + I в macOS), натисніть на вкладку «Додаток» в DevTools (вона може бути прихована за значком шеврона, якщо панель devtools вузька). Натисніть поруч із сервісним працівником, який наразі зареєстрований, а потім перезавантажте сторінку.
Скасування реєстрації сервісного працівника в DevTools Firefox
Параметри експортування
Повний список доступних опцій експорту можна знайти в довіднику класу EditorExportPlatformWeb.