godot-sight

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.