Repository navigation
Godot Runtime MCP v3.2.0 — Runtime Black Box
This release integrates the opt-in Runtime Black Box functionality developed after v3.1.0 into the canonical Godot 4 .NET backend and native CLI/MCP host.
New capabilities
- Capture complete observable scene node topology, storage properties, structured Godot Variants and shared Resources into durable, hashed Scene Checkpoints.
- Query checkpoints after a game exits, reconstruct scenes with an isolated Godot Mono worker and export a verified native
.tscn, runtime diagnostics, external-dependency hashes and structured reports. - Record bounded runtime timelines with node/property changes, live process frame indices and loss accounting; start, inspect and stop recording through MCP/CLI.
- Explicitly opt in to observing supported Godot input or signal callbacks. Unicode/IME text and textual signal parameters are excluded/redacted. Text-editing focus blocks key capture when focus is observable; keycodes can otherwise still reveal entered characters. Do not enable input capture for untrusted or sensitive content.
- Explicitly opt in to saving bounded, private viewport PNG screenshots, and export a static HTML timeline gallery with integrity-checked embedded images. Dummy Headless rendering yields explicit unavailable markers.
- Run supported input metadata in an isolated, trusted original Godot project worker and compare reconstructed exported scene properties at observation points. Matched, divergent, inconclusive and failed reports remain inspectable offline.
Scope and limitations
- Replay is not generally deterministic. Input code, event ordering and relative process-frame offsets are best-effort. Unknown, skipped or redacted inputs are not replayed; a report of
matched_observed_statemeans only supported, serialized scene state matched at sampled boundaries, not CPU, physics, networking, animation, audio, GPU or private C# state. - Runtime workers load and execute the user's trusted Godot game code, including Autoloads. They do not sandbox untrusted projects and never attach to the original running game process.
- Timeline changes are between observations; transients between samples can be missed. Strict replay refuses dropped observations and unsupported callback types.
- External
res://Resources remain project dependencies, verified by file hashes. Unsupported native Resource cycles cause export failure with a report instead of an invalid success. - A screenshot may show a rendered frame preceding the sampled scene state. Screenshots, HTML exports, keycodes and event logs can be sensitive; they are off by default and stored with owner-private permissions on supported systems.
- Precompiled binaries are verified only on macOS arm64 and x64. No Linux, Windows, iOS or Android binary is claimed.
- Existing v3.1.0 binary and addon packages do not contain these features. Upgrade CLI/MCP and Godot addon together.
Reproducible validation
Run from this source checkout:
dotnet build Godot-Mcp.sln -c Release
dotnet run --project Tests/Tests.csproj -c Release
sh scripts/test-snapshot-headless.sh
sh scripts/test-timeline-headless.sh
sh scripts/test-replay-headless.sh
sh scripts/test-timeline-graphical.sh # requires logged-in macOS graphical desktop
sh scripts/publish-release.sh v3.2.0 osx-arm64
sh scripts/publish-release.sh v3.2.0 osx-x64
(cd dist/v3.2.0 && shasum -a 256 -c SHA256SUMS.txt)Verify the generated native CLI under dist/v3.2.0/.stage-osx-arm64/godot-runtime-cli with the MCP SDK client suite and native CLI end-to-end tests. The Release ZIP is regenerated from canonical addons/godot_mcp on each publish invocation; the example addon is synced via scripts/sync-example-addon.sh. Check the published Release assets and checksums independently before recommending a release to users.
User-facing commands
godot-runtime-cli godot-snapshot-capture --project /absolute/path/to/game
godot-runtime-cli godot-timeline-start --project /absolute/path/to/game --sample-every-frames 10 --max-samples 30 --capture-input true --capture-screenshots true
godot-runtime-cli godot-timeline-sessions --project /absolute/path/to/game
godot-runtime-cli godot-timeline-events --project /absolute/path/to/game --session-id SESSION_ID
godot-runtime-cli godot-timeline-export-gallery --project /absolute/path/to/game --session-id SESSION_ID
godot-runtime-cli godot-replay-start --project /absolute/path/to/game --session-id SESSION_ID
godot-runtime-cli godot-replay-status --project /absolute/path/to/game --job-id JOB_ID
godot-runtime-cli godot-replay-report --project /absolute/path/to/game --job-id JOB_IDThe command option names, required parameters and supported scenarios are discoverable via godot-runtime-cli help COMMAND.
v3.2.0 release-candidate acceptance (macOS, 2026-10-21)
- .NET Release solution build: 0 warnings / 0 errors; 132/132 independent host tests pass.
- Real Godot 4 .NET Headless suites: complete Scene Checkpoint export and strict failures; timeline, signal/input privacy, screenshot-unavailable handling and offline HTML; isolated input replay matching & deliberate divergence — all passed.
- Real macOS graphical render: 4/4 viewport PNG captures; decoded pixels contain the test scene's colored patch.
- Native AOT arm64 and x64: both executables ran locally, reported v3.2.0, and each passed 132/132 host tests through their respective native MCP implementations.
- Native arm64 CLI separately completed the real offline replay and timeline/gallery end-to-end probes.
- Both binaries and addon ZIP:
shasum -a 256 -c SHA256SUMS.txtsucceeded; ZIP integrity passed. - Native AOT package inherits external ASP.NET Core IL2026 / IL3053 trim-analysis and Apple linker deprecation warnings; standard .NET build had no warnings. These are documented and not treated as proof of guaranteed trim safety.
This section describes local validation; GitHub publication must be checked separately. If no new v3.2.0 assets are published, releases/latest may still point to v3.1.0.