feat: add visual test harness for screenshotting running games#96
Open
SwiftEngineer wants to merge 1 commit into
Open
feat: add visual test harness for screenshotting running games#96SwiftEngineer wants to merge 1 commit into
SwiftEngineer wants to merge 1 commit into
Conversation
Adds three MCP tools — install_test_harness, uninstall_test_harness,
and capture_screenshot — so agents can visually inspect what a Godot
project actually renders, not just whether its tests pass. Screenshots
are returned as MCP image content blocks so vision-capable clients
see the frame inline.
Mechanism: a small GDScript autoload, shipped by this server, runs
inside a debug Godot process and exposes a loopback TCP endpoint.
run_project picks a free port and passes it via `++ --mcp-port N`
(Godot's user-args separator); projects without the harness installed
simply ignore the extra argument. The Node side speaks a minimal
length-prefixed binary protocol over `net` — no new runtime deps.
Export safety — three independent guarantees that this cannot ship in
an exported game:
1. The autoload entry is written to override.cfg, not project.godot.
Godot explicitly excludes override.cfg from exported projects.
2. mcp_harness.gd calls queue_free() and returns on the first frame
if OS.is_debug_build() is false.
3. The TCPServer binds 127.0.0.1 only, never 0.0.0.0.
No new dependencies: uses Node 18+ built-ins (net, fs.cpSync,
fs.rmSync). scripts/build.js copies the bundled addon into
build/scripts/addons/ alongside godot_operations.gd. README gains a
"Visual testing" section documenting the workflow and the export
safety story, and the Cline auto-approve list picks up the three new
tools.
SwiftEngineer
force-pushed
the
feat/visual-test-harness
branch
from
cf21cb5 to
a95f37e
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
While working on a game, I found it annoying to have to take screenshots to show agents what I was seeing in the game. I asked Claude to cook this PR up as a simple solution. I've been using it for a while in my game and it seems to be working well, so I thought I'd open it as a PR here in case anyone else finds it useful.
The high-level idea of it is:
In case you're worried that this TCP server might end up getting shipped inside of someone's game, the autoload entry is written to override.cfg, not project.godot. Godot explicitly excludes override.cfg from exported projects. To be even more safe, I also directed Claude to make it so that the server is not started unless
OS.is_debug_build() == true.--- Note to maintainer:
I wrote this PR description, Opus 4.6 wrote literally everything else about this PR. I've given it a review, but I will be forthcoming and say that I am not super familiar with Godot or gdscript, so I apologize if I missed something.