Game Agent Harness

Game Agent Harness is a deterministic test runner for Godot games. It launches the demo in a separate process, calls a narrow domain API, validates JSON responses, simulates input, captures screenshots, and writes diagnostic artifacts.

Licensed under the Apache License 2.0.

The repository contains an original 8x6 tactics micro-game. It uses primitive Godot drawing only; no reference-project code or artwork is included.

Requirements

• Godot 4.6.3

• Python 3.11 or newer

• macOS, Linux, or Windows with a display available for screenshot and UI tests

The Python client and vendored Godot addon are both pinned to godot-e2e==1.2.0. The stdio MCP facade uses the official mcp==2.0.0 Python SDK.

Install

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

Open examples/tactics_demo/project.godot in Godot to play the demo manually. The automation server remains dormant in a normal game session.

Run scenarios

.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 means pass, 1 means a game assertion failed, and 2 means a configuration, process, transport, or protocol error.

Every run creates artifacts/<run-id>/ with the resolved scenario, commands, events, states, screenshots, captured Godot logs, and reports in JSON and Markdown. Give report.md and its adjacent JSONL files to Codex when diagnosing a failed run.

MCP server

Start the local stdio server with an absolute workspace path:

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

An MCP host can launch it with this configuration:

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

The server publishes four tools:

• list_scenarios lists YAML files under scenarios/.

• run_scenario runs one listed scenario.

• soak_scenario repeats a listed scenario, with a hard limit of 100 runs.

• read_report reads report.json from one direct child of artifacts/.

The MCP layer uses the same ScenarioRunner as the CLI. It does not expose arbitrary filesystem paths, Godot node calls, property writes, or a code-editing tool. Scenario projects and generated artifacts must stay inside the configured workspace.

Game Agent API

/root/GameAgent exposes six methods during an --e2e session:

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

The 0.1.0 contract is defined by the schemas under protocol/. An action request carries a unique request_id, the caller's expected_revision, an action name, and its arguments. A stale revision or invalid action is rejected without changing game state.

To add an action:

1. Implement validation and behavior in TacticsGameController.perform_action.

2. Add its argument schema to GameAgent.agent_get_manifest.

3. Return a stable error code without incrementing revision on failure.

4. Add a domain test and a scenario step.

The CLI deliberately does not expose arbitrary Godot node calls.

Verify

scripts/verify.sh

The script runs headless Godot domain tests, Python unit tests, Ruff, mypy, and the smoke scenario. It uses .venv/bin/python when available, otherwise python3. Set GAME_AGENT_PYTHON=/path/to/python to select another installed environment. The package is loaded directly from orchestrator/, but its third-party dependencies must be installed first.

VisualProbe

VisualProbe is isolated in examples/visual_probe_fixture, a Forward+ fixture that does not affect the Compatibility renderer used by tactics_demo. It exposes only the registered target fixture and orthographic views front, back, left, right, and top. The supported passes are beauty, silhouette, depth, normal, object_id, and wireframe.

Install the optional image stack and use the dedicated verifier on a GPU runner:

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

Visual runs store PNGs beneath visual/targets/<target>/; variant captures use visual/targets/<target>/variants/<id>/. A baseline package is stored under scenarios/baselines/<id>/ and contains metadata.json plus mapped PNGs in images/. Its metadata must match the capture renderer and resolution before a silhouette diff is calculated. PNGs and baseline files are size-bounded and are read without following symlinks.

The fixture transport listens only on loopback, requires the per-run e2e token, accepts frames up to 64 MiB, and permits only VisualProbe calls on /root/GameAgent. A missing Godot 4.6 installation, GPU environment, or visual dependency is a configuration error (exit code 2), never a passing substitute.

Reference projects

The design was informed by:

• Grid Tactics Foundation

• Godot RPG Demo

• 2D Tactical RPG Demo

No code or art was copied from these projects. See THIRD_PARTY_NOTICES.md for the vendored dependency.