# Godot Sight > 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 - Skill: `lanc3/godot-sight` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add lanc3/godot-sight` - Raw SKILL.md: https://api.skillmd.com/api/skills/lanc3/godot-sight/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: Lanc3 (https://skillmd.com/u/lanc3) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/lanc3/godot-sight --- # 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](reference.md); playtest YAML grammar is in [playtests.md](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. 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/.yml # encode the happy path 11. run_playtest playtests/.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. 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. 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/.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 - 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](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):** `` — e.g. `C:\\dev\\my-game` or `/Users/you/dev/my-game`. **Bridge:** `127.0.0.1:8765` **Evidence root:** `/.godot_sight/runs//` **Playtest folder:** `/playtests/` **Server identifier:** `godot-sight` (the key under `mcpServers:` in your MCP client config). Some clients prepend a slug (e.g. Cursor adds `project--`); match whatever your client reports in its tool list. Full per-tool argument and response shape: [reference.md](reference.md). Playtest YAML grammar and recipes: [playtests.md](playtests.md).