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

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

Η υπηρεσία μηχανής είναι μια υπηρεσία HTTP ανάπτυξης που ανήκει σε μια δοκιμαστική μηχανή (dmengine) η οποία εκτελείται.

Είναι ξεχωριστή από τον διακομιστή επεξεργαστή, ο οποίος ανήκει στον επεξεργαστή Defold και ελέγχει το ανοιχτό έργο.

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

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

Διαθεσιμότητα και εντοπισμός θύρας

Όταν ο επεξεργαστής εκκινεί μια δοκιμαστική μηχανή, ζητά μια δυναμικά εκχωρημένη θύρα υπηρεσίας. Η μηχανή αναφέρει την επιλεγμένη θύρα στο Console (`και στο αρχείο καταγραφής της αν εκτελείται από CLI):

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

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

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

Ο διακομιστής είναι προσβάσιμος στο localhost (127.0.0.1) σε μια δεδομένη θύρα:

Ενσωματωμένα τελικά σημεία

Η τρέχουσα δοκιμαστική μηχανή καταχωρίζει ένα μικρό σύνολο βασικών διαδρομών.

Για παράδειγμα:

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

Χρησιμοποιήστε την τεκμηρίωση εγγενούς 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 που ορίζονται από επεκτάσεις.