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

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

Важно

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

Внимание

Возникают значительные ошибки при запуске HTML5-проектов на iOS (независимо от браузера). Мы рекомендуем использовать iOS родную функциональность экспорта <doc_exporting_for_ios>` вместо этого, так как это также приведет к лучшей производительности.

WebGL version

Depending on your choice of renderer, Godot can target WebGL 1.0 (GLES2) or WebGL 2.0 (GLES3).

WebGL 1.0 is the recommended option if you want your project to be supported on all browsers with the best performance.

Godot's GLES3 renderer targets high end devices, and the performance using WebGL 2.0 can be subpar. Some features are also not supported in WebGL 2.0 specifically.

Additionally, while most browsers support WebGL 2.0, this is not yet the case for Safari. WebGL 2.0 support is coming in Safari 15 for macOS, and is not available yet for any iOS browser (all WebKit-based like Safari). See Can I use WebGL 2.0 for details.

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

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

Вы можете выбрать Тип экспорта, чтобы выбрать, какие функции будут доступны:

  • Regular: наиболее совместим с браузерами, не будет поддерживать потоки и GDNative.

  • Threads: will require the browser to support SharedArrayBuffer. See Can I use SharedArrayBuffer for details.

  • GDNative: включает поддержку GDNative, но увеличивает размер двоичного файла и замедляет загрузку.

Если вы планируете использовать Сжатие VRAM, убедитесь, что Сжатие текстур Vram включено для целевых платформ (включение для настольных компьютеров и для мобильных приведет к большему, но более совместимому экспорту).

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

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

Важно

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

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

Типы экспорта, кроме Regular, пока не поддерживаются версией C#.

Ограничения

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

Важно

Поставщики браузеров делают все больше и больше функций, доступных только в безопасных контекстах <https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts> _, это означает, что такие функции доступны только в том случае, если веб-страница обслуживается через безопасное соединение HTTPS (localhost обычно освобождается от такого требования).

Совет

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

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

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

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

Потоки

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

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

Требуется безопасный контекст. Браузеры также начинают требовать, чтобы веб-страница обслуживалась с определенными `заголовками изоляции между источниками <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy > `__.

GDNative

Как уже упоминалось выше GDNative доступен, только если установлен соответствующий Тип экспорта.

При экспорте также будут скопированы необходимые файлы GDNative с расширением ``.wasm `` в выходную папку (их необходимо загрузить на ваш сервер вместе с игрой).

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

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

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

Аудио

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

См.также

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

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

Для доступа к микрофону требуется безопасный контекст.

Сеть

Сеть на низком уровне не реализована из-за отсутствия поддержки в браузерах.

В настоящее время поддерживаются только HTTP-клиент, HTTP-запросы, WebSocket (клиент) и WebRTC.

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

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

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

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

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

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

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

Буфер обмена

Синхронизация буфера обмена между движком и операционной системой требует браузер, поддерживающий API буфера обмена `<https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API> `__, кроме того, из-за асинхронного характера API может быть ненадежным при доступе из GDScript.

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

Требуется безопасный контекст.

Геймпады

Геймпады не будут обнаружены, пока не будет нажата одна из их кнопок. Геймпады могут иметь неправильное отображение в зависимости от комбинации браузера/ОС/геймпада, к сожалению, API Геймпада не обеспечивают надежный способ обнаружения информации геймпада, необходимой для их переназначения на основе модели/поставщика/ОС из соображений конфиденциальности.

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

Требуется безопасный контекст.

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

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.

Хосты, предоставляющие сжатие на лету: GitHub Pages (gzip)

**Хосты, которые не предоставляют сжатие на лету:**itch.io, GitLab Pages (поддерживает предварительное сжатие gzip вручную)

Вызов 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 могут быть built без поддержки синглтона для повышения безопасности. С такими шаблонами и на платформах, отличных от HTML5, вызов JavaScript.eval также вернет null. Наличие синглтона можно проверить с помощью тега JavaScript :ref:``feature tag <doc_feature_tags>`:

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)