Unreal Bridge

UnrealBridge

Execute Python directly inside a running UE 5.3+ editor. Protocol-v2 auto-discovery defaults to paired host-local UDP probes: multicast 239.255.42.99:9876 with TTL 0 plus loopback 127.0.0.1:9876. Use --discovery-scope=lan only when another host must be discovered; it raises multicast TTL to 1 while retaining loopback. Malformed replies and Windows UDP reset notifications are skipped independently, valid responses are de-duplicated by Server-start UUID, and wildcard binds use the UDP response source IP. The six pre-existing exact commands remain the minimum capability set; exact_editor_status is advertised and negotiated separately, so an older protocol-v2 endpoint remains usable for its supported base commands. Unique future capabilities remain forward-compatible. Every bounded TCP response is rechecked against the frozen identity. The TCP data port is OS-assigned per editor.

Preconditions

If bridge.py returns discovery: no UnrealBridge editors found, walk these in order — don't troubleshoot Python or firewalls first:

1. Plugin and matching skill installed with sync_project.bat <UEProjectRoot>. Check: <UEProject>/Plugins/UnrealBridge/UnrealBridge.uplugin exists. The legacy sync_plugin.bat command name accepts the same project-root argument.
2. Plugin enabled — check <UEProject>/<Project>.uproject "Plugins" block for {"Name":"UnrealBridge", "Enabled":false} and flip if present.
3. Editor up and ready — bridge.py ping returns "ready": true. false means MainFrame still loading; wait 10–60s.

The loopback probe keeps local discovery working when multicast is blocked by a VPN, virtual NIC, or Windows firewall policy. The discovery group must be an IPv4 multicast address; direct unicast mode is intentionally fail-closed: --endpoint, --instance-id, --expected-pid, and --expected-project-path (or matching UNREAL_BRIDGE_* variables) are one inseparable tuple. Copy the identity values verbatim from one discovery response or Server startup line; project_path is case- and representation-sensitive on every OS. A host/port alone can be stale and is never used as a legacy fallback. Python 3.7+ stdlib only.

Waiting for the editor to become ready (post-launch / post-relaunch)

After launching/relaunching the editor, poll readiness with Monitor (streams progress events, recommended) or Bash with run_in_background: true (one completion event). Don't write a foreground for/sleep countdown — the harness blocks long leading sleeps and you'll miss readiness.

Paste this verbatim as the command for either tool:

end=$(( $(date +%s) + 300 ))
i=0
until python .claude/skills/unreal-bridge/scripts/bridge.py --json --timeout 3 ping 2>/dev/null | grep -q '"ready": *true'; do
  now=$(date +%s)
  [ "$now" -ge "$end" ] && { echo "[wait] TIMEOUT after 300s"; exit 1; }
  i=$((i + 1))
  [ $((i % 3)) -eq 0 ] && echo "[wait] still booting ($((end - now))s left)"
  sleep 10
done
echo "[wait] READY"

Then call one of:

Monitor(description="UE editor ready-poll", command=<block above>,
        timeout_ms=360000, persistent=false)

Bash(description="Wait for UE editor ready", command=<block above>,
     run_in_background=true, timeout=360000)

Locks (don't change without reading):

• Grep "ready": *true — TCP-up ≠ MainFrame-ready. success:true, ready:false means exec calls will be rejected; ping success alone is not enough.
• Ping FIRST then sleep — no leading sleep (harness blocks long ones).
• i % 3 echo gate — caps notifications at ~10 over 5 min so Monitor doesn't trip its event-flood auto-stop.
• end deadline must stay below the tool timeout_ms/timeout so you get [wait] TIMEOUT rather than a silent harness kill.
• Path is relative to repo root; ${CLAUDE_SKILL_DIR} is not reliably set in Monitor/Bash subshells — don't substitute it here.
• After the loop returns, do one foreground bridge.py ping before real work — bg success is past tense.
• Multi-editor host: append --project=<name> to the ping inside the loop.
• Skip this entirely when invoking rebuild_relaunch.py — it polls internally and prints [rebuild] bridge is ready. on success.

Bridge CLI

python "${CLAUDE_SKILL_DIR}/scripts/bridge.py" [options] <command> [args]

Discovery-mode optional flags: --project=<name|path> (disambiguate when >1 editors run; or env UNREAL_BRIDGE_PROJECT), --discovery-scope=local|lan (local default; or env UNREAL_BRIDGE_DISCOVERY_SCOPE), --token=<secret>, --timeout=<s>, --json, --no-preflight. Global flags precede the subcommand, for example bridge.py --discovery-scope=lan list-editors. Direct mode requires the complete --endpoint=host:port --instance-id=<uuid> --expected-pid=<pid> --expected-project-path=<uproject> tuple; none of its four fields is optional.

Workflow

1. Always ping first.
2. Default to exec --stdin heredoc, NOT exec-file. A heredoc is the right mode for ~95% of one-shot work — no temp file to name, no cleanup, prompt stays self-contained, no risk of dangling scripts in $TEMP / .tmp / project root. Only reach for exec-file when you genuinely intend to re-run the same script multiple times (iterating on a fix, comparing runs). One-shots like "find X, list Y, build a report" → heredoc. If you find yourself writing with open("/tmp/foo.py", "w") followed by bridge.py exec-file /tmp/foo.py, stop and rewrite as a heredoc.
3. --json for parseable output.
4. Exit codes: 0 success · 1 runtime/transport · 2 bad CLI args · 3 AST preflight rejected.
5. If exec hangs: read the timeout response first. blocked_by_modal:true includes the active window and its controls. Otherwise use status first: it reads cached Engine/Slate ages without dispatching fresh GameThread work. Follow with gamethread-ping only when a fresh liveness probe is useful, or resume for a BP breakpoint.

Blocking modal dialogs — inspect, decide, then act

Slate dialogs run a nested event loop that blocks the normal Python exec queue. UnrealBridge's modal commands use a separate GameThread task path, so they keep working while the original call is suspended.

1. Run modal-status (an exec* timeout does this automatically).
2. Read the title and full body, then decide whether an action is safe and consistent with the user's request. Never click the first/default/affirmative button merely to unblock the editor.
3. Use the exact snapshot_id and control id returned by that inspection.
4. After modal-set-text or modal-set-checkbox, use the new snapshot returned by that command for the next action. A stale id is deliberately rejected.
5. If the dialog is destructive, ambiguous, requests credentials/consent, or expands the user's authorized scope, leave it open and ask the user.

Example:

python "${CLAUDE_SKILL_DIR}/scripts/bridge.py" --json modal-status
python "${CLAUDE_SKILL_DIR}/scripts/bridge.py" modal-click 8f1a2b3c4d5e6f70 0

Password input contents are reported only as <redacted>. These commands cover UE Slate modals. A platform-native file picker or crash reporter may stop the GameThread before it can pump this bypass; treat a modal-status GameThread timeout as a distinct native-window/deadlock diagnosis rather than blind retry.

Multi-line example:

python "${CLAUDE_SKILL_DIR}/scripts/bridge.py" exec --stdin <<'EOF'
from unreal_bridge import Asset
paths, _ = Asset.search_assets_in_all_content(query="Hero", max_results=5)
for p in paths:
    print(p.export_text())
EOF

Windows path gotcha (Bash tool only): unquoted backslashes get eaten by bash word-splitting — python G:\Claude\UnrealBridge\.claude\skills\unreal-bridge\scripts\bridge.py exec ... arrives as G:ClaudeUnrealBridge.claudeskillsunreal-bridgescriptsbridge.py and fails with "No such file or directory". Use forward slashes (G:/Claude/...) or single-quote the path ('G:\Claude\...'). The body inside <<'EOF' ... EOF is literal and unaffected — only the arg before the heredoc matters. PowerShell tool is unaffected.

API surface — use the wrapper module first

from unreal_bridge import Asset, Level, Blueprint, Editor, Anim, Rig, Niagara, Material, PoseSearch, Chooser, StateTree, SmartObject, ...
paths, _ = Asset.search_assets_in_all_content(query="Hero", max_results=20)

The wrapper has 26 classes (one per UnrealBridge*Library) with kwargs-only signatures — positional args raise TypeError immediately, no UE round-trip. This is the structural fix for positional-arg-order hallucinations. Regenerate after C++ header changes via python tools/gen_manifest.py.

Fallback: raw unreal.UnrealBridge*Library.foo(...) works (preflight catches errors), but prefer the wrapper.

AST preflight (automatic — safety net only)

Every exec* call runs an AST preflight in the bridge client BEFORE sending. Reads scripts/bridge_manifest.json and rejects locally (exit 3, no UE round-trip) when:

• Function/library name doesn't exist (with did-you-mean)
• Required args missing / unknown kwarg / param given twice
• unreal.BridgeXxx.YYY enum member doesn't exist

Type validation is NOT done by preflight. Wrong asset paths / wrong scope still surface at runtime — references prose still matters for those.

Treat preflight as a backstop, not a planning tool. If you write code expecting preflight to autocorrect your guesses, you'll produce noisy output and still hit runtime tracebacks for the half it can't catch (USTRUCT field names, Python attribute access, EditDefaultsOnly violations). See "Verify before you call" below.

Bypass with --no-preflight (rare). Preview with bridge.py preflight <path>.

Common semantic traps (preflight does NOT catch)

Verify before you call — don't lean on preflight

Preflight is a safety net, not a planning tool. Writing code from imagined API / field / attribute names and waiting for preflight to tell you the right one produces noisy output (4-8 [WARN] per script, often still ending in a runtime traceback) and wastes round-trips. Verify FIRST, then write the script. Four axes:

1. Bridge function names — grep scripts/bridge_manifest.json or read the relevant references/bridge-*-api.md. Don't translate the C++ name into snake_case in your head and assume.
2. Bridge USTRUCT return-value fields — return types like BridgeGameplayEffectInfo keep a minimum set of fields (not exhaustive); UE 5.x evolves struct shape between versions. Look up the fields in bridge_manifest.json structs section, OR run a one-off probe print([a for a in dir(obj) if not a.startswith('_')]) BEFORE writing the consumer code.
3. UE object attributes — never <obj>.<attr>. Always get_editor_property (and respect protected: / EditDefaultsOnly rejection). Use Level.list_actor_properties(actor_name=...) or Level.list_class_properties(class_path=...) to list first.
4. Function signatures — when unsure: unreal.UnrealBridgeXxx.fn.__doc__ first line is the signature. Cheaper than a guess + correction round-trip.

Symptom you're in the bad loop: your last few exec attempts produced [WARN] lines from preflight followed by AttributeError tracebacks. Stop, run one heredoc with dir() / manifest grep, then write the real script.

Never silently bail to raw unreal.*

If a bridge call returns empty / errors, suspect your parameters (wrong scope / path / filter), not the wrapper. Falling back to unreal.AssetRegistryHelpers etc. bypasses preflight, audit logging, and often walks 100k–2M registry entries.

Preflight emits [WARN] on known raw-fallback patterns and shows the bridge equivalent inline. To look up before writing: bridge.py suggest [pattern]. Patterns currently mapped:

If you genuinely believe no bridge function covers your case, ask the user before reaching for raw unreal.*.

Reference index — read these for usage / traps / workflow patterns

Signatures are now mechanically enforced (preflight). References carry semantic traps, scope warnings, and workflow patterns preflight can't catch.