#UECopilot 插件手册

版本: 1.0.0 | 最后更新: 2026-05-08 适用引擎: Unreal Engine 5.7

#1. 插件概述

#1.1 什么是 UECopilot？

UECopilot 是一个集成在 Unreal Engine 5 编辑器中的 AI 辅助开发插件。它通过蓝图 MCP 服务端 (Blueprint Model Context Protocol Server, UEMCP)，将 UE5 的蓝图数据结构和编辑操作暴露为 HTTP API，让 AI 模型（如 Claude、GPT 等）能够直接读取、理解、创建和修改蓝图资产。

一句话总结：UECopilot 让 AI 能"看懂"你的蓝图，并能像一名经验丰富的 TA/程序员一样帮你操作它们。

#1.2 运行模式

#2. 核心能力总览

UECopilot 的 UEMCP 模块经过全面分析，当前提供 80+ 个 MCP 工具，覆盖以下 9 大能力域：

能力评级说明：

• 成熟：工具功能完整，边缘情况处理完善，有 SEH 保护
• 稳定：核心路径可用，部分边界情况需留意
• 发展中：基础能力可用，高级场景有待完善

#2.1 能做什么？（场景化描述）

场景一：AI 辅助蓝图调试

用户："帮我检查这个蓝图里有没有断开的引脚连接"
AI → 调用 find_disconnected_pins → 返回所有未连接的输入引脚
AI → 给出修复建议

场景二：AI 辅助蓝图重构

用户："把所有引用到 OldClass 的函数调用改成 NewClass"
AI → 调用 replace_function_calls（支持 dry_run 预览）→ 执行替换

场景三：AI 辅助材质创建

用户："帮我创建一个带法线贴图和颜色调整的材质"
AI → create_material → add_material_expression (TextureSample、Multiply 等)
     → connect_material_pins → 完成材质网络

场景四：AI 辅助动画状态机

用户："在这棵动画蓝图中添加一个 Idle→Run 的转换"
AI → add_anim_state → add_anim_transition → set_transition_rule

场景五：安全实验

用户："我想修改这个函数参数类型，但怕出问题"
AI → snapshot_graph（先快照）→ change_function_parameter_type → 如果出错则 restore_graph

#3. 系统要求

• Unreal Engine: 5.7+
• 操作系统: Windows 64 位（已完整测试）
• 额外依赖: Node.js（用于 Web UI 服务，MCP 服务不需要）

#4. 使用引导

#4.1 工作流程建议

推荐的工作流程是 "预览 → 快照 → 执行 → 验证" 四个步骤：

步骤 1：预览分析
  ├── 使用 get_blueprint / get_blueprint_graph 了解当前状态
  ├── 使用 search_blueprints 搜索相关节点
  └── 使用 check_pin_compatibility 预检引脚连接可行性

步骤 2：创建安全快照
  └── 使用 snapshot_graph 保存当前图状态

步骤 3：执行变更
  ├── 使用 add_node / connect_pins / delete_node 等
  ├── 支持 dryRun 参数的修改工具先做干运行
  └── 重大变更使用 validate_blueprint 检查编译结果

步骤 4：验证与恢复
  ├── 使用 validate_blueprint 验证蓝图完整性
  ├── 使用 diff_graph 对比变更前后差异
  └── 如有问题使用 restore_graph 回滚到快照状态

#4.2 AI 对话提示词技巧

好的提示词示例：

# 明确指定操作对象
"在蓝图 MyCharacter 的 EventGraph 中添加一个 Print String 节点，打印 'Hello'"

# 分步骤操作
"1. 先对 MyCharacter 的 EventGraph 做快照
 2. 然后把 MoveForward 函数的输入参数类型从 float 改成 double
 3. 最后验证蓝图是否有编译错误"

# 先查询后操作
"先列出项目中所有继承自 Character 的蓝图，
 然后告诉我它们的名字和路径"

需要避免的模糊提示词：

✗ "帮我修一下这个蓝图" — 哪个蓝图？修什么？
✗ "加个功能" — 什么功能？在哪加？
✗ "改一下材质" — 哪个材质？改成什么样？

#4.3 使用注意事项

1. MCP 服务不是头部安全的：虽然使用了 SEH（结构化异常处理）保护，但极端情况下错误操作仍可能导致编辑器崩溃。建议在操作前先保存项目，并备份重要蓝图。

2. 所有写操作支持 Ctrl+Z 撤销：服务端为每个写操作包装了 Undo 事务，但在持续操作后建议及时手动保存。

3. 快照保存在磁盘：快照文件保存在 Project/Saved/BlueprintMCP/Snapshots/ 目录，不会随项目版本控制。重要操作建议手动备份。

4. AI 模型对 UE 术语的理解差异：不同 AI 模型对 UE 特定术语（如"引脚连接"、"分解结构体"、"事件调度器"）的理解可能存在差异，请在提示词中使用 UE5 官方术语。

#5. MCP 工具大全

说明：以下列出所有可通过 AI 对话直接调用的 MCP 工具。工具名称采用蛇形命名法（snake_case），您可以在提示词中直接使用这些工具名。

#5.1 蓝图检索与读取（8 个工具）

#5.2 蓝图节点编辑（15 个工具）

#5.3 蓝图变量系统（6 个工具）

#5.4 函数与参数管理（4 个工具）

#5.5 蓝图结构与元数据（9 个工具）

#5.6 组件系统（3 个工具）

#5.7 用户自定义类型（4 个工具）

#5.8 材质系统（18 个工具）

材质读取：

材质写入：

材质实例：

材质函数：

材质安全：

#5.9 动画蓝图系统（12 个工具）

#5.10 安全与快照系统（6 个工具）

#5.11 资产发现与反射（5 个工具）

#5.12 工具函数与安全机制

类型解析器（ResolveTypeFromString）

支持的类型解析格式：

SEH 安全保护（Windows 专用）

对于高风险操作（蓝图编译、材质表达式添加、包保存等），使用了 __try/__except 结构化异常处理（SEH）机制。这意味着即使操作导致引擎内部崩溃（如访问冲突），服务也不会完全崩溃，而是返回错误信息。

Undo 事务支持

所有修改蓝图的工具调用都会包裹在 Undo/Redo 事务中，这意味着在编辑器中使用时，可以通过 Ctrl+Z 撤销 AI 执行的操作。

#6. 使用边界与限制

#6.1 已知限制

#6.2 不支持的场景

1. C++ 代码操作：只能操作蓝图和资产，不能创建或修改 C++ 代码文件
2. 运行时调试：不支持断点、单步执行等调试功能
3. 多用户协作：无并发控制机制，不适合多人同时操作同一蓝图
4. 内容迁移：不支持跨项目的内容迁移
5. 源码控制集成：不直接与 Perforce/Git/SVN 交互
6. 打包构建：不支持打包、烘焙等构建流程
7. 关卡编辑：不直接支持关卡中的 Actor 放置和编辑
8. 数据表操作：暂时不支持 DataTable/CurveTable 的编辑
9. Niagara 系统：不支持 Niagara 粒子系统的操作
10. UI/UW 编辑：不支持 Widget Blueprint 的编辑

#6.3 安全边界

✅ 可以做的：
   · 读取/创建/修改蓝图资产
   · 读取/创建/修改材质资产
   · 读取/创建/修改动画蓝图
   · 创建结构体和枚举
   · 进行安全快照和恢复
   · 在编辑器中使用 Ctrl+Z 撤销

❌ 不应做的：
   · 将编辑器暴露到外网访问
   · 在无版本控制的情况下批量修改
   · 依赖 AI 完全理解复杂图结构的语义
   · 跳过测试在关键节点上直接使用

⚠️ 需要谨慎的：
   · 修改已有蓝图的父类（可能导致大量断连）
   · 批量重命名/删除资产
   · 修改变量类型（可能断开现有连接）
   · 在动画蓝图状态机中大规模修改

#7. 对话式 MCP 操作的提示词准确度难点

#7.1 核心难点

使用自然语言通过 AI 模型操作 UE5 蓝图，存在以下核心挑战：

#难点一：图结构的三维语义丢失

蓝图图是一个二维视觉结构。AI 只能看到一个扁平的 JSON 节点列表，丢失了空间信息，例如：

• 节点位置和布局（靠近意味着逻辑分组）
• 通过注释框实现的视觉分组
• 执行流方向（从左到右、从上到下的约定）
• 颜色提示（节点类型指示、执行线颜色）

影响：AI 难以理解图的"设计意图"，只能看到结构化的连接数据。

#难点二：引脚类型的隐性知识

引脚类型在 UE5 中是一个复杂系统：

影响：AI 在构造 connect_pins 请求时，可能给出语义不正确的引脚配对。

#难点三：变更的级联效应

一个简单的修改可能产生连锁反应：

修改变量类型（int → float）
  → 所有 Get/Set 节点的输出引脚类型变化
    → 连接到这些引脚的节点可能断连
      → 下游节点的输入值变成无效
        → 编译时产生警告或错误

影响：AI 难以完整预测一个变更的全部级联效应，即使有 dryRun 支持。

#难点四：UE 术语的多义性

影响：AI 可能混淆不同上下文中的术语含义，导致请求参数错误。

#难点五：会话状态维护

第1轮：AI → "列出所有蓝图"
       服务 → 返回 50 个蓝图名

第2轮：AI → "打开第一个看看"
       问题 → "第一个"指的哪个？用户需要维护对话上下文

影响：插件本身无状态，每次工具调用都是独立的。AI 模型需要在对话中维护状态，但上下文窗口有限。

#7.2 当前缓解策略

插件层面已实现的缓解措施：

1. 详细的错误信息：当操作失败时返回具体的错误原因和可用选项列表（如列出可用引脚名、可用图名等）
2. dryRun 模式：关键修改操作支持预览模式，返回影响分析
3. 快照机制：支持操作前快照，操作后可恢复
4. SEH 保护：极端情况下的崩溃保护

#10. 常见问题与故障排除

#10.1 操作问题

问：操作蓝图后没有生效

1. 检查操作返回的 JSON 中 saved 字段是否为 true
2. 在编辑器中手动保存资产（Ctrl+S）
3. 重新打开蓝图图查看变更

问：蓝图编译出现错误

1. 使用 validate_blueprint 工具查看具体错误信息
2. 如果有快照，使用 restore_graph 恢复
3. 或在编辑器中使用 Ctrl+Z 撤销

问：AI 无法找到指定的蓝图

1. 确保蓝图名称正确（区分大小写）
2. 使用 list_blueprints 工具查看所有可用蓝图
3. Level Blueprint 需要通过地图名引用

#10.2 性能问题

问：首次调用 list_blueprints 响应慢

首次调用会触发资产注册表全量扫描。后续调用使用缓存，速度会提升。

#11. 附录：能力统计总表

#11.1 概览数据

#11.3 类型支持覆盖

#结语

UECopilot 的目标是让 AI 成为 UE5 开发者的得力副驾——不是替代你的判断力，而是帮助你更快地完成重复性工作、减少人为失误、并在大型项目中保持操作的准确性和可追溯性。

给用户的建议：

• 从小处开始：先在简单的蓝图上试用
• 善用快照：任何重大操作前先做快照
• 渐进式使用：从读取 → 简单修改 → 复杂创建，逐步深入
• 保持反馈：遇到问题请提供详细日志，帮助插件持续改进

UECopilot - 让 Unreal Engine 开发插上 AI 的翅膀