Сервіс рушія та 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

У зворотному виклику ініціалізації застосунку нативного розширення отримайте сервер через dmEngine::GetWebServer(app_params) і реєструйте обробники лише тоді, коли повернений дескриптор не дорівнює null. Налаштування зворотного виклику див. у розділі Життєвий цикл розширення.

Перевантаження dmWebServer::AddHandler() із чотирма аргументами приймає об’єкт Paths Object OpenAPI 3.0.3 як рядок JSON. Ключами верхнього рівня об’єкта є шляхи маршрутів. Кожен шлях має починатися із зареєстрованого префікса й не бути вже задокументованим іншим обробником. Використовуйте вбудовані схеми або посилання на шляхи в кінцевому документі.

Наприклад, ця допоміжна функція реєструє зворотний виклик і опис його кінцевої точки стану:

#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);
}

Передайте зворотний виклик, який реалізує GET /example/v1/status і повертає задокументовану відповідь text/plain. Зворотний виклик і далі відповідає за перевірку шляхів і методів запитів та формування відповідей. Перевіряйте результат реєстрації: некоректні або конфліктні метадані повертають 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, визначених розширеннями.