# UE BPToolkit

**Blueprint read / review / generate toolkit for AI coding agents (ZCode, Claude Code, Cursor, any MCP client) on Unreal Engine 5.4+.**

`.uasset` blueprints are binary and UE's Python API cannot touch graph internals (`EdGraph.Nodes` is protected) — so agents can't see your blueprint logic. UE_BPToolkit ships a small editor-side C++ plugin that exposes safe read/write primitives, a warm headless-editor session that drives them, and an MCP server + CLI on top.

Verified on **UE 5.4.4** with the [City Sample](https://www.unrealengine.com/marketplace/en-US/product/city-sample) project (985+ node blueprints, Wwise audio integration).

## What you can do

| Capability | How |
|---|---|
| **Read** blueprint logic | `bp_dump` / `bpt dump` — full JSON: graphs → nodes (function/variable/event info) → pins (type, defaults, links, orphaned flags) + SCS component tree + variables |
| **Review** logic chains & Wwise | `bp_review` / `bpt review` — reconstructs execution chains from each entry event, inventories Wwise touchpoints, flags issues (orphaned pins, missing assets, empty RTPC/Event refs, PostEvent reachable from Tick) |
| **Generate** blueprints | `bp_generate` / `bpt generate` — build a blueprint from a JSON spec (components, variables, function graphs, nodes, wiring), compile and save; compiler errors come back per-node |
| **Drive the editor** | `bp_eval` — arbitrary python inside the editor as an escape hatch |

## Architecture

```
MCP client (ZCode / Claude Code)          CLI (bpt)
        │  MCP stdio                           │
        ▼                                      ▼
  bptoolkit-mcp ────────────┬──────────── bptoolkit.cli
                            ▼
                  SessionManager ── file-based job queue ──► headless UnrealEditor-Cmd.exe
                  (starts once, stays warm)                   └─ BPToolkit plugin (C++)
                                                                  └─ EdGraph primitives
```

- **First tool call boots the editor (30–90 s); subsequent calls are fast.** The session lives in `<project>/Saved/BPToolkit/` and shuts down when your MCP server stops.
- The C++ plugin (`UEPlugin/BPToolkit`) exposes ~14 UFUNCTIONs (dump / create / add component-variable-functiongraph / spawn event-call-variable-self nodes / connect pins / set defaults / compile / save). Write operations take the `UBlueprint` object directly; nodes are addressed by GUID.

## Install

Requirements: Python 3.10+, Unreal Engine 5.4+ (Windows; source-built or launcher), and for the plugin: VS 2022 with the C++ workload.

```bash
git clone <this repo>
cd UE_BPToolkit
pip install -e ".[mcp]"
```

Then install the plugin into your project (copies `UEPlugin/BPToolkit` to `<project>/Plugins/` and enables it in `.uproject`):

```bash
bpt install-plugin --project D:/path/MyGame
# then build the editor target once, e.g.:
# "D:/Game/Epic Games/UE_5.4/Engine/Build/BatchFiles/Build.bat" MyGameEditor Win64 Development -project=D:/path/MyGame/MyGame.uproject -WaitMutex
```

## Use as an MCP server

ZCode / Claude Code config (`.mcp.json` / `mcp_servers`):

```json
{
  "bptoolkit": {
    "command": "bptoolkit-mcp",
    "args": ["--project", "D:/path/MyGame", "--engine", "D:/Game/Epic Games/UE_5.4"]
  }
}
```

Environment fallback: `BPT_PROJECT`, `BPT_ENGINE`, `BPT_UEPLUGIN`.

## Use from the CLI

```bash
export BPT_PROJECT=D:/path/MyGame          # or pass --project each time

bpt status
bpt dump /Game/Audio/Vehicles/BP_Vehicle_AudioController_Wwise --out bp.json
bpt review /Game/Crowd/Blueprints/BP_CrowdCharacter --out review.md
bpt generate examples/specs/selftest.json   # needs a project with the Wwise integration
bpt selftest                                # generate -> dump round-trip validation
```

## Example: generate a Wwise blueprint

```json
{
  "asset": "/Game/Testing/BPToolkit/BPT_TestSound",
  "delete_existing": true,
  "parent": "/Script/Engine.Actor",
  "components": [
    {"class": "/Script/AkAudio.AkComponent", "name": "AkComp"}
  ],
  "variables": [
    {"name": "TestEvent", "type": "object", "sub": "/Script/AkAudio.AkAudioEvent"}
  ],
  "graphs": [{
    "name": "EventGraph",
    "nodes": [
      {"id": "bp", "kind": "event", "function": "/Script/Engine.Actor:ReceiveBeginPlay", "x": 0, "y": 0},
      {"id": "akcomp", "kind": "var_get", "variable": "AkComp", "x": 200, "y": 100},
      {"id": "evget", "kind": "var_get", "variable": "TestEvent", "x": 200, "y": 200},
      {"id": "post", "kind": "call", "function": "/Script/AkAudio.AkComponent:PostAkEvent", "x": 450, "y": 0}
    ],
    "connections": [
      {"from": ["bp", "then"], "to": ["post", "execute"]},
      {"from": ["akcomp", "AkComp"], "to": ["post", "self"]},
      {"from": ["evget", "TestEvent"], "to": ["post", "AkEvent"]}
    ]
  }],
  "compile": true, "save": true
}
```

Node/pin notes for spec authors: a call node's target pin is named `self` (the compiler error text calls it "Target"); variable-get nodes expose an output pin named after the variable; exec pins are `execute`/`then`. A "pre-compile" pass runs automatically so freshly added components/variables resolve.

## Wwise review rules

Detection is structural, not name-based allow-lists: any call into `/Script/Ak*` / `/Script/Wwise*` owners (`PostAkEvent`, `PostEvent`, `SetRTPCValue*`, `SetSwitchGroupValue`, `SetStateValue`, ...), any `Ak*/Wwise*` typed variable/component/pin, any default object under `/Game/WwiseAudio/`. Issues checked: orphaned pins (stale signatures), compile messages, missing referenced assets, empty Event/RTPC pins, post-events reachable from Tick.

## Troubleshooting

- **"BPToolkit plugin is not loaded"** — run `bpt install-plugin`, rebuild the editor target, retry.
- **UBT error about rules assembly / `DLSSUtility`** — delete `Intermediate/Build/Win64/x64/<Target>/Development/Makefile.bin` in the project and rebuild.
- **MSVC 14.44+ compile error in `ConcurrentLinearAllocator.h`** — UE 5.4 header needs a guard; patch is one line:
  `#elif __has_feature(address_sanitizer)` → `#elif defined(__has_feature) && __has_feature(address_sanitizer)`. (Short-circuit `&&` in the same `#if` does **not** work — use a nested `#if defined(__has_feature)` / `#if __has_feature(...)`.)

## Security & caveats

- **`bp_eval` is arbitrary code.** `bp_eval` runs unrestricted Python inside the headless editor (`unreal` module + `BPL` library in scope). Treat the MCP server as a local-only tool. Do not expose it on a network or to untrusted clients; do not point it at a `.uproject` you don't trust.
- **`bp_generate` mutates your project.** A bad spec can create/delete/save blueprint assets inside the target project. Always run against a project you own and ideally under version control.
- **Editor binaries are not in this repo.** You must build `UEPlugin/BPToolkit` inside your own UE 5.4+ project before the first session (see Install above). The prebuilt `.dll`/`.pdb` shipped here is gitignored on purpose.
- **Windows-only runner.** The host launches `UnrealEditor-Cmd.exe`. Linux/macOS support is on the roadmap.

## Roadmap

- [ ] Mac/Linux editor support (runner is Windows-only today)
- [ ] Wwise bank/event cross-checks against the generated Wwise project data
- [ ] Blueprint diffing (two dumps → semantic diff)
- [ ] Macro / interface scaffolding in generate
- [ ] Remote TCP transport inside the editor (alternative to the file queue)

## License

MIT — see [LICENSE](LICENSE).