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

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

Важно

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

Внимание

There are significant bugs when running HTML5 projects on iOS (regardless of the browser). We recommend using iOS' native export functionality instead, as it will also result in better performance.

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 и больше не поддерживается.

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

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

You can choose the Export Type to select which features will be available:

  • Regular: is the most compatible across browsers, will not support threads, nor GDNative.

  • Threads: will require the browser to support SharedArrayBuffer

  • GDNative: enables GDNative support but makes the binary bigger and slower to load.

If you plan to use VRAM compression make sure that Vram Texture Compression is enabled for the targeted platforms (enabling both For Desktop and For Mobile will result in a bigger, but more compatible export).

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

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

Важно

Each project must generate their own HTML file. On export, several text placeholders are replaced in the generated HTML file specifically for the given export options. Any direct modifications to that HTML file will be lost in future exports. To customize the generated file, use the Custom HTML shell option.

Предупреждение

Export types other then Regular are not yet supported by the C# version.

Ограничения

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

Важно

Browser vendors are making more and more functionalities only available in secure contexts, this means that such features are only be available if the web page is served via a secure HTTPS connection (localhost is usually exempt from such requirement).

Совет

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

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

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

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

Потоки

As mentioned above multi-threading is only available if the appropriate Export Type is set and support for it across browsers is still limited.

Предупреждение

Requires a secure context. Browsers are also starting to require that the web page is served with specific cross-origin isolation headers.

GDNative

As mentioned above GDNative is only available if the appropriate Export Type is set.

The export will also copy the required GDNative .wasm files to the output folder (and must be uploaded to your server along with your game).

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

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

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

Аудио

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

См.также

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

Предупреждение

Access to microphone requires a secure context.

Сеть

Low level networking is not implemented due to lacking support in browsers.

Currently, only HTTP client, HTTP requests, WebSocket (client) and WebRTC are supported.

The HTTP classes also have several restrictions on the HTML5 platform:

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

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

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

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

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

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

Clipboard

Clipboard synchronization between engine and the operating system requires a browser supporting the Clipboard API, additionally, due to the API asynchronous nature might not be reliable when accessed from GDScript.

Предупреждение

Requires a secure context.

Gamepads

Gamepads will not be detected until one of their button is pressed. Gamepads might have the wrong mapping depending on the browser/OS/gamepad combination, sadly the Gamepad API does not provide a reliable way to detect the gamepad information necessary to remap them based on model/vendor/OS due to privacy considerations.

Предупреждение

Requires a secure context.

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

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

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

Hosts that provide on-the-fly compression: GitHub Pages (gzip)

Hosts that don't provide on-the-fly compression: itch.io, GitLab Pages (supports manual gzip precompression)

Вызов 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)