godot-agent-vision

name

godot-agent-vision

description

Agentic eyes for Godot work: cross-platform screenshot CLI (asset/region/window/screen) to budgeted WebP, TEMP editor viewport bridge under .gdskills/, and Taste Receptor Atlas v2 (~237 micro-receptors × 0–2: hierarchy, contrast, typography×41, affordance, space, color, icon, composition, light/FX, motion-tells, anti-slop, originality, identity). Use when agents must see UI, assets, or the editor — not for in-game screenshot Autoloads. Keywords: agent vision, screenshot, WebP, visual QA, taste receptors, typography, UI review, asset sheet, editor viewport, anti-slop.

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

Need	Mode	MANDATORY loads
Asset files / sheets	asset	capture-modes.md, webp-budgets.md, rubric V6–V8 + originality-sight.md
Desktop rectangle	region	capture-modes + budgets + rubric axes in frame
Godot/editor/game window	window --title	capture-modes (OS limits!)
Full monitor	screen	last resort (secret chrome)
Editor 2D/3D pixels	editor	editor-bridge-lifecycle.md

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.

When scoring…	Load
Any review	MANDATORY taste-receptors.md
TYPE-* / HUD numerals / menus	MANDATORY 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
SLOP-* / UI cross-check	anti-slop-sight.md, ui-taste-sight.md
ORIG-*	originality-sight.md
ID-*	identity-sight.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.

Editor bridge

• EditorPlugin (Node) can await RenderingServer.frame_post_draw safely; EditorScript is RefCounted and can free mid-await.
• Capture: EditorInterface.get_editor_viewport_2d/3d → get_texture().get_image() after ≥1–2 frame waits; set main screen 2D/3D first or texture is stale/empty.
• Empty get_image() ⇒ missing await or wrong main screen — not proof the GPU is fine.
• Handshake: write PNG under raw/, then done flag; Python waits for size-stable PNG.
• Teardown must strip res://addons/_gdskills_agent_vision/plugin.cfg from [editor_plugins] enabled= and delete the addon — underscore name signals private/temp.
• Control crops: full editor image + get_global_rect → Image.get_region, clamped to bounds.

Sight / taste (why the atlas is heavy)

• Score receptors, not vibes: hierarchy is composite size×contrast×motion×sat (HIER-WEIGHT-MATH); peripheral HUD must read as shape (HIER-PERIPH-READ); contrast is worst-case on plates (CTRST-GRAD-WORST, CTRST-BODY-45).
• Agents default to AI UI centroids (purple wash, neon glow cards, cream+serif, Lucide soup). T≥3 without ownership ⇒ SLOP-STACK=0 / overall F.
• Typography is ship-blocking (41 TYPE receptors): TYPE-DISPLAY-HUD-SPLIT, TYPE-OPSZ-MATCH, TYPE-NUM-TABULAR/TIMER-STABLE, TYPE-GLYPH-INTEGRITY, TYPE-FACE-CAP — display cuts at HUD size and tabular wobble are zeroes, not “style.”
• Color/icon: 4–6 semantic roles + accent budget ~5–15%; silhouette test on icon sets; CVD shape backup (COLOR-ONLY / ICON-SIL).
• Composition/FX/motion: power-point vs HUD conflict (COMP-POWER-CONFLICT); bloom/particles must not replace hierarchy or occlude UI; freeze-frames leak shake/tween artifacts (MOT-*) — sequence capture when peak ambiguous.
• Originality: filter scènes à faire first; fail franchise silhouette/mark matches and stacked construction tells.
• Identity: palette roles + edge grammar + motif recurrence (2–4) + type pairing + icon grid + HUD↔menu↔key-art DNA — gradient-alone is not a brand.

Decision tree

1. Files on disk? → asset (± sheet) → Read → score COLOR/ICON/ORIG/ID/SLOP (+ TYPE if labels) → fixes.
2. Known window? → window (else region) → Read → score all applicable atlas families → fixes.
3. Editor viewport fidelity? → editor → teardown → score → fixes.
4. Else screen (last resort).
5. TYPE/CTRST illegible at 512? → --detail or text crop → re-score those receptors.
6. MOT/hit-peak ambiguous? → 2–8 frame sequence → re-score MOT/LIGHT hit receptors.

Reference

Progressive disclosure: open Official Documentation only for a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• EditorPlugin — TEMP bridge host; enable/disable lifecycle.
• EditorInterface — get_editor_viewport_2d/3d, main screen switch before grab.
• Using Viewports — viewport textures feeding Image captures.
• Image — save_png, get_region for Control crops.
• SubViewport — editor/game nested view surfaces.
• RenderingServer — frame_post_draw wait before texture readback.
• Migration hops: migration-notes.md

Related Skills

Prerequisites

• godot-project-foundations — project root / .gitignore hygiene before vision scratch.
• godot-ui-containers — layout must be honest before vision blames Theme.

Complements

• godot-ui-theming — Theme/StyleBox/font APIs after V3/V8 finds chrome/type debt.
• godot-ui-rich-text — BBCode/fonts that must stay coherent with HUD type roles.
• godot-auditor — architectural anti-slop kinship.
• godot-debugging-profiling — runtime/orphan issues beyond pixels.
• godot-builder — CLI/GODOT_PATH patterns when launching editor for bridge captures.

Downstream / consumers

• Genre and UI skills that ship screens — route here when agents must see results, not guess.

Master

• godot-master — Decision matrix row Agent Eyes / Visual QA.