Экспорт в Web
См. также
На этой странице описано, как экспортировать проект Godot в HTML5. Если вы хотите скомпилировать редактор или экспортировать двоичные файлы шаблонов из исходного кода, см. Компиляция для Web-Браузера.
Экспорт в HTML5 позволяет публиковать игры, созданные на движке Godot, в браузере. Для этого требуется поддержка WebAssembly и WebGL 2.0 в браузере пользователя.
Внимание
Проекты, написанные на C# с использованием Godot 4, в настоящее время не могут быть экспортированы в веб. Подробнее см. в этой записи блога <https://godotengine.org/article/platform-state-in-csharp-for-godot-4-2/#web>`__.
Чтобы использовать 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 can only target WebGL 2.0 (using the Compatibility rendering method). Forward+/Mobile are not supported on the web platform, as these rendering methods are designed around modern low-level graphics APIs. Godot currently does not support WebGPU, which is a prerequisite for allowing Forward+/Mobile to run on the web platform.
Список версий браузеров, поддерживающих WebGL 2.0, см. в разделе Можно ли использовать WebGL 2.0. Обратите внимание, что в Safari есть несколько проблем с поддержкой WebGL 2.0, которых нет в других браузерах, поэтому мы рекомендуем по возможности использовать браузер на базе Chromium или Firefox.
Мобильные аспекты
Web-экспорт может работать на мобильных платформах с некоторыми оговорками. Хотя нативные экспорты для Android и iOS всегда будут работать значительно быстрее, Web-экспорт позволяет запускать ваш проект без необходимости обращаться в магазины приложений.
Помните, что производительность CPU и GPU критически важна при работе на мобильных устройствах. Это особенно актуально при запуске проекта, экспортированного в веб-версию (поскольку это WebAssembly, а не нативный код). Советы по оптимизации проекта см. в разделе Производительность документации. Если ваш проект работает на платформах, отличных от веб-версии, вы можете использовать Теги особенностей для применения настроек, ориентированных на низкий уровень производительности, при запуске проекта, экспортированного в веб-версию.
Чтобы ускорить загрузку на мобильных устройствах, также следует скомпилировать оптимизированный шаблон экспорта с отключенными неиспользуемыми функциями. В зависимости от функций, используемых в вашем проекте, это может значительно сократить размер полезной нагрузки WebAssembly, ускорив её загрузку и инициализацию (даже при кэшировании).
Воспроизведение аудио
Начиная с Godot 4.3, воспроизведение звука осуществляется через API Web Audio на веб-платформе. Этот Sample режим воспроизведения обеспечивает низкую задержку даже при экспорте проекта без поддержки потоков, но имеет ряд ограничений:
AudioEffects не поддерживается.
Эффекты reverberation и doppler не поддерживаются.
Процедурная генерация звука не поддерживается.
Позиционный звук может не всегда работать правильно в зависимости от свойств узла.
Чтобы использовать собственную систему воспроизведения звука Godot на веб-платформе, можно изменить режим воспроизведения по умолчанию в настройках проекта Audio > General > Default Playback Type.web или изменить свойство Playback Type на Stream в узле AudioStreamPlayer, AudioStreamPlayer2D или AudioStreamPlayer3D. Это приводит к увеличению задержки (особенно при отключенной поддержке потоков), но позволяет использовать весь набор аудиофункций Godot.
Опции экспорта
Если доступен работоспособный шаблон для экспорта, появляется кнопка между кнопками Остановка сцены и Запустить измененную сцену в редакторе чтобы быстро открыть игру в браузере по умолчанию для тестов.
Если ваш проект использует GDExtension, необходимо включить Extension Support.
Если вы планируете использовать сжатие VRAM, убедитесь, что VRAM Texture Compression включено для целевых платформ (включение For Desktop и For Mobile приведет к большему, но более совместимому экспорту).
Если дан путь для файла пользовательской HTML оболочки, он будет использован вместо стандартной HTML страницы. Смотрите Пользовательская HTML-страница для Web-экспорта.
Head Include соединена с элементом <head> созданной HTML страницы. Это позволяет, к примеру, загружать вебшрифты и сторонние JavaScript API, включать CSS, или использовать код Javascript.
Размер окна по умолчанию автоматически будет соответствовать размеру окна браузера. IЕсли вы хотите использовать фиксированный размер независимо от размера окна браузера, измените Canvas Resize Policy на None. Это позволяет управлять размером окна с помощью пользовательского кода JavaScript в HTML-оболочке. Вы также можете установить его в Project, чтобы он работал ближе к нативному экспорту, согласно project settings.
Важно
Каждый проект должен генерировать свой собственный HTML-файл. При экспорте в сгенерированном HTML-файле заменяется несколько текстовых заполнителей специально для заданных параметров экспорта. Любые прямые изменения в этом HTML-файле будут потеряны при последующем экспорте. Чтобы настроить сгенерированный файл, используйте опцию Custom HTML shell.
Поддержка потоков и расширений
Если включена Thread Support, экспортированный проект сможет использовать многопоточность для повышения производительности. Это также обеспечивает воспроизведение звука с малой задержкой, если выбран тип воспроизведения Stream (вместо Sample, используемого по умолчанию при экспорте в web). Для включения этой функции требуются заголовочные файлы кросс-источниковой изоляции, описанные в разделе Обслуживание файлов ниже.
Если включена Extensions Support, GDExtensions будет доступен для загрузки. Обратите внимание, что GDExtensions по-прежнему необходимо специально скомпилировать для работы веб-платформы. Как и для поддержки потоков, включение этой функции требует использования заголовочных файлов с кросс-источниковой изоляцией.
Экспорт в виде Прогрессивного Web-приложения (PWA)
Если включено Progressive Web App > Enable, это будет иметь несколько эффектов:
Настройте значки высокого разрешения, режим отображения и ориентацию экрана. Эти настройки находятся в конце раздела «Progressive Web App» в параметрах экспорта. Эти параметры используются, если пользователь добавляет проект на главный экран своего устройства, что часто встречается на мобильных платформах. Это также поддерживается на настольных платформах, хотя и с меньшими возможностями.
Разрешить загрузку проекта без подключения к Интернету, если он был загружен хотя бы один раз. Это работает благодаря service worker, который устанавливается при первой загрузке проекта в браузере пользователя. Этот service worker обеспечивает локальный резервный режим при отсутствии подключения к Интернету.
Обратите внимание, что веб-браузеры могут удалять кэшированные данные, если у пользователя заканчивается место на диске или если он некоторое время не открывал проект. Чтобы обеспечить более длительное кэширование данных, пользователь может добавить страницу в закладки или, в идеале, добавить её на главный экран своего устройства.
Если офлайн-данные недоступны из-за удаления из кэша, вы можете настроить Offline Page, которая будет отображаться в этом случае. Страница должна быть в формате HTML и будет сохранена на компьютере клиента при первой загрузке проекта.
Обеспечьте постоянное наличие заголовков кросс-доменной изоляции, даже если веб-сервер не настроен на их отправку. Это позволяет экспортировать данные с включенными потоками при размещении на любом веб-сайте, даже если у вас нет возможности контролировать отправляемые заголовки.
Такое поведение можно отключить, сняв флажок Enable Cross Origin Isolation Headers в разделе Progressive Web App.
Ограничения
По соображениям безопасности и конфиденциальности многие функции, которые легко работают на собственных платформах, на веб-платформе являются более сложными. Ниже приводится список ограничений, о которых следует помнить при переносе игры Godot в Интернет.
Важно
Поставщики браузеров делают все больше и больше функций, доступных только в secure contexts, это означает, что такие функции доступны только в том случае, если веб-страница обслуживается через безопасное соединение HTTPS (localhost обычно освобождается от такого требования).
Фоновая обработка
Браузер приостановит проект, когда вкладка перестанет быть активной в браузере пользователя. Это означает, что такие функции, как _process() и _physics_process(), больше не будут выполняться до тех пор, пока пользователь снова не сделает вкладку активной (переключившись обратно на вкладку). Это может привести к отключению сетевых игр, если пользователь долго переключается между вкладками.
Это ограничение не распространяется на несфокусированный браузер windows. Следовательно, со стороны пользователя эту проблему можно обойти, запустив проект в отдельном окне вместо отдельной вкладки.
Полный экран и захват мыши
Браузеры не позволяют произвольно переходить в полноэкранный режим. То же самое касается захвата курсора. Вместо этого эти действия должны происходить как ответ на событие ввода JavaScript. В Godot это означает переход в полноэкранный режим из нажатой функции обратного вызова события ввода, такой как _input или _unhandled_input. Запроса синглтона Input недостаточно, соответствующее событие ввода в настоящее время должно быть активным.
По той же причине настройка полноэкранного проекта не работает, если движок не запущен из допустимого обработчика событий ввода. Для этого требуется настройка HTML-страницы.
Аудио
Некоторые браузеры ограничивают автовоспроизведение звука на веб-сайтах. Самый простой способ обойти это ограничение — попросить игрока нажать кнопку, щелкнуть, коснуться экрана или клавишу/кнопку для включения звука, например, при отображении заставки в начале игры.
См. также
Google предлагает дополнительную информацию о своих Web Audio autoplay policies.
Команда Safari компании Apple также опубликовала дополнительную информацию об Auto-Play Policy Changes for macOS.
Предупреждение
Для доступа к микрофону требуется безопасный контекст.
Предупреждение
Начиная с Godot 4.3, по умолчанию при веб-экспорте для воспроизведения звука вместо потоков будут использоваться сэмплы.
Это связано с тем, как браузеры предпочитают воспроизводить аудио, и с недостатком вычислительной мощности, доступной при экспорте веб-игр с отключенной опцией экспорта Use Threads.
Обратите внимание, что аудиоэффекты для сэмплов пока не реализованы.
Сетевое взаимодействие
Низкоуровневое сетевое взаимодействие не реализовано из-за отсутствия поддержки в браузерах.
В настоящее время поддерживаются только HTTP-клиент, HTTP-запросы, WebSocket (клиент) и WebRTC.
Классы HTTP также имеют ряд ограничений на платформе HTML5:
Доступ или изменение
StreamPeerневозможноПотоковый (threaded) и режим блокирования (blocking mode) не доступны
Не может изменяться более чем раз в кадр, поэтому опрос в цикле приведет к зависаниям
Нет отрывочных ответов
Проверка хоста не может быть отключена
В соответствии same-origin policy
Буфер обмена
Для синхронизации буфера обмена между движком и операционной системой требуется браузер, поддерживающий Clipboard API, кроме того, из-за асинхронной природы API может быть ненадежной при доступе из GDScript.
Предупреждение
Требуется безопасный контекст.
Геймпады
Геймпады не будут обнаружены, пока не будет нажата одна из их кнопок. Геймпады могут иметь неправильное отображение в зависимости от комбинации браузера/ОС/геймпада, к сожалению, API Геймпада не обеспечивают надежный способ обнаружения информации геймпада, необходимой для их переназначения на основе модели/поставщика/ОС из соображений конфиденциальности.
Предупреждение
Требуется безопасный контекст.
Обслуживание файлов
При экспорте в Интернет создается несколько файлов для обслуживания с веб-сервера, включая HTML-страницу по умолчанию для презентации. Можно использовать собственный HTML-файл, см. Пользовательская HTML-страница для Web-экспорта.
Предупреждение
Только при экспорте с Use Threads, чтобы обеспечить низкую задержку звука и возможность использования Thread в веб-экспорте, веб-экспорт Godot 4 использует SharedArrayBuffer. Для этого требуется безопасный контекст, а также необходимо установить следующие заголовки 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 для размещения локального веб-сервера. Этот скрипт предназначен для тестирования веб-редактора, но его также можно использовать для тестирования экспортированных проектов.
Сохраните связанный скрипт в файле с именем 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
См. специальную страницу, чтобы узнать, как взаимодействовать с JavaScript и получать доступ к некоторым уникальным функциям веб-браузера.
Переменные среды
Вы можете использовать следующие переменные окружения, чтобы задавать опции экспорта вне редактора. Во время процесса экспорта, они переопределяют значения, которые были заданы в меню экспорта.
Опции экспорта |
Переменная окружения |
|---|---|
Шифрование / Ключ шифрования |
|
Устранение неполадок
Запуск экспорта локально показывает другой проект вместо
Если вы используете функцию "Развёртывание в один клик" в нескольких проектах, вы можете заметить, что вместо текущего проекта отображается один из проектов, который вы уже развернули. Это связано с кэшированием service worker, в котором в настоящее время отсутствует механизм автоматической очистки кэша.
В качестве обходного пути вы можете вручную отменить регистрацию текущего service worker, чтобы сбросить кэш. Это также позволит зарегистрировать новый service worker. В браузерах на базе Chromium откройте "Developer Tools", нажав F12 или Ctrl + Shift + I (Cmd + Option + I в macOS), затем перейдите на вкладку "Application" в DevTools (она может быть скрыта за значком шеврона, если панель DevTools узкая). Вы можете либо установить флажок и перезагрузить страницу, либо нажать рядом с зарегистрированным service worker, а затем перезагрузить страницу.
Отмена регистрации сервисного работника в DevTools браузеров на базе Chromium
В Firefox процедура аналогична. Откройте "Инструменты разработчика", нажав F12 или Ctrl + Shift + I (Cmd + Option + I в macOS), перейдите на вкладку "Приложение" в DevTools (она может быть скрыта за значком шеврона, если панель DevTools узкая). Нажмите рядом с зарегистрированным service worker, затем перезагрузите страницу.
Отмена регистрации service worker в DevTools Firefox
Опции экспорта
Полный список доступных параметров экспорта можно найти в справочнике классов EditorExportPlatformWeb.