game-agent-harness

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는 구성, 프로세스, 전송 또는 프로토콜 오류를 의미합니다.

모든 실행은 해석된 시나리오, 명령, 이벤트, 상태, 스크린샷, 캡처된 Godot 로그, JSON 및 Markdown 형식의 보고서를 포함하는 artifacts/<run-id>/를 생성합니다. 실패한 실행을 진단할 때 Codex에 report.md와 그와 인접한 JSONL 파일을 제공하세요.

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

서버는 네 가지 도구를 제공합니다:

• list_scenarios는 scenarios/ 아래의 YAML 파일을 나열합니다.

• run_scenario는 나열된 하나의 시나리오를 실행합니다.

• soak_scenario는 나열된 시나리오를 최대 100회 실행으로 반복합니다.

• read_report는 artifacts/의 직접 하위 항목 하나에서 report.json을 읽습니다.

MCP 계층은 CLI와 동일한 ScenarioRunner를 사용합니다. 임의의 파일시스템 경로, Godot 노드 호출, 속성 쓰기 또는 코드 편집 도구를 노출하지 않습니다. 시나리오 프로젝트와 생성된 아티팩트는 구성된 작업 영역 안에 있어야 합니다.

Game Agent API

/root/GameAgent은 --e2e 세션 동안 여섯 가지 메서드를 노출합니다:

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

비주얼 실행은 visual/targets/<target>/ 아래에 PNG를 저장합니다. 변형 캡처는 visual/targets/<target>/variants/<id>/를 사용합니다. 기준선 패키지는 scenarios/baselines/<id>/ 아래에 저장되며 metadata.json과 images/의 매핑된 PNG를 포함합니다. 실루엣 차이를 계산하기 전에 해당 메타데이터가 캡처 렌더러 및 해상도와 일치해야 합니다. PNG와 기준선 파일은 크기가 제한되며 심볼릭 링크를 따르지 않고 읽습니다.

픽스처 전송은 루프백에서만 수신하고, 실행별 e2e 토큰을 요구하며, 최대 64MiB 프레임을 허용하고, /root/GameAgent에서 VisualProbe 호출만 허용합니다. Godot 4.6 설치, GPU 환경 또는 비주얼 종속성이 없으면 구성 오류(종료 코드 2)이며, 통과로 대체되지 않습니다.

참조 프로젝트

디자인은 다음에서 참고했습니다:

• Grid Tactics Foundation

• Godot RPG Demo

• 2D Tactical RPG Demo

이 프로젝트에서 코드나 아트를 복사하지 않았습니다. 번들된 종속성은 THIRD_PARTY_NOTICES.md를 참조하세요.