miracle1814/ue5-automation

**English** | 简体中文
**Let AI agents (or scripts) actually operate the Unreal Editor** — read blueprints, build them from scratch, edit them incrementally, author materials and UMG widget blueprints, verify behavior in PIE at runtime, self-service logs, and audit whole projects.
**Engine support: UE 5.1 – 5.8** (5.1 & 5.8 ship with prebuilt bridges — zero compilation).
> 🎬 **Demo GIF** — coming soon: a 60–120s capture of "one sentence → agent builds a
> blueprint → PIE runtime verification" will be embedded here.
---
Why this exists
Most "AI controls Unreal" attempts die at the same wall: **Python cannot reach UEdGraph**.
You can demo asset creation in a day, but node-level graph authoring, reliable connections,
and "the operation actually did what it claimed" are where projects stall.
This toolkit solves that with:
- **A C++ bridge plugin** (59 editor UFUNCTIONs): node creation, pin/connection editing with
GUID-based targeting, widget-tree authoring, material expression enumeration — the things
Python physically cannot do in-engine.
- **A verification discipline**: every write operation is **read back and compared**
(fail-loud, never fake success), connections are verified against live topology,
compile results are read back with a log-pattern scan.
- **Runtime behavior checks**: start PIE, read live actor state, teleport with read-back —
prove the logic *runs*, not just that it compiles.
- **A security model you can defend to a studio**: localhost-only, token auth,
a 72-command whitelist (no arbitrary code execution), transaction logs, rollback.
Feature overview
| Domain | What it does |
|:--|:--|
| 🔍 Blueprint analysis | classes / variables / CDO / node graph / connections → Markdown + Mermaid reports |
| 🏗️ Blueprint creation | asset + variables + components + interfaces + events + function nodes + wiring + compile (atomic, rolls back on failure) |
| ✏️ Incremental editing | pin default values, connect/disconnect (topology-verified), delete with reference checks, transaction rollback |
| 🎨 Materials | create → expressions (params, math, samplers) → connect to properties → compile → instances |
| 🧩 UMG widget blueprints | create → widget tree (panels/text/buttons…) → set properties → graph logic reuses blueprint commands |
| ▶️ PIE runtime verification | start/state/live actors/read properties/teleport with read-back/stop |
| 🖥️ Actors & levels | query / spawn / transform / read properties |
| 🩺 Log diagnostics | parse engine logs + 19-rule error pattern library + incremental log reader |
| 📐 Project audit | whole-project scan: counts, complexity, coupling, circular deps, hot spots |
| ⚡ Batch execution | multi-step operations in a single request |
**Security model**: localhost bind, token auth, command whitelist, read-back verification on
writes, transaction logs, scoped saves only (never saves the whole project).
Requirements
| Engine | Read/audit/diagnose | Node-level blueprint writes | Materials/UMG | MCP access |
|:--|:--|:--|:--|:--|
| **5.1.x** | ✅ out of the box | ✅ prebuilt DLL included | ✅ | ✅ built-in /mcp |
| 5.2–5.5 | ✅ | ⚠️ compile the bridge once (bridge/Source/build_for_engine.bat) | ⚠️ same | ✅ |