kevinpbuckley/VibeUE

**VibeUE 是一款专为 Unreal Engine 5.8+ 打造的 MCP 扩展 + AI 编辑器工具集。** Unreal 5.8 内置了 MCP server 和 AI 工具集；而 VibeUE 是一款直接接入其中的 **MCP 扩展**，并 添加了一套深度的 **AI 编辑器工具集** —— 这是一座编辑器功能库 —— 包含 Blueprints、材质、地形、植被、动画、Niagara、UMG、音频、StateTree、 gameplay tags、输入、UV、**性能/分析** 等 —— 它们会被注册到引擎自带的 `ToolsetRegistry` 和 `ModelContextProtocol` server 中，同时通过 Unreal 原生的 `AgentSkill` 系统提供丰富的特定领域 **技能**。任何支持 MCP 的 agent（Claude Code、Cursor、Copilot 等……）都可以通过 Unreal 的标准 MCP endpoint 来驱动你的编辑器。 ## ✨ VibeUE 增加了什么 Unreal 5.8 自带了 AI 工具集（Blueprints、材质、actors、assets、meshes、data tables 等）。 VibeUE 对其进行了**补充** —— 它专注于引擎未涵盖的领域和深度： - **地形与世界** —— Landscape 雕刻/heightmaps/splines，Landscape 自动材质 + RVT， Foliage，程序化 FPS **Map Blockout**，以及**真实世界地形**（来自 GPS 的 heightmaps + 水体）。 - **音频** —— MetaSound 和 SoundCue 图表编写。 - **动画 assets** —— AnimSequence 关键帧编辑，AnimMontage 编写，AnimBP 状态机， Skeleton 骨骼/socket/retarget/blend-profile 编辑。 - **FX 深度** —— Niagara emitter 颜色/曲线编写以及 **Custom-HLSL scratch-pad** 模块。 - **UI** —— 带有 MVVM 绑定的 UMG widgets、动画编写以及预览/PIE 验证。 - **高阶 Blueprint 编写** —— timelines、event dispatchers、delegates、custom-event pins、 comment boxes，以及批量 `build_graph` 构建器。 - **编辑器安全性** —— `TransactionService` 封装了编辑器的 transaction buffer（撤销 / 重做 / 检查点），以便 agent 可以对其自身的编辑进行分组和回滚 —— 引擎自带的工具集并未提供此功能。 - **⚡ 性能与分析** —— VibeUE 的亮点功能：请参阅下面的专门章节。 - **Python 优先访问** —— 在编辑器中运行任何 `unreal.*` Python 代码，并内省整个 API。 - **Web 研究** —— 搜索 / 获取 / geocode，用于上下文研究和地形工作流。 它特意**不重复**引擎的通用工具（基本的 asset/actor/blueprint/material CRUD、截图、日志、PIE）—— agent 可以使用 Unreal 原生的工具集来完成这些任务。 ## ⚡ 性能与分析（旗舰功能） **Unreal 原生的 AI 工具集拥有 *零* 性能分析工具** —— 它们可以启动 PIE/Simulate，但无法 测量任何东西。VibeUE 的 `PerformanceService` 填补了这一空白，让 agent 能够真正*诊断并 修复* 帧率： - **`frame_timing()`** —— Game/Render/GPU/RHI 线程拆分 + **CPU 限制与 GPU 限制判定**以及 具体的下一步提示。*首先运行此项* —— 在 CPU 受限的帧上进行 GPU 优化是徒劳的。 - **Unreal Insights 捕获** —— `start_trace` / `stop_trace` / `get_trace_status`，包含 `bookmark` 和 `region_start` / `region_end` 标记。 - **`analyse()`** —— 读取 trace **以及**日志，并返回性能摘要（帧统计、最差 帧、卡顿、值得注意的日志行）。 - **Trace 附带的 `start_standalone`** —— 分析具有代表性的独立构建版本，而不仅仅是 编辑器视口。 ``` import unreal print(unreal.PerformanceService.frame_timing()) # CPU vs GPU bound — diagnose FIRST unreal.PerformanceService.start_trace("cap", "") # Insights trace # …复现 workload（理想情况下在 PIE / standalone 下）… unreal.PerformanceService.stop_trace() print(unreal.PerformanceService.analyse("both", "")) ``` 结合 `profiling` 和 `frame-rate` 技能，以获取完整的 CPU/GPU 深入分析结果。 ## 🏗️ 架构 VibeUE 接入了三个原生 UE 5.8+ 系统： 1. **Toolsets** (`ToolsetRegistry`) —— VibeUE 的服务注册为 `UToolsetDefinition`，因此它们的 方法成为了 MCP endpoint 上的 AICallable 工具。它们同时也是 `BlueprintCallable`，因此可以通过 Python 调用相同的方法，如 `unreal.Service.()`。 2. **MCP server** (`ModelContextProtocol`) —— 少量 VibeUE 实用工具直接注册在 endpoint 上：`execute_python_code`、`discover_python_module`/`_class`/`_function`、 `list_python_subsystems`、`deep_research`、`terrain_data`。 3. **Skills** (`AgentSkillToolset`) —— 约 34 个 markdown 技能包注册为原生的 `UAgentSkill`， 可以通过 `ListSkills` 发现，并通过 `GetSkills` 懒加载，与引擎自身的技能并存。 **（针对 agent 的）高效使用方式：** `execute_python_code` 是核心工具 —— 它将整个 多步骤任务批处理为一次往返调用，并触及每个 VibeUE 服务以及完整的 `unreal.*` API。 对于技能和少数没有 Python 路径的引擎工具集（截图等），请仅使用 `call_tool`。请参阅 [`Content/samples/AGENTS.md.sample`](Content/samples/AGENTS.md.sample) 获取完整的 agent 指南。 ## 🚀 安装与设置 **要求：** Unreal Engine **5.8+** · Git ### 第 1 步 — 设置 Unreal 的原生 MCP（请务必首先执行此操作） 1. **Edit → Plugins** → 启用 **Unreal MCP**（这将自动启用 **Toolset Registry**）和 **Editor Tools**（引擎自带的 AI 工具集，以便 agent 可以同时使用两者）。这些功能目前处于实验阶段。提示时请重启。 2. **Edit → Editor Preferences → General → Model Context Protocol** → 启用 **Auto Start Server** （或运行控制台命令 `ModelContextProtocol.StartServer`）。默认 endpoint 为 `http://127.0.0.1:8000/mcp`（端口/路径可配置）。启用 **Tool Search** 可以让 agent 的 上下文保持精简 —— 它将识别 `list_toolsets` / `describe_toolset` / `call_tool` 并按需加载工具。 ### 第 2 步 — 安装 VibeUE ``` cd /path/to/YourProject/Plugins git clone https://github.com/kevinpbuckley/VibeUE.git ``` 使用项目脚本进行构建（请勿直接运行 `Build.bat`）： ``` Plugins/VibeUE/BuildAndLaunchGame.ps1 # builds + launches the editor Plugins/VibeUE/BuildAndLaunchGame.ps1 -StrictRebuild # full recompile (warnings-as-errors) ``` 然后 **Edit → Plugins** → 启用 **VibeUE** 并重启。它的服务、工具和技能现在将 与引擎自带的功能一起，注册到同一个 endpoint 上。 ### 第 3 步 — 连接你的 agent 在编辑器中输入两条控制台命令（使用 `` ` `` 打开控制台）： **1. 写入 MCP server 配置**（位于项目根目录的 `.mcp.json`）： ``` ModelContextProtocol.GenerateClientConfig ClaudeCode ``` （支持 `ClaudeCode`、`Cursor`、`VSCode`、`Gemini`、`Codex` 或 `All`。） **2. 写入 VibeUE 的 agent 指南**，以便助手使用高效的模式： ``` VibeUE.GenerateAgentConfig ClaudeCode ``` 这会将指南写入适合你 agent 的正确文件中 —— `CLAUDE.md` (Claude Code)、`GEMINI.md` (Gemini)、`AGENTS.md` (Codex / Cursor) 或 `.github/copilot-instructions.md` (Copilot) —— 或者传入 `All` 以一次性写入 CLAUDE.md + GEMINI.md + AGENTS.md。它会自动 解析插件位置，因此无论 VibeUE 是通过 **FAB** 还是 **Git** 安装的，它都能正常工作。该指南位于一个 托管块中，因此随时可以重新运行以进行刷新，而不会干扰你自己的笔记。传入 `import` 可以使用单行 `@import` 链接指南，而不是复制内容（仅限 Claude Code / Gemini —— 其他 agent 无法解析导入，因此它们将始终获得副本）。 该指南教授：调用前先发现（`discover_python_class`），使用 `execute_python_code` 进行批处理， 通过 `ListSkills`/`GetSkills` 加载技能，以及何时需要使用 `deep_research` / `terrain_data`。 ## 🎯 技能 技能是通过 Unreal 原生的 `AgentSkillToolset` 提供的、懒加载的特定领域知识（工作流、坑点、属性格式）： ``` # discover（仅摘要 — 开销小） call_tool(tool_name="ListSkills", toolset_name="ToolsetRegistry.AgentSkillToolset") # 加载你需要的 pack（完整 markdown，lazy） call_tool(tool_name="GetSkills", toolset_name="ToolsetRegistry.AgentSkillToolset", arguments={"skillPaths": ["/VibeUE/Python/init_unreal_PY.VibeUE_blueprints"]}) ``` ## 🔧 插件依赖 **原生引擎前提条件（在第 1 步中启用 —— Epic 的 MCP 堆栈）：** | Plugin | 用途 | |--------|---------| | **Unreal MCP** (`ModelContextProtocol`) | 原生 MCP server endpoint | | **Toolset Registry** (`ToolsetRegistry`) | 原生 AI 工具集 + `AgentSkill` 注册（由 Unreal MCP 自动启用） | | **Editor Tools** (`EditorToolset`) | 引擎自带的 AI 工具集 —— VibeUE 对其进行补充 | **由 VibeUE 自动启用：** `PythonScriptPlugin` (`unreal.*` API)、 `EditorScriptingUtilities`，以及其服务所需的特定领域插件 —— `Niagara`、`MetaSound`、 `EnhancedInput`、`ModelViewViewModel`、`StateTree`、`MeshModelingToolset`、 `GameplayTagsEditor`。（VibeUE 还依赖于 `ToolsetRegistry` + `ModelContextProtocol`，因此启用 VibeUE 会自动引入它们 —— 但你仍需按照第 1 步启用 **Editor Tools** 并启动 server。） ## 🛠️ 构建与启动脚本 `BuildAndLaunchGame.ps1`（位于项目根目录或 `Plugins/VibeUE/`）会停止正在运行的编辑器、进行构建并 重新启动： - `-StrictRebuild` — 在 warnings-as-errors 下完全重新编译插件 - `-Clean` — 首先清除 intermediate/binaries - `-SkipBuild` — 仅重新启动 ## 📚 实时 API VibeUE 有意在本文档中**不保留静态方法目录** —— 因为接口会随 引擎不断演进。权威且始终最新的参考内容包括： - **`ListSkills`** → 存在哪些领域以及何时使用它们。 - **`discover_python_class('unreal.Service')`** → 精确的方法签名。 - **`describe_toolset('VibeUE.Service')`** → 该工具集的工具 + JSON schema（占用大量 token； 首选 skills + 发现机制）。 ## License MIT — 请参阅 [LICENSE](LICENSE)。项目主页：https://www.vibeue.com/