Skip to content

feat: add capture_screenshot and capture_scene_screenshot tools (fixes #88)#115

Open
Yoshyaes wants to merge 1 commit into
Coding-Solo:mainfrom
Yoshyaes:feat/capture-screenshot-tools
Open

feat: add capture_screenshot and capture_scene_screenshot tools (fixes #88)#115
Yoshyaes wants to merge 1 commit into
Coding-Solo:mainfrom
Yoshyaes:feat/capture-screenshot-tools

Conversation

@Yoshyaes

Copy link
Copy Markdown

Summary

  • Adds capture_screenshot and capture_scene_screenshot MCP tools that return a rendered Godot scene as a base64 PNG image, closing Feature Request: Visual Debugging / Automated Playtest Capture Tool #88
  • Routes through the existing godot_operations.gd bundled script (no new GDScript files, no autoloads, no editor plugins)
  • Runs Godot without --headless so the renderer produces real pixels; fixes the Y-axis inversion from ViewportTexture with img.flip_y()
  • Output always goes to a secure OS temp path (user never controls it); temp file is cleaned up after every call

Why this over the existing PRs

PR Problem
#62 / #65 Require a ScreenshotManager autoload in the user's project, breaking the no-plugin architecture
#100 Standalone GDScript outside godot_operations.gd; Y-axis flip bug; user-controlled output path

This PR follows the same bundled-script pattern as every other tool and addresses all open review comments from #100.

How to test

# Build
npm install && npm run build

# Structural test (no Godot needed)
npm test  # 4 pass, 3 skipped (skipped = Godot not installed)

# Full test with Godot installed
GODOT_PATH=/path/to/godot npm test  # all 4 pass

# Manual CLI smoke test
godot --path tests/fixtures/capture-test-project \
      --script src/scripts/godot_operations.gd \
      capture_scene_screenshot \
      '{output_path:/tmp/test.png,scene_path:res://scenes/main.tscn}'
# Open /tmp/test.png -- should be a solid red 1280x720 frame

Rendering context note

These tools require a real display (not --headless). On a local dev machine (macOS, Windows, Linux desktop) they work out of the box. On headless Linux wrap Godot in xvfb-run -- see the README Visual Debugging section for the wrapper script pattern.

What is not in this PR

record_playtest (capture a frame sequence over N seconds) is scoped to a follow-up PR to keep this one reviewable.


Fixes #88

…Coding-Solo#88)

Add two MCP tools for visual debugging of Godot scenes. Both tools run
Godot with a real rendering context (not --headless), capture a viewport
frame via GDScript, and return the result as base64 PNG image content so
AI agents can visually verify scenes.

Changes:
- src/scripts/godot_operations.gd: add capture_screenshot and
  capture_scene_screenshot operations using async coroutines, root.get_texture(),
  and img.flip_y() to correct Y-axis inversion from ViewportTexture
- src/tools/capture.ts: standalone handlers that spawn Godot without --headless,
  write to a temp path, read and base64-encode the PNG, clean up the temp file
- src/index.ts: register both tools in ListTools and CallTool
- tests/fixtures/capture-test-project/: minimal Godot 4 project with a solid-red
  ColorRect scene for CI-style validation
- src/tests/capture.test.ts: integration tests using node:test (no new deps);
  skip gracefully when Godot is not available
- README.md: Visual Debugging section with parameter tables and xvfb-run guide

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
awils27 added a commit to awils27/godot-mcp that referenced this pull request Jun 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature Request: Visual Debugging / Automated Playtest Capture Tool

1 participant