ue5-gameplay-mcp

MCP-сервер, который играет в запущенные игры Unreal Engine 5. Он принимает ввод с виртуального геймпада, клавиатуры и мыши, а отдаёт скриншоты, строки логов и состояние UMG.

Это не плагин движка, а клиент. Два плагина уже выполняют работу внутри движка, и каждый держит собственный порт. Этот сервер подключается к обоим и предоставляет их как единый интерфейс инструментов.

В оба плагина был добавлен небольшой объём C++ кода для этого сервера. Они остаются независимыми и сохраняют собственные протоколы. Дополнения обратно совместимы, поэтому даже старые клиенты могут общаться с пересобранной игрой:

• FImageMeta.SourceSize — размер игрового заднего буфера. Он упакован в область, ранее бывшую зарезервированной, чтобы сохранить размер структуры в 24 байта. Благодаря этому клиент может сопоставлять точки на уменьшенном захвате экрана с пикселями окна.

• CMD_GET_GAME_STATE (520) и IRemoteGameStateProvider — подробности ниже.

Установка

cd ue5_gameplay_mcp
uv sync

Требуется MCP Python SDK v2 (mcp.server.MCPServer).

Related MCP server: VERA MCP Server

Запуск

Сначала запустите игру. В этом проекте Game-таргет в некученном проекте немедленно завершается, поэтому автономная игра запускается из бинарника редактора:

"C:/Program Files/Epic Games/UE_5.8/Engine/Binaries/Win64/UnrealEditor.exe" "<PATH>/MyProject.uproject" -game -windowed -resx=1280 -resy=720 -log -nosplash

Затем зарегистрируйте сервер. Лежащий в корне проекта .mcp.json уже делает это, поэтому Claude Code автоматически подхватывает его. Ручная команда эквивалентна следующей:

claude mcp add ue5-gameplay -- uv run --directory <PATH>/ue5_gameplay_mcp -m ue5_gameplay_mcp

Сервер подключается лениво, поэтому фактический порядок запуска не важен. Даже если он запущен раньше игры, подключение произойдёт при первом вызове инструмента.

Опционально: --host, --console-port, --capture-port, --format, --quality, --max-size, --grid-step, --transport streamable-http --mcp-port 14102.

Инструменты

Сессия — game_connect, game_status, game_reset_input

Наблюдение — game_observe, game_state, game_log, game_wait_for_log

Действия — game_pad, game_pad_sequence, game_key, game_mouse, game_console, game_time_scale

UMG — game_ui_dump, game_ui_click, game_ui_focus

Как устроен API и почему

Пока агент совершает обход между сервером и собой, проходят секунды, а игра работает на 60 Гц. Поэтому покадровые действия нереалистичны, и приняты следующие соглашения:

• Все Endpoint инструменты принимают duration и выполняют локально последовательность нажатие/удержание/отпускание в темпе, соответствующем соединению. Один раунд передаёт не один кадр, а одно намерение (интент).

• Инструменты действий по умолчанию выполняют наблюдение. game_pad(ly=1.0, duration=0.5) продвигает вперёд и возвращает результирующий кадр. Так тратится вдвое меньше раунд-трипов, чем при раздельном действии и подтверждении.

• game_pad_sequence сворачивает целую комбинацию в один вызов, когда важнее тайминг ввода, чем подтверждение между отдельными вводами.

• game_time_scale(0.2) позволяет выиграть время внутри игры, когда требуется точность до мгновения.

• hold=True продолжает применять ввод между ходами абаложения, чтобы персонаж двигался, пока агент размышляет. Сбрасывается командой game_reset_input.

Числа, а не пиксели

game_state возвращает уровень, игровое время, паузу/замедление времени, трансформ и скорость пешки игрока, режим перемещения, камеру, а также дистанцию до ближайшего актёра и нормализованную экранную позициюs. Это те же координаты от 0 до 1, которые принимает game_mouse, поэтому цель из отчёта о состоянии можно сразу взять на прицел. Это стоит лишь малую долю обработки изображения и исключает неверное чтение чисел на HUD.

game_observe(state=True) встраивает это в наблюдение, а game_pad(..., state=True) — в действие, поэтому перемещение и подтверждение по-прежнему укладываются в один раунд-трип.

В реальных картах большинство ближайших актёров — фоновые объекты, поэтому в отчёт также включается class_counts — сводка по всем объектам в радиусе. Достаточно прочитать его один раз, а затем отфильтровать с помощью class_filter="Enemy".

Добавление уникальных чисел игры

Встроенному отчёту не требуется игровой код. Чтобы получить в него только данные этого проекта — здоровье, очки, флаги квестов и т.п. — реализуйте IRemoteGameStateProvider на любом актёре (Plugins/RemoteConsole2/Source/RemoteConsole2/RemoteGameState.h) и верните строку с JSON-объектом:

FString AMyGameMode::GetRemoteGameState_Implementation()
{
    return FString::Printf( TEXT("{\"score\":%d,\"wave\":%d}"), Score, Wave );
}

Это BlueprintNativeEvent, поэтому переопределить можно даже в проекте без C++, только на Blueprint. Все возвращённые значения сохраняются в разделе custom под ключом с именем актёра. Провайдеры собираются независимо от фильтра по дистанции, поэтому скоркипер, размещённый в начале координат, тоже отправляет свой отчёт. Невалидный JSON не отбрасывается, а передаётся как строка, поэтому даже простой отладочный Printf на этапе запуска оказывается полезен.

Три способа взаимодействия с ками (в порядке предпочтительности)

1. game_ui_dump + game_ui_click — точно и быстро, но распознаёт только виджеты, зарегистрированные через UMG. В играх с кастомным UI на Slate ничего не возвращается, но инструмент сообщает об этом сам, а не зависает.

2. Навигация с помощью панели — game_pad(buttons=["DOWN"]), game_pad(buttons=["A"]). Работает почти в любой игре.

3. Смотреть и нажимать — game_observe(grid=True) накладывает размеченную координатную сетку сюземента варий 0–1. Считайте цель с изображения и передайте те же координаты в game_mouse(x=..., y=...). Он безразличен к разрешению и работает независимо от того, как построен UI.

Условности

• Стик следует спецификации UE: ly=+1 — движение вперёд. (В сетевом протоколе ось Y инвертируется, но здесь она снова корректируется, поэтому API инструмента соответствует собственной карте осей игры.)

• Координаты мыши нормализованы от 0 до 1 с началом координат в левом верхнем углу и переводятся в пиксели через фактический размер заднего буфера игры. Захват сообщает изменённые размеры, поэтому этот размер опрашивается отдельно.

• game_observe возвращает только новые строки лога с момента последнего наблюдения, thereby при длинных сессиях тот же output не отправляет repetedly.

Известные проproblems and недоделанный

• Когда игра хостится в бинарнике редактора, консольные команды маршрутэтся через Python. FGameOnline a.sighty=... Hmm.

Wait I made a weird typo. Need fix.

Let's rewrite that bullet carefully:

• Когда игра хостируется бинарником редактора, консольные команды маршрутизируются через Python. FGameAccessAPI::ExecConsoleCommand диспетчётся реализацию IConsoleCommandExecutor[0], но, если загружен плагин Python для редактора, этот слот занимает Python, а не Cmd. Поэтому даже stat fps возвращается как SyntaxError. Сервер один раз при первом использовании выполняет проверку и при обнаружении оборачивает команду в unreal.SystemLibrary.execute_console_command. В упакованных сборках исполнителя Python нет, поэтому обход не требуется. Переопределение возможно через game_console(via="cmd").

• Клики по экрану предполагают, что захват полностью заполняет окно игры. Это верно для -game -windowed. В полноэкранных режимах с letterboxing внутри сообщаемого размера исходникаТакже содержатся чёрные полосы, и сопоставление поедет.

• game_state при каждом выозе traversы все актёры levelа. For обычнй карты это допустимо, но в streaming-style открыт мирах потребуетссясь пространственный запрос вместо TActorIterator.

Тest

uv run test/smoke_test.py

Общается с игрой напрямую и записывает smoke_*.jpg, чтобы вы могли глазами пров comport захват и наложенную сетку.

uv run test/mcp_client_test.py

Запускает сервер как настоящий MCP-клиент через stdio и прогоняет/проверяет все инструменты, включая сценарии с ошибками.