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

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

Важно

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

Внимание

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

Совет

Python offers an easy method to start a local server. Use python -m http.server 8000 --bind 127.0.0.1 with Python 3 to serve the current working directory at http://localhost:8000. Refer to MDN for additional information.

Внимание

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

Средство визуализации 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 is not available
  • Cannot progress more than once per frame, so polling in a loop will freeze
  • No chunked responses
  • Проверка хоста не может быть отключена
  • В соответствии same-origin policy

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

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

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

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

Shader language limitations

При экспорте проекта 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, его имя по умолчанию никогда не зависит от него.

The HTML page draws the game at maximum size within the browser window. This way it can be inserted into an <iframe> with the game's size, as is common on most web game hosting sites.

The other exported files are served as they are, next to the .html file, names unchanged. The .wasm file is a binary WebAssembly module implementing the engine. The .pck file is the Godot main pack containing your game. The .js file contains start-up code and is used by the .html file to access the engine. The .png file contains the boot splash image. It is not used in the default HTML page, but is included for custom HTML pages.

Файл .pck является двоичным, обычно поставляется с MIME-типом application/octet-stream. Файл .wasm поставляется как application/wasm.

Осторожно

Delivering the WebAssembly module (.wasm) with a MIME-type other than application/wasm can prevent some start-up optimizations.

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

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

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

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

Head Include is appended into the <head> element of the generated HTML page. This allows to, for example, load webfonts and third-party JavaScript APIs, include CSS, or run JavaScript code.

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

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

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

The value of the last JavaScript statement is converted to a GDScript value and returned by eval() under certain circumstances:

  • JavaScript number is returned as GDScript float
  • JavaScript boolean is returned as GDScript bool
  • JavaScript string is returned as GDScript String
  • JavaScript ArrayBuffer, TypedArray and DataView are returned as GDScript PoolByteArray
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 также принимает второй необязательный логический аргумент, который указывает, следует ли выполнять код в глобальном контексте выполнения, по умолчанию - false, чтобы предотвратить загрязнение глобального пространства имен:

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