Unreal Engine

概述

使用本技能将 OpenClaw 风格的智能体工作流连接至 Unreal Engine 5.0+，确保该集成方案可兼容引擎的次要版本变更。在已评估的 Unreal Engine 源码仓库中，内置的 RemoteControl、HttpBlueprint、JsonBlueprintUtilities、PythonScriptPlugin 和 WebSockets 功能均已就绪，因此应优先采用组合（composition）方式，而非修改引擎源码（patching）。

推荐以下集成路径：

1. 编辑器自动化路径：使用 Unreal Remote Control 实现编辑器运行时的对象/属性检查与自动化操作。
2. 蓝图低代码路径：组合使用 HttpBlueprint 与 JsonBlueprintUtilities，构建由蓝图驱动的请求/响应工作流。
3. 项目/插件路径：添加一个轻量级插件，向 C++ 和蓝图暴露 OpenClaw 特定的传输层、认证、会话及任务钩子。

切勿假设某一套 Unreal API 在所有 5.x 版本中行为完全一致。应尽可能减少编译期依赖，并将版本敏感代码隔离处理。

集成策略

1. 首先选择合适的控制平面

根据具体任务类型进行选择：

• 蓝图检查、编辑器对象/属性修改、调用已暴露的编辑器函数、基于预设的工具链
  • 优先选用 Unreal Remote Control。
  • 适用于编辑器内编排，无需将智能体逻辑深度嵌入游戏逻辑代码。
• 以蓝图为主、C++ 介入较少的 HTTP/JSON 工作流
  • 优先使用内置的 HttpBlueprint + JsonBlueprintUtilities。
  • 适用于快速原型开发及面向设计师的任务流程。
• 编辑器自动化场景中，Python 比 C++/蓝图更适用
  • 优先选用 PythonScriptPlugin。
  • 适用于内容工具开发、批量编辑器脚本编写及快速迭代。
• 打包后游戏或 PIE 会话中的运行时通信、蓝图工具节点、项目特定任务执行、自定义认证/传输机制
  • 优先选用 项目插件。
• 同时涵盖编辑器和运行时任务
  • 混合使用：Remote Control 处理编辑器侧工作；在适当时机使用内置蓝图/Python 工具；通过插件实现运行时安全的 OpenClaw 特定行为。

2. 保持广泛的版本兼容性

针对 UE 5.0+：

• 优先选用长期稳定的引擎模块：Core、CoreUObject、Engine、HTTP、Json、JsonUtilities、WebSockets。
• 将版本敏感代码封装于辅助函数或宏之后。
• 避免在运行时代码中依赖仅限编辑器使用的模块。
• 仅当任务确实需要编辑器扩展时，才将运行时与编辑器关注点拆分为独立模块。

3. 将蓝图支持视为头等需求

当用户提及蓝图时，不可止步于 C++ 底层对接。需提供：

• UBlueprintFunctionLibrary 节点，用于一次性操作
• 可选的 UGameInstanceSubsystem 或 UEngineSubsystem，用于持久化连接/状态管理
• 委托（Delegate）/事件（Event）接口，用于异步结果回调
• 在类型化 Schema 尚未确定前，提供简易的 JSON 输入/输出回退节点

默认架构

除非项目有特殊要求，否则请采用此思维模型：

• OpenClaw 侧
  • 负责任务编排，可选支持 HTTP/WebSocket 通信，能生成结构化的 JSON 任务信封。
• Unreal 编辑器
  • Remote Control 暴露可由编辑器管理的对象/函数/属性。
• Unreal 插件
  • 提供蓝图节点及运行时传输能力。
  • 接收任务信封，分发至蓝图/C++ 处理器，并返回结构化结果。

任务模式

模式 A：编辑器时段的蓝图与资源类任务

适用于以下目标：

• 在编辑器中检查或调整 Actor/组件
• 触发编辑器工具中已暴露的函数
• 更新 Remote Control 预设中的属性
• 支撑技术美术 / 虚拟制片类工作流

实施方法：

1. 确保项目已启用 Unreal Remote Control。
2. 仅暴露必需的对象/函数/属性。
3. 由 OpenClaw 调用 Remote Control 的 HTTP/WebSocket API。
4. 对具有破坏性或影响编辑器状态的操作，明确限定其作用域并显式声明。

典型适用场景：

• 关卡搭建辅助工具
• 虚拟制片控制面板
• 编辑器工具 Actor/Widget
• 批量属性更新

模式 B：运行时或贴近游戏玩法的任务

适用于以下目标：

• 将正在运行的客户端/编辑器会话连接至 OpenClaw
• 通过 HTTP 或 WebSocket 发送提示词/任务/结果
• 使任务可通过蓝图调用
• 支持打包构建（packaged builds）或 PIE 行为

实施方法：

1. 添加一个运行时插件。
2. 将传输逻辑置于 Subsystem 或 Manager UObject 中。
3. 暴露简洁的蓝图节点。
4. 返回结构化结果及明确的错误信息。

典型适用场景：

• AI 驱动的 NPC 工具链
• 依托运行时安全传输机制实现的编辑器内 Copilot 面板
• 游戏测试钩子（gameplay testing hooks）
• 诊断与遥测桥接器

工作流

请按以下顺序执行。

步骤 1：识别集成目标

需明确：

• 引擎版本或版本范围
• 仅编辑器、仅运行时，还是两者皆需
• 是否必须直接支持蓝图
• 传输需求：HTTP、WebSocket、本地 CLI 桥接，或混合方案
• 是否需支持打包构建

若无法访问源码仓库，请明确说明，并基于标准规范生成脚手架。

步骤 2：检查项目结构

对于 Unreal 项目，需查找：

• *.uproject
• Source/
• Plugins/
• 现有模块的 .Build.cs 文件
• 任何已存在的编辑器工具 Widget、Subsystem 或自动化脚本

若需新建插件，建议将其置于 Plugins// 目录下。

步骤 3：选择插件形态

在可行前提下，默认采用 单个运行时模块。

仅在必要时创建额外模块：

• 运行时模块：用于打包构建/运行时安全的功能
• 编辑器模块：仅用于细节面板、菜单、自定义标签页或纯编辑器 API

步骤 4：暴露蓝图接口

最低可用接口应包含：

• 连接/断开连接节点
• 发送 JSON 任务/请求节点
• 异步结果委托（Delegate）或轮询获取器（polling getter）
• 可用性/状态查询节点

若 Schema 尚未成熟，建议优先实现以下稳定节点：

• ConnectToOpenClaw(Url, ApiKey)
• DisconnectFromOpenClaw()
• SendTaskJson(TaskJson)
• GetConnectionStatus()

待 Schema 稳定后，再逐步叠加类型化节点。

步骤 5：显式定义 JSON 协议契约

定义精简的消息信封，例如：

{
  "id": "task-123",
  "type": "run_blueprint_task",
  "task": "summarize_scene",
  "payload": {
    "target": "/Game/Maps/TestMap"
  }
}

返回结果示例：

{
  "id": "task-123",
  "ok": true,
  "result": {
    "summary": "..."
  },
  "error": null
}

确保这些信封与引擎版本无关，并避免将 Unreal 内部实现细节泄露至协议层，除非确有必要。

步骤 6：保守处理 UE 版本差异

采用防御式编码：

• 头文件中仅包含最少必要头文件。
• 模块依赖较重的头文件移至 .cpp 文件中引入。
• 当存在旧版等效 API 时，避免依赖新版辅助函数。
• 在必要时，使用 ENGINE_MAJOR_VERSION / ENGINE_MINOR_VERSION 宏进行版本分支判断。

蓝图指导原则

当用户要求“支持所有类型任务（含蓝图）”时，至少应满足：

• 可被蓝图调用的连接节点
• 可被蓝图调用的请求/响应节点
• 用于异步完成通知的蓝图事件/委托
• 展示用法的示例 Actor/Component/Subsystem

推荐采用以下 Unreal 模式：

• UBlueprintFunctionLibrary：用于无状态便捷方法
• UGameInstanceSubsystem：用于持久化连接生命周期管理
• DECLARE_DYNAMIC_MULTICAST_DELEGATE_*：用于蓝图事件定义

首次实现切忌过度设计。一个可在 UE 5.0+ 全系列编译通过的最小插件，远胜于仅适配单一次要版本的高功能插件。

Remote Control 指导原则

当任务本质属于编辑器侧时，应使用 Remote Control。预期通过 HTTP/WebSocket 控制已暴露的属性与函数。除非项目明确配置了相应机制，否则不得将其描述为面向打包游戏的运行时自动化层。

若用户提出广泛操作蓝图的需求，请拆分为：

• 在编辑器中编辑/检查由蓝图拥有的对象 → Remote Control / 编辑器工具链
• 在运行时调用蓝图节点 → 插件暴露的蓝图库 / Subsystem

推荐的仓库交付物

搭建 Unreal 集成时，建议产出以下内容：

• references/architecture.md —— 集成决策与权衡说明
• references/blueprints.md —— 蓝图支持模式文档
• assets/OpenClawUnrealPlugin/ —— 开箱即用的 UE 插件脚手架
• 可选：用于将插件复制/安装至目标 UE 项目的脚本

验证清单

宣称集成成功前，请确认以下各项：

• 插件描述符（plugin descriptor）存在，且正确命名模块
• .Build.cs 仅包含必需依赖项
• 公有头文件保持精简
• 蓝图节点命名清晰，且异步行为已有明确文档说明
• 运行时专用场景不依赖任何仅编辑器可用的模块
• 版本声明应表述为“面向 UE 5.0+ 设计”，除非实际已在多个版本上完成编译与测试

参考资料

references/

按需查阅：

• references/architecture.md：集成选型与兼容性规则
• references/blueprints.md：面向蓝图的 API 模式
• references/remote-control-notes.md：编辑器自动化指导
• references/openclaw-api-contract.md：默认 /api/unreal/task 请求/响应 Schema
• references/repo-evaluation-notes.md：经验证的目标仓库结构及集成影响分析
• references/engine-builtins.md：可优先组合使用的内置 Unreal 系统（优于新增自定义代码）
• references/install-strategy.md：引擎源码集成 vs 项目插件部署策略对比
• references/integration-map.md：将 OpenClaw 任务映射至已确认引擎系统的关系图
• references/sample-blueprint-flow.md：内置蓝图 HTTP/JSON 连接示例
• references/sample-python-flow.md：编辑器 Python 自动化模式示例
• references/openclaw-server-notes.md：OpenClaw 服务端处理器边界说明
• references/sample-uproject-plugin-config.md：项目级插件启用配置示例
• references/openclaw-server-handler-example.md：具体的 /api/unreal/task 处理器草稿
• references/remote-control-extension-points.md：源码仓库中观察到的 Remote Control / WebRemoteControl 扩展点
• references/webremotecontrol-route-observations.md：所检视引擎分支中实际观测到的路由/请求/响应行为

scripts/

使用 scripts/install_plugin.sh 将脚手架插件复制至目标 Unreal 项目。

assets/

将 assets/OpenClawUnrealPlugin/ 作为 UE 5.0+ 项目的开箱即用插件脚手架使用。