Αυτοματοποίηση του επεξεργαστή Defold

Ο Επεξεργαστής Defold ανοίγει έναν ειδικό διακομιστή για αυτοματοποιημένες ενέργειες. Το HTTP API ελέγχει το ανοιχτό έργο. Χρησιμοποιήστε το για εντολές επεξεργαστή, δημιουργίες, πόρους έργου, προεπισκοπήσεις, προτιμήσεις, έξοδο κονσόλας, αναζήτηση τεκμηρίωσης ή ενσωματώσεις σεναρίων επεξεργαστή. Για να επιθεωρήσετε ή να ελέγξετε το παιχνίδι που εκτελείται, χρησιμοποιήστε την υπηρεσία μηχανής ή ένα API αυτοματισμού χρόνου εκτέλεσης.

Εκκίνηση του επεξεργαστή από εξωτερικό εργαλείο

Ένα εξωτερικό εργαλείο χρειάζεται το εκτελέσιμο αρχείο του επεξεργαστή και την απόλυτη διαδρομή προς το αρχείο game.project του έργου.

Οι εγκατεστημένες εκδόσεις του Defold μπορούν να εντοπιστούν μέσω του installations.json, όπως περιγράφεται στο εγχειρίδιο του Επεξεργαστή. Το πεδίο launcherPath περιέχει το εκτελέσιμο αρχείο που θα εκκινηθεί. Μεταβιβάστε τη διαδρομή του game.project ως το πρώτο όρισμα θέσης για να ανοίξετε απευθείας αυτό το έργο.

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

# Linux
/path/to/Defold/Defold --port 8181 /absolute/path/to/project/game.project

# macOS
/path/to/Defold.app/Contents/MacOS/Defold --port 8181 /absolute/path/to/project/game.project

# Windows
C:\path\to\Defold\Defold.exe --port 8181 C:\absolute\path\to\project\game.project

Ο επεξεργαστής είναι μια γραφική εφαρμογή υπολογιστή. Εκκινήστε τον σε μια διαδραστική περίοδο λειτουργίας χρήστη με πρόσβαση στην οθόνη. Χρησιμοποιήστε το Bob όταν δεν είναι διαθέσιμη γραφική περίοδος λειτουργίας, όπως σε CI χωρίς γραφικό περιβάλλον, ή για αυτοματισμό μόνο μεταγλώττισης και δημιουργία αυτόνομων πακέτων.

Αφού εκκινήσετε τον επεξεργαστή, περιμένετε ώσπου να ανοίξει το έργο και να υπάρχει το .internal/editor.port. Έπειτα υποβάλλετε περιοδικά ερωτήματα στο /openapi.json μέχρι να επιστρέψει έγκυρο έγγραφο. Μην υποθέτετε ότι η δημιουργία της διεργασίας σημαίνει πως το έργο είναι έτοιμο.

Εντοπισμός του διακομιστή επεξεργαστή

Ο επεξεργαστής εκκινεί έναν τοπικό διακομιστή HTTP όσο είναι ανοιχτό ένα έργο. Επιλέξτε Help ▸ Open Editor Server για να ανοίξετε την αρχική του σελίδα στο προεπιλεγμένο πρόγραμμα περιήγησης:

Η επιλεγμένη θύρα γράφεται μέσα στο έργο στο:

.internal/editor.port

Τα παραδείγματα και οι εντολές αυτού του εγχειριδίου θα αναφέρονται εφεξής σε αυτές τις μεταβλητές κελύφους:

PORT="$(cat .internal/editor.port)"
BASE_URL="http://127.0.0.1:$PORT"

Το αρχείο θύρας ανήκει στην τρέχουσα περίοδο λειτουργίας του επεξεργαστή. Διαβάστε το ξανά μετά την επανεκκίνηση του επεξεργαστή.

Εντοπισμός λειτουργιών μέσω OpenAPI

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

curl -sS "http://127.0.0.1:$(cat .internal/editor.port)/openapi.json"

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

Παραθέστε τις τεκμηριωμένες διαδρομές:

curl -sS "$BASE_URL/openapi.json" |
  jq -r '.paths | keys[]'

Παραθέστε τις διαθέσιμες εντολές επεξεργαστή:

curl -sS "$BASE_URL/openapi.json" |
  jq -r '
    .paths["/command/{command}"].post.parameters[]
    | select(.name == "command")
    | .schema.enum[]
  '

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

Οι διαδρομές που ορίζονται από το έργο εμφανίζονται επίσης στο /openapi.json, όταν τα σενάρια επεξεργαστή τους παρέχουν μια περιγραφή λειτουργίας OpenAPI.

Εκτέλεση εντολών επεξεργαστή

Οι εντολές επεξεργαστή καλούνται μέσω:

POST /command/{command}

Για παράδειγμα, η τρέχουσα εντολή build μεταγλωττίζει και εκτελεί το έργο:

curl -sS \
  -X POST \
  "$BASE_URL/command/build" |
  jq

Μια επιτυχής δημιουργία επιστρέφει δομημένο αποτέλεσμα:

{
  "success": true,
  "issues": []
}

Μια αποτυχημένη δημιουργία επιστρέφει κατάσταση HTTP 422 με ζητήματα όπως:

{
  "success": false,
  "issues": [
    {
      "message": "Example compiler message",
      "severity": "error",
      "resource": "/main/player.script",
      "range": {
        "start": {
          "line": 12,
          "character": 4
        },
        "end": {
          "line": 12,
          "character": 17
        }
      }
    }
  ]
}

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

Στις συχνά χρήσιμες εντολές, όταν παρατίθενται από τον επεξεργαστή που εκτελείται, περιλαμβάνονται:

build

Μεταγλώττιση και εκτέλεση του έργου.

clean-build

Εκκαθάριση της προσωρινής μνήμης δημιουργίας και έπειτα μεταγλώττιση και εκτέλεση. Χρησιμοποιήστε το μόνο όταν μια συνηθισμένη δημιουργία συμπεριφέρεται ασυνεπώς ή φαίνεται να παραλείπει αλλαγές.

build-html5

Δημιουργία του έργου για HTML5 και διάθεση της εξόδου μέσω του διακομιστή επεξεργαστή.

fetch-libraries

Λήψη και επαναφόρτωση των εξαρτήσεων του έργου.

hot-reload

Επαναφόρτωση τροποποιημένων πόρων σε ένα παιχνίδι που εκτελείται.

reload-extensions

Επαναφόρτωση σεναρίων επεξεργαστή.

debugger-start, debugger-stop και οι εντολές βηματισμού του προγράμματος εντοπισμού σφαλμάτων

Έλεγχος μιας περιόδου εντοπισμού σφαλμάτων και του έργου που εκτελείται.

Τα ακριβή ονόματα και η διαθεσιμότητα εξαρτώνται από την έκδοση και την τρέχουσα κατάσταση του επεξεργαστή· εντοπίστε τα από το /openapi.json.

Οι εντολές που λειτουργούν σε πόρους έργου συγχρονίζουν τις εξωτερικές αλλαγές αρχείων πριν από την εκτέλεση.

Αποκρίσεις εντολών και ασύγχρονη εργασία

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

Μια απόκριση HTTP 202 δεν αποδεικνύει ότι υπάρχει το ζητούμενο αποτέλεσμα. Περιμένετε τη σχετική έξοδο, τον πόρο, τον δείκτη κονσόλας ή τη διαθέσιμη διεύθυνση URL και επιβάλετε χρονικό όριο.

Δημιουργία HTML5

Αν το τρέχον έγγραφο OpenAPI περιλαμβάνει το build-html5, καλέστε το μέσω της λειτουργίας εντολών:

curl -sS \
  -X POST \
  "$BASE_URL/command/build-html5"

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

http://127.0.0.1:<editor-port>/html5/

Περιμένετε ώσπου η διεύθυνση URL να είναι διαθέσιμη πριν ξεκινήσετε δοκιμές προγράμματος περιήγησης. Δείτε τις Δοκιμές προγράμματος περιήγησης για HTML5 για περισσότερες λεπτομέρειες.

Αναζήτηση τεκμηρίωσης API

Όταν υπάρχει στο /openapi.json, η λειτουργία /ref αναζητά την τεκμηρίωση API που περιλαμβάνεται στην έκδοση του επεξεργαστή η οποία εκτελείται. Παρέχει ονόματα και υπογραφές που αντιστοιχούν σε αυτή την έκδοση.

Για παράδειγμα, για να αναζητήσετε μια συνάρτηση, χρησιμοποιήστε:

curl -sS \
  --get \
  --data-urlencode "q=go.animate" \
  "$BASE_URL/ref" |
  jq

Φιλτράρετε ανά περιβάλλον και γλώσσα:

curl -sS \
  --get \
  --data-urlencode "environment=runtime" \
  --data-urlencode "language=Lua" \
  --data-urlencode "q=collision message|raycast" \
  "$BASE_URL/ref" |
  jq

Οι παράμετροι αναζήτησης είναι:

environment

editor, runtime ή τιμές διαχωρισμένες με κόμμα.

language

Lua, C, C++ ή τιμές διαχωρισμένες με κόμμα.

q

Μια έκφραση χωρίς διάκριση πεζών-κεφαλαίων. Τα κενά αντιπροσωπεύουν AND, ενώ το | αντιπροσωπεύει OR.

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

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

Ανάγνωση εξόδου κονσόλας

Διαβάστε την κονσόλα του επεξεργαστή ως JSON:

curl -sS "$BASE_URL/console" | jq

Η απόκριση περιέχει κείμενο κονσόλας στο lines και σημασιολογικές περιοχές στο regions, συμπεριλαμβανομένων σφαλμάτων, αποτελεσμάτων αξιολόγησης και αναφορών πόρων.

Για να παρακολουθείτε συνεχώς την έξοδο της κονσόλας, χρησιμοποιήστε:

curl -N "$BASE_URL/console/stream"

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

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

Απόδοση προεπισκοπήσεων σκηνής

Ο επεξεργαστής Defold (από την έκδοση 1.13.1) μπορεί να αποδώσει ένα «στιγμιότυπο οθόνης» ενός υποστηριζόμενου πόρου σκηνής σε PNG μέσω της εντολής /preview/{path}:

mkdir -p build/automation

curl -sS \
  "$BASE_URL/preview/main/main.collection?width=1280&height=720" \
  --output build/automation/main-preview.png

Αυτό αποδίδει την κύρια συλλογή από το ανοιχτό έργο του προτύπου Basic 3D σε μια προεπιλεγμένη αρχική προβολή:

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

curl -sS \
  "$BASE_URL/preview/assets/models/cube.model?width=1280&height=720" \
  --output build/automation/cube-preview.png

Η διαδρομή μετά το /preview/ δεν περιλαμβάνει αρχική κάθετο. Οι προαιρετικές διαστάσεις έχουν ως προεπιλογή το μέγεθος προβολής του έργου και πρέπει να βρίσκονται μεταξύ 1 και 4096.

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

Εκτέλεση Lua στον επεξεργαστή

Η ελεγχόμενη λειτουργία POST /eval εκτελεί Lua στο περιβάλλον επεκτάσεων του επεξεργαστή. Το διακριτικό φορέα ανά περίοδο λειτουργίας αποθηκεύεται στο:

.internal/editor.token

Διαβάστε το διακριτικό και εκτελέστε κώδικα:

TOKEN="$(cat .internal/editor.token)"

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary 'print(editor.version) return editor.platform' \
  "$BASE_URL/eval"

Η εκτυπωμένη έξοδος και οι τιμές επιστροφής επιστρέφονται ως κείμενο. Τυπικές αποκρίσεις είναι:

Ένας πελάτης μπορεί να δοκιμάσει ξανά μετά από 503, αλλά θα πρέπει να χρησιμοποιεί οριοθετημένο αριθμό προσπαθειών. Διορθώστε τον κώδικα πριν επαναλάβετε ένα αίτημα που επέστρεψε 422.

Ο κώδικας που αξιολογείται μπορεί να χρησιμοποιεί το Editor API και το περιβάλλον σεναρίων επεξεργαστή. Δεν μπορεί να χρησιμοποιεί API χρόνου εκτέλεσης του παιχνιδιού, όπως το go.*, για να χειρίζεται ένα παιχνίδι που εκτελείται. Χρησιμοποιήστε μια δοκιμή χρόνου εκτέλεσης, το πρόγραμμα εντοπισμού σφαλμάτων, μια δοκιμή προγράμματος περιήγησης ή ένα API αυτοματισμού χρόνου εκτέλεσης για το παιχνίδι.

Τροποποίηση πόρων και αρχείων

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

Επιθεωρήστε έναν πόρο πριν τον αλλάξετε:

curl -sS \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary '
    local path = "/game.project"
    pprint(editor.properties(path))
    return editor.get(path, "path")
  ' \
  "$BASE_URL/eval"

Ελέγξτε τις editor.can_get(), editor.can_set() και τις άλλες συναρτήσεις editor.can_*() πριν εκτελέσετε μια συναλλαγή.

Χρησιμοποιήστε την editor.execute() σε Lua του επεξεργαστή για να εκτελέσετε ένα εργαλείο μορφοποίησης, έναν επικυρωτή ή ένα εργαλείο παραγωγής:

local output = editor.execute(
  "python3",
  "scripts/generate_levels.py",
  {
    out = "capture"
  }
)

print(output)

Όταν η εντολή δεν τροποποιεί πόρους έργου, ορίστε reload_resources = false για να αποφύγετε μια περιττή επαναφόρτωση.

Προτιμήσεις

Οι προτιμήσεις του επεξεργαστή μπορούν να διαβαστούν και να γραφτούν μέσω της διαδρομής που τεκμηριώνεται στο OpenAPI, επί του παρόντος /prefs/{path}.

Μπορείτε, για παράδειγμα, να διαβάσετε το ρυθμισμένο μέγεθος γραμματοσειράς κώδικα:

curl -sS "$BASE_URL/prefs/code/font/size" | jq

Ή να το ορίσετε, π.χ., σε 16:

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  --data '16' \
  "$BASE_URL/prefs/code/font/size"

Ο επεξεργαστής επικυρώνει την τιμή με βάση το σχήμα προτιμήσεών του. Μια μη έγκυρη διαδρομή ή τιμή επιστρέφει HTTP 400.

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

Διαδρομές που ορίζονται από το έργο

Τα σενάρια επεξεργαστή μπορούν να ορίζουν πρόσθετες διαδρομές με το get_http_server_routes(). Ένας προαιρετικός πίνακας λειτουργίας OpenAPI εκθέτει μια διαδρομή μέσω του ίδιου εγγράφου /openapi.json με τις ενσωματωμένες λειτουργίες.

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

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

Οι διαδρομές που ορίζονται από το έργο δεν προστατεύονται αυτόματα από το διακριτικό /eval. Προσθέστε έλεγχο ταυτότητας και ελέγχους ασφάλειας ειδικά για το έργο όταν μια διαδρομή εκτελεί ευαίσθητες λειτουργίες.

Άγκιστρα κύκλου ζωής

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

local M = {}

local function validate_project()
  print(editor.execute(
    "python3",
    "scripts/validate_project.py",
    {
      out = "capture",
      reload_resources = false
    }
  ))
end

function M.on_build_started(opts)
  validate_project()
end

function M.on_build_finished(opts)
  print("Build successful:", opts.success)
end

return M

Ένα σφάλμα που εγείρεται από την on_build_started() σταματά τη δημιουργία στον επεξεργαστή. Τα άγκιστρα κύκλου ζωής εκτελούνται μόνο στον επεξεργαστή· τοποθετήστε την κοινή λογική επικύρωσης και παραγωγής σε αυτόνομα σενάρια που μπορούν επίσης να καλούνται από CI.

Ασφάλεια και συμβατότητα

Αντιμετωπίστε ολόκληρο τον διακομιστή επεξεργαστή ως αξιόπιστη τοπική διεπαφή:

• Μην εκθέτετε δημόσια την πρόσβαση στη θύρα.
• Προστατεύστε το .internal/editor.token· εξουσιοδοτεί το /eval για την τρέχουσα περίοδο λειτουργίας.
• Μην παρέχετε απεριόριστη εξωτερική πρόσβαση στο /eval.
• Διατηρήστε το διακριτικό στο τοπικό επίπεδο ενσωμάτωσης και όχι σε προτροπές, αναφορές ή αρχεία καταγραφής.
• Να θυμάστε ότι οι διαδρομές που ορίζονται από το έργο δεν κληρονομούν τον έλεγχο ταυτότητας του /eval.
• Χρησιμοποιείτε ενημερωμένο /openapi.json.
• Χρησιμοποιείτε οριοθετημένες αναμονές για ασύγχρονες αυτόματες εντολές και για την εκκίνηση του επεξεργαστή.

Διακομιστής μηχανής

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