Сервис движка и HTTP API среды выполнения

При запуске проекта в режиме Debug создаётся процесс для конкретного экземпляра среды выполнения движка с вашей игрой и специальным сервисом движка, доступным для инфраструктуры разработки и профилирования, логики и сообщений среды выполнения, состояния движка и расширений.

Сервис движка — это HTTP-сервис разработки, принадлежащий запущенному отладочному движку (dmengine).

Он отделён от сервера редактора, который принадлежит редактору Defold и управляет открытым проектом.

Эти два сервиса используют разные порты. Инструмент, подключённый к порту редактора, не может вызывать через него маршруты расширений среды выполнения, и наоборот — инструмент, подключённый к сервису движка, не может вызывать операции редактора.

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

Доступность и определение порта

Когда редактор запускает отладочный движок, он запрашивает динамически назначенный порт сервиса. Движок сообщает выбранный порт в Console (и в журнале при запуске из CLI):

INFO:ENGINE: Engine service started on port <port>

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

Движок также объявляет цели разработки посредством обнаружения сервисов на поддерживаемых платформах. Этот механизм в основном используется инструментами Defold, и его не следует заменять постоянным жёстко заданным портом.

Сервер доступен на localhost (127.0.0.1) по заданному порту:

Встроенные эндпоинты

Текущий отладочный движок регистрирует небольшой набор основных маршрутов.

Например:

curl -sS "$ENGINE_URL/ping"
curl -sS "$ENGINE_URL/info" | jq
curl -sS "$ENGINE_URL/state" | jq

Маршрут /post используется такими операциями разработки, как горячая перезагрузка, перезапуск, изменение размера и управление процессом. Его тело — бинарное Protobuf-сообщение типа, указанного в маршруте; это не API сообщений JSON.

Эти маршруты относятся к инфраструктуре разработки; кроме того, в реализации движка существуют дополнительные маршруты профайлера и инспекции ресурсов.

Маршруты среды выполнения, определяемые расширениями

В отладочных сборках SDK нативных расширений может предоставлять доступ к веб-серверу движка. Расширение может зарегистрировать на этом сервере префикс маршрута и предоставить операции, зависящие от данных среды выполнения.

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

API автоматизации среды выполнения, определяемый расширением, должен:

• использовать отдельный версионированный префикс маршрута;
• сообщать о поддерживаемых возможностях;
• возвращать структурированные ошибки;
• явно обрабатывать недоступные возможности платформы или движка;
• ограничивать операции локальными задачами разработки и тестирования;
• документировать, отсутствует ли он в релизных сборках.

Расширение Automation Bridge

Официальный Automation Bridge от Defold — это нативное расширение только для отладки, построенное на сервисе движка. Оно регистрирует версионированный API автоматизации среды выполнения по адресу:

http://127.0.0.1:<engine-service-port>/automation-bridge/v1

Его API среды выполнения предоставляет такие возможности, как инспекция сцен и узлов, ввод, информация об экране, снимки экрана, запись, информация о жизненном цикле и необязательная синхронизация, определяемая приложением. Некоторые операции:

Используйте документацию нативного API расширения и документацию вспомогательной библиотеки Python для версии, установленной в проекте.

Automation Bridge не предоставляет ни свой HTTP API, ни свой модуль Lua в релизных сборках.

Клиенты редактора и среды выполнения

Вспомогательные библиотеки Python для Automation Bridge иллюстрируют архитектуру с двумя клиентами. Функция editor.open_project() возвращает клиент проекта редактора, а project.build_and_run() — отдельный клиент движка.

Разделение между project и game явно отражает границу процессов. Операции редактора остаются на сервере редактора, а наблюдения и действия над запущенной игрой — в сервисе движка.

from automation_bridge import editor

project = editor.open_project(".")
game = project.build_and_run()

Ограничения и безопасность

Сервис движка и маршруты, определяемые расширениями, являются инструментами разработки, и относиться к ним следует соответственно.

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

• Не публикуйте сервис через маршрутизатор, общедоступный интерфейс или недоверенный туннель.
• Не предполагайте, что маршруты сервиса движка требуют аутентификации.
• Маршруты среды выполнения могут различаться в зависимости от версии расширения, платформы, графического бэкенда и возможностей движка.
• Используйте согласование версии или возможностей для актуальных API, определяемых расширениями.