El servicio del motor y las API HTTP de runtime

Ejecutar un proyecto en modo Debug crea un proceso para una instancia de runtime determinada del motor con tu juego y un servicio especial del motor al que se puede acceder para la infraestructura de desarrollo y profiling, la lógica y los mensajes de runtime, el estado del motor y las extensiones.

El servicio del motor es un servicio HTTP de desarrollo que pertenece a un motor de depuración o headless en ejecución (dmengine o dmengine_headless).

Es independiente del servidor del editor, que pertenece al editor Defold y controla el proyecto abierto.

Los dos servicios utilizan puertos distintos. Una herramienta que se conecte al puerto del editor no puede llamar allí a rutas de extensiones de runtime y, a la inversa, una herramienta que se conecte al servicio del motor no puede llamar a operaciones del editor.

El servicio del motor forma parte de la infraestructura de depuración, desarrollo y profiling. Las instancias del motor de release no crean el servicio.

Disponibilidad y detección del puerto

Cuando el editor inicia un motor de depuración, solicita un puerto de servicio asignado dinámicamente. El motor indica el puerto seleccionado en Console y en su log cuando se ejecuta desde una CLI:

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

El motor también registra la URL completa de descubrimiento de OpenAPI con su dirección real y el puerto asignado:

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

Estas líneas aparecen en la consola del editor cuando el juego se ha lanzado desde él. Un controlador local sencillo puede analizarlas, pero una integración reutilizable debería dejar que el editor o su envoltorio lleven el seguimiento de la instancia del motor y su puerto registrado. Esto evita confundir un puerto antiguo con un proceso recién iniciado o reutilizado.

El motor también anuncia objetivos de desarrollo mediante la detección de servicios en las plataformas compatibles. Este mecanismo lo utilizan principalmente las herramientas de Defold y no debe sustituirse por un puerto fijado permanentemente en el código.

El servidor está disponible en localhost (127.0.0.1) en un puerto determinado:

Descubrir operaciones mediante OpenAPI

GET /openapi.json devuelve un documento OpenAPI 3.0.3 que describe la API HTTP de runtime. Usa el puerto del servicio del motor indicado en el log. Para un motor local, sustituye <port> a continuación por ese puerto:

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

El documento describe las rutas, los métodos, los parámetros, los cuerpos de las solicitudes y las respuestas de los manejadores registrados actualmente, incluidas las extensiones nativas que proporcionan metadatos OpenAPI. Su objeto paths cambia al agregar o eliminar manejadores. Las rutas del profiler y de las extensiones dependen de la plataforma, la configuración y las extensiones registradas del motor en ejecución, por lo que debes obtener el documento de la instancia que estés usando.

Los manejadores registrados sin metadatos OpenAPI siguen pudiendo llamarse, pero no aparecen en el documento. Una ruta documentada también puede indicar que una funcionalidad no está disponible; revisa las descripciones de sus respuestas y cualquier endpoint de capacidades antes de usar operaciones que dependan de la plataforma.

El editor tiene su propio documento OpenAPI en el puerto del editor. Usa el documento del motor para las operaciones de runtime.

Endpoints integrados

El motor de depuración actual registra un pequeño conjunto de rutas principales.

Por ejemplo:

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

La ruta /post se utiliza para operaciones de desarrollo como hot reload, reinicio, cambio de tamaño y control de procesos. Su cuerpo es un mensaje binario Protobuf del tipo indicado en la ruta; no es una API de mensajes JSON. El mensaje Protobuf no puede superar los 1024 bytes una vez serializado; de lo contrario, se devolverá 400 Too large message.

Estas rutas son infraestructura de desarrollo, y existen rutas adicionales de profiler e inspección de recursos en la implementación del motor.

Endpoints de grabación

Los motores de depuración de escritorio también exponen la grabación nativa de MP4 mediante las siguientes rutas. Se omiten en builds release, headless, móviles y web, y cuando Exclude Record está activado en App Manifest.

Descubre estas rutas mediante /openapi.json y comprueba /recording/capabilities para conocer las capacidades de la plataforma actual. Las operaciones de grabación que modifican el estado requieren la cabecera X-Recording-Instance, y detener una grabación también requiere el operation_id aceptado. El inicio y la detención son asíncronos; espera a que finalice antes de descargar el archivo. Consulta el manual de grabación para conocer el procedimiento completo.

El servicio HTTP comparte el grabador con Lua. Las grabaciones iniciadas por HTTP activan el audio de la aplicación de forma predeterminada si se admite; las iniciadas por Lua solo graban video de forma predeterminada. Solo las grabaciones iniciadas por HTTP tienen un comprobante file descargable. Antes de descargarlo, espera a que se cumplan pending: false, finalized: true y file.state: "complete", y después verifica el tamaño y el SHA-256 del archivo. Consulta cómo compartir el grabador al combinar clientes Lua y HTTP.

Endpoint de trazas de GPU Metal

En macOS, los motores de depuración exponen /profiler/gputrace para capturar trazas de GPU Metal. La ruta solo aparece en /openapi.json en macOS. La captura requiere el adaptador nativo Metal y METAL_CAPTURE_ENABLED=1 en el entorno de lanzamiento del motor. Si la captura no está disponible, la solicitud devuelve HTTP 501 con error.code: "gputrace_unsupported".

Las solicitudes aceptadas devuelven HTTP 200 con ok: true y un objeto data. La captura avanza de forma asíncrona: consulta GET hasta que data.state sea complete, canceled o failed. Los fallos del inicio nativo se notifican en data.error. La traza se escribe en el host del motor. Consulta la guía de captura de trazas de GPU Metal para ver comandos de lanzamiento, descubrimiento de compatibilidad, ejemplos de captura y cómo abrir el resultado en Xcode.

Rutas de runtime definidas por extensiones

En las builds de depuración, el SDK de extensiones nativas puede proporcionar acceso al servidor web del motor. Una extensión puede registrar un prefijo de ruta en ese servidor y exponer operaciones que dependan de datos de runtime.

Esto resulta útil para las herramientas de desarrollo porque una extensión puede compartir el servicio existente del motor en lugar de abrir otro servidor HTTP.

Una API de automatización de runtime definida por una extensión debe:

• utilizar un prefijo de ruta distintivo y versionado;
• exponer las funcionalidades compatibles;
• devolver errores estructurados;
• gestionar de forma explícita las funcionalidades no disponibles de la plataforma o el motor;
• limitar las operaciones al desarrollo y las pruebas;
• documentar si se omite en las builds de release.

Publicar operaciones de extensiones en OpenAPI

En el callback de inicialización de la aplicación de una extensión nativa, obtén el servidor mediante dmEngine::GetWebServer(app_params) y registra manejadores solo cuando el handle devuelto no sea nulo. Consulta el ciclo de vida de las extensiones para configurar el callback.

La sobrecarga de cuatro argumentos de dmWebServer::AddHandler() acepta un objeto Paths de OpenAPI 3.0.3 como cadena JSON. El objeto tiene las rutas como claves de primer nivel. Cada ruta debe comenzar con el prefijo registrado y no estar ya documentada por otro manejador. Usa esquemas en línea o referencias a rutas del documento resultante.

Por ejemplo, esta función auxiliar registra un callback y la descripción de su endpoint de estado:

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

Pasa un callback que implemente GET /example/v1/status y devuelva la respuesta text/plain documentada. El callback sigue siendo responsable de comprobar las rutas y los métodos de las solicitudes y de generar las respuestas. Comprueba el resultado del registro: los metadatos no válidos o en conflicto devuelven dmWebServer::RESULT_ERROR_INVAL.

El servidor conserva el puntero JSON sin copiar la cadena. Mantén su almacenamiento sin cambios y válido hasta que se elimine el manejador con dmWebServer::RemoveHandler() o se destruya el servidor. El array static const char del ejemplo cumple este requisito. Al eliminar el manejador también se eliminan sus rutas de las respuestas posteriores de /openapi.json.

La sobrecarga de tres argumentos dmWebServer::AddHandler(server, prefix, &params) sigue admitiéndose. Equivale a pasar 0 como cuarto argumento: el manejador se registra sin metadatos OpenAPI y se omite del descubrimiento.

Extensión Automation Bridge

La Automation Bridge oficial de Defold es una extensión nativa exclusiva para depuración basada en el servicio del motor. Registra una API de automatización de runtime versionada en:

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

Su API de runtime proporciona funcionalidades como la inspección de escenas y nodos, input, información de la pantalla, capturas de pantalla, grabación, información del ciclo de vida y sincronización opcional definida por la aplicación. Algunas de sus operaciones son:

Consulta la documentación de la API nativa y la documentación del helper de Python de la extensión para conocer la versión instalada en el proyecto.

Automation Bridge no expone su API HTTP ni su módulo Lua en las builds de release.

Clientes del editor y de runtime

Los helpers de Python de Automation Bridge ilustran la arquitectura de dos clientes. La función editor.open_project() devuelve un cliente de proyecto del editor y project.build_and_run() devuelve un cliente independiente del motor.

La separación entre project y game hace explícito el límite entre procesos. Las operaciones del editor permanecen en el servidor del editor, mientras que las observaciones y acciones sobre el juego activo permanecen en el servicio del motor.

from automation_bridge import editor

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

Limitaciones y seguridad

El servicio del motor y las rutas definidas por extensiones son herramientas de desarrollo y deben tratarse como tales.

Los scripts de runtime, las físicas, el input, los objetos creados dinámicamente y el renderizado específico de la plataforma requieren un motor en ejecución y deben verificarse mediante pruebas automatizadas de runtime.

• No publiques el servicio mediante un router, una interfaz pública o un túnel que no sea de confianza.
• No des por sentado que las rutas del servicio del motor requieren autenticación.
• Las rutas de runtime pueden variar según la versión de la extensión, la plataforma, el backend de gráficos y las funcionalidades del motor.
• Utiliza la negociación de versiones o funcionalidades para las API actualizadas definidas por extensiones.