Setup guide
Everything you must provision before this skill can run — the exact credentials, permissions, and where to click. Links go to the official consoles and docs, which stay current.
No API keys. You need the Godot 4 binary on PATH and, for automated capture on Linux/CI, a virtual display — Godot cannot take screenshots in --headless mode.
You need to already have
- A Godot 4.x project
- Godot 4 binary available on PATH
How the pieces connect
Credentials this skill needs
Set these as environment variables. Never paste secrets into a chat or commit them.
| Variable | What it is | Where to get it |
|---|---|---|
GODOT_BINoptional | Path to the Godot 4 binary format: absolute path | Wherever you installed Godot; defaults to `godot` on PATH |
Step by step
- 1
Install Godot 4
Download Godot 4.x and confirm with `godot --version`. The standard (non-.NET) build is fine unless the project uses C#.
Open in the console / docs ↗ - 2
Add the VisualProbe autoload
Project > Project Settings > Globals > Autoload. Add the script from the reference implementation with node name "VisualProbe" so it is globally callable.
Open in the console / docs ↗ - 3
Enable capture on Linux/CI
Install xvfb and run via `xvfb-run -a godot ...`. Do NOT use --headless: it loads the dummy rendering driver and every screenshot comes out blank.
Open in the console / docs ↗ - 4
Confirm the harness actually renders
Run a scene that calls VisualProbe.capture("smoke") and open the PNG under user://visual_debug. If it is blank, fix the rendering context before diagnosing anything else.
Open in the console / docs ↗
Check it worked
godot --version && xvfb-run -a godot --path . --quit-after 5 res://scenes/debug_capture.tscn
If you hit an error
Saved PNG is completely blank or transparentCause: Running with --headless, which uses the dummy rendering driver and never draws a frame.
Fix: Drop --headless; use xvfb-run on Linux or run windowed.
Screenshot shows the previous frame or is emptyCause: get_image() was called before the frame finished drawing.
Fix: await RenderingServer.frame_post_draw before get_viewport().get_texture().get_image().
Node reports visible = true but nothing appearsCause: An ancestor has visible = false or modulate.a = 0; the child still reports its own values.
Fix: Walk the parent chain with VisualProbe.explain_visibility instead of checking the node alone.
Effect works in the editor but not in the exported or web buildCause: SDFGI, VoxelGI, SSAO, SSIL, SSR and volumetric fog are unsupported on the Compatibility renderer.
Fix: Test with --rendering-method gl_compatibility and pick an effect the target renderer supports.
Official documentation: https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html ↗
API operations this skill uses (14)
Every call the skill makes, linked to its official reference page.
| Operation | Call | Permission | Ref |
|---|---|---|---|
| Capture the framebuffer Produce a PNG the agent can inspect | CLI get_viewport().get_texture().get_image() | — | docs ↗ |
| Wait for frame completion Avoid capturing an undrawn frame | CLI await RenderingServer.frame_post_draw | — | docs ↗ |
| Set debug draw mode Split geometry faults from material/lighting faults | CLI Viewport.debug_draw = Viewport.DEBUG_DRAW_OVERDRAW | — | docs ↗ |
| Read draw call count Distinguish culled from drawn-but-invisible | CLI RenderingServer.get_rendering_info(RENDERING_INFO_TOTAL_DRAW_CALLS_IN_FRAME) | — | docs ↗ |
| Read primitives in frame Confirm geometry reached the GPU | CLI RenderingServer.get_rendering_info(RENDERING_INFO_TOTAL_PRIMITIVES_IN_FRAME) | — | docs ↗ |
| Read texture memory used Spot missing or oversized textures | CLI RenderingServer.get_rendering_info(RENDERING_INFO_TEXTURE_MEM_USED) | — | docs ↗ |
| Sample a pixel Objectively read the rendered colour at a coordinate | CLI Image.get_pixelv(Vector2i) | — | docs ↗ |
| Save capture to disk Persist evidence for comparison | CLI Image.save_png("user://visual_debug/shot.png") | — | docs ↗ |
| Inspect a material Confirm a material exists and read its parameters | CLI MeshInstance3D.get_active_material(0) | — | docs ↗ |
| Select renderer Differential test across renderers | CLI godot --rendering-method forward_plus|mobile|gl_compatibility | — | docs ↗ |
| Select rendering driver Isolate driver-specific faults | CLI godot --rendering-driver vulkan|opengl3|d3d12 | — | docs ↗ |
| Force resolution Reproduce resolution-dependent symptoms | CLI godot --resolution 1280x720 | — | docs ↗ |
| Deterministic capture Frame-stable captures independent of real time | CLI godot --fixed-fps 60 --write-movie out.avi | — | docs ↗ |
| Run under a virtual display Render in CI, where --headless cannot draw | CLI xvfb-run -a godot --path . res://scenes/debug_capture.tscn | — | docs ↗ |