skilld
All skills
thedivergentai avatar

/godot-agent-vision

@90634df
by Divergent AIthedivergentai/gd-agentic-skills783 stars
48

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.

Ask your Agent

Use this Skill: https://skilld.dev/gh/thedivergentai/gd-agentic-skills/godot-agent-vision

This session only. Nothing lands on disk.

referenceseditor-bridge-lifecycle.md

≈823 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Editor bridge lifecycle

TEMP Godot EditorPlugin for viewport grabs Python cannot see cleanly. NEVER Autoload. NEVER export. NEVER leave the staged addon committed.

Paths

Path Role
.gdskills/vision/bridge/ Copied templates (scratch)
addons/_gdskills_agent_vision/ Staged TEMP addon (delete after)
.gdskills/vision/request Mode line: 2d / 3d / main
.gdskills/vision/raw/*.png Bridge output
.gdskills/vision/done Written after PNG flush

Steps

  1. ensure_gitignore → .gdskills/
  2. Copy templates → stage addons/_gdskills_agent_vision/
  3. Append res://addons/_gdskills_agent_vision/plugin.cfg to project.godot [editor_plugins] enabled=
  4. Open/focus Godot editor on the project (plugin _process polls request)
  5. Python waits for done + stable PNG → encode WebP → delete handshake files
  6. Teardown: remove plugin from enabled=, delete addons/_gdskills_agent_vision/

CLI:

python scripts/capture.py editor --project-root . --editor-mode 3d
python scripts/capture.py editor --project-root . --godot "C:/Path/Godot_v4.7.exe" --editor-mode 2d
# debug only — MUST teardown afterward:
python scripts/capture.py editor --keep-bridge

When --godot is set, the CLI Popens godot -e --path <project> after staging so the plugin can see request.

Capture WHY (empty / wrong pixels)

  • Always await RenderingServer.frame_post_draw (twice is safer) before Viewport.get_texture().get_image() — otherwise the Image can be empty or one frame stale.
  • HDR / float viewports may need conversion before PNG; if save_png fails or Image is empty, switch main screen (2D/3D) and retry.
  • DPI mis-crop on Windows OS capture: process not Per-Monitor V2 aware → window rect in wrong space → black bars or wrong panel. Sympton for OS modes, not editor SubViewport grabs.
  • Control crop WHEN: need a dock/inspector slice rather than the 2D/3D scene SubViewport. HOW: capture editor main viewport Image, then Image.get_region(Rect2i(control.get_global_rect())) (see capture_viewport.gd). Clamp to image bounds — global rects can extend off-screen.

Recovery

Symptom Fix
Timeout waiting for done Editor not open; plugin disabled; .gdskills not under project root; pass --godot
Empty PNG / plugin error Wrong main screen; await frames; try --editor-mode main
Leftover addon after kill Manually delete addons/_gdskills_agent_vision/ and strip enabled= entry
--keep-bridge left on Run teardown: disable plugin, delete addon, restore project.godot

Invariants

  • Underscore addon name signals private/temp.
  • Do not register docks, export plugins, or autoloads.
  • Prefer EditorInterface.get_editor_viewport_2d/3d + await RenderingServer.frame_post_draw.
  • If timeout: confirm editor is open, plugin enabled, and .gdskills/vision/request is visible to the editor (res://.gdskills/...).

Docs

Source: SKILL.md on GitHub

Third-party checks

1 warning1mo3 checks · Risk MEDIUM
  • Gen Agent Trust Hub1mo

    The skill captures screenshots and interfaces with the Godot editor by executing system commands and modifying project configuration files. It includes a temporary editor bridge staged as a Godot plugin, which introduces risks related to command execution and dynamic module loading.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

Provenance

Signed by skilld at 90634df. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 weeks ago.

Activeupdated 2 months ago

README badge

README badge for thedivergentai/gd-agentic-skills/godot-agent-vision