| name | godot-sight |
| description | Drive the Godot Sight MCP server as the agent's eyes and hands during Godot 4 development. Use proactively whenever code, scenes, shaders, UI, or game logic are being authored, refactored, debugged, or reviewed — not only when the user explicitly asks. Triggers: writing or editing GDScript, modifying .tscn scenes, adjusting shaders, building UI/menus, implementing a story or feature, fixing a visual bug, fixing a script or logic bug, suspected regression, before marking work done, before code review, generating test evidence for a story, reproducing a user-reported bug, or any phrase like 'this looks wrong', 'it crashes', 'doesn't work', 'broken', 'verify', 'check the game', 'show me what happens', 'screenshot', 'test the menu', 'does this run', 'did I break anything'. Wraps the 12 MCP tools (doctor, project_info, verify_project, run_scene, stop, get_logs, get_runtime_state, get_scene_tree, screenshot, input_action, run_playtest, latest_report) into the development inner loop so Cursor verifies before editing more, sees the actual game (not just source), and writes playtest YAML as living regression specs. |
| argument-hint | [scenario: feature | bugfix | visual | refactor | review | regress | freeform] |
| user-invocable | true |
| allowed-tools | Read, Write, Glob, Grep, Shell, CallMcpTool, AskQuestion |
Godot Sight: Development Inner Loop
Godot Sight is not a debugging utility you reach for when stuck. It is the agent's eyes and hands for every Godot edit. The rule of thumb:
If you wrote code that could change the running game, see it run before you write more code.
This skill teaches Cursor when to use Sight (not just how). The how is in reference.md; playtest YAML grammar is in playtests.md.
The Core Loop
For any change to GDScript, .tscn, .tres, shaders, or project.godot:
EDIT → VERIFY → RUN → SEE → ASSERT → STOP → next edit
| Step | Tool | Cost | What it catches |
|---|
| VERIFY | godot_sight_verify_project | ~1 s | Parse errors, missing UIDs, broken preload, missing autoloads |
| RUN | godot_sight_run_scene (+6 s wait) | ~6 s | Crashes during _ready, autoload failures, signal binding errors |
| SEE | godot_sight_get_scene_tree, godot_sight_screenshot | <1 s | Visual regressions, missing nodes, wrong hierarchy, blank UI |
| ASSERT | godot_sight_run_playtest (YAML) | ~2 s | Logic regressions, interaction flow |
| STOP | godot_sight_stop | <1 s | Releases port 8765 so the next run works |
Skip nothing. Each step is cheap; the cost of skipping is debugging an unrelated symptom later.
Proactive Triggers
Run Sight steps without being asked when any of the following happens in a session:
| You just… | Run this | Why |
|---|
Edited any .gd script | verify_project | Catches parse errors instantly |
Edited a .tscn scene | run_scene + get_scene_tree | Confirms the scene still loads and structure is intact |
| Edited UI / menu code or scenes | screenshot (before + after if possible) | Visual diff |
| Edited a shader | run_scene + screenshot | Many shader bugs are invisible until you render |
| Added a new autoload, signal, or state machine | run_scene + get_logs | Surfaces runtime init errors |
| Finished an acceptance criterion | screenshot → save as story evidence | Becomes the visual proof for /story-done |
| Implemented a complete feature | Write a .yml playtest + run it | Becomes a regression test that ships with the feature |
| Heard "it crashes" / "looks wrong" / "broken" from the user | run_scene + get_logs + screenshot BEFORE touching code | Reproduce first; never debug from imagination |
If the user says "keep going" or "next" without a Sight check between major edits, run verify_project silently anyway. It's a 1-second guard against compounding errors.
Scenario Playbooks
Scenario A — New Feature
Use when implementing a story or building a fresh system.
1. verify_project # baseline: project compiles
2. <edit code / scenes>
3. verify_project # catch parse errors
4. run_scene (target scene of the feature) # confirm it loads
5. wait 6 s
6. get_scene_tree # confirm new nodes mounted
7. screenshot # baseline visual
8. input_action (if interactive) # drive the feature
9. screenshot # confirm reaction
10. Write playtests/<feature>.yml # encode the happy path
11. run_playtest playtests/<feature>.yml # green-bar before declaring done
12. stop
13. Commit the playtest with the feature.
The playtest YAML is the regression test. Always commit it alongside the feature. The .yml is the spec the agent enforces forever.
Scenario B — Visual Bug ("looks wrong")
Use when the user says a UI element is wrong, a sprite is missing, a shader looks off, or "the menu is broken".
1. run_scene (the scene the user named, or main scene)
2. wait 6 s
3. screenshot # capture the actual visual
4. get_scene_tree # is the node even there?
5. get_logs # shader compile errors? missing resources?
6. ONLY NOW edit code/scene
7. verify_project after each edit
8. run_scene + screenshot to confirm fix
9. stop
Do not edit before screenshotting. A screenshot before any change is the only ground truth.
If the screenshot reveals a missing node, check get_scene_tree for the parent and search the .tscn for that path. If the screenshot looks fine but the user disagrees, show them the PNG path — sometimes the bug is on their machine state, not the project.
Scenario C — Script / Logic Bug ("it crashes" / "doesn't fire")
Use for runtime errors, null refs, signals not firing, conditions never evaluating.
1. run_scene (a scene that triggers the bug)
2. wait 6 s
3. get_logs # find the ERROR / GDScript backtrace
4. If bug needs interaction:
input_action ... # drive the path
get_logs # post-interaction errors
5. <fix the code>
6. verify_project # catches at least syntactic regressions
7. run_scene + get_logs # confirm error gone
8. stop
get_logs.data.data.recent[] is sorted oldest→newest; the last ERROR line is the most recent one. The GDScript backtrace under it points to your fault.
For autoload-init errors (_ready failures), they appear within the first 200 log lines. For lazy bugs (only on user action), drive them with input_action while the game is running, then re-call get_logs.
Scenario D — UI / HUD Polish
Use when iterating on layout, theme, colors, fonts, panel sizes, button focus.
Loop:
1. <edit theme/scene/script>
2. verify_project
3. run_scene → wait 6 s → screenshot → stop
4. Show screenshot path to the user, ask "does this look right?"
5. Adjust based on feedback, repeat.
For multi-state UI (menus, dialogs, pause screens):
1. run_scene → wait 6 s
2. screenshot # state 1
3. input_action ui_accept # transition
4. wait via Shell (Start-Sleep)
5. screenshot # state 2
6. input_action ui_cancel
7. screenshot # state 3
8. stop
Save all screenshots in a story's evidence folder so reviewers can see every state.
Scenario E — Refactor / Rename / Move
Use when you've renamed files, moved scripts, reorganised autoloads, or changed class names.
1. verify_project # FIRST. Refactors break paths silently.
2. If errors:
- Read each error.category=parse_error and fix the broken reference.
- verify_project again. Loop until clean.
3. run_scene (main scene) # catch runtime path failures
4. get_logs # look for "Cannot load resource" / "Class not found"
5. run any existing playtests # regression check
6. stop
A refactor is "done" only when verify_project is clean and every existing playtest still passes.
Scenario F — Pre-Commit / Pre-Review Check
Run before saying "ready for review" or /story-done.
1. verify_project # must be clean
2. run_scene (main scene of the story)
3. get_scene_tree # confirm acceptance-criterion nodes mount
4. screenshot # attach to story evidence
5. run_playtest playtests/<story>.yml # if a playtest exists
6. get_logs # confirm no NEW errors vs baseline
7. stop
If any of those fail, the story is not done. Send it back through Scenario B/C.
Scenario G — "Did I break anything?"
Run after a large change, autoload rewire, dependency bump, or engine upgrade.
1. verify_project
2. For each *.yml in playtests/:
- run_scene (the playtest's scene)
- wait 6 s
- run_playtest <file>
- stop
3. Report a pass/fail table.
This is your regression suite. If you don't have one yet, build it incrementally — every feature scenario above ends by writing a playtest. After a few features the suite becomes useful automatically.
Integration With Studio Skills
This skill plugs into the existing CCGS workflow — invoke it from inside other skills, not as a replacement.
| Studio skill | Where Sight fits |
|---|
/dev-story | Run Scenario A inside the implementation phase. Each acceptance criterion gets a screenshot or assert_node_exists step. |
/story-done | Run Scenario F before marking complete. Attach screenshots + playtest pass to story evidence. |
/code-review | Run Scenario E if any file moved/renamed; otherwise Scenario F. |
/smoke-check | The "automated tests" Phase 2 should run all playtests/*.yml via run_playtest. Replaces the GDUnit fallback for projects that use Sight. |
/bug-report | Run Scenario B or C first to gather evidence. Attach screenshot path, scene tree excerpt, and the offending log lines to the bug. |
/regression-suite | Maintains the playtests/ folder. Every fixed bug should add or update a .yml playtest. |
/test-evidence-review | Audit that every Logic/UI story has an associated .yml playtest in playtests/. |
When dev-story finishes implementing a piece, do not ask "should I check it?" — just run Scenario A. The user wants the loop closed, not narrated.
Decision Tree (what to call next)
Use this as the agent's default reasoning:
Was the last action an edit?
├── No → Are we mid-scenario?
│ ├── Yes → next step of that scenario
│ └── No → ask user what's next
│
└── Yes → What kind of edit?
├── .gd script → verify_project, then continue
├── .tscn scene → verify_project + run_scene + get_scene_tree
├── theme/UI/.tres → verify_project + run_scene + screenshot
├── shader → run_scene + screenshot
├── project.godot → verify_project + run_scene + get_logs
└── autoload added → run_scene + get_logs (init errors are loud here)
Anti-Patterns
1. Edit five files, then debug.
Verify after every edit. If you let three edits stack, you spend more time bisecting which edit broke things than you saved skipping the checks.
2. Calling bridge tools without run_scene first.
get_scene_tree, screenshot, input_action, run_playtest all need a live game. The MCP server will return not_available with connection refused. Always launch first; always wait 5–8 s; always stop at the end.
3. Writing playtests for things that don't exist yet.
The supervisor only implements 4 step kinds (wait_ms, input_action, assert_node_exists, screenshot-noop). Other contract-doc steps return unsupported. See playtests.md.
4. "It probably works."
If you didn't see a screenshot or a green playtest, it doesn't work. The whole point of Sight is to remove "probably" from the loop.
5. Asking permission to run Sight tools.
Sight is read-only against the project (it just launches Godot and reads sockets). Run it. Show the result. Don't ask first — that interrupts the flow the user explicitly enabled this skill for.
6. Forgetting to stop.
Zombie Godot holds port 8765. Next run_scene will succeed but the bridge will be the old game's bridge → confusing scene trees, wrong screenshots. Always stop.
7. Reading source to guess the scene tree.
get_scene_tree is faster and authoritative. Don't infer node paths from .tscn text — Godot may rename, reparent, or omit nodes at runtime. Read the live tree.
Quick Reference
Project path (escape backslashes on Windows JSON): <absolute-path-to-your-godot-project> — e.g. C:\\dev\\my-game or /Users/you/dev/my-game.
Bridge: 127.0.0.1:8765
Evidence root: <project>/.godot_sight/runs/<run_id>/
Playtest folder: <project>/playtests/
Server identifier: godot-sight (the key under mcpServers: in your MCP client config). Some clients prepend a slug (e.g. Cursor adds project-<n>-); match whatever your client reports in its tool list.
Full per-tool argument and response shape: reference.md.
Playtest YAML grammar and recipes: playtests.md.
