Vibeue

VibeUE 是面向 Unreal Engine 5.8+ 的 MCP 扩展 + AI 编辑器工具集。 Unreal 5.8 新增了内置 MCP 服务和 AI 工具集；VibeUE 是一个MCP 扩展，可直接接入这些功能，并提供丰富的AI 编辑器工具集——一个编辑器能力库，涵盖蓝图、材质、景观、植被、动画、Niagara、UMG、音频、StateTree、行为树和黑板、游戏玩法标签、输入、UV、性能/性能分析等——并注册到引擎自身的 ToolsetRegistry 和 ModelContextProtocol 服务中，还通过 Unreal 原生的 AgentSkill 系统提供丰富的领域技能。任何支持 MCP 的 Agent（Claude Code、Cursor、Copilot 等）都可以通过 Unreal 的标准 MCP 端点驱动你的编辑器。

⚠️ 使用 VibeUE 前，必须先设置 Unreal 原生 MCP——启用 Unreal MCP 插件（该插件会自动启用 Toolset Registry）和 Editor Tools 插件，然后启动 MCP 服务。 请按照 Epic 的指南操作：Unreal Editor 中的 Unreal MCP。 随后，VibeUE 会扩展该端点——无需单独的服务，也无需在编辑器内聊天。 免费 API 密钥 （在 Editor Preferences → Plugins → VibeUE 中设置）可解锁真实世界的地形工具；其他所有功能无需密钥即可使用。

---

✨ VibeUE 的新增功能

Unreal 5.8 自带 AI 工具集（蓝图、材质、Actor、资产、网格体、数据表等）。 VibeUE 为其提供补充——专注于引擎尚未覆盖的领域和深度：

• 地形与世界 — Landscape 雕刻／高度图／样条线、Landscape 自动材质 + RVT、 Foliage、程序化 FPS 地图白盒搭建，以及真实世界地形（通过 GPS 获取高度图 + 水体）。
• 音频 — MetaSound 和 SoundCue 图表创作。
• 动画资产 — AnimSequence 关键帧编辑、AnimMontage 创作、AnimBP 状态机、 Skeleton 骨骼／插槽／重定向／混合配置文件编辑。
• FX 深度功能 — Niagara 发射器颜色／曲线创作和 Custom-HLSL 临时模块。
• UI — 带 MVVM 绑定的 UMG 控件、动画创作和预览／PIE 验证。
• 更高级的蓝图创作 — 时间轴、事件分发器、委托、自定义事件引脚、 注释框，以及批量 build_graph 构建器。
• AI 行为创作 — 按结构路径编辑行为树节点／装饰器／服务，并支持黑板键绑定、 JSON 树往返转换以及验证／修复；完整的 Blackboard 资产 + 键 CRUD。写入操作通过编辑器 EdGraph 完成，并带有考虑 PIE 和打开编辑器状态的拒绝防护。
• 编辑器安全性 — TransactionService 封装编辑器的事务缓冲区（撤销／重做／检查点），让 Agent 可以将自身编辑分组并回滚——引擎工具集不提供这些功能。
• 经过验证的工作流 — WorkflowService 提供权威的引擎／构建清单、带受影响资产来源信息的持久任务日志、异步 PIE 场景（编译 → 输入 → 断言 → 捕获 → 保证拆解），以及先试运行、可恢复的批量维护。
• ⚡ 性能与分析 — VibeUE 的突出特色：详见下文专门章节。
• Python 优先访问 — 在编辑器中运行任意 unreal.* Python，并内省整个 API。
• 网络研究 — 搜索／获取／地理编码，用于上下文研究和地形工作流。

它有意不重复引擎的通用工具（基本资产／Actor／蓝图／材质 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() — 读取跟踪数据和日志，并返回性能摘要（帧统计、最差帧、卡顿、重要日志行）。
• 附带跟踪的 start_standalone — 分析有代表性的独立构建，而不仅仅是编辑器视口。

import unreal
print(unreal.PerformanceService.frame_timing())   # CPU vs GPU bound — diagnose FIRST
unreal.PerformanceService.start_trace("cap", "")   # Insights trace
# … reproduce the workload (ideally under PIE / standalone) …
unreal.PerformanceService.stop_trace()
print(unreal.PerformanceService.analyse("both", ""))

搭配 profiling 和 frame-rate 技能，即可进行完整的 CPU／GPU 深入分析。

---

🏗️ 架构

VibeUE 接入 UE 5.8+ 的三个原生系统：

1. 工具集（ToolsetRegistry）— VibeUE 的服务会注册为 UToolsetDefinition，因此其方法会成为 MCP 端点上的 AICallable 工具。它们也标记为 BlueprintCallable，所以可以通过 Python 调用相同的方法：unreal.<Name>Service.<method>()。
2. MCP 服务（ModelContextProtocol）— 一小组 VibeUE 实用工具会直接注册到端点：execute_python_code、discover_python_module/_class/_function、list_python_subsystems、deep_research、terrain_data。
3. 技能（AgentSkillToolset）— 约 36 个 Markdown 技能包会注册为原生 UAgentSkill，可通过 ListSkills 发现，并通过 GetSkills 延迟加载，同时提供引擎自带的技能。

高效用法（适用于 Agent）： execute_python_code 是主力工具——它可以将整个多步骤任务批量合并为一次往返调用，并访问每个 VibeUE 服务以及完整的 unreal.* API。只有技能和少数无法通过 Python 调用的引擎工具集（如截图等）才使用 call_tool。完整的 Agent 指南请参阅 Content/samples/AGENTS.md.sample。

---

🚀 安装与设置

要求： Unreal Engine 5.8+ · Git

步骤 1 — 设置 Unreal 原生 MCP（请先完成）

VibeUE 是对 Unreal 内置 MCP 支持的扩展，因此请先启用内置支持。详情请参阅 Epic 的指南：Unreal 编辑器中的 Unreal MCP。

1. 编辑 → 插件 → 启用 Unreal MCP（这会自动启用 Toolset Registry）和 Editor Tools（引擎自带的 AI 工具集，让 Agent 两者都能使用）。这些功能均为实验性功能。出现提示时重启。
2. 编辑 → 编辑器首选项 → 通用 → Model Context Protocol → 启用 Auto Start Server（或运行控制台命令 ModelContextProtocol.StartServer）。默认端点为 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

使用项目脚本进行构建：

Plugins/VibeUE/BuildAndLaunchGame.ps1                  # builds + launches the editor
Plugins/VibeUE/BuildAndLaunchGame.ps1 -StrictRebuild   # full recompile (warnings-as-errors)
Plugins/VibeUE/BuildAndLaunchGame.ps1 -Map /Game/Maps/MyMap   # open a specific map (issue #554)

在 Linux 或 macOS 上，使用可自动检测平台的 Shell 脚本：

Plugins/VibeUE/BuildAndLaunchGame.sh --engine /path/to/UE5
Plugins/VibeUE/BuildAndLaunchGame.sh --engine /path/to/UE5 --strict-rebuild
Plugins/VibeUE/BuildAndLaunchGame.sh --engine /path/to/UE5 --map /Game/Maps/MyMap

然后进入 编辑 → 插件 → 启用 VibeUE 并重启。其服务、工具和技能现在会与引擎自带的内容一起注册到同一端点。

步骤 3 — 连接 Agent

在编辑器中运行以下两个控制台命令（按 ` 打开控制台）：

1. 写入 MCP 服务配置（位于项目根目录的 .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 / Hermes / Cursor）或 .github/copilot-instructions.md（Copilot）；也可以传入 All，一次性写入 CLAUDE.md + GEMINI.md + AGENTS.md。它会自动解析插件位置，因此无论 VibeUE 是通过 FAB 还是 Git 安装都能正常工作。指南会写入受管理的区块，因此可以随时重新运行以更新内容，而不会影响你自己的备注。传入 import 可通过单行 @import 链接指南，而不是复制内容（仅适用于 Claude Code / Gemini；其他 Agent 无法解析导入，因此始终会获得副本）。

MCP 服务仅监听回环地址，且没有身份验证——仅限在同一台机器上使用（依据 Epic 的文档）。

该指南会说明：调用前先发现（discover_python_class）、使用 execute_python_code 批量执行、通过 ListSkills/GetSkills 加载技能，以及何时使用 deep_research / terrain_data。

🎯 技能

技能是由 Unreal 原生 AgentSkillToolset 提供的按需加载领域知识（工作流、注意事项、属性格式）：

# discover (summaries only — cheap)
call_tool(tool_name="ListSkills", toolset_name="ToolsetRegistry.AgentSkillToolset")

# load the packs you need (full markdown, lazy)
call_tool(tool_name="GetSkills", toolset_name="ToolsetRegistry.AgentSkillToolset",
          arguments={"skillPaths": ["/VibeUE/Python/init_unreal_PY.VibeUE_blueprints"]})

ListSkills 是可用内容的实时事实来源（它会读取每个包中的 SKILL.md）。 技能会告诉你要做什么以及为什么；编写代码前，请使用 discover_python_class('unreal.<Name>Service', method_filter='…') 获取准确的签名。

---

🔧 插件依赖项

原生引擎前置要求（在步骤 1 中启用 — Epic 的 MCP 栈）：

插件	用途
Unreal MCP（ModelContextProtocol）	原生 MCP 服务端点
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 并启动服务。）

---

🛠️ 构建与启动脚本

BuildAndLaunchGame.ps1（项目根目录或 Plugins/VibeUE/）会停止正在运行的编辑器、进行构建并重新启动：

• -StrictRebuild — 在将警告视为错误的情况下完整重新编译插件
• -Clean — 首先清除中间文件/二进制文件
• -SkipBuild — 仅重新启动

---

📚 实时 API

VibeUE 特意在本 README 中不保留静态方法目录 — API 范围会随引擎演进。权威且始终最新的参考资料包括：

• ListSkills → 可用的领域及其适用时机。
• discover_python_class('unreal.<Name>Service') → 准确的方法签名。
• describe_toolset('VibeUE.<Name>Service') → 工具集中的工具及其 JSON 架构（占用大量令牌； 优先使用技能 + 发现功能）。

---

许可证

MIT — 参见 LICENSE。项目主页：https://www.vibeue.com/