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; 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

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:

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.

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.