Godot Runtime MCP v3.2.0 — Runtime Black Box

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_state means 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_ID

The 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.txt succeeded; 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.

Godot Runtime MCP v3.1.0

Godot Runtime MCP v3.1.0

Runtime inspection and control for Godot 4 .NET/C#, with 46 runtime tools + 5 management tools.

Highlights

• Standalone godot-runtime-cli, with typed named options and built-in --help / tools --search.
• Official Model Context Protocol C# SDK for MCP stdio and authenticated loopback Streamable HTTP.
• AI-ready single-file Agent Skill: give the Skill URL to a terminal-enabled assistant to bootstrap and configure the CLI.
• Strongly typed transport/installer contracts and independently discoverable Godot game instances.
• macOS ARM64/x64 Native AOT binaries; no .NET SDK or runtime needed to launch the CLI.

Downloads

• godot-runtime-tools-v3.1.0-osx-arm64.tar.gz — Apple Silicon CLI + MCP stdio server
• godot-runtime-tools-v3.1.0-osx-x64.tar.gz — Intel Mac CLI + MCP stdio server
• godot-runtime-addon-v3.1.0.zip — Godot 4 .NET addon
• SHA256SUMS.txt — SHA-256 checksums for all archives

Verify SHA-256 before extracting. The CLI can install its embedded addon using godot-runtime-cli install --project /path/to/game. Compile and run the game with Godot 4 .NET before using runtime tools.

Notes

• Linux/Windows release artifacts are not provided.
• macOS binaries are not Apple-notarized.
• execute_csharp is a legacy unsupported placeholder.
• Native AOT compilation reports known ASP.NET Core 8 framework-level trimming warnings (IL2026 / IL3053); both macOS architectures have been built and tested.