Work in progress

The content of this page was not yet updated for Godot 4.6 and may be outdated. If you know how to improve this page or you can confirm that it's up to date, feel free to open a pull request.

Справочник классов оболочки HTML5

Проекты, экспортируемые для Интернета (Web), предоставляют класс Engine() среде JavaScript, что позволяет осуществлять точный контроль над процессом запуска движка.

Этот API построен асинхронно и требует базовых знаний Promises.

Engine (Двигатель)

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

Статические методы

Обещание	`load` ( string basePath )
void	`unload` ( )
boolean	`isWebGLAvailable` ( [ номер majorVersion=1 ] )

Методы экземпляра

Обещание	`init` ( [ string basePath ] )
Обещание	`preloadFile` ( string\|файл ArrayBuffer [, строковый путь ] )
Обещание	`start` ( Переопределение EngineConfig )
Обещание	`startGame` ( Переопределение EngineConfig )
void	`copyToFS` ( путь к строке, буфер ArrayBuffer )
void	`requestQuit` ( )

class Engine(initConfig)

Создайте новый экземпляр Engine с заданной конфигурацией.

Аргументы:

initConfig (EngineConfig()) -- Начальная конфигурация для этого экземпляра.

Статические методы

Engine.load(basePath)

Загрузите движок с указанного базового пути.

Аргументы:

basePath (string()) -- Базовый путь двигателя для загрузки.

Результат:

Promise (Обещание), которое разрешается после загрузки двигателя.

Тип результата:

Обещание

Engine.unload()

Разгрузите движок, чтобы освободить память.

Этот метод будет вызван автоматически в зависимости от конфигурации. См. unloadAfterInit.

Engine.isWebGLAvailable([majorVersion=1])

Проверьте наличие WebGL. При желании укажите конкретную версию WebGL для проверки.

Аргументы:

majorVersion (number()) -- Основная версия WebGL, которую следует проверить.

Результат:

Если указанная основная версия WebGL доступна.

Тип результата:

boolean

Методы экземпляра

Engine.prototype.init([basePath])

Инициализируйте экземпляр движка. При необходимости передайте базовый путь к движку для его загрузки, если он ещё не загружен. См. Engine.load().

Аргументы:

basePath (string()) -- Базовый путь двигателя для загрузки.

Результат:

Promise (Обещание), которое разрешается после загрузки и инициализации движка.

Тип результата:

Обещание

Engine.prototype.preloadFile(file[, path])

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

Если не указан, путь выводится из URL-адреса загруженного файла.

Аргументы:

file (string|ArrayBuffer()) -- Файл для предварительной загрузки. Если это string, файл будет загружен по указанному пути. Если это ArrayBuffer или представление по нему, в качестве содержимого файла будет использоваться буфер.
path (string()) -- Путь, по которому будет доступен файл. Обязательно, если file не является строкой.

Результат:

Promise (Обещание), которое разрешается после загрузки файла.

Тип результата:

Обещание

Engine.prototype.start(override)

Запустите экземпляр движка, используя заданную конфигурацию переопределения (если таковая имеется). Вместо этого в типичных случаях можно использовать startGame.

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

Завершается ошибкой, если холст не найден на странице или не указан в конфигурации.

Аргументы:

override (EngineConfig()) -- Необязательное переопределение конфигурации.

Результат:

Promise (Обещание), что проблема исчезнет, как только двигатель запустится.

Тип результата:

Обещание

Engine.prototype.startGame(override)

Запустите экземпляр игры, используя заданное переопределение конфигурации (если таковое имеется).

Это инициализирует экземпляр, если он ещё не инициализирован. Для ручной инициализации см. init.

Это нагрузит двигатель, если он не нагружен, , и предварительно загрузить основной пакет (main pck).

Этот метод ожидает, что начальная конфигурация (или переопределение) будет иметь установленные свойства executable и mainPack (обычно это делается редактором во время экспорта).

Аргументы:

override (EngineConfig()) -- Необязательное переопределение конфигурации.

Результат:

Обещание, которое разрешится после начала игры.

Тип результата:

Обещание

Engine.prototype.copyToFS(path, buffer)

Создать файл по указанному path с переданным как buffer в файловой системе экземпляра.

Аргументы:

path (string()) -- Место, где будет создан файл.
buffer (ArrayBuffer()) -- Содержимое файла.

Engine.prototype.requestQuit()

Запросить завершение работы текущего экземпляра.

Это похоже на нажатие пользователем кнопки закрытия в оконном менеджере, и не даст никакого эффекта, если движок завис или зациклился.

Настройка движка

Объект, используемый для настройки экземпляра Engine на основе параметров экспорта Godot и для их переопределения в пользовательских HTML-шаблонах при необходимости.

Свойства

тип	имя
boolean	`unloadAfterInit`
HTMLCanvasElement	`canvas`
string	`executable`
string	`mainPack`
string	`locale`
число	`canvasResizePolicy`
Array (Массив).<string (строка)>	`args`
функция	`onExecute`
функция	`onExit`
функция	`onProgress`
функция	`onPrint`
функция	`onPrintError`

EngineConfig

Объект конфигурации движка. Это просто typedef (определение_типа), создайте его как обычный объект, например:

const MyConfig = { исполняемый файл: 'godot', unloadAfterInit: false }

Описания свойства

unloadAfterInit

Будет ли автоматически выгружаться двигатель после инициализации экземпляра.

тип:: boolean
значение:: true

canvas

HTML DOM-объект Canvas для использования.

По умолчанию будет использоваться первый элемент холста в документе, если не указан ни один элемент.

тип:: HTMLCanvasElement
значение:: null

executable

Имя файла WASM без расширения. (Задается процессом экспорта Godot Editor).

тип:: string
значение:: ""

mainPack

Альтернативное имя для загружаемого игрового диска. В противном случае используется имя исполняемого файла.

тип:: string
значение:: null

locale

Укажите код языка, чтобы выбрать правильную локализацию игры.

Если локаль браузера не указана, будет использоваться её локаль. Полный список поддерживаемых локалей см. в разделе supported locales.

тип:: string
значение:: null

canvasResizePolicy

Политика изменения размера холста определяет, как Godot должен изменять размер холста.

0 означает, что Godot не будет изменять размер. Это полезно, если вы хотите управлять размером холста с помощью кода JavaScript в шаблоне.

1 означает, что Godot изменит размер холста при запуске и при изменении размера окна с помощью функций движка.

2 означает, что Godot адаптирует размер холста к размеру всего окна браузера.

тип:: число
значение:: 2

args

Аргументы, которые необходимо передать в качестве аргументов командной строки при запуске.

См. command line tutorial.

Примечание: startGame всегда добавит аргумент --main-pack.

тип:: Array (Массив).<string (строка)>
значение:: []

onExecute(path, args)

Функция обратного вызова для обработки вызовов Godot OS.execute.

Например, это используется в шаблоне веб-редактора для переключения между Менеджером Проекта и Редактором, а также для запуска игры.

Аргументы:

path (string()) -- Путь, который Godot хочет осуществить.
args (Array.) -- Аргументы "command" для выполнения.

onExit(status_code)

Функция обратного вызова для уведомления о завершении работы экземпляра Godot.

Примечание: Эта функция не будет вызвана, если двигатель выйдет из строя или перестанет отвечать.

Аргументы:

status_code (number()) -- Код статуса, возвращаемый Godot при выходе.

onProgress(current, total)

Функция обратного вызова для отображения хода загрузки.

Функция вызывается один раз для каждого кадра при загрузке файлов, поэтому использование requestAnimationFrame() не является обязательным.

Если функция обратного вызова получает нулевое количество байтов, это означает, что вычисление невозможно. Возможные причины:

Файлы поставляются с фрагментированным сжатием на стороне сервера
Файлы поставляются с сжатием на стороне сервера Chromium
Еще не все загрузки файлов начались (обычно на серверах без многопоточности)

Аргументы:

current (number()) -- Текущее количество загруженных байтов на данный момент.
total (number()) -- Общее количество байтов для загрузки.

onPrint([...var_args])

Функция обратного вызова для обработки стандартного потока вывода. Этот метод обычно следует использовать только на отладочных страницах.

По умолчанию используется console.log().

Аргументы:

var_args (*()) -- Переменное число аргументов, которые необходимо вывести.

onPrintError([...var_args])

Функция обратного вызова для обработки стандартного потока ошибок. Этот метод обычно следует использовать только на отладочных страницах.

По умолчанию используется console.error().

Аргументы:

var_args (*()) -- Переменное число аргументов, которые следует вывести как ошибки.