Game Agent Harness

Game Agent Harness — это детерминированный тестовый раннер для игр на Godot. Он запускает демо в отдельном процессе, вызывает узкий доменный API, проверяет JSON-ответы, имитирует ввод, делает скриншоты и записывает диагностические артефакты.

Лицензировано под Apache License 2.0.

Репозиторий содержит оригинальную тактическую мини-игру 8x6. Она использует только примитивную отрисовку Godot; код и графика из референсных проектов не включены.

Требования

• Godot 4.6.3

• Python 3.11 или новее

• macOS, Linux или Windows с доступным дисплеем для тестов скриншотов и пользовательского интерфейса

Python-клиент и поставляемый аддон Godot закреплены на godot-e2e==1.2.0. Stdio MCP-фасад использует официальный Python SDK mcp==2.0.0.

Установка

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

Откройте examples/tactics_demo/project.godot в 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"
      ]
    }
  }
}

Сервер публикует четыре инструмента:

• list_scenarios выводит список YAML-файлов в каталоге scenarios/.

• run_scenario запускает один указанный сценарий.

• soak_scenario повторяет указанный сценарий с жёстким ограничением в 100 запусков.

• read_report читает report.json из одного непосредственного дочернего элемента artifacts/.

Слой MCP использует тот же ScenarioRunner, что и CLI. Он не открывает произвольные пути файловой системы, вызовы узлов 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 и smoke-сценарий. Он использует .venv/bin/python при наличии, иначе — python3. Установите GAME_AGENT_PYTHON=/path/to/python, чтобы выбрать другое установленное окружение. Пакет загружается напрямую из orchestrator/, но его сторонние зависимости должны быть установлены заранее.

VisualProbe

VisualProbe изолирован в examples/visual_probe_fixture — это фикстура Forward+, которая не влияет на рендерер Compatibility, используемый tactics_demo. Он предоставляет только зарегистрированную цель 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 плюс сопоставленные PNG в images/. Его метаданные должны соответствовать рендереру и разрешению захвата, прежде чем будет вычислена разница силуэтов. PNG и файлы базовых пакетов ограничены по размеру и читаются без перехода по символическим ссылкам.

Транспорт фикстуры прослушивает только loopback, требует e2e-токен для каждого запуска, принимает кадры размером до 64 МиБ и разрешает только вызовы VisualProbe на /root/GameAgent. Отсутствие установки Godot 4.6, GPU-окружения или визуальной зависимости является ошибкой конфигурации (код возврата 2), а не допустимой заменой успешного прохождения.

Референсные проекты

На дизайн повлияли:

• Grid Tactics Foundation

• Godot RPG Demo

• 2D Tactical RPG Demo

Никакой код или графика не были скопированы из этих проектов. См. THIRD_PARTY_NOTICES.md о поставляемой зависимости.