UnrealBridge CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

UnrealBridge is a TCP bridge between external tools (Claude Code) and Unreal Engine 5.3+ (verified clean BuildPlugin against 5.3.2 / 5.4.4 / 5.5.4 / 5.6.1 / 5.7.1 / 5.8.0 via tools/build_matrix.py; some libraries are gated to 5.7+ and a few inline shims handle 5.3 and 5.8 — see docs/version-compatibility.md). UE 5.2 and earlier are not supported. It consists of:

• A UE Editor plugin (Plugin/UnrealBridge/) that runs a TCP server inside the editor
• A Python CLI client (.claude/skills/unreal-bridge/scripts/bridge.py) used by the unreal-bridge skill
• API reference docs and helper scripts for querying/manipulating UE assets via Python

Key Commands

Sync plugin and matching skills to a UE project:

sync_project.bat D:\Path\To\YourProject

Mirrors Plugin/UnrealBridge/ plus .claude/skills/unreal-bridge/ into the target project's plugin, .agents, and .claude destinations. Local plugin build outputs are retained. sync_plugin.bat is a legacy command-name alias with the same project-root argument.

Test bridge connection:

python .claude/skills/unreal-bridge/scripts/bridge.py ping

Execute Python in UE:

python .claude/skills/unreal-bridge/scripts/bridge.py exec "print('hello')"
python .claude/skills/unreal-bridge/scripts/bridge.py exec-file script.py

Architecture

TCP Protocol

Length-prefixed JSON over TCP on an OS-assigned port (default bind 127.0.0.1, port auto-allocated at startup). Clients find the editor via the UDP discovery service (host-local by default; see next section) — port 9876 is no longer hardcoded on the TCP data channel.

• Request: [4 bytes big-endian length][JSON: {"id":"...", "command":"exact_exec", "expected":{"protocol_version":2,"instance_id":"...","pid":...,"project_path":"..."}, "request":{"script":"...","timeout":30}, "token":"..." (optional)}]
• Response: [4 bytes big-endian length][JSON: {"id":"...", "success":bool, "output":"...", "error":"...", "protocol_version":2, "instance_id":"...", "pid":..., "project_path":"..."}]
• Token auth: required when the server binds non-loopback. The token is written to <Project>/Saved/UnrealBridge/token.txt; clients read it and add "token":"<value>" to every request. Constant-time compared on the server.
• Every request uses an exact_* command with frozen discovery identity. Payload fields live under request, so a legacy server cannot mistake exact_exec for an ordinary script request. The production dispatcher rejects missing/malformed identity, request objects, and unknown/legacy commands before any command body, work admission, or GameThread dispatch; the client rejects response identity drift. project_path is one wire-canonical string and must match discovery/startup output exactly on every OS.
• Client response frames are bounded to MAX_RESPONSE_FRAME_BYTES (10 MiB), must be non-empty, valid UTF-8, and decode to a JSON object before identity fields are read.
• Special exact commands (handled inline on the worker thread, bypass the Python exec queue):
  • exact_ping → pong (TCP-only liveness)
  • exact_editor_status → cached Engine/Slate tick ages, readiness, staleness and modal-attention summary (no fresh GameThread dispatch)
  • exact_gamethread_ping → alive/unresponsive + latency_ms (GT liveness)
  • exact_debug_resume → unsticks a paused BP breakpoint via FKismetDebugUtilities::RequestAbortingExecution
  • exact_modal_status → structured active-Slate-modal snapshot (title, body, buttons, redacted inputs, checkboxes)
  • exact_modal_action → guarded click/input/checkbox action; rejects stale snapshots