Game Agent Harness

Game Agent Harness es un ejecutor de pruebas determinista para juegos de Godot. Inicia la demo en un proceso separado, llama a una API de dominio limitada, valida respuestas JSON, simula entrada, captura capturas de pantalla y escribe artefactos de diagnóstico.

Licenciado bajo Apache License 2.0.

El repositorio contiene un micro-juego táctico original de 8x6. Utiliza únicamente dibujo primitivo de Godot; no se incluye código ni arte de proyectos de referencia.

Requisitos

• Godot 4.6.3

• Python 3.11 o más reciente

• macOS, Linux o Windows con una pantalla disponible para pruebas de captura de pantalla y de interfaz de usuario.

El cliente Python y el complemento de Godot incluido están fijados a godot-e2e==1.2.0. La fachada MCP stdio utiliza el SDK oficial de Python mcp==2.0.0.

Instalación

python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'

Abre examples/tactics_demo/project.godot en Godot para jugar la demo manualmente. El servidor de automatización permanece inactivo en una sesión de juego normal.

Ejecutar escenarios

.venv/bin/python -m game_agent_harness run scenarios/tactics_smoke.yaml
.venv/bin/python -m game_agent_harness run scenarios/tactics_full.yaml
.venv/bin/python -m game_agent_harness run scenarios/tactics_ui.yaml
.venv/bin/python -m game_agent_harness soak scenarios/tactics_smoke.yaml --runs 100

El código de salida 0 significa aprobado, 1 significa que falló una aserción del juego, y 2 significa un error de configuración, proceso, transporte o protocolo.

Cada ejecución crea artifacts/<run-id>/ con el escenario resuelto, comandos, eventos, estados, capturas de pantalla, registros de Godot capturados e informes en JSON y Markdown. Entrega report.md y sus archivos JSONL adyacentes a Codex al diagnosticar una ejecución fallida.

Servidor MCP

Inicia el servidor stdio local con una ruta de espacio de trabajo absoluta:

.venv/bin/game-agent-harness-mcp \
  --workspace-root /absolute/path/to/game-agent-codex

Un host MCP puede iniciarlo con esta configuración:

{
  "mcpServers": {
    "game-agent-harness": {
      "command": "/absolute/path/to/game-agent-codex/.venv/bin/game-agent-harness-mcp",
      "args": [
        "--workspace-root",
        "/absolute/path/to/game-agent-codex"
      ]
    }
  }
}

El servidor publica cuatro herramientas:

• list_scenarios enumera los archivos YAML en scenarios/.

• run_scenario ejecuta un escenario listado.

• soak_scenario repite un escenario listado, con un límite máximo de 100 ejecuciones.

• read_report lee report.json de un hijo directo de artifacts/.

La capa MCP utiliza el mismo ScenarioRunner que la CLI. No expone rutas arbitrarias del sistema de archivos, llamadas a nodos de Godot, escrituras de propiedades ni una herramienta de edición de código. Los proyectos de escenario y los artefactos generados deben permanecer dentro del espacio de trabajo configurado.

API de Game Agent

/root/GameAgent expone seis métodos durante una sesión --e2e:

agent_get_manifest()
agent_reset(options)
agent_get_state()
agent_list_actions()
agent_perform_action(request)
agent_get_events(after_sequence)

El contrato 0.1.0 está definido por los esquemas en protocol/. Una solicitud de acción lleva un request_id único, el expected_revision del llamante, un nombre de acción y sus argumentos. Una revisión obsoleta o una acción no válida se rechazan sin cambiar el estado del juego.

Para añadir una acción:

1. Implementa la validación y el comportamiento en TacticsGameController.perform_action.

2. Añade su esquema de argumentos a GameAgent.agent_get_manifest.

3. Devuelve un código de error estable sin incrementar revision en caso de fallo.

4. Añade una prueba de dominio y un paso de escenario.

La CLI deliberadamente no expone llamadas arbitrarias a nodos de Godot.

Verificación

scripts/verify.sh

El script ejecuta pruebas de dominio de Godot sin interfaz gráfica, pruebas unitarias de Python, Ruff, mypy y el escenario de humo. Usa .venv/bin/python si está disponible; de lo contrario, python3. Establece GAME_AGENT_PYTHON=/path/to/python para seleccionar otro entorno instalado. El paquete se carga directamente desde orchestrator/, pero sus dependencias de terceros deben instalarse primero.

VisualProbe

VisualProbe está aislado en examples/visual_probe_fixture, un fixture Forward+ que no afecta al renderizador Compatibility utilizado por tactics_demo. Expone solo el objetivo registrado fixture y las vistas ortográficas front, back, left, right y top. Los pases admitidos son beauty, silhouette, depth, normal, object_id y wireframe.

Instala la pila de imágenes opcional y usa el verificador dedicado en un ejecutor con GPU:

.venv/bin/pip install -e '.[dev,visual]'
scripts/verify-visual.sh

Las ejecuciones visuales almacenan PNGs en visual/targets/<target>/; las capturas de variantes usan visual/targets/<target>/variants/<id>/. Un paquete de línea base se almacena en scenarios/baselines/<id>/ y contiene metadata.json más los PNG mapeados en images/. Sus metadatos deben coincidir con el renderizador y la resolución de captura antes de que se calcule una diferencia de silueta. Los PNG y los archivos de línea base tienen un límite de tamaño y se leen sin seguir enlaces simbólicos.

El transporte del fixture escucha solo en loopback, requiere el token e2e de cada ejecución, acepta tramas de hasta 64 MiB y permite únicamente llamadas a VisualProbe en /root/GameAgent. Una instalación faltante de Godot 4.6, un entorno GPU o una dependencia visual es un error de configuración (código de salida 2), nunca un sustituto que pase.

Proyectos de referencia

El diseño se basó en:

• Grid Tactics Foundation

• Godot RPG Demo

• 2D Tactical RPG Demo

No se copió código ni arte de estos proyectos. Consulta THIRD_PARTY_NOTICES.md para la dependencia incluida.