Usługa silnika i interfejsy HTTP API czasu działania

Uruchomienie projektu w trybie Debug tworzy proces konkretnej instancji silnika z grą oraz specjalną usługę silnika, która udostępnia infrastrukturę programistyczną i profilowania, logikę i wiadomości czasu działania, stan silnika oraz rozszerzenia.

Usługa silnika jest programistyczną usługą HTTP należącą do uruchomionego silnika debugowania (dmengine).

Jest oddzielona od serwera edytora, który należy do edytora Defold i steruje otwartym projektem.

Obie usługi korzystają z różnych portów. Narzędzie połączone z portem edytora nie może wywoływać na nim tras rozszerzeń czasu działania i odwrotnie — narzędzie połączone z usługą silnika nie może wywoływać operacji edytora.

Usługa silnika stanowi część infrastruktury debugowania, tworzenia i profilowania. Instancje silnika w wersji wydaniowej nie tworzą tej usługi.

Dostępność i wykrywanie portu

Gdy edytor uruchamia silnik debugowania, żąda dynamicznie przypisanego portu usługi. Silnik zgłasza wybrany port w Console (`i w swoim logu, jeśli został uruchomiony z CLI):

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

Wiersz pojawia się w konsoli edytora, gdy gra została uruchomiona z edytora. Prosty kontroler lokalny może przeanalizować ten wiersz, ale integracja wielokrotnego użytku powinna pozwolić edytorowi lub narzędziu opakowującemu śledzić instancję silnika i zarejestrowany port. Pozwala to uniknąć pomylenia starego portu z nowo uruchomionym lub ponownie użytym procesem.

Silnik ogłasza też cele programistyczne za pomocą wykrywania usług na obsługiwanych platformach. Mechanizm ten jest używany przede wszystkim przez narzędzia Defold i nie należy zastępować go trwale zakodowanym portem.

Serwer jest dostępny na hoście lokalnym (127.0.0.1) pod określonym portem:

Wbudowane punkty końcowe

Bieżący silnik debugowania rejestruje niewielki zestaw tras podstawowych.

Na przykład:

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

Trasa /post jest używana przez operacje programistyczne, takie jak szybkie przeładowanie, ponowne uruchamianie, zmiana rozmiaru i sterowanie procesem. Jej treść jest binarną wiadomością Protobuf typu podanego w trasie; nie jest to API wiadomości JSON.

Trasy te należą do infrastruktury programistycznej. Implementacja silnika zawiera też dodatkowe trasy profilera i sprawdzania zasobów.

Trasy czasu działania zdefiniowane przez rozszerzenia

W wersjach debugowania SDK rozszerzeń natywnych może udostępniać serwer WWW silnika. Rozszerzenie może zarejestrować prefiks trasy na tym serwerze i udostępnić operacje zależne od danych czasu działania.

Jest to przydatne w przypadku narzędzi programistycznych, ponieważ rozszerzenie może współdzielić istniejącą usługę silnika, zamiast otwierać kolejny serwer HTTP.

API automatyzacji w czasie działania zdefiniowane przez rozszerzenie powinno:

• używać odrębnego, wersjonowanego prefiksu trasy;
• udostępniać obsługiwane możliwości;
• zwracać ustrukturyzowane błędy;
• jawnie obsługiwać niedostępne funkcje platformy lub silnika;
• ograniczać operacje do tworzenia i testowania;
• dokumentować, czy jest pomijane w wersjach wydaniowych.

Rozszerzenie Automation Bridge

Oficjalne rozszerzenie Defold Automation Bridge jest rozszerzeniem natywnym dostępnym wyłącznie w trybie debugowania i zbudowanym na usłudze silnika. Rejestruje ono wersjonowane API automatyzacji w czasie działania pod adresem:

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

Jego API czasu działania udostępnia między innymi sprawdzanie scen i węzłów, wejście, informacje o ekranie, zrzuty ekranu, nagrywanie, informacje o cyklu życia i opcjonalną synchronizację zdefiniowaną przez aplikację. Niektóre operacje to:

Należy korzystać z dokumentacji natywnego API rozszerzenia i dokumentacji pomocniczych narzędzi Python dla wersji zainstalowanej w projekcie.

Automation Bridge nie udostępnia ani swojego HTTP API, ani modułu Lua w wersjach wydaniowych.

Klienty edytora i środowiska uruchomieniowego

Pomocnicze narzędzia Python rozszerzenia Automation Bridge ilustrują architekturę dwóch klientów. Funkcja editor.open_project() zwraca klienta projektu edytora, a project.build_and_run() — osobnego klienta silnika.

Podział na project i game uwidacznia granicę między procesami. Operacje edytora pozostają na serwerze edytora, a obserwacje i działania dotyczące uruchomionej gry — w usłudze silnika.

from automation_bridge import editor

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

Ograniczenia i bezpieczeństwo

Usługa silnika i trasy zdefiniowane przez rozszerzenia są narzędziami programistycznymi i należy je w ten sposób traktować.

Skrypty czasu działania, fizyka, wejście, dynamicznie tworzone obiekty i renderowanie charakterystyczne dla platformy wymagają uruchomionego silnika i powinny być weryfikowane przez automatyczne testy czasu działania.

• Nie należy udostępniać usługi przez router, interfejs publiczny ani niezaufany tunel.
• Nie należy zakładać, że trasy usługi silnika wymagają uwierzytelnienia.
• Trasy czasu działania mogą się różnić zależnie od wersji rozszerzenia, platformy, backendu graficznego i możliwości silnika.
• W przypadku aktualnych interfejsów API zdefiniowanych przez rozszerzenia należy uzgadniać wersję lub możliwości.