Godot Agent Vision

Godot Agent Vision

Host-side eyes for coding agents building Godot projects: capture → budgeted WebP → scored visual review. Not a game Autoload, not an exportable screenshot API.

Do NOT Load every reference for one task. Load the MANDATORY file for the active mode, then only the rubric axes you are scoring.

NEVER Do

• NEVER ship the editor bridge as an Autoload or leave addons/_gdskills_agent_vision/ committed — stage, capture, teardown.
• NEVER leave --keep-bridge on after debugging — skips teardown and dirties the consumer project.
• NEVER dump uncompressed PNG walls into model context — WebP only; default short-edge 512; --detail only when pixels fail (especially type).
• NEVER replace scored taste with binary PASS/FAIL or vibes — score applicable rows in taste-receptors.md (Atlas v2, 237 receptors × 0–2); V1–V8 /120 in vision-review-rubric.md is rollup only.
• NEVER invent taste without loading Family deep refs when those pixels are present: TYPE → typography-sight.md; HIER/CTRST → hier-contrast-receptors.md; SPACE/AFF → space-affordance-receptors.md; COLOR/ICON → color-icon-receptors.md; COMP/LIGHT/MOT → composition-fx-receptors.md; plus anti-slop-sight.md / ui-taste-sight.md.
• NEVER treat purple-gradient / glow-card / cream-serif AI defaults as “good UI” unless the capture owns that identity with legible critical info and type discipline (SLOP-STACK / TYPE-DISPLAY-HUD-SPLIT).
• NEVER put ornate display faces on ammo/HP/timers — TYPE-DISPLAY-HUD-SPLIT ship blocker; data type is boring on purpose.
• NEVER promise silent window-by-title on Wayland — region, grim, X11, or editor bridge.
• NEVER trust black fullscreen BitBlt/mss frames — exclusive fullscreen / some GPU paths return empty; windowed, region, DXGI-only if justified, or editor bridge.
• NEVER commit .gdskills/vision/** — ensure .gdskills/ is gitignored first.

When to use

After capture: Read WebP(s) → score Taste Receptor Atlas (not vibes) → zero-list + ordered fixes keyed to receptor IDs. If any TYPE-* / micro-seam ≤1 for illegibility at 512 short-edge, re-capture --detail or text crop before locking.

Setup (agent host)

pip install -r skills/godot-agent-vision/requirements-vision.txt
# optional macOS window titles:
# pip install pyobjc-framework-Quartz

Requires a display session. Use repo/project venv Python.

Available Scripts

Do NOT Load every script. Call only what the mode needs.

capture.py

Main CLI: doctor, list-windows, screen, region, window, asset, editor. Prints wrote=, bytes=, budget=short-edge:N|long-edge:N.

webp_encode.py

Default fit short-edge 512; --detail / --max-edge switches to long-edge cap (1568). Never upscales. Soft re-encode if >1MB.

asset_sheet.py

Single asset or ≤2×2 contact sheet with labels; res:// resolution against --project-root.

ensure_gitignore.py

Appends .gdskills/ so vision scratch never stages.

stage_editor_bridge.py

Stages TEMP addon, optional --godot launch, handshake wait, WebP encode, teardown + project.godot plugin strip.

Editor bridge templates

• plugin.cfg / plugin.gd — @tool EditorPlugin polls request → raw/*.png → done
• capture_viewport.gd — Control crop helper (get_global_rect → Image.get_region)

Capture CLI (golden path)

python skills/godot-agent-vision/scripts/capture.py doctor
python skills/godot-agent-vision/scripts/capture.py window --project-root . --title Godot
python skills/godot-agent-vision/scripts/capture.py asset --project-root . --paths res://ui/icons --sheet
python skills/godot-agent-vision/scripts/capture.py editor --project-root . --editor-mode 3d --godot "%GODOT_PATH%"
# typography / OCR / dense layout only:
python skills/godot-agent-vision/scripts/capture.py window --project-root . --title Godot --detail

Default out: {project}/.gdskills/vision/YYYYMMDD-HHMMSS-<mode>[-label].webp

MANDATORY platform landmines: capture-modes.md. MANDATORY budgets: webp-budgets.md.

Editor bridge (TEMP)

Stages templates → addons/_gdskills_agent_vision/ → .gdskills/vision/{request,raw,done} → WebP → delete addon + restore enabled=.

MANDATORY: editor-bridge-lifecycle.md. Prefer EditorPlugin over EditorScript (await across RefCounted is unsafe).

Structured review (Taste Receptor Atlas → optional /120)

MANDATORY primary: taste-receptors.md — 237 micro-receptors across 13 families (HIER, CTRST, TYPE×41, AFF, SPACE, COLOR, ICON, COMP, LIGHT, MOT, SLOP, ORIG, ID), each 0/1/2, grade by % of applicable, hard gates. Routing + V-rollup: vision-review-rubric.md.

Expert Knowledge Delta

Capture / OS

• Windows: Per-Monitor DPI V2 before geometry; mss before DPI-clobbering imports; monitors[0] virtual union can be negative-origin; longest title match for Godot’s path-in-title windows.
• Windows black frames: minimized / exclusive fullscreen / GPU-protected content — not “empty UI.” Prefer windowed + region or editor bridge; DXGI is optional weight, not default.
• macOS: Screen Recording attaches to responsible binary; wallpaper-only = hard fail; screencapture CLI attribution breaks under agents — prefer in-process Quartz/mss.
• macOS Retina: pick logical points (automation) vs backing pixels (OCR) and do not mix without scale metadata.
• Linux: Wayland → skip mss; grim on wlroots; no silent title grab; portal paths are interactive.
• Asset res:// resolves against --project-root; missing paths must error loudly — never invent files.

WebP / context

• Vision tokens track pixel area; request size tracks codec. Default short-edge 512 for identity/overview/anti-slop; escalate long-edge 1568 only for glyphs, seams, dense full-layout.
• Contact sheets ≤2×2 with gutters — 3×3+ makes panel text sub-pixel after model downscale.
• Never upscale tiny icons to fill 512/1568 — wastes tokens without information.