Η υπηρεσία μηχανής και τα HTTP API χρόνου εκτέλεσης

Η εκτέλεση ενός έργου σε λειτουργία Debug δημιουργεί μια διεργασία για ένα συγκεκριμένο στιγμιότυπο χρόνου εκτέλεσης της μηχανής με το παιχνίδι σας και μια ειδική υπηρεσία μηχανής, στην οποία υπάρχει πρόσβαση για υποδομές ανάπτυξης και δημιουργίας προφίλ, λογική και μηνύματα χρόνου εκτέλεσης, κατάσταση της μηχανής και επεκτάσεις.

Η υπηρεσία μηχανής είναι μια υπηρεσία HTTP ανάπτυξης που ανήκει σε μια μηχανή Debug ή χωρίς γραφικό περιβάλλον (headless), η οποία εκτελείται (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 αλλάζει όταν προστίθενται ή αφαιρούνται χειριστές. Οι διαδρομές του profiler και των επεκτάσεων εξαρτώνται από την πλατφόρμα, τη διαμόρφωση και τις καταχωρισμένες επεκτάσεις της μηχανής που εκτελείται, επομένως ανακτήστε το έγγραφο από το στιγμιότυπο που χρησιμοποιείτε.

Οι χειριστές που καταχωρίζονται χωρίς μεταδεδομένα 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 byte μετά τη σειριοποίηση, διαφορετικά επιστρέφεται το σφάλμα 400 Too large message.

Αυτές οι διαδρομές αποτελούν υποδομή ανάπτυξης, ενώ στην υλοποίηση της μηχανής υπάρχουν πρόσθετες διαδρομές δημιουργίας προφίλ και επιθεώρησης πόρων.

Τελικά σημεία εγγραφής

Οι μηχανές Debug για επιτραπέζιες πλατφόρμες παρέχουν επίσης εγγενή εγγραφή MP4 μέσω των ακόλουθων διαδρομών. Οι διαδρομές παραλείπονται από δημιουργίες Release, headless, κινητών συσκευών και ιστού, καθώς και όταν είναι ενεργή η επιλογή Exclude Record στο App Manifest.

Εντοπίστε αυτές τις διαδρομές μέσω του /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, οι μηχανές Debug παρέχουν το /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() δέχεται ένα OpenAPI 3.0.3 Paths Object ως συμβολοσειρά 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 που ορίζονται από επεκτάσεις.