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

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

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

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

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

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

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

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

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

Движок также записывает в журнал полный URL обнаружения OpenAPI с фактическим адресом и назначенным портом:

INFO:ENGINE: OpenAPI: http://<address>:<port>/openapi.json

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

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

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

Обнаружение операций через OpenAPI

GET /openapi.json возвращает документ OpenAPI 3.0.3 с описанием HTTP API среды выполнения. Используйте порт сервиса движка из журнала. Для локального движка замените <port> ниже этим портом:

ENGINE_URL="http://127.0.0.1:<port>"
curl -fsS "$ENGINE_URL/openapi.json" | jq

Документ описывает пути, методы, параметры, тела запросов и ответы, предоставляемые зарегистрированными обработчиками, включая нативные расширения с метаданными OpenAPI. Его объект paths меняется при добавлении или удалении обработчиков. Маршруты профайлера и расширений зависят от платформы запущенного движка, конфигурации и зарегистрированных расширений, поэтому получайте документ именно у используемого экземпляра.

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

У редактора есть собственный документ OpenAPI на порту редактора. Для операций среды выполнения используйте документ движка.

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

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

Например:

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

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

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

Эндпоинты записи

Отладочные движки для настольных платформ также предоставляют нативную запись MP4 через следующие маршруты. Они исключены из релизных сборок, сборок без графики, мобильных и веб-сборок, а также при включённом Exclude Record в манифесте приложения.

Обнаружьте эти маршруты через /openapi.json, затем проверьте /recording/capabilities для определения поддержки на текущей платформе. Изменяющие состояние операции записи требуют заголовка X-Recording-Instance, а остановка — также принятого operation_id. Запуск и остановка асинхронны; дождитесь завершения файла перед загрузкой. Полный порядок работы см. в руководстве по записи.

HTTP-сервис использует общий с Lua рекордер. Запуск через HTTP по умолчанию включает аудио приложения, если оно поддерживается; запуск из Lua по умолчанию записывает только видео. Только записи, запущенные через HTTP, получают поле file со сведениями для загрузки. Перед загрузкой дождитесь pending: false, finalized: true и file.state: "complete", затем проверьте размер файла и SHA-256. При сочетании Lua и HTTP-клиентов см. раздел совместного использования рекордера.

Эндпоинт трассировки GPU Metal

На macOS отладочные движки предоставляют /profiler/gputrace для захвата трассировок GPU Metal. Маршрут появляется в /openapi.json только на macOS. Для захвата необходимы нативный адаптер Metal и METAL_CAPTURE_ENABLED=1 в окружении запуска движка. Если захват недоступен, запрос возвращает HTTP 501 с error.code: "gputrace_unsupported".

Принятые запросы возвращают HTTP 200 с ok: true и объектом data. Захват выполняется асинхронно: опрашивайте GET, пока data.state не станет complete, canceled или failed. Нативные ошибки запуска сообщаются в data.error. Трассировка записывается на хосте движка. Команды запуска, определение поддержки, примеры захвата и открытие результата в Xcode описаны в руководстве по захвату трассировок GPU Metal.

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

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

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

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

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

Публикация операций расширения в OpenAPI

В callback инициализации приложения нативного расширения получите сервер через dmEngine::GetWebServer(app_params) и регистрируйте обработчики только если возвращённый дескриптор не равен null. Настройка callback описана в разделе жизненного цикла расширения.

Перегрузка dmWebServer::AddHandler() с четырьмя аргументами принимает объект Paths OpenAPI 3.0.3 как JSON-строку. Ключи верхнего уровня объекта — пути маршрутов. Каждый путь должен начинаться с зарегистрированного префикса и не должен уже описываться другим обработчиком. Используйте встроенные схемы или ссылки на пути в итоговом документе.

Например, эта вспомогательная функция регистрирует callback и описание его эндпоинта статуса:

#include <dmsdk/dlib/webserver.h>

static const char STATUS_OPENAPI[] = R"json(
{
  "/example/v1/status": {
    "get": {
      "summary": "Get extension status",
      "responses": {
        "200": {
          "description": "Current extension status",
          "content": {
            "text/plain": {
              "schema": { "type": "string" }
            }
          }
        }
      }
    }
  }
}
)json";

dmWebServer::Result RegisterStatusHandler(dmWebServer::HServer server,
                                        dmWebServer::Handler callback,
                                        void* context)
{
    dmWebServer::HandlerParams params;
    params.m_Handler = callback;
    params.m_Userdata = context;
    return dmWebServer::AddHandler(
        server, "/example/v1", &params, STATUS_OPENAPI);
}

Передайте callback, который реализует GET /example/v1/status и возвращает описанный ответ text/plain. Callback по-прежнему отвечает за проверку путей и методов запросов и формирование ответов. Проверяйте результат регистрации: некорректные или конфликтующие метаданные возвращают dmWebServer::RESULT_ERROR_INVAL.

Сервер сохраняет указатель на JSON, не копируя строку. Её память должна оставаться неизменной и доступной до удаления обработчика через dmWebServer::RemoveHandler() или уничтожения сервера. Массив static const char в примере удовлетворяет этому требованию. Удаление обработчика также удаляет его пути из последующих ответов /openapi.json.

Перегрузка dmWebServer::AddHandler(server, prefix, &params) с тремя аргументами по-прежнему поддерживается. Она эквивалентна передаче 0 четвёртым аргументом: обработчик регистрируется без метаданных OpenAPI и не участвует в обнаружении.

Расширение 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, определяемых расширениями.