Il servizio del motore e le API HTTP a runtime

L’esecuzione di un progetto in modalità Debug crea un processo per una determinata istanza del motore a runtime, contenente il gioco e uno speciale servizio del motore. Questo servizio consente di accedere all’infrastruttura di sviluppo e profilazione, alla logica e ai messaggi a runtime, allo stato del motore e alle estensioni.

Il servizio del motore è un servizio HTTP di sviluppo appartenente a un motore di debug o headless in esecuzione (dmengine o dmengine_headless).

È distinto dal server dell’editor, che appartiene all’editor Defold e controlla il progetto aperto.

I due servizi utilizzano porte diverse. Uno strumento connesso alla porta dell’editor non può richiamare lì le route delle estensioni a runtime e, viceversa, uno strumento connesso al servizio del motore non può richiamare operazioni dell’editor.

Il servizio del motore fa parte dell’infrastruttura di debug, sviluppo e profilazione. Le istanze del motore nelle build di release non creano il servizio.

Disponibilità e individuazione della porta

Quando avvia un motore di debug, l’editor richiede una porta del servizio assegnata dinamicamente. Il motore riporta la porta selezionata nella Console e nel proprio log quando viene eseguito dalla CLI:

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

Il motore registra anche l’URL completo di rilevamento OpenAPI usando il proprio indirizzo effettivo e la porta assegnata:

INFO:ENGINE: OpenAPI: http://<address>:<port>/openapi.json

Queste righe compaiono nella console dell’editor quando il gioco è stato avviato dall’editor. Un semplice controller locale può analizzarle, ma un’integrazione riutilizzabile dovrebbe lasciare che l’editor o il suo wrapper tengano traccia dell’istanza del motore e della porta registrata. Ciò evita di confondere una vecchia porta con quella di un processo appena avviato o riutilizzato.

Il motore annuncia inoltre le destinazioni di sviluppo tramite il rilevamento dei servizi sulle piattaforme supportate. Tale meccanismo viene utilizzato principalmente dagli strumenti Defold e non dovrebbe essere sostituito con un numero di porta fisso nel codice.

Il server è accessibile su localhost (127.0.0.1) alla porta indicata:

Rilevamento delle operazioni tramite OpenAPI

GET /openapi.json restituisce un documento OpenAPI 3.0.3 che descrive l’API HTTP a runtime. Usa la porta del servizio del motore riportata nel log. Per un motore locale, sostituisci <port> di seguito con quella porta:

ENGINE_URL="http://127.0.0.1:<port>"
curl -fsS "$ENGINE_URL/openapi.json" | jq

Il documento descrive percorsi, metodi, parametri, corpi delle richieste e risposte forniti dai gestori attualmente registrati, comprese le estensioni native che forniscono metadati OpenAPI. Il suo oggetto paths cambia quando vengono aggiunti o rimossi gestori. Le route del profiler e delle estensioni dipendono dalla piattaforma, dalla configurazione e dalle estensioni registrate del motore in esecuzione: recupera quindi il documento dall’istanza che stai usando.

I gestori registrati senza metadati OpenAPI restano richiamabili, ma non compaiono nel documento. Anche una route documentata può segnalare una funzionalità non disponibile; esamina le descrizioni delle risposte e gli eventuali endpoint delle funzionalità prima di usare operazioni dipendenti dalla piattaforma.

L’editor dispone di un proprio documento OpenAPI sulla porta dell’editor. Usa il documento del motore per le operazioni a runtime.

Endpoint integrati

Il motore di debug corrente registra un piccolo insieme di route principali.

Ad esempio:

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

La route /post è utilizzata da operazioni di sviluppo come hot reload, riavvio, ridimensionamento e controllo dei processi. Il relativo corpo è un messaggio binario Protobuf del tipo indicato nella route; non è un’API per messaggi JSON. Il messaggio Protobuf serializzato non può superare i 1024 byte; in caso contrario, viene restituito 400 Too large message.

Queste route fanno parte dell’infrastruttura di sviluppo; nell’implementazione del motore sono presenti ulteriori route per la profilazione e l’ispezione delle risorse.

Endpoint di registrazione

I motori di debug desktop espongono anche la registrazione MP4 nativa tramite le route seguenti. Queste sono escluse dalle build di release, headless, mobili e web e quando Exclude Record è abilitato nell’App Manifest.

Rileva queste route tramite /openapi.json, quindi controlla /recording/capabilities per conoscere il supporto della piattaforma corrente. Le operazioni che modificano la registrazione richiedono l’intestazione X-Recording-Instance; l’arresto richiede anche l’operation_id accettato. Avvio e arresto sono asincroni: attendi la finalizzazione prima di scaricare il file. Consulta il manuale della registrazione per il flusso di lavoro completo.

Il servizio HTTP condivide il registratore con Lua. Gli avvii tramite HTTP abilitano l’audio dell’applicazione per impostazione predefinita, se supportato; quelli da Lua registrano soltanto il video per impostazione predefinita. Solo le registrazioni avviate tramite HTTP dispongono di una ricevuta file scaricabile. Prima del download, attendi pending: false, finalized: true e file.state: "complete", quindi verifica le dimensioni e lo SHA-256 del file. Consulta Condivisione del registratore se usi insieme client Lua e HTTP.

Endpoint delle tracce GPU Metal

Su macOS, i motori di debug espongono /profiler/gputrace per acquisire tracce GPU Metal. La route compare in /openapi.json solo su macOS. L’acquisizione richiede l’adattatore Metal nativo e METAL_CAPTURE_ENABLED=1 nell’ambiente di avvio del motore. Se l’acquisizione non è disponibile, la richiesta restituisce HTTP 501 con error.code: "gputrace_unsupported".

Le richieste accettate restituiscono HTTP 200 con ok: true e un oggetto data. L’acquisizione procede in modo asincrono: interroga GET finché data.state non è complete, canceled o failed. Gli errori di avvio nativi vengono riportati in data.error. La traccia viene scritta sull’host del motore. Consulta la guida all’acquisizione delle tracce GPU Metal per i comandi di avvio, il rilevamento del supporto, gli esempi di acquisizione e l’apertura del risultato in Xcode.

Route a runtime definite dalle estensioni

Nelle build di debug, l’SDK delle estensioni native può fornire accesso al server web del motore. Un’estensione può registrare un prefisso di route su tale server ed esporre operazioni che dipendono dai dati a runtime.

Ciò è utile per gli strumenti di sviluppo, perché un’estensione può condividere il servizio del motore esistente anziché aprire un altro server HTTP.

Un’API di automazione a runtime definita da un’estensione dovrebbe:

• utilizzare un prefisso di route distinto e con versione;
• esporre le capacità supportate;
• restituire errori strutturati;
• gestire esplicitamente le funzionalità della piattaforma o del motore non disponibili;
• limitare le operazioni allo sviluppo e ai test locali;
• documentare se viene omessa dalle build di release.

Pubblicazione delle operazioni delle estensioni in OpenAPI

Nel callback di inizializzazione dell’applicazione di un’estensione nativa, ottieni il server con dmEngine::GetWebServer(app_params) e registra i gestori solo se l’handle restituito non è nullo. Consulta il ciclo di vita delle estensioni per la configurazione del callback.

L’overload a quattro argomenti di dmWebServer::AddHandler() accetta un oggetto Paths di OpenAPI 3.0.3 come stringa JSON. L’oggetto ha i percorsi delle route come chiavi di primo livello. Ogni percorso deve iniziare con il prefisso registrato e non essere già documentato da un altro gestore. Usa schemi inline o riferimenti a percorsi nel documento risultante.

Per esempio, questa funzione di supporto registra un callback e la descrizione del relativo endpoint di stato:

#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);
}

Passa un callback che implementi GET /example/v1/status e restituisca la risposta text/plain documentata. Il callback rimane responsabile di controllare i percorsi e i metodi delle richieste e di produrre le risposte. Controlla il risultato della registrazione: metadati non validi o in conflitto restituiscono dmWebServer::RESULT_ERROR_INVAL.

Il server conserva il puntatore JSON senza copiare la stringa. Mantienine la memoria invariata e valida finché il gestore non viene rimosso con dmWebServer::RemoveHandler() o il server non viene distrutto. L’array static const char dell’esempio soddisfa questo requisito. La rimozione del gestore rimuove anche i suoi percorsi dalle successive risposte di /openapi.json.

L’overload a tre argomenti dmWebServer::AddHandler(server, prefix, &params) resta supportato. Equivale a passare 0 come quarto argomento: il gestore viene registrato senza metadati OpenAPI ed escluso dal rilevamento.

Estensione Automation Bridge

L’estensione ufficiale Automation Bridge di Defold è un’estensione nativa disponibile soltanto in modalità debug e basata sul servizio del motore. Registra un’API di automazione a runtime con versione in:

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

La sua API di runtime offre funzionalità quali ispezione di scene e nodi, input, informazioni sullo schermo, schermate, registrazione, informazioni sul ciclo di vita e sincronizzazione facoltativa definita dall’applicazione. Alcune operazioni includono:

Consulta la documentazione dell’API nativa e la documentazione dell’helper Python dell’estensione per la versione installata nel progetto.

Automation Bridge non espone né la propria API HTTP né il proprio modulo Lua nelle build di release.

Client dell’editor e del runtime

Gli helper Python di Automation Bridge illustrano l’architettura a due client. La funzione editor.open_project() restituisce un client del progetto nell’editor, mentre project.build_and_run() restituisce un client del motore separato.

La divisione tra project e game rende esplicito il confine tra i processi. Le operazioni dell’editor restano sul server dell’editor, mentre le osservazioni e le azioni sul gioco in esecuzione restano sul servizio del motore.

from automation_bridge import editor

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

Limitazioni e sicurezza

Il servizio del motore e le route definite dalle estensioni sono strumenti di sviluppo e devono essere considerati tali.

Script a runtime, fisica, input, oggetti creati dinamicamente e rendering della piattaforma richiedono un motore in esecuzione e dovrebbero essere verificati tramite test automatici a runtime.

• Non pubblicare il servizio tramite un router, un’interfaccia pubblica o un tunnel non attendibile.
• Non presupporre che le route del servizio del motore richiedano autenticazione.
• Le route a runtime possono variare in base alla versione dell’estensione, alla piattaforma, al backend grafico e alle capacità del motore.
• Utilizza la negoziazione di versione o capacità per API aggiornate definite dalle estensioni.