#UECopilot 插件手册

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

#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 模块经过全面扩展，当前提供 130+ 个 MCP 工具，覆盖以下 16 大能力域：

能力评级说明：

• 成熟：工具功能完整，边缘情况处理完善，有 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

场景六：场景自动化搭建

用户："在关卡中心生成一个 10x10 的 StaticMesh Cube 网格"
AI → list_actors（了解当前状态）→ 循环 spawn_actor → set_actor_transform
     → 完成后 focus_actor 聚焦查看

场景七：自动化 PIE 运行时测试

用户："启动游戏，把玩家传送到 Boss 区域，确认 Boss 已正确生成"
AI → start_pie → is_pie_running（等待就绪）
     →  pie_teleport_player → pie_query_actors(classFilter="Boss") → stop_pie

场景八：自动化视觉验证

用户："切换到 Wireframe 模式截个图，然后切回 Lit 模式"
AI → set_view_mode(mode="Wireframe") → take_screenshot
     → set_view_mode(mode="Lit")

场景九：UMG 界面编程化操作

用户："在 WBP_MainMenu 的 Root 下添加一个 'Start Game' 按钮"
AI → list_widget_tree → add_widget(widgetClass="Button", name="StartButton")
     → set_widget_property(property="Text", value="Start Game")

场景十：性能调试

用户："看看当前 r.Shadow 相关设置，并降低阴影质量"
AI → list_cvars(filter="r.Shadow") → set_cvar(name="r.ShadowQuality", value="2")

场景十一：工作流编排

用户："选中最里面的 3 个 StaticMeshActor，复制一份偏移到右侧 200cm"
AI → begin_transaction("Duplicate actors") → set_editor_selection(["SM_A", "SM_B", "SM_C"])
     → duplicate_actor(offset={x:200}) → end_transaction

#3. 系统要求

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

#4. 使用引导

#4.1 工作流程建议

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

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

步骤 2：创建安全快照
  ├── 使用 snapshot_graph 保存当前图状态
  └── 使用 begin_transaction / end_transaction 包裹多步操作

步骤 3：执行变更
  ├── 使用 add_node / connect_pins / delete_node 等编辑蓝图
  ├── 使用 spawn_actor / set_actor_transform 操作关卡
  ├── 使用 add_widget / set_widget_property 修改 UMG
  ├── 支持 dryRun 参数的修改工具先做干运行
  └── 重大变更使用 validate_blueprint 检查编译结果

步骤 4：验证与恢复
  ├── 使用 validate_blueprint 验证蓝图完整性
  ├── 使用 diff_graph 对比变更前后差异
  ├── 使用 get_dirty_packages 检查未保存修改
  └── 如有问题使用 restore_graph 回滚或 undo 撤销

#4.2 AI 对话提示词技巧

好的提示词示例：

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

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

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

# 关卡操作
"在当前关卡中选中所有 StaticMeshActor，获取每个的属性"

需要避免的模糊提示词：

✗ "帮我修一下这个蓝图" — 哪个蓝图？修什么？
✗ "加个功能" — 什么功能？在哪加？
✗ "改一下材质" — 哪个材质？改成什么样？
✗ "跑一下" — 运行 PIE？验证蓝图？搜索资产？

#4.3 使用注意事项

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

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

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

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

5. 编辑器模式 vs 命令let 模式的差异：

• 编辑器模式下 PIE/视口/关卡/Actor 工具完全可用
• 命令let 模式下仅蓝图层和 CVar 工具可用（无 World 上下文）

#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 关卡与 Actor 管理（v2 新增，16 个工具）

#5.12.1 Actor 基础操作

#5.12.2 Actor 查询与状态

#5.12.3 Actor 父子级操作

#5.12.4 空间查询

#5.12.5 子关卡管理

#5.13 PIE 运行时控制与查询（v2 新增，7 个工具）

#5.13.1 PIE 生命周期

#5.13.2 PIE 运行时查询

#5.14 视口相机与渲染（v2 新增，9 个工具）

#5.14.1 相机控制

#5.14.2 渲染模式

#5.14.3 屏幕截图

截图保存路径：{Project}/Saved/Screenshots/

#5.15 编辑器工具与选择（v2 新增，11 个工具）

#5.15.1 编辑器选择管理

#5.15.2 内容浏览器

#5.15.3 编辑器工具

#5.15.4 撤销/重做

begin_transaction / end_transaction 之间执行的所有 MCP 写操作将被组合为一个原子撤销操作。

#5.16 UMG 控件管理（v2 新增，7 个工具）

常见控件类：TextBlock, Button, Image, VerticalBox, HorizontalBox, Overlay, CanvasPanel, Border, SizeBox, ScaleBox, ScrollBox, Spacer, ProgressBar, Slider, CheckBox

#5.17 CVar 与输出日志（v2 新增，5 个工具）

#5.17.1 控制台变量 (CVar)

支持模式：编辑器模式和命令let 模式。注意某些 CVar 需重启编辑器生效。

#5.17.2 输出日志

首次调用 get_output_log 时自动开始日志捕获。日志过滤支持按文本匹配消息/类别，或按严重级别 (Error / Warning) 筛选。

#5.18 资产特殊操作（v2 新增，8 个工具）

#5.18.1 Groom 毛发绑定

#5.18.2 骨架与 Socket

#5.18.3 控制台命令

#5.18.4 关卡 Gameplay 快照

#5.19 工作流资源 (MCP Resources)

除了工具（Tools），TypeScript MCP Server 还暴露了两个只读资源 (Resources)，供 AI 在工作前查阅：

#5.20 工具函数与安全机制

类型解析器（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. DataTable 操作：暂时不支持 DataTable/CurveTable 的编辑
8. Niagara 系统：不支持 Niagara 粒子系统的操作

#6.3 安全边界

✅ 可以做的：
   · 读取/创建/修改蓝图、材质、动画蓝图资产
   · 创建结构体和枚举
   · 进行安全快照和恢复
   · 在关卡中生成/删除/修改 Actor
   · 启动/停止/暂停 PIE 并查询运行时状态
   · 控制视口相机和渲染模式
   · 截取视口截图
   · 创建和修改 Widget Blueprint (UMG)
   · 读写 CVar 控制台变量
   · 读取和过滤输出日志
   · 导航内容浏览器和打开资产编辑器
   · 管理编辑器选择状态
   · 批量操作并原子化撤销

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

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

#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 需要通过地图名引用

问：关卡 Actor 操作失败（"requires editor mode"）

1. 确认 UE5 编辑器正在运行（非命令let 模式）
2. 检查 is_pie_running — 编辑模式操作不能在 PIE 运行时执行
3. 确认当前有关卡打开（非空世界）

#10.2 性能问题

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

问：PIE 操作启动慢 PIE 启动需要编译关卡和加载资源。可通过 is_pie_running 轮询等待就绪状态。

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

#11.1 概览数据

#11.3 类型支持覆盖

#结语

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

给用户的建议：

• 从小处开始：先在简单的蓝图上试用
• 善用快照：任何重大操作前先做快照
• 渐进式使用：从读取 → 简单修改 → 复杂创建 → 关卡/PIE 全流程，逐步深入
• 善用事务：使用 begin_transaction / end_transaction 组合多步操作为原子撤销
• 保持反馈：遇到问题请提供详细日志，帮助插件持续改进

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