Экспорт для Интернета

Экспорт HTML5 позволяет публиковать игры, созданные в Godot Engine, в браузере. Для этого требуется поддержка WebAssembly и WebGL в браузере пользователя.

Важно

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

Внимание

Многие браузеры, в том числе браузеры на базе Firefox и Chromium, не загружают экспортированные проекты при открытии локально по протоколу file://. Чтобы обойти это, используйте локальный сервер.

Совет

Python предлагает простой способ запустить локальный сервер. Используйте python -m http.server 8000 --bind 127.0.0.1 с Python 3 для обслуживания текущего рабочего каталога по адресу http://localhost:8000. Для получения дополнительной информации смотрите документацию MDN.

Внимание

При запуске проектов HTML5 на iOS (независимо от браузера) возникают серьёзные ошибки. Мы рекомендуем вместо этого использовать родную функцию экспорта iOS, так как это также приведет к повышению производительности.

Примечание

If you use Linux, due to poor Firefox WebGL performance, it's recommended to play the exported project using a Chromium-based browser instead of Firefox.

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), поэтому они также не будут работать.

Средство визуализации Godot WebGL 2 имеет проблемы с 3D и больше не поддерживается.

Ограничения

По соображениям безопасности и конфиденциальности многие функции, которые легко работают на собственных платформах, на веб-платформе являются более сложными. Ниже приводится список ограничений, о которых следует помнить при переносе игры Godot в Интернет.

Использование файлов cookie для сохранения данных

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

Метод OS.is_userfs_persistent() может использоваться для проверки того, является ли файловая система user:// постоянным, но в некоторых случаях может давать ложные срабатывания.

Полный экран и захват мыши

Браузеры не позволяют произвольно переходить в полноэкранный режим. То же самое касается захвата курсора. Вместо этого эти действия должны происходить как ответ на событие ввода JavaScript. В Godot это означает переход в полноэкранный режим из нажатой функции обратного вызова события ввода, такой как _input или _unhandled_input. Запроса синглтона Input недостаточно, соответствующее событие ввода в настоящее время должно быть активным.

По той же причине настройка полноэкранного проекта не работает, если движок не запущен из допустимого обработчика событий ввода. Для этого требуется настройка HTML-страницы.

Автовоспроизведение аудио

Chrome ограничивает воспроизведение аудио на веб-сайтах. Возможно, игроку потребуется щёлкнуть, коснуться или нажать клавишу, чтобы включить звук.

См.также

Google предлагает дополнительную информацию о своих политиках автоматического воспроизведения веб-аудио.

HTTPClient и HTTPRequest

Классы HTTP имеют несколько ограничений на платформе HTML5:

  • Доступ или изменение StreamPeer невозможно

  • Потоковый (threaded) и режим блокирования (blocking mode) не доступны

  • Не может изменяться более чем раз в кадр, поэтому опрос в цикле приведет к зависаниям

  • Нет отрывочных ответов

  • Проверка хоста не может быть отключена

  • В соответствии same-origin policy

Экспортированный файл .html нельзя использовать повторно

Каждый проект должен генерировать свой собственный HTML-файл. При экспорте несколько заполнителей текста заменяются в сгенерированном HTML-файле специально для данных параметров экспорта. Любые прямые изменения сгенерированного HTML-файла будут потеряны при дальнейшем экспорте. Чтобы настроить сгенерированный файл, см. Custom HTML page for Web export.

Загрузочная заставка не отображается

HTML-страница по умолчанию не отображает загрузочную заставку во время загрузки. Тем не менее, изображение экспортируется в виде PNG-файла, поэтому настройка HTML страницы могут его отобразить.

Ограничения языка шейдеров

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

Нереализованный функционал

Следующие функции, в настоящее время, недоступны на платформе HTML5:

  • Потоки

  • GDNative

  • C#

  • Синхронизация буфера обмена между движком и операционной системой

  • Сеть, отличная от HTTPClient и WebSocketClient

Совет

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

Обслуживание файлов

При экспорте в Интернет создается несколько файлов для обслуживания с веб-сервера, включая 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-типа отличным от :mimetype:`application/wasm`может предотвратить некоторые оптимизации запуска.

Доставка файлов с сжатием на стороне сервера особенно рекомендуется для .pck и ``.wasm``файлов, которые обычно большого размера. Модуль WebAssembly сжимает особенно хорошо, вплоть до четверти изначального размера с сжатием gzip.

Опции экспорта

Если доступен работоспособный шаблон для экспорта, появляется кнопка между кнопками Остановка сцены и Запустить измененную сцену в редакторе чтобы быстро открыть игру в браузере по умолчанию для тестов.

Если дан путь для файла пользовательской HTML оболочки, он будет использован вместо стандартной HTML страницы. Смотрите Custom HTML page for Web export.

Head Include соединена с элементом <head> созданной HTML страницы. Это позволяет, к примеру, загружать вебшрифты и сторонние JavaScript API, включать CSS, или использовать код Javascript.

Вызов JavaScript из сприпта (сценария)

В веб-сборки включен синглтон JavaScript. Он предлагает единственный метод названный eval который работает схоже с функцией Javascript названной так же. Этот метод как аргумент берет строку и выполняет её как код Javascript. Это позволяет взаимодействовать с браузером такими путями, которые не были бы возможны со встроенными в Godot скриптовыми языками.

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

Значение последнего выражения Javascript превращается в значение GDScript и возвращается eval() при определенных обстоятельствах:

  • Число в Javascript возвращается как класс GDScript :ref:`class_float`(число с плавающей точкой)

  • ``Булевое``значение в Javascript возвращается как класс GDScript bool (булевое значение)

  • Строка в Javascript возвращается как класс GDScript :ref:`class_String`(строка)

  • JavaScript ArrayBuffer, TypedArray и DataView возвращается как класс GDScript PoolByteArray

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 также принимает второй необязательный логический аргумент, который указывает, следует ли выполнять код в глобальном контексте выполнения, по умолчанию - false, чтобы предотвратить загрязнение глобального пространства имен:

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