Ue Agent Bridge

UE_AgentBridge

UE_AgentBridge gives coding agents eyes and hands in Unreal Engine.

It combines an Unreal plugin, an MCP bridge, and companion agent skills so tools like Codex and Claude can look inside a live Unreal Editor session, understand what is actually happening, and perform a small set of safe actions.

The point is to stop wasting time and tokens on guesswork. Instead of making the model infer Unreal state from code alone, UE_AgentBridge lets it ask the editor directly while code edits, builds, and git stay in the normal repo workflow.

This project is plugin-first:

• TypeScript MCP server over stdio
• reusable Unreal project plugin under [unreal-plugin/UEAgentBridge](./unreal-plugin/UEAgentBridge)
• plugin mode for normal live-editor use
• remote-control fallback for asset search and explicit property reads/writes
• mock mode for local validation without Unreal

Why It Exists

AI agents can write and change Unreal code, but they usually cannot see what Unreal Editor is doing right now.

This project fixes that gap.

With UE_AgentBridge, an external agent can:

• check whether the editor is ready and connected
• inspect selected actors, level actors, and object properties
• make narrow, explicit property changes
• read output log slices and editor diagnostics
• move the viewport camera and capture useful screenshots
• inspect debug draw output for visual debugging
• check Live Coding readiness and trigger a safe reload path
• run only a small allowlisted set of safe console actions

That helps in two ways:

• the agent can query real editor state instead of guessing from code alone
• it can pull the exact screenshot, actor state, or log slice it needs instead of burning tokens on back-and-forth trial and error

What stays outside Unreal on purpose:

• repo navigation
• file editing
• git
• shell and build command execution
• architecture and code reasoning

Unreal provides the eyes and hands. The repository stays the source of truth for code work. That split is what makes the workflow safer, clearer, and cheaper in tokens.

Install

Requirements:

• Node.js 20+
• Unreal Engine 5.7 tested on Windows

Install JS dependencies:

npm install

Install the Unreal plugin into a target project:

1. run powershell -ExecutionPolicy Bypass -File .\scripts\sync-ue-plugin.ps1 -ProjectRoot ""
2. build Editor
3. launch Unreal Editor

Build a distributable plugin zip:

npm run package:plugin

That stages a clean plugin package under artifacts/plugin-package and creates a zip for third-party installation testing.

Quick Start

Local mock validation

1. npm install
2. npm test
3. npm run dev
4. run ue_healthcheck

Real Unreal validation

1. install the UEAgentBridge plugin into the target Unreal project
2. make sure Unreal Editor is running locally
3. keep Remote Control enabled for ue_asset_search, ue_get_property, and ue_set_property
4. start the bridge with UE_BACKEND_MODE=plugin
5. run ue_healthcheck
6. exercise a few live tools such as ue_get_level_actors, ue_get_output_log, ue_get_editor_state, ue_frame_actor, and ue_get_live_coding_status

Build, run, and checks

npm run typecheck
npm test
npm run build
npm run dev

For repeatable plugin smoke validation:

npm run build
npm run smoke:plugin

For C++ iteration, use the external build loop in [CPPITERATIONWORKFLOW.md](./docs/guides/CPPITERATIONWORKFLOW.md). Full external Editor target builds should run with Unreal Editor closed, while in-editor iteration should use the bridge's Live Coding path after a successful external build.

Architecture

The repository is split into:

• MCP layer: tool registration, validation, formatting, and error handling
• backend layer: Unreal transport adapters
• Unreal plugin package: bounded editor-side backend
• docs: operator guides, release notes, contracts, and archive material

Repo layout:

docs/
  archive/
  contracts/
  guides/
  integrations/
  planning/
  release/
src/
  backend/
  config/
  server/
  tools/
  types/
  utils/
test/
unreal-plugin/
  UEAgentBridge/

Contributing

Contributions are welcome.

Start with [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request. For workflow-sensitive changes, keep the repo/Unreal boundary aligned with [AGENTPLAYBOOK.md](./docs/guides/AGENTPLAYBOOK.md).

License

This project is released under the [MIT License](./LICENSE).

Documentation

Most users only need the core guides:

• [AGENTPLAYBOOK.md](./docs/guides/AGENTPLAYBOOK.md)
• [CPPITERATIONWORKFLOW.md](./docs/guides/CPPITERATIONWORKFLOW.md)
• [PLUGINRUNBOOK.md](./docs/guides/PLUGINRUNBOOK.md)
• [THIRDPARTYINSTALL.md](./docs/guides/THIRDPARTYINSTALL.md)
• [CLIENTINTEGRATION.md](./docs/guides/CLIENTINTEGRATION.md)

Full documentation index:

• [docs/README.md](./docs/README.md)

Useful starting points:

• [AGENTPLAYBOOK.md](./docs/guides/AGENTPLAYBOOK.md) for the intended repo/Unreal operating model
• [PLUGINRUNBOOK.md](./docs/guides/PLUGINRUNBOOK.md) for day-to-day plugin workflow
• [THIRDPARTYINSTALL.md](./docs/guides/THIRDPARTYINSTALL.md) for installation outside this repo
• [FABRELEASEREADINESS.md](./docs/release/FABRELEASEREADINESS.md) for marketplace preparation

Internal planning, contracts, release checklists, and historical notes remain available from the full docs index.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aborigen19961202
• Source: aborigen19961202/ue-agent-bridge
• License: MIT

Install and usage instructions live in the source repository linked above.