Game Agent Harness

Game Agent Harness は、Godot ゲーム用の決定論的テストランナーです。デモを別プロセスで起動し、限定されたドメイン API を呼び出し、JSON レスポンスを検証し、入力をシミュレートし、スクリーンショットを撮影し、診断アーティファクトを書き出します。

Apache License 2.0 に基づいてライセンスされています。

このリポジトリには、オリジナルの 8x6 タクティクスマイクロゲームが含まれています。Godot のプリミティブ描画のみを使用しており、参照プロジェクトのコードやアートワークは含まれていません。

要件

• Godot 4.6.3

• Python 3.11 以降

• スクリーンショットと UI テスト用にディスプレイが利用可能な macOS、Linux、Windows

Python クライアントとベンダリングされた Godot アドオンは、どちらも godot-e2e==1.2.0 に固定されています。stdio MCP ファサードは、公式の mcp==2.0.0 Python SDK を使用します。

インストール

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

Godot で examples/tactics_demo/project.godot を開いて、デモを手動でプレイします。自動化サーバーは、通常のゲームセッションでは休止状態のままです。

シナリオの実行

.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

終了コード 0 は成功、1 はゲームのアサーション失敗、2 は設定、プロセス、トランスポート、またはプロトコルのエラーを意味します。

実行ごとに artifacts/<run-id>/ が作成され、解決済みのシナリオ、コマンド、イベント、状態、スクリーンショット、取得した Godot ログ、JSON および Markdown のレポートが格納されます。失敗した実行を診断するときは、report.md とその隣接する JSONL ファイルを Codex に渡してください。

MCP サーバー

絶対パスのワークスペースを指定して、ローカル stdio サーバーを起動します:

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

MCP ホストは、次の構成で起動できます:

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

サーバーは4つのツールを公開します:

• list_scenarios は scenarios/ 配下の YAML ファイルを一覧表示します。

• run_scenario は一覧にある1つのシナリオを実行します。

• soak_scenario はリストされたシナリオを繰り返し実行します。上限は100回です。

• read_report は artifacts/ の直接の子ディレクトリの1つから report.json を読み取ります。

MCP レイヤーは CLI と同じ ScenarioRunner を使用します。任意のファイルシステムパス、Godot ノード呼び出し、プロパティ書き込み、またはコード編集ツールは公開されません。シナリオプロジェクトと生成されたアーティファクトは、設定されたワークスペース内に留まる必要があります。

Game Agent API

/root/GameAgent は --e2e セッション中に6つのメソッドを公開します:

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

0.1.0 コントラクトは protocol/ 配下のスキーマで定義されています。アクションリクエストには、一意の request_id、呼び出し元の expected_revision、アクション名、およびその引数が含まれます。古いリビジョンまたは不正なアクションは、ゲーム状態を変更せずに拒否されます。

アクションを追加するには:

1. TacticsGameController.perform_action に検証と動作を実装します。

2. 引数スキーマを GameAgent.agent_get_manifest に追加します。

3. 失敗時に revision を増やさず、安定したエラーコードを返します。

4. ドメインテストとシナリオステップを追加します。

CLI は意図的に、任意の Godot ノード呼び出しを公開していません。

検証

scripts/verify.sh

このスクリプトは、ヘッドレス Godot ドメインテスト、Python ユニットテスト、Ruff、mypy、スモークシナリオを実行します。利用可能な場合は .venv/bin/python を、それ以外の場合は python3 を使用します。別のインストール済み環境を選択するには、GAME_AGENT_PYTHON=/path/to/python を設定します。パッケージは orchestrator/ から直接読み込まれますが、サードパーティの依存関係を先にインストールする必要があります。

VisualProbe

VisualProbe は examples/visual_probe_fixture に分離されています。これは tactics_demo で使用される Compatibility レンダラーに影響を与えない Forward+ フィクスチャです。登録されたターゲット fixture と、正投影ビュー front、back、left、right、top のみを公開します。サポートされているパスは beauty、silhouette、depth、normal、object_id、wireframe です。

オプションのイメージスタックをインストールし、GPU ランナー上で専用の検証ツールを使用します:

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

ビジュアル実行は PNG を visual/targets/<target>/ 配下に保存し、バリアントキャプチャは visual/targets/<target>/variants/<id>/ を使用します。ベースライン パッケージは scenarios/baselines/<id>/ に保存され、metadata.json と images/ 内のマップされた PNG が含まれます。シルエット差分を計算する前に、そのメタデータがキャプチャのレンダラーと解像度に一致している必要があります。PNG とベースラインファイルはサイズ制限があり、シンボリックリンクをたどらずに読み取られます。

フィクスチャのトランスポートはループバックのみでリッスンし、実行ごとの e2e トークンを必要とし、最大 64 MiB のフレームを受け入れ、/root/GameAgent に対する VisualProbe 呼び出しのみを許可します。Godot 4.6 のインストール、GPU 環境、またはビジュアル依存関係が欠落している場合は、設定エラー（終了コード 2）であり、合格の代替にはなりません。

参考プロジェクト

設計は以下から影響を受けています:

• Grid Tactics Foundation

• Godot RPG Demo

• 2D Tactical RPG Demo

これらのプロジェクトからコードやアートはコピーされていません。ベンダリングされた依存関係については、THIRD_PARTY_NOTICES.md を参照してください。