UE 5.8 AI工具链

本文基于UE 5.8源码

实践

1. 启用必需插件：Toolset Registry、Unreal MCP；按需启用All Toolsets或单个Toolsets/*工具集插件；需要外向连接时启用MCPClientToolset并配置UMCPToolsetSettings。

2. 启动HTTP服务：在Model Context Protocol（编辑器偏好设置）中勾选 bAutoStartServer自动启动。或者用ModelContextProtocol.StartServer <port>手动启动。如果端口被占用了换一个。

3. 生成外部AI agent客户端所需配置文件：执行控制台命令ModelContextProtocol.GenerateClientConfig <ClaudeCode|Cursor|VSCode|Gemini|Codex|All>。

   以Cursor为例，执行完后，生成的文件位于项目目录下的.cursor\mcp.json，随后在Cursor的Tools & MCPs设置中可以开启unreal-mcp。

4. 通过AI agent控制UE，调用UE的工具集插件。

相关插件

角色	路径	说明
MCP服务端层	Engine/Plugins/Experimental/ModelContextProtocol/	Unreal MCP插件
工具注册与执行层	Engine/Plugins/Experimental/ToolsetRegistry/	Toolset Registry插件
工具集插件	Engine/Plugins/Experimental/Toolsets/*/	不同领域的工具集插件

MCP服务端层

即Unreal MCP插件，让UE编辑器成为一个标准的MCP服务端。包含以下模块：

模块名	类型	职责摘要
ModelContextProtocol	Runtime	HTTP 路由 + JSON-RPC 分发 + Session/SSE(Server-Sent Events)
ModelContextProtocolEngine	Runtime	开发者设置（端口、路径、是否自动启动）、客户端配置文件生成、默认Analytics代理接入
ModelContextProtocolEditor	Editor	与ToolsetRegistry桥接（工具列表/调用映射）、延迟工具加载、编辑器启动时可选自动起 HTTP 服务
ModelContextProtocol*Tests	UncookedOnly	自动化测试用例

在 ModelContextProtocol.h 中定义：

• 最新协议版本：ProtocolVersion = "2025-11-25"。
• 服务端声明支持的版本列表：2025-11-25、2025-06-18、2024-11-05。
• 默认端口：DefaultServerPort = 8000（可在 UModelContextProtocolSettings 中改 ServerPortNumber）。
• 默认URL路径：DefaultServerUrlPath = "/mcp"（可在设置里改 ServerUrlPath）。
• 默认服务名：DefaultServerName = "unreal-mcp"。

UModelContextProtocolSettings（config=EditorPerProjectUserSettings）提供 bAutoStartServer：为true时，编辑器模块在SetupEditorIntegration()里调用IModelContextProtocolModule::StartServer(...)。让UE编辑器在启动完成并完成Toolset适配注册后，自动启动MCP的HTTP Server，这样外部MCP客户端（Cursor/Claude等）就能自动连上来。

// 服务端的核心路由方法
class FModelContextProtocolServer 
{
    ProcessPostRequest()         // JSON-RPC请求
    ProcessGetRequest()          // SSE事件流
    ProcessDeleteRequest()       // 会话清理
    
    ProcessJsonRpcCall()         // 路由到具体处理器
    ProcessToolCallJsonRpcCall() // 工具调用入口
    
    BroadcastToolsListChanged()  // 工具变更时推送到所有客户端
};

工具注册与执行层

UToolsetRegistrySubsystem 是UEditorSubsystem的子类，负责：

• 工具集注册管理：维护所有已注册工具集的列表。
• 工具发现：向外部提供可用工具的元数据。
• 工具执行路由：将工具调用请求路由到对应的工具集实现。
• 生命周期管理：处理工具集的加载、初始化和卸载。

根据实现方式和来源，ToolsetRegistry 管理的工具集可分为以下几类：

内置工具集

直接集成在 ToolsetRegistry 插件中的工具集，UToolsetRegistrySubsystem 初始化时自动注册，无需额外启用：

工具集名称	功能
UEditorAppToolset	编辑器应用层操作，获取编辑器状态、打开/保存关卡、资源导入导出
UAgentSkillToolset	AI技能资产管理，支持技能的CRUD操作，ListSkills、GetSkills、CreateSkill、UpdateSkill、DeleteSkill
ULogsToolset	日志系统交互，查询日志、过滤警告/错误、实时日志流

领域工具集

位于 Engine/Plugins/Experimental/Toolsets/*/ 目录下的工具集，每个专注于特定领域：

工具集插件名称	功能
AIModuleToolset	AIModule系统工具集（当前仅模块骨架，暂无AICallable工具暴露）
AnimationAssistantToolset	动画相关工具集（依赖ControlRig/SequencerScripting等；当前仅模块骨架，暂无AICallable工具暴露）
AutomationTestToolset	自动化测试发现与执行：DiscoverTests初始化/发现；ListTests过滤列举；RunTests运行；GetTestStatus/GetTestResults拉取状态/结果；StopTests终止
ConversationToolset	Conversation系统工具集（依赖CommonConversation；当前仅模块骨架，暂无AICallable工具暴露）
DataflowAgent	Dataflow图编辑工具：创建Graph、读取结构；列举NodeTypes/Schema；节点增删改查/移动；Pin连接/断开；变量增删改；Comment box 增删
GameFeaturesToolset	Game Feature Plugin 工具：列举GameFeatures；加载UGameFeatureData、查询Actions；创建新Game Feature插件并生成初始GameFeatureData资产
GameplayTagsToolset	GameplayTag管理：列举/查询Tag 信息（comment/source/children）；Add/Remove/Rename；按Tag查引用资源包（Referencers）
GASToolsets	Gameplay Ability System工具集：ASC运行时检查（属性值/ActiveEffects/GrantedAbilities/ActiveTags）；发现 AttributeSet 类与属性；GameplayCue（列举/查询、对选中Actor触发Cue、查找/创建Notify、查缺失Notify的CueTag、增删CueTag）
MCPClientToolset	将编辑器作为MCP客户端/适配器：读取UMCPToolsetSettings连接本地/私有MCP Server，把远端tools映射成ToolsetRegistry工具；支持Legacy SSE、Streamable HTTP 与 OAuth2(PKCE)
NiagaraToolsets	Niagara 编辑/诊断工具集：System/Emitter/Module/Renderer的schema与topology查询；读写数据（system/emitter/renderer/stack input/user vars）；编辑操作（增删emitter/renderer/module、设置input/参数）；编译状态与stack issues获取/修复
PhysicsToolsets	PhysicsAsset工具：由SkeletalMesh创建PhysicsAsset；Body/Shape（sphere/capsule/box）CRUD；Body物理模式/质量缩放；Constraint CRUD 与角度限制设置
SlateInspectorToolset	Slate UI自动化/检查（Playwright风格）：Snapshot/Observe/Unobserve；Screenshot；交互（Click/Hover/Type/PressKey/SelectOption/Drag）；窗口管理与WaitFor/FillForm
StateTreeToolset	StateTree工具集（uplugin标注为Inspection；当前仅模块骨架，暂无AICallable工具暴露）
UMGToolSet	UMG Widget Blueprint反射式编辑：创建WBP；枚举widget tree/NamedSlots/可用类；Add/Move/Remove/Rename/SetVariable；Reparent；编译WBP（属性读写配合ObjectTools.*）
WorldConditionsToolset	WorldConditions检查/可读化：把 FWorldConditionQueryDefinition/单条Condition生成人类可读描述；并注册 Query JSON 转换器以便序列化/传参
LiveCodingToolset	Live Coding 编译触发：从编辑器触发Live Coding compile，等待完成并返回结果 + LogLiveCoding 输出 + UBT诊断摘要
SequencerAnimMixerToolset	Sequencer Animation Mixer的工具集（声明依赖MovieSceneAnimMixer；该插件目录下无自有实现）

有一个不是工具集插件的批量启动插件 Engine/Plugins/Experimental/Toolsets/AllToolsets/ ，启用它即启用所有工具集，除了：

• LiveCodingToolset
• SequencerAnimMixerToolset

需在插件面板单独启用对应插件（或自行改AllToolsets.uplugin依赖）。

远程工具集

通过 MCPClientToolset动态映射的外部工具： - 连接到本地或私有MCP Server - 将远端tools映射为ToolsetRegistry可识别的工具 - 支持Legacy SSE、Streamable HTTP与OAuth2(PKCE) 认证

自定义工具集

自定义工具集继承自UToolsetDefinition，给UFUNCTION加上meta = (AICallable)或meta = (AIIgnore)来决定是否暴露给AI。

FFunctionLibraryToolset会遍历自定义工具集类中的所有UFunction，为通过UToolsetDefinition::IsFunctionAICallable筛选的UFunction创建FObjectFunctionToolCall对象，将函数签名转换为JSON Schema。

工具集运行流程

1. 初始化阶段

• FToolsetRegistry构造函数
  • 注册内置 JSON转换器
  • 初始化ToolsetHandlers (空Map)

2. 注册阶段

• RegisterToolset(TSharedPtr <FToolset> Toolset)

  • 检查 Toolset 有效性
  • 检查是否已存在同名工具集
  • 添加到ToolsetHandlers
  • 触发OnToolsetRegistryChanged委托

3. Schema 获取

• UToolsetRegistry::GetAllToolsetJsonSchemas()
  • 遍历所有已注册工具集，生成各自的Schema并拼接在一起。使得调用方能够了解可以执行哪些操作以及如何正确构造请求参数。

4. 工具执行阶段

• ExecuteTool("ToolsetName.ToolName", JsonInput)
  • Step 1: 解析工具名称，FToolDescriptor::FromString()
  • Step 2: 查找工具集，Find(ToolsetName)
  • Step 3: 执行工具， Toolset->ExecuteTool(ToolName, JsonInput)
  • Step 4: 返回异步结果，TFuture<TValueOrError<FString, FString>>

Agent Skill

相当于给AI编写Skill。

UObject (Unreal Engine 基类)
└── UAgentSkill (基础技能类)
    ├── 属性:
    │   ├── Description (FString) - 技能简要描述
    │   ├── Toolsets (TArray<TSoftClassPtr<UToolsetDefinition>>) - 依赖的工具集列表
    │   └── Instructions (FString) - 详细使用说明
    │
    ├── 方法:
    │   ├── GetDetails() → FAgentSkillDetails
    │   │   └── 返回技能的详细信息（包含工具集名称和处理后的指令）
    │   │
    │   └── GeneratePrompt(FString InitialInstructions) → FString
    │       └── 生成最终的提示文本，默认返回初始指令
    │
    └── UAgentSkillBestPractices (最佳实践技能类)
        ├── 构造函数: UAgentSkillBestPractices()
        │   └── 设置描述
        │
        └── 重写方法: GeneratePrompt_Implementation(FString InitialInstructions) → FString
            └── 在初始指令后追加以下最佳实践规范:
                • 技能应专注于提供LLM不知道且无法通过工具学习的重要信息
                • 技能可以包括概念解释或逐步指导，或两者混合
                • 技能应像给同事的简报，而不是用自然语言编写的程序
                • 技能应避免嵌入可能随时间变化的细节（如属性名、工具名）
                • 技能应与基础设施无关，避免引用编排、角色、模型名称等
                • 较短的技能更高效，移除非必要或非永恒的信息

FAgentSkillDetails 
├── Toolsets (TArray<FString>) - 技能依赖的工具集名称列表
└── Instructions (FString) - 使用说明