FFVII-Rebirth-Cait-GPT

A local, bounded game-playing harness for FINAL FANTASY VII REBIRTH on Windows. Connect an MCP-capable agent to game telemetry, navigation, exploration, combat, menus, save handling, and Queen's Blood tools. The model chooses its actions; the harness validates observations and sends bounded controller input.

Contributions target master; see contributing for scope, privacy and the owner-reviewed merge workflow.

Start in simulation

Requires Python 3.11 or newer and Git. Run from this repository:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e "Tools/ff7r-codex-agent-mvp[dev]"
.\.venv\Scripts\ff7r-agent.exe observe
.\.venv\Scripts\ff7r-agent.exe demo
.\Start-CaitGPT.ps1

The launcher starts the MCP server at http://127.0.0.1:8766/mcp in simulation. It never launches the game, installs probes, loads a save, starts OBS, or sends real input. Configure your MCP client to use that loopback URL. The server must run from a clean Git checkout; branch and source identity checks stay enabled. For a feature branch use -ExpectedRef <branch> -ExpectedCommit <full SHA>.

For a foreground stdio server, set FF7R_INPUT_BACKEND=simulation and run .venv\Scripts\ff7r-agent-mcp.exe.

Related MCP server: Godot Agent Loop

Real game setup

Read setup and the component READMEs before enabling real input. Use your own legally installed game, compatible UE4SS SDK/runtime, and controller mapping. The native probes are source only; building or installing them is a separate explicit step. No game binaries, UE4SS binaries, saves, account data, recordings, screenshots, topology caches, or credentials are bundled.

# After installing and verifying the matching telemetry probes:
.\Start-CaitGPT.ps1 -InputBackend windows `
  -TelemetryFile 'C:\CaitGPT\Telemetry\state.json' `
  -GameExecutable 'C:\Games\FINAL FANTASY VII REBIRTH\End\Binaries\Win64\ff7rebirth_.exe'

Opening a control session and loading a save are separate MCP actions. Check observed outcomes, poll asynchronous jobs to completion, and stop on ambiguous placement, telemetry, process, or input state. Never overwrite occupied saves.

Included components

• Tools/ff7r-codex-agent-mvp: Python agent, MCP runtime, safety/input brokers, navigation and exploration, battle/menu/save tools, Queen's Blood, tests and benchmarks.

• Tools/ff7r-telemetry-exporter: read-only gameplay telemetry and Queen's Blood adapters.

• Tools/ff7r-navigation-probe: Lua and native navigation probes plus build/install helpers.

• Tools/ff7r-map-surface-probe: optional legacy read-only map probe.

• Tools/ff7r-navigation-validation: independent offline route validator.

• Tools/ff7r-route-following-simulator: offline traversal simulator and replay fixtures.

• Tools/ff7r-first-live-route-selection: offline route candidate selection using your own topology.

• ProjectKnowledge/Current: gameplay catalogues and the stable operation contract only.

Optional speech, event and recording receipts are lightweight integration hooks. The OBS monitor, narrator worker, video editor, clipping, thumbnails, YouTube uploader, channel automation, modding tools and Unreal editor project are excluded. The old session_startup module requires an external compatible service manager; use Start-CaitGPT.ps1 for this standalone distribution. The live Queen's Blood campaign still requires verified external driver/stream/save receipts; offline simulation does not award live progress. See extraction notes.

Tests

.\.venv\Scripts\python.exe -m pytest Tools/ff7r-codex-agent-mvp/tests -q
Push-Location Tools/ff7r-route-following-simulator
..\..\.venv\Scripts\python.exe -m unittest discover -s tests -v
Pop-Location

CI runs offline tests only. Tests requiring the excluded owner's raw topology, historical readiness matrix, external SDK/header dumps or OBS service manager are explicitly skipped when those optional inputs are absent. Native or live game compatibility must be validated separately; simulation is not native proof. See export validation for the checks performed on this copy.

License

Original harness code is available under the MIT license. Game-derived identifiers and catalogue/fixture data retain their respective owners' rights; see third-party notices. This project is unofficial and is not affiliated with Square Enix or OpenAI.

Read the security policy and source security review before enabling real input or preparing a public release.