Game Agent Harness

Game Agent Harness ist ein deterministischer Test-Runner für Godot-Spiele. Es startet die Demo in einem separaten Prozess, ruft eine eng gefasste Domänen-API auf, validiert JSON-Antworten, simuliert Eingaben, erfasst Screenshots und schreibt Diagnose-Artefakte.

Lizenziert unter der Apache License 2.0.

Das Repository enthält ein originelles 8x6-Taktik-Microgame. Es verwendet ausschließlich primitive Godot-Zeichenfunktionen; es sind keinerlei Code oder Grafiken aus Referenzprojekten enthalten.

Anforderungen

• Godot 4.6.3

• Python 3.11 oder neuer

• macOS, Linux oder Windows mit einem verfügbaren Display für Screenshot- und UI-Tests

Der Python-Client und das mitgelieferte Godot-Addon sind beide auf godot-e2e==1.2.0 festgelegt. Die Stdio-MCP-Fassade verwendet das offizielle Python-SDK mcp==2.0.0.

Installation

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

Öffnen Sie examples/tactics_demo/project.godot in Godot, um die Demo manuell zu spielen. Der Automatisierungsserver bleibt in einer normalen Spielsitzung inaktiv.

Szenarien ausführen

.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

Exit-Code 0 bedeutet bestanden, 1 bedeutet, dass eine Spiel-Assertion fehlgeschlagen ist, und 2 bedeutet einen Konfigurations-, Prozess-, Transport- oder Protokollfehler.

Jeder Lauf erstellt artifacts/<run-id>/ mit dem aufgelösten Szenario, Befehlen, Ereignissen, Zuständen, Screenshots, erfassten Godot-Protokollen sowie Berichten in JSON und Markdown. Geben Sie report.md und die zugehörigen JSONL-Dateien an Codex, wenn Sie einen fehlgeschlagenen Lauf diagnostizieren.

MCP-Server

Starten Sie den lokalen Stdio-Server mit einem absoluten Arbeitsbereichspfad:

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

Ein MCP-Host kann ihn mit dieser Konfiguration starten:

{
  "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"
      ]
    }
  }
}

Der Server stellt vier Tools bereit:

• list_scenarios listet YAML-Dateien unter scenarios/ auf.

• run_scenario führt ein aufgelistetes Szenario aus.

• soak_scenario wiederholt ein aufgelistetes Szenario, mit einer strikten Obergrenze von 100 Läufen.

• read_report liest report.json aus einem direkten Kind von artifacts/.

Die MCP-Schicht verwendet denselben ScenarioRunner wie das CLI. Sie legt keine beliebigen Dateisystempfade, Godot-Knotenaufrufe, Eigenschaftsschreibvorgänge oder ein Code-Editierwerkzeug offen. Szenarioprojekte und generierte Artefakte müssen innerhalb des konfigurierten Arbeitsbereichs bleiben.

Game Agent API

/root/GameAgent stellt während einer --e2e-Sitzung sechs Methoden bereit:

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

Der Vertrag 0.1.0 wird durch die Schemas unter protocol/ definiert. Eine Aktionsanforderung enthält eine eindeutige request_id, die expected_revision des Aufrufers, einen Aktionsnamen und dessen Argumente. Eine veraltete Revision oder eine ungültige Aktion wird abgelehnt, ohne den Spielzustand zu ändern.

So fügen Sie eine Aktion hinzu:

1. Implementieren Sie Validierung und Verhalten in TacticsGameController.perform_action.

2. Fügen Sie ihr Argumentschema zu GameAgent.agent_get_manifest hinzu.

3. Geben Sie bei einem Fehler einen stabilen Fehlercode zurück, ohne revision zu erhöhen.

4. Fügen Sie einen Domänentest und einen Szenarioschritt hinzu.

Das CLI legt bewusst keine beliebigen Godot-Knotenaufrufe offen.

Verifizieren

scripts/verify.sh

Das Skript führt Headless-Godot-Domänentests, Python-Unit-Tests, Ruff, mypy und das Smoke-Szenario aus. Es verwendet .venv/bin/python, falls verfügbar, andernfalls python3. Setzen Sie GAME_AGENT_PYTHON=/path/to/python, um eine andere installierte Umgebung auszuwählen. Das Paket wird direkt aus orchestrator/ geladen, aber seine Drittanbieterabhängigkeiten müssen zuerst installiert werden.

VisualProbe

VisualProbe ist in examples/visual_probe_fixture isoliert, einer Forward+-Fixture, die den von tactics_demo verwendeten Compatibility-Renderer nicht beeinflusst. Sie stellt nur das registrierte Ziel fixture und die orthografischen Ansichten front, back, left, right und top bereit. Die unterstützten Passes sind beauty, silhouette, depth, normal, object_id und wireframe.

Installieren Sie den optionalen Bild-Stack und verwenden Sie den dedizierten Verifizierer auf einem GPU-Runner:

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

Visuelle Läufe speichern PNGs unter visual/targets/<target>/; Variantenaufnahmen verwenden visual/targets/<target>/variants/<id>/. Ein Baseline-Paket wird unter scenarios/baselines/<id>/ gespeichert und enthält metadata.json sowie zugeordnete PNGs in images/. Seine Metadaten müssen mit dem Aufnahme-Renderer und der Auflösung übereinstimmen, bevor ein Silhouetten-Diff berechnet wird. PNGs und Baseline-Dateien sind größenbegrenzt und werden ohne Verfolgen von Symlinks gelesen.

Der Fixture-Transport lauscht nur auf Loopback, erfordert das e2e-Token pro Lauf, akzeptiert Frames bis zu 64 MiB und erlaubt nur VisualProbe-Aufrufe auf /root/GameAgent. Eine fehlende Godot-4.6-Installation, GPU-Umgebung oder visuelle Abhängigkeit ist ein Konfigurationsfehler (Exit-Code 2) und niemals ein Ersatz, der als bestanden gilt.

Referenzprojekte

Das Design wurde durch folgende Projekte inspiriert:

• Grid Tactics Foundation

• Godot RPG Demo

• 2D Tactical RPG Demo

Aus diesen Projekten wurde weder Code noch Kunst kopiert. Siehe THIRD_PARTY_NOTICES.md für die mitgelieferte Abhängigkeit.