godot-interactive

What this skill does

# Godot Interactive Testing Skill

Playwright-like interaction loop for Godot games via MCP. Launch, observe, click, inspect, and manipulate a running game through a bridge autoload.

## Overview

This skill enables LLM-driven interactive testing of Godot games through the godot-mcp MCP server and a GodotMCPBridge autoload. You can:

- Launch and stop Godot projects via MCP
- Capture viewport screenshots automatically or on-demand
- Inspect the scene tree with Control node positions and text
- Simulate clicks, key presses, and input actions
- Read and write node properties at runtime
- Implement iterative test/debug loops (observe → inspect → interact → observe)

This is particularly useful for:
- Automated UI testing
- Debugging visual issues
- Verifying game state without manual playtesting
- Creating reproducible test scenarios
- Validating UI layouts and interactions

## Prerequisites

**godot-mcp server:**
- Installed at `~/code/godot-mcp` (or configurable path)
- Built with `npm install && npm run build`
- Repository: https://github.com/yourusername/godot-mcp

**Claude Desktop configuration:**
- MCP server configured in `~/.claude/mcp.json` (see Setup)

**Godot project setup:**
- GodotMCPBridge autoload installed
- Remote debugger enabled (automatic when running via `run_project`)

## Setup for New Projects

### 1. Copy the Bridge Autoload

Copy the bridge script into your project:
```bash
cp assets/templates/godot_mcp_bridge.gd res://scripts/autoload/godot_mcp_bridge.gd
```

### 2. Register the Autoload

Add to `project.godot`:
```ini
[autoload]

GodotMCPBridge="*res://scripts/autoload/godot_mcp_bridge.gd"
```

Or via Godot editor:
- Project → Project Settings → Autoload
- Path: `res://scripts/autoload/godot_mcp_bridge.gd`
- Name: `GodotMCPBridge`
- Enable: Yes

### 3. Create MCP Configuration

Create `.mcp.json` at project root (use template):
```bash
cp assets/templates/mcp.json.template .mcp.json
```

Edit paths:
```json
{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["<PATH_TO_GODOT_MCP>/build/index.js"],
      "env": {
        "GODOT_PATH": "<PATH_TO_GODOT_BINARY>"
      }
    }
  }
}
```

**Example paths:**
- macOS: `/Applications/Godot 4.5.app/Contents/MacOS/Godot`
- Linux: `/usr/bin/godot` or `~/godot/bin/godot`
- Windows: `C:/Godot/godot.exe`

**Project-local godot-mcp:**
If you keep godot-mcp in your project (e.g., `.tools/godot-mcp`):
```json
"args": [".tools/godot-mcp/build/index.js"]
```

## MCP Tools Reference

All tools are provided by the godot-mcp server and work through the GodotMCPBridge autoload.

### run_project(projectPath)

Launch a Godot project with remote debugger enabled.

**Parameters:**
- `projectPath` (string): Absolute path to project directory containing `project.godot`

**Returns:**
- Success confirmation with process ID

**Example:**
```typescript
run_project({ projectPath: "/Users/ben/code/my-game" })
```

**Notes:**
- Automatically enables remote debugger on port 6007
- Takes 2-3 seconds for project to fully start
- Bridge begins auto-capturing screenshots every 2 seconds
- Check `get_debug_output()` if game doesn't appear to start

### stop_project()

Stop the currently running Godot project.

**Parameters:** None

**Returns:**
- Success confirmation

**Example:**
```typescript
stop_project()
```

**Notes:**
- Kills the Godot process gracefully
- Cleans up debugger connection
- Safe to call even if no project is running

### get_debug_output()

Retrieve stdout/stderr from the running Godot process.

**Parameters:** None

**Returns:**
- Array of log lines (most recent first)

**Example:**
```typescript
get_debug_output()
// Returns: ["Frame 1234", "Button pressed", "MCP command: click", ...]
```

**Use cases:**
- Check if game started successfully
- Debug print statements from your game
- Verify bridge initialization ("Godot MCP Bridge initialized")
- Inspect error messages

### game_screenshot()

Capture the current viewport and return as base64 image.

**Parameters:** None

**Returns:**
- Base64-encoded PNG image of the game viewport

**Example:**
```typescript
game_screenshot()
// Returns: base64 PNG data
```

**Notes:**
- Captures the main viewport at full resolution
- Bridge auto-saves screenshots to `/tmp/godot_screenshot.png` every 2 seconds
- This tool provides immediate capture via MCP response
- Works on stock Godot (unlike `capture_screenshot` from upstream DAP)

### game_scene_tree(path, depth)

Inspect the scene tree with node types, positions, and properties.

**Parameters:**
- `path` (string, optional): Root path to start inspection, default: `/root`
- `depth` (number, optional): Traversal depth, default: 3

**Returns:**
- JSON tree structure with nodes

**Node properties:**
- `name`: Node name
- `type`: Node class (Control, Button, Label, Node3D, etc.)
- `rect`: For Control nodes: `{x, y, w, h}` in screen coordinates
- `visible`: For Control nodes: visibility state
- `text`: For Button/Label nodes: display text
- `children`: Array of child nodes (up to depth limit)

**Example:**
```typescript
game_scene_tree({ path: "/root/Main/UILayer", depth: 2 })
// Returns:
{
  "name": "UILayer",
  "type": "CanvasLayer",
  "children": [
    {
      "name": "VictoryPopup",
      "type": "CenterContainer",
      "rect": {"x": 640, "y": 360, "w": 400, "h": 200},
      "visible": true,
      "children": [
        {
          "name": "OKButton",
          "type": "Button",
          "rect": {"x": 720, "y": 480, "w": 80, "h": 40},
          "text": "OK",
          "visible": true
        }
      ]
    }
  ]
}
```

**Use cases:**
- Find clickable UI elements (buttons, controls)
- Verify UI layout and positioning
- Check visibility states
- Locate nodes by name/type for property access

**Key gotcha:** UI coordinates are full resolution (e.g., 1920x1080), not screenshot pixel coordinates. Always use `game_scene_tree` to get accurate `rect` values for clicking.

### game_click(x, y, button)

Simulate a mouse click at screen coordinates.

**Parameters:**
- `x` (number): Screen X coordinate
- `y` (number): Screen Y coordinate
- `button` (number, optional): Mouse button index, default: 1 (left click)
  - 1: Left button (MOUSE_BUTTON_LEFT)
  - 2: Right button (MOUSE_BUTTON_RIGHT)
  - 3: Middle button (MOUSE_BUTTON_MIDDLE)

**Returns:**
- Success confirmation with coordinates
- Automatically captures screenshot after click

**Example:**
```typescript
game_click({ x: 720, y: 480, button: 1 })
// Returns: {"type": "click", "success": true, "x": 720, "y": 480}
```

**Notes:**
- Simulates press + release with 50ms delay
- Takes a screenshot 200ms after release
- Use `game_scene_tree` to find button `rect` coordinates
- Coordinates are in full window resolution, not SubViewport pixels

**Workflow:**
1. Call `game_screenshot()` to see the game
2. Call `game_scene_tree()` to find button positions
3. Call `game_click()` with button's center coordinates
4. Call `game_screenshot()` to verify result

### game_key(key)

Simulate a key press using Godot key names.

**Parameters:**
- `key` (string): Godot key name (e.g., "Space", "Escape", "Enter", "A")

**Returns:**
- Success confirmation
- Automatically captures screenshot after key press

**Example:**
```typescript
game_key({ key: "Space" })
game_key({ key: "Escape" })
game_key({ key: "Q" })
```

**Common key names:**
- Letters: "A", "B", "C", etc.
- Numbers: "0", "1", "2", etc.
- Special: "Space", "Enter", "Escape", "Tab"
- Arrows: "Up", "Down", "Left", "Right"
- Function: "F1", "F2", etc.

**Notes:**
- Uses `OS.find_keycode_from_string()` - must be valid Godot key name
- Simulates press + release with 50ms delay
- Takes screenshot 200ms after release
- Case-sensitive for letters (use uppercase "A", not "a")

### game_action(name)

Trigger a Godot input action defined in InputMap.

**Parameters:**
- `name` (string): Action name from project InputMap

**Returns:**
- Success confirmation
- Automatically captures screenshot after action

**Example:**
`