Skip to main content
Version: 0.5.0

EYES MANDATORY — never program blind

Before any other rule in this docs site, this one: agents driving ClaudusBridge MUST USE THE STREAMING CAPTURES. API success is not visual success. Every editor tool returns success based on whether the API call completed, NOT whether the resulting asset actually looks right. The only way to catch the gap is to look at the editor through the WebRTC /preview stream and analyze the PNG with multimodal vision.

This is the rule the rest of the system is built around. Everything else is plumbing.

Concrete examples — three real failures from one session​

These all happened in a single multi-sub-agent test where the agents were told "verify structurally, no captures needed." Every one passed compile and returned success. Every one was visually broken — the user spotted it immediately.

M_HoloPanel — solid black sphere​

A material with a Time → Sine → Multiply → Emissive Color chain plus a Fresnel + Constant3Vector base color. Compiled clean, recompile_material returned success: true, errors: 0. Looked like:

Solid pure-black sphere in the preview viewport.

The Constant3Vector was left at default (0, 0, 0) — never set to the cyan it was supposed to be. The pulse-amplitude Constant was 0 — multiplications down the chain produce zero. Emissive Color received zero, sphere rendered black. Compile success, visual zero.

BP_HealthPickup — events disabled, won't fire​

A pickup actor with a Tick event that should rotate the mesh slowly. Compiled clean, compile_blueprint returned success: true, has_errors: false. Looked like:

Three "Event Tick" nodes in the canvas, all marked "This node is disabled and will not be called." The Make Rotator → AddActorLocalRotation graph existed but the Tick events weren't firing.

The agent had called add_event_node for Tick three times — UE only supports one Tick event per actor. The duplicates remain in the graph as orphaned, disabled nodes. Compile success, runtime zero.

WBP_GameHUD — three bars stacked invisibly​

A HUD widget with Health / Stamina / Mana progress bars. Compiled clean, compile_widget_blueprint returned success: true. Designer tab looked like:

One tiny gray sliver at the top-left around (388, 217). Hierarchy showed RootCanvas only (collapsed).

Two hidden defects: all three bars had Percent: 0 (so they were invisible — only the dark gray track shows), and all three had been positioned at canvas slot (0, 0) because the agent set Position instead of the canonical LayoutData struct (which set_slot_property silently rejects). Three bars stacked at one point, all invisible. Compile success, visual zero.

The mandatory cadence​

For any editor work where the result has visual implications (which is most editor work), the cadence is:

1. cb call open_asset_editor '{"asset_path":"/Game/<asset>"}'
2. wait ~3 seconds (let the editor focus + stream catch up)
3. capture via cb capture OR Claude in Chrome MCP `computer screenshot`
4. READ the returned PNG with your own multimodal vision
5. describe what you actually see (preview color, node count, errors,
   focused tab, hierarchy entries) — do NOT trust the API returns
6. make ONE small change
7. capture again — confirm the visual changed in the expected direction
   (if it did NOT, the tool call did not work; record gotcha + retry)
8. repeat 6-7 until visually correct

Structural verification (read_blueprint, get_widget_tree, get_material_graph) is complementary, not a substitute. Use both. Structural reads are fast and detail-rich; visual reads catch the silent failures structural reads can't see.

Editor refresh quirks worth knowing​

Some quirks are about the editor itself, not the tools. Document them; don't fight them.

Material edits don't auto-apply to the preview​

Even after set_expression_property and recompile_material both return success, the material editor's preview sphere stays stale until the Apply button in the toolbar is clicked (around screen-px 240, 64 in a default editor layout). This is UE behavior, not a tool bug.

If your post-recompile capture still shows the old preview, the material is fine but the editor hasn't pushed the new shader to the preview yet. Click Apply, recapture, confirm.

realtime_mode is often OFF​

When the editor is idle, the viewport stops ticking until interaction. get_editor_state shows realtime: false and delta_time: 0.33 (i.e. 3 fps). Your /preview captures will show whatever was last drawn — which can be many seconds old.

Before any sequence of captures (especially of animations, particles, or anything time-varying), call:

cb call set_realtime_mode '{"enabled":true}'

Restore to false after to save GPU.

ProgressBar Percent: 0 is invisible​

A canvas-mode UMG ProgressBar with Percent: 0 shows only the dark gray track and reads as "no fill" — even with FillColorAndOpacity correctly set. To verify the color visually, set Percent: 0.5 (or any non-zero value) so the colored fill is actually visible. Set the runtime value via your widget's logic afterward.

UMG canvas slot positioning uses LayoutData, not Position​

set_slot_property rejects Position ("Slot property not found") but accepts the full LayoutData struct:

"value": "(Anchors=(Minimum=(X=0,Y=0),Maximum=(X=0,Y=0)),Offsets=(Left=20,Top=20,Right=200,Bottom=24))"

If you've set Position-like fields and the bars all stack at (0, 0), this is why.

When spawning sub-agents​

If you orchestrate sub-agents to do editor work (specialists for material, blueprints, UMG, etc.), the spawn prompt MUST require captures. Telling a sub-agent "verify structurally, no captures needed" produces blind programming — the kind that compiles cleanly and looks completely wrong.

Even one capture per asset is infinitely better than zero. One capture per meaningful change is the right cadence per the Iterative Dialogue pattern.

A sub-agent prompt template:

You are a [domain] specialist. You MUST use streaming captures throughout.
Programming blind is the failure mode you are explicitly avoiding.

Mandatory setup:
  1. Load Claude in Chrome MCP browser tools via ToolSearch
     (or assume `cb capture` is available via the Codex bridge).
  2. Find the existing /preview tab and cache its tabId.
  3. Verify cb stream returns ready: true.

Mandatory cadence per asset:
  A) cb call open_asset_editor '{"asset_path":"/Game/<asset>"}'
  B) wait 3 seconds
  C) Take screenshot
  D) READ the PNG with native vision; describe what you see
  E) Diagnose what's wrong visually (if anything)
  F) Make ONE small change
  G) Take another screenshot, READ it, confirm visual changed
  H) Repeat F-G until visually correct

Structural verification (read_blueprint, get_widget_tree, etc.) is
complementary, never a substitute. Always vision-verify.

Why this matters for the user experience​

When an agent programs blind and ships work that compiles but looks wrong, the user sees the failure first — and instantly loses trust in the system. The whole reason ClaudusBridge ships an in-process watcher, a canonical visual watcher prompt, a Codex bridge with existingTab capture, a cb capture shortcut, and per-asset open_asset_editor is so this never happens.

The streaming exists to be the agent's eyes. Without eyes, the agent is guessing in the dark and the user pays the cost of catching every silent failure. With eyes, the agent works the way a human works — make a change, look at it, decide what's next.

This is non-negotiable. Everything else in this docs site is built on top of it.

Next steps​