Le service du moteur et les API HTTP d’exécution

L’exécution d’un projet en mode Debug crée un processus pour une instance d’exécution donnée du moteur avec votre jeu et un service spécial du moteur accessible pour l’infrastructure de développement et de profilage, la logique et les messages d’exécution, l’état du moteur et les extensions.

Le service du moteur est un service HTTP de développement appartenant à un moteur de débogage ou sans interface graphique en cours d’exécution (dmengine ou dmengine_headless).

Il est distinct du serveur de l’éditeur, qui appartient à l’éditeur Defold et contrôle le projet ouvert.

Les deux services utilisent des ports différents. Un outil qui se connecte au port de l’éditeur ne peut pas y appeler les routes des extensions d’exécution, et inversement : un outil qui se connecte au service du moteur ne peut pas appeler les opérations de l’éditeur.

Le service du moteur fait partie de l’infrastructure de débogage, de développement et de profilage. Les instances Release du moteur ne créent pas ce service.

Disponibilité et découverte du port

Lorsque l’éditeur démarre un moteur de débogage, il demande un port de service attribué dynamiquement. Le moteur indique le port sélectionné dans la Console et dans son journal lorsqu’il est exécuté depuis une CLI :

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

Le moteur consigne également l’URL complète de découverte OpenAPI avec son adresse réelle et le port attribué :

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

Ces lignes apparaissent dans la console de l’éditeur lorsque le jeu a été lancé depuis celui-ci. Un contrôleur local simple peut les analyser, mais une intégration réutilisable devrait laisser l’éditeur, ou l’outil qui l’encapsule, suivre l’instance du moteur et le port enregistré. Cela évite de confondre un ancien port avec celui d’un processus nouvellement démarré ou réutilisé.

Le moteur annonce également les cibles de développement au moyen de la découverte de services sur les plateformes prises en charge. Ce mécanisme est principalement utilisé par les outils Defold et ne devrait pas être remplacé par un port codé en dur de manière permanente.

Le serveur est accessible sur localhost (127.0.0.1) au port indiqué :

Découvrir les opérations via OpenAPI

GET /openapi.json renvoie un document OpenAPI 3.0.3 décrivant l’API HTTP d’exécution. Utilisez le port du service du moteur indiqué dans le journal. Pour un moteur local, remplacez <port> ci-dessous par ce port :

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

Le document décrit les chemins, méthodes, paramètres, corps de requête et réponses fournis par les gestionnaires actuellement enregistrés, y compris les extensions natives qui fournissent des métadonnées OpenAPI. Son objet paths change lorsque des gestionnaires sont ajoutés ou supprimés. Les routes du profileur et des extensions dépendent de la plateforme, de la configuration et des extensions enregistrées du moteur en cours d’exécution ; récupérez donc le document depuis l’instance que vous utilisez.

Les gestionnaires enregistrés sans métadonnées OpenAPI restent accessibles mais n’apparaissent pas dans le document. Une route documentée peut aussi signaler qu’une fonctionnalité est indisponible ; examinez ses descriptions de réponse et tout point de terminaison de capacités avant d’utiliser des opérations dépendant de la plateforme.

L’éditeur possède son propre document OpenAPI sur le port de l’éditeur. Utilisez le document du moteur pour les opérations d’exécution.

Points de terminaison intégrés

Le moteur de débogage actuel enregistre un petit ensemble de routes principales.

Par exemple :

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

La route /post est utilisée par des opérations de développement telles que le rechargement à chaud, le redémarrage, le redimensionnement et le contrôle du processus. Son corps est un message Protobuf binaire du type indiqué dans la route ; il ne s’agit pas d’une API de messages JSON. La taille du message Protobuf sérialisé ne peut pas dépasser 1024 octets ; sinon, une réponse 400 Too large message est renvoyée.

Ces routes font partie de l’infrastructure de développement. D’autres routes de profilage et d’inspection des ressources existent dans l’implémentation du moteur.

Points de terminaison d’enregistrement

Les moteurs de débogage pour ordinateur exposent également l’enregistrement MP4 natif via les routes suivantes. Elles sont omises des builds de publication, sans interface graphique, mobiles et web, ainsi que lorsque Exclude Record est activé dans le manifeste d’application.

Découvrez ces routes via /openapi.json, puis consultez /recording/capabilities pour connaître la prise en charge sur la plateforme courante. Les opérations qui modifient l’enregistrement nécessitent l’en-tête X-Recording-Instance, et l’arrêt exige aussi l’operation_id accepté. Le démarrage et l’arrêt sont asynchrones ; attendez la finalisation avant de télécharger le fichier. Consultez le manuel d’enregistrement pour le flux de travail complet.

Le service HTTP partage l’enregistreur avec Lua. Les démarrages HTTP activent l’audio de l’application par défaut lorsqu’il est pris en charge ; les démarrages Lua enregistrent uniquement la vidéo par défaut. Seuls les enregistrements démarrés via HTTP possèdent un reçu file téléchargeable. Avant le téléchargement, attendez pending: false, finalized: true et file.state: "complete", puis vérifiez la taille et le SHA-256 du fichier. Consultez le partage de l’enregistreur pour combiner des clients Lua et HTTP.

Point de terminaison des traces GPU Metal

Sur macOS, les moteurs de débogage exposent /profiler/gputrace pour capturer des traces GPU Metal. La route n’apparaît dans /openapi.json que sur macOS. La capture nécessite l’adaptateur Metal natif et METAL_CAPTURE_ENABLED=1 dans l’environnement de lancement du moteur. Une demande renvoie HTTP 501 avec error.code: "gputrace_unsupported" si la capture est indisponible.

Les demandes acceptées renvoient HTTP 200 avec ok: true et un objet data. La capture progresse de manière asynchrone : interrogez GET jusqu’à ce que data.state soit complete, canceled ou failed. Les échecs de démarrage natif sont signalés dans data.error. La trace est écrite sur l’hôte du moteur. Consultez le guide de capture de traces GPU Metal pour les commandes de lancement, la découverte de la prise en charge, les exemples de capture et l’ouverture du résultat dans Xcode.

Routes d’exécution définies par des extensions

Dans les builds de débogage, le SDK des extensions natives peut donner accès au serveur web du moteur. Une extension peut enregistrer sur ce serveur un préfixe de route et exposer des opérations qui dépendent des données d’exécution.

C’est utile pour les outils de développement, car une extension peut partager le service existant du moteur au lieu d’ouvrir un autre serveur HTTP.

Une API d’automatisation à l’exécution définie par une extension devrait :

• utiliser un préfixe de route distinct et versionné ;
• exposer les fonctionnalités prises en charge ;
• renvoyer des erreurs structurées ;
• gérer explicitement les fonctionnalités indisponibles de la plateforme ou du moteur ;
• limiter les opérations au développement et aux tests ;
• indiquer dans sa documentation si elle est omise des builds Release.

Publier les opérations des extensions dans OpenAPI

Dans le callback d’initialisation de l’application d’une extension native, obtenez le serveur avec dmEngine::GetWebServer(app_params) et n’enregistrez des gestionnaires que si le handle renvoyé n’est pas nul. Consultez le cycle de vie des extensions pour configurer le callback.

La surcharge à quatre arguments de dmWebServer::AddHandler() accepte un objet Paths OpenAPI 3.0.3 sous forme de chaîne JSON. Les clés de premier niveau de l’objet sont les chemins des routes. Chaque chemin doit commencer par le préfixe enregistré et ne pas être déjà documenté par un autre gestionnaire. Utilisez des schémas en ligne, ou des références à des chemins du document résultant.

Par exemple, cet utilitaire enregistre un callback et la description de son point de terminaison d’état :

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

Passez un callback qui implémente GET /example/v1/status et renvoie la réponse text/plain documentée. Le callback reste responsable de la vérification des chemins et méthodes des requêtes ainsi que de la production des réponses. Vérifiez le résultat de l’enregistrement : des métadonnées non valides ou conflictuelles renvoient dmWebServer::RESULT_ERROR_INVAL.

Le serveur conserve le pointeur JSON sans copier la chaîne. Gardez son stockage inchangé et valide jusqu’à la suppression du gestionnaire avec dmWebServer::RemoveHandler() ou jusqu’à la destruction du serveur. Le tableau static const char de l’exemple satisfait cette exigence. La suppression du gestionnaire supprime également ses chemins des réponses /openapi.json suivantes.

La surcharge à trois arguments dmWebServer::AddHandler(server, prefix, &params) reste prise en charge. Elle équivaut à passer 0 comme quatrième argument : le gestionnaire est enregistré sans métadonnées OpenAPI et omis de la découverte.

Extension Automation Bridge

L’extension officielle Automation Bridge de Defold est une extension native réservée au débogage et fondée sur le service du moteur. Elle enregistre une API d’automatisation à l’exécution versionnée sous :

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

Son API d’exécution fournit notamment l’inspection de scènes et de nœuds, les entrées, des informations sur l’écran, les captures d’écran, l’enregistrement, des informations sur le cycle de vie et une synchronisation facultative définie par l’application. Voici quelques-unes de ses opérations :

Consultez la documentation de l’API native de l’extension et la documentation des utilitaires Python pour la version installée dans le projet.

Automation Bridge n’expose ni son API HTTP ni son module Lua dans les builds Release.

Clients de l’éditeur et d’exécution

Les utilitaires Python d’Automation Bridge illustrent l’architecture à deux clients. La fonction editor.open_project() renvoie un client de projet de l’éditeur, tandis que project.build_and_run() renvoie un client distinct pour le moteur.

La séparation entre project et game rend explicite la limite entre les processus. Les opérations de l’éditeur restent sur son serveur, tandis que les observations et les actions sur le jeu en cours d’exécution restent sur le service du moteur.

from automation_bridge import editor

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

Limites et sécurité

Le service du moteur et les routes définies par les extensions sont des outils de développement et devraient être traités comme tels.

Les scripts d’exécution, la physique, les entrées, les objets créés dynamiquement et le rendu propre à une plateforme nécessitent un moteur en cours d’exécution et devraient être vérifiés par des tests d’exécution automatisés.

• Ne publiez pas le service par l’intermédiaire d’un routeur, d’une interface publique ou d’un tunnel non fiable.
• Ne supposez pas que les routes du service du moteur nécessitent une authentification.
• Les routes d’exécution peuvent varier en fonction de la version de l’extension, de la plateforme, du backend graphique et des fonctionnalités du moteur.
• Utilisez une négociation de version ou de fonctionnalités pour les API à jour définies par les extensions.