{"slug": "playwright-for-godot", "title": "Playwright for Godot", "summary": "Stagehand, a new open-source tool for the Godot game engine, now enables external automation and testing of games through a WebSocket connection and a Go-based MCP server. The tool allows AI agents, CI pipelines, and test runners to programmatically click buttons, read properties, take screenshots, and assert performance from outside the engine, addressing the lack of automated UI testing in Godot. By providing a direct connection to running games, Stagehand aims to replace manual click-through testing with automated visual regression, integration, and performance checks.", "body_md": "External automation and testing for running Godot games — like Playwright, but for game engines.\n\n**New to Stagehand?** → [Quickstart guide](/mrf/godot-stagehand/blob/main/docs/quickstart.md) — zero to connected in 5 minutes, no Go or JSON experience required.\n\nGame testing is manual. You click through menus, eyeball the results, and hope you caught the regressions. Automated UI tests exist for the web, but Godot has nothing equivalent — no way for an external process to connect to a running game and drive it programmatically.\n\nStagehand fixes that. It gives AI agents, test runners, and CI pipelines a real connection to your running game. Click buttons, read properties, wait for signals, take screenshots, assert performance — all from outside the engine.\n\n**AI-assisted playtesting**— Let Claude (or any MCP client) explore your game, find bugs, and verify fixes without manual clicking.** Visual regression testing**— Save baseline screenshots, diff them later. Catch UI regressions before your players do. See the[visual smoke contract](/mrf/godot-stagehand/blob/main/docs/visual-smoke-contract.md)for how to set up a visual gate in your game repo.**Integration tests**— Write tests that drive your actual game: navigate menus, trigger gameplay, assert on real game state.** CI pipelines**— Run headless Godot in CI, connect Stagehand, and gate merges on automated gameplay checks.** Performance monitoring**— Poll engine performance counters and fail builds when frame times regress.** Input recording/replay**— Record a play session, replay it deterministically for regression testing.\n\n```\n┌─────────────┐       ┌──────────────────┐       ┌──────────────┐\n│  MCP Client │◄─────►│  Go Server       │◄─────►│  Your Game   │\n│  (Claude,   │ stdio │  (godot-stagehand)│  WS   │  (Godot +    │\n│   CI, etc.) │       │                  │ :26700 │   addon)     │\n└─────────────┘       └──────────────────┘       └──────────────┘\n```\n\n**The addon** lives inside your Godot game. It opens a WebSocket port and waits for commands. When it receives one (like \"click this button\" or \"get the scene tree\"), it executes it inside the running game and sends back the result.\n\n**The Go server** sits in the middle. It speaks MCP (the protocol AI tools use) on one side and the Godot wire protocol on the other. It handles connection management, selector parsing, screenshot encoding, and error translation so the addon stays simple.\n\n| Tool | Description |\n|---|---|\n`godot_connect` |\nConnect to a running game |\n`godot_launch` |\nLaunch Godot and connect |\n`godot_status` |\nConnection status |\n`godot_get_tree` |\nSnapshot the scene tree |\n`godot_find_nodes` |\nFind nodes by selector |\n`godot_get_property` / `godot_set_property` |\nRead/write node properties |\n`godot_call_method` |\nCall methods on nodes |\n`godot_evaluate` |\nEvaluate GDScript expressions |\n`godot_click` |\nClick nodes or coordinates |\n`godot_press_key` |\nSimulate keyboard input |\n`godot_press_action` |\nTrigger input actions |\n`godot_touch` |\nSimulate touch/drag |\n`godot_type_text` |\nType text into controls |\n`godot_mouse_move` |\nMove mouse cursor |\n`godot_screenshot` |\nCapture viewport |\n`godot_screenshot_save_baseline` / `godot_screenshot_diff` |\nVisual regression testing (\n|\n\n`godot_wait_for_node`\n\n`godot_wait_for_signal`\n\n`godot_wait_for_property`\n\n`godot_change_scene`\n\n`godot_get_game_state`\n\n`godot_get_performance`\n\n/ `godot_assert_performance`\n\n`godot_record_start`\n\n/ `godot_record_stop`\n\n/ `godot_replay`\n\nTarget nodes using familiar patterns:\n\n| Syntax | Example | Finds |\n|---|---|---|\n| Path | `/root/UI/StartButton` |\nNode at exact path |\n| Name | `name:*Button*` |\nGlob match on node name |\n| Class | `class:Button` |\nAll nodes of class |\n| Group | `group:interactive` |\nAll nodes in group |\n| Text | `text:Start` |\nNodes containing text |\n| Meta | `meta:id=player` |\nNodes with metadata |\n| Chain | `class:Panel >> name:*Btn*` |\nScoped search (find within) |\n\nDownload the prebuilt binary for your platform from the [latest release](https://github.com/mrf/godot-stagehand/releases/latest):\n\n| Platform | File |\n|---|---|\n| Linux x86-64 | `godot-stagehand-linux-amd64` |\n| macOS Apple Silicon | `godot-stagehand-darwin-arm64.zip` |\n| macOS Intel | `godot-stagehand-darwin-amd64.zip` |\n| Windows x86-64 | `godot-stagehand-windows-amd64.exe` |\n\nmacOS: unzip the archive, then `chmod +x godot-stagehand-darwin-*`\n\n.\n\n**From source** (requires Go 1.25+ and Godot 4.3+):\n\n```\ngo build -o godot-stagehand .\ngodot-stagehand setup /path/to/your/godot/project\n```\n\nThis copies the addon, enables the plugin, and registers the `StagehandServer`\n\nautoload — idempotently, so it is safe to re-run. It then prints the MCP client\nconfig snippet (with this binary's detected path) and the exact command to run\nyour game. Pass `--force`\n\nto overwrite an existing addon installation. On WSL it\nalso prints WSL-specific connection guidance.\n\nThe old\n\n`./copy-addon.sh`\n\nscript is deprecated; it now forwards to`godot-stagehand setup`\n\n.\n\n```\ngodot --path /path/to/your/project --stagehand\n```\n\nYou should see `Stagehand: Server listening on port 26700`\n\nin the output.\n\nThe `setup`\n\ncommand prints this snippet for you; add it to your MCP client config\n(e.g. `.claude/settings.json`\n\n):\n\n```\n{\n  \"mcpServers\": {\n    \"godot-stagehand\": {\n      \"command\": \"/absolute/path/to/godot-stagehand\"\n    }\n  }\n}\n```\n\nCall `godot_connect`\n\nto attach to the running game. Local Linux/macOS and Linux Godot inside WSL use `127.0.0.1`\n\nby default. For Windows Godot controlled from WSL, use `localhost`\n\nwith WSL mirrored networking or the WSL default gateway IP with NAT/default networking.\n\nWindows / WSL?See the[Windows setup guide].\n\n| Method | Example |\n|---|---|\n| CLI flag | `godot --stagehand` |\n| Env var | `STAGEHAND_ENABLED=1 godot ...` |\n| Editor toggle | Stagehand button in toolbar |\n| Custom port | `STAGEHAND_PORT=9999` or `--stagehand-port=9999` |\n\n**\"Connection refused\"** — Game isn't running with `--stagehand`\n\n, or wrong host/port.\n\n**\"Connection reset\"** — Godot started but `_process`\n\nisn't ticking (common in headless with heavy scenes). Use a visible window or a lighter scene.\n\n**Screenshots are empty, black, or grey** — Visual workflows need a visible rendered window. Use `godot_launch(headless=false, expect_screenshots=true)`\n\n; headless launches are for structural tools.\n\n**Port conflict** — Another instance on 26700. Set `STAGEHAND_PORT=26701`\n\n.\n\n**Addon not in plugin list** — Run `godot-stagehand setup /path/to/project`\n\nagain; it idempotently enables the plugin and autoload.\n\nMIT — see [LICENSE](/mrf/godot-stagehand/blob/main/LICENSE).", "url": "https://wpnews.pro/news/playwright-for-godot", "canonical_source": "https://github.com/mrf/godot-stagehand", "published_at": "2026-06-05 20:37:01+00:00", "updated_at": "2026-06-05 20:48:42.598769+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "ai-products"], "entities": ["Stagehand", "Godot", "Claude", "Playwright"], "alternates": {"html": "https://wpnews.pro/news/playwright-for-godot", "markdown": "https://wpnews.pro/news/playwright-for-godot.md", "text": "https://wpnews.pro/news/playwright-for-godot.txt", "jsonld": "https://wpnews.pro/news/playwright-for-godot.jsonld"}}