This translation is community contributed and may not be up to date. We only maintain the English version of the documentation. Read this manual in English
Сервіс рушія та HTTP API середовища виконання
Запуск проєкту в режимі Debug створює процес для певного екземпляра середовища виконання рушія з вашою грою та спеціальним сервісом рушія, доступним для інфраструктури розробки й профілювання, логіки та повідомлень середовища виконання, стану рушія й розширень.
Сервіс рушія — це HTTP-сервіс розробки, що належить запущеному налагоджувальному рушію (dmengine).
Він відокремлений від сервера редактора, який належить редактору Defold і керує відкритим проєктом.
Два сервіси використовують різні порти. Інструмент, підключений до порту редактора, не може викликати там маршрути розширень середовища виконання, і навпаки — інструмент, підключений до сервісу рушія, не може викликати операції редактора.
Сервіс рушія є частиною інфраструктури налагодження, розробки й профілювання. Екземпляри рушія випуску не створюють цей сервіс.
Доступність і виявлення порту
Коли редактор запускає налагоджувальний рушій, він запитує динамічно призначений порт сервісу. Рушій повідомляє вибраний порт у Console (`та у своєму журналі, якщо його запущено з CLI):
INFO:ENGINE: Engine service started on port <port>
Цей рядок з’являється в консолі редактора, коли гру запущено з редактора. Простий локальний контролер може аналізувати цей рядок, але інтеграція для повторного використання повинна дозволяти редактору або його оболонці відстежувати екземпляр рушія й зареєстрований порт. Це дає змогу не сплутати старий порт із щойно запущеним або повторно використаним процесом.
Рушій також оголошує цілі розробки через виявлення сервісів на підтримуваних платформах. Цей механізм переважно використовується інструментами Defold, і його не слід замінювати постійно жорстко закодованим портом.
Сервер доступний на localhost (127.0.0.1) за певним портом:
Вбудовані кінцеві точки
Поточний налагоджувальний рушій реєструє невеликий набір основних маршрутів.
| Кінцева точка | Призначення |
|---|---|
GET /ping |
Перевірити, чи відповідає сервіс рушія |
GET /info |
Прочитати версію рушія, платформу, ідентифікатор збірки й інформацію сервісу журналювання |
GET /state |
Прочитати стан підключення для розробки, який використовують інструменти Defold |
POST /post/<socket>/<message-type> |
Надіслати закодоване в Protobuf повідомлення Defold до іменованого сокета рушія |
Наприклад:
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 середовища виконання надає такі можливості, як інспектування сцен і вузлів, введення, інформація про екран, знімки екрана, записування, інформація про життєвий цикл і необов’язкова визначена застосунком синхронізація. Деякі операції:
| Операція | Дія |
|---|---|
GET /automation-bridge/v1/health |
Звіт про стан, можливості й сумісність API |
POST /automation-bridge/v1/input/click |
Взаємодії введення в середовищі виконання |
GET /automation-bridge/v1/screenshot |
Знімки екрана середовища виконання |
Використовуйте документацію нативного API розширення та документацію допоміжних засобів Python для версії, установленої в проєкті.
Automation Bridge не відкриває ані HTTP API, ані модуль Lua у збірках випуску.
Клієнти редактора й середовища виконання
Допоміжні засоби Python Automation Bridge ілюструють двоклієнтську архітектуру. Функція editor.open_project() повертає клієнт проєкту редактора, а project.build_and_run() повертає окремий клієнт рушія.
| Клієнт | Призначення |
|---|---|
| Project | HTTP API редактора, команди, налагоджувач, консоль, налаштування, довідка, попередні перегляди, збирання й виявлення порту |
| Game - engine service | Сцена, введення, знімки екрана, стан середовища виконання й синхронізація |
Поділ між project і game робить межу процесів явною. Операції редактора залишаються на сервері редактора, а спостереження й дії щодо запущеної гри — на сервісі рушія.
from automation_bridge import editor
project = editor.open_project(".")
game = project.build_and_run()
Обмеження й безпека
Сервіс рушія й визначені розширеннями маршрути є засобами розробки, і поводитися з ними слід відповідно.
Наразі сервіс рушія не публікує документ OpenAPI. Інтеграції мають обмежуватися задокументованою поведінкою або версійованим API розширення.
Скрипти середовища виконання, фізика, введення, динамічно створені об’єкти й платформний рендеринг потребують запущеного рушія й мають перевірятися за допомогою автоматизованого тестування середовища виконання.
- Не публікуйте сервіс через маршрутизатор, загальнодоступний інтерфейс або недовірений тунель.
- Не припускайте, що маршрути сервісу рушія потребують автентифікації.
- Маршрути середовища виконання можуть відрізнятися залежно від версії розширення, платформи, графічного бекенду й можливостей рушія.
- Використовуйте узгодження версії або можливостей для актуальних API, визначених розширеннями.