Natfii/UnrealClaude

# UnrealClaude       **专用于 Unreal Engine 5.7 的 Claude Code CLI 集成** - 在编辑器中直接获得内置 UE5.7 文档上下文的 AI 编码辅助。 **Claude Code 计划变更，请在 6 月 15 日之前阅读以便继续使用** [Anthropic 宣布的变更](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan)可能会导致在使用**自定义编辑器内聊天框**时产生额外的使用费用。 由于该插件会在编辑器启动时运行 MCP server，**您可以继续通过 '/mcp' 命令在 Claude Code 中使用 UnrealClaude。** ## 概述 UnrealClaude 将 [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)直接集成到 Unreal Engine 5.7 编辑器中，并运行一个 MCP server 供其他编程代理访问。

**核心功能：** - **原生编辑器集成** - 停靠在编辑器中的聊天面板，支持实时流式响应、工具调用分组和代码块渲染 - **MCP Server** - 提供 20 多种 Model Context Protocol 工具，涵盖 Actor 操作、Blueprint 编辑、关卡管理、材质、输入等 - **动态 UE 5.7 上下文系统** - MCP bridge 包含一个动态上下文加载器，可按需提供准确的 UE 5.7 API 文档 - **Blueprint 编辑** - 创建和修改 Blueprint、Animation Blueprint、状态机（仍存在少量 Bug，请勿完全依赖） - **关卡管理** - 以编程方式打开、创建和管理关卡及地图模板 - **资产管理** - 搜索资产，查询依赖项和引用者 - **异步任务队列** - 长时间运行的操作不会超时 - **脚本执行** - Claude 可以在您的许可下编写、编译（通过 Live Coding）和执行脚本 - **会话持久化** - 对话历史可跨编辑器会话保存 - **项目感知** - 自动收集项目上下文（模块、插件、资产），并能够查看编辑器视口 - **使用 Claude Code 身份验证** - 无需单独管理 API key ## 前置条件 ### 1. 安装 Claude Code CLI ``` npm install -g @anthropic-ai/claude-code ``` ### 2. 验证 Claude Code ``` claude auth login ``` 这将打开一个浏览器窗口，用于验证您的 Anthropic 帐户（Claude Pro/Max 订阅）或设置 API 访问权限。 ### 3. 验证安装 ``` claude --version claude -p "Hello, can you see me?" ``` ## 安装说明 （在插件浏览器的 Editor 类别中查看。如果搜索未找到，您可能需要向下滚动） ### 第一步：克隆并构建 必须为您的平台和引擎版本从源码构建此插件。不包含预编译的二进制文件。 1. 克隆此存储库（包含 MCP bridge 子模块）： git clone --recurse-submodules https://github.com/Natfii/UnrealClaude.git 如果您在克隆时没有使用 `--recurse-submodules`，请运行： cd UnrealClaude git submodule update --init 2. 构建插件： **Windows:** Engine\Build\BatchFiles\RunUAT.bat BuildPlugin -Plugin="PATH\TO\UnrealClaude\UnrealClaude\UnrealClaude.uplugin" -Package="OUTPUT\PATH" -TargetPlatforms=Win64 **Linux:** Engine/Build/BatchFiles/RunUAT.sh BuildPlugin -Plugin="/path/to/UnrealClaude/UnrealClaude/UnrealClaude.uplugin" -Package="/output/path" -TargetPlatforms=Linux **macOS:** Engine/Build/BatchFiles/RunUAT.sh BuildPlugin -Plugin="/path/to/UnrealClaude/UnrealClaude/UnrealClaude.uplugin" -Package="/output/path" -TargetPlatforms=Mac ### 第二步：安装插件 将构建好的插件复制到您的**项目**或**引擎**插件文件夹中。 **选项 A：项目插件（推荐）** 将构建输出复制到您项目的 `Plugins` 目录： ``` YourProject/ ├── Content/ ├── Source/ └── Plugins/ └── UnrealClaude/ ├── Binaries/ ├── Source/ ├── Resources/ ├── Config/ └── UnrealClaude.uplugin ``` **选项 B：引擎插件（所有项目）** 复制到您引擎的插件文件夹中： **Windows:** ``` C:\Program Files\Epic Games\UE_5.7\Engine\Plugins\Marketplace\UnrealClaude\ ``` **Linux:** ``` /path/to/UnrealEngine/Engine/Plugins/Marketplace/UnrealClaude/ ``` ### 第三步：安装 MCP Bridge 依赖 Blueprint 工具和编辑器集成必需： ``` cd /UnrealClaude/Resources/mcp-bridge npm install ``` ### 第四步：启动 启动编辑器 - 插件将自动加载。 ### 第五步：（可选但推荐）：连接 Claude Code CLI 以在没有聊天框的情况下使用 Unreal 1. **启动 Claude Code 或 Claude CLI** 并将其指向您的 UnrealClaude 安装路径。 2. 确认一切正常后，**只需重启 Claude Code / CLI 即可保存更改。**

## macOS 快速入门（Apple Silicon） 有关完整详细信息，请参阅 [INSTALL_MAC.md](INSTALL_MAC.md)。 1. **安装 Node.js 和 Claude Code CLI：** brew install node npm install -g @anthropic-ai/claude-code claude 2. **安装插件**到您项目的 `Plugins/` 目录中 3. **安装 MCP bridge 依赖：** cd YourProject/Plugins/UnrealClaude/Resources/mcp-bridge npm install 4. **启动**编辑器并打开 **Tools > Claude Assistant** ## Linux 快速入门（Rocky/Fedora） 有关完整详细信息，请参阅 [INSTALL_LINUX.md](INSTALL_LINUX.md)。 1. **安装库：** sudo dnf install -y nss nspr mesa-libgbm libXcomposite libXdamage libXrandr alsa-lib pciutils-libs libXcursor atk at-spi2-atk pango cairo gdk-pixbuf2 gtk3 2. **安装剪贴板支持：** sudo dnf install -y wl-clipboard # Wayland sudo dnf install -y xclip # X11 fallback 3. **设置 Wayland：** export SDL_VIDEODRIVER=wayland export UE_Linux_EnableWaylandNative=1 4. **构建并启动：** ./UnrealEditor -vulkan ## 使用说明 ### 打开 Claude 面板 菜单 → Tools → Claude Assistant ### 示例提示 ``` How do I create a custom Actor Component in C++? What's the best way to implement a health system using GAS? Explain World Partition and how to set up streaming for an open world. Write a BlueprintCallable function that spawns particles at a location. How do I properly use TObjectPtr<> vs raw pointers in UE5.7? ``` ### 输入快捷键 | 快捷键 | 操作 | |----------|--------| | `Enter` | 发送消息 | | `Shift+Enter` | 在输入框中换行 | | `Escape` | 取消当前请求 | ## 功能 ### 会话持久化 对话会自动保存到您项目的 `Saved/UnrealClaude/` 目录中，并在您重新打开编辑器时恢复。该插件可跨会话维护对话上下文。 ### 项目上下文 UnrealClaude 会自动收集有关您项目的信息： - 源码模块及其依赖项 - 已启用的插件 - 项目设置 - 最近的资产 - 自定义 `CLAUDE.md` 指令 ### 脚本编写 ### MCP Server 该插件包含一个带有 20 多种工具的 Model Context Protocol (MCP) server，可向 Claude 和外部工具公开编辑器功能。MCP server 默认在端口 3000 上运行，并在编辑器加载时自动启动。 **工具分类：** - **Actor 工具** - 生成、移动、删除、检查 Actor 并设置其属性 - **关卡管理** - 打开关卡，从模板创建新关卡，列出可用模板 - **Blueprint 工具** - 创建和修改 Blueprint（变量、函数、节点、引脚） - **Animation Blueprint 工具** - 完整的状态机编辑（状态、转换、条件、批量操作） - **资产工具** - 搜索资产，通过分页查询依赖项和引用者 - **角色工具** - 角色配置、移动设置和数据查询 - **材质工具** - 材质和材质实例操作 - **Enhanced Input 工具** - 输入动作和映射上下文管理 - **实用工具** - 控制台命令、输出日志、视口捕获、脚本执行 - **异步任务队列** - 用于长时间运行操作的后台执行 有关包含参数、示例和 API 详细信息的完整 MCP 工具文档，请参阅 [UnrealClaude 的 MCP Bridge](https://github.com/Natfii/ue5-mcp-bridge)存储库。 #### 动态 UE 5.7 上下文系统 MCP bridge 包含一个动态上下文加载器，可按需提供准确的 UE 5.7 API 文档。使用 `unreal_get_ue_context` 可按类别（animation、blueprint、slate、actor、assets、replication）进行查询，或按关键字搜索。上下文状态显示在 `unreal_status` 输出中。 ## 配置 ### 项目设置 在 **Project Settings → Plugins → Unreal Claude** 中： - **自动批准脚本执行**（默认：OFF）— 设置为 ON 时，通过 MCP bridge 或编辑器内聊天触发的每一个 Python / C++ / Console / Editor Utility 脚本都会立即运行，而不会显示权限对话框。每个自动批准的脚本都会写入一条包含其类型和描述的 `LogUnrealClaude` 日志条目，从而保留审计跟踪。专为受信任的 MCP 驱动 / 代理驱动工作流而设计，在这些工作流中，每个脚本的确认会成为主要的阻碍；**仅在连接的客户端受信任的计算机和项目中启用**。 该设置会持久化保存到 `Config/DefaultEditor.ini` 中的 `[/Script/UnrealClaude.UnrealClaudeSettings]` 下。 ### 自定义系统提示 您可以通过在项目根目录下创建一个 `CLAUDE.md` 文件来扩展内置的 UE5.7 上下文： ``` # 我的项目上下文 ## Architecture - This is a multiplayer survival game - Using Dedicated Server model - GAS for all abilities ## Coding Standards - Always use UPROPERTY for Blueprint access - Prefix interfaces with I (IInteractable) - Use GameplayTags for ability identification ``` ### 允许的工具 默认情况下，插件在运行 Claude 时会使用以下工具：`Read`、`Write`、`Edit`、`Grep`、`Glob`、`Bash`。您可以在 `ClaudeSubsystem.cpp` 中修改此项： ``` Config.AllowedTools = { TEXT("Read"), TEXT("Grep"), TEXT("Glob") }; // Read-only ``` ## 工作原理 1. 用户在编辑器组件中输入提示 2. 插件根据 UE5.7 知识 + 项目信息构建上下文 3. 执行：`claude -p --skip-permissions --append-system-prompt "..." "your prompt"` 4. Claude Code 将您的项目作为工作目录运行 5. 捕获响应并显示在聊天面板中 6. 对话将持久化保存以供将来会话使用 ### 等效的命令行操作 ``` cd "C:\YourProject" claude -p --skip-permissions \ --allowedTools "Read,Write,Edit,Grep,Glob,Bash" \ --append-system-prompt "You are an expert Unreal Engine 5.7 developer..." \ "How do I create a custom GameMode?" ``` ## 常见问题排查 ### "未找到 Claude CLI" 1. 验证是否已安装 Claude：`claude --version` 2. 检查它是否在您的 PATH 中：`where claude` 3. 安装后重启 Unreal Editor ### "需要身份验证" 在终端中运行 `claude auth login` 进行身份验证。 ### 响应缓慢 Claude Code 会在您的项目目录中执行，并可能会读取文件以获取上下文。对于大型项目，初始响应可能会较慢。 您可能还启用了太多的全局 Claude Code 插件（例如：Superpowers、ralp-loop、context7）。这些插件注入的上下文可能会导致长达 3 分钟以上的延迟。 ### 插件无法编译 确保您使用的是 Unreal Engine 5.7。支持的平台为 Windows (Win64)、Linux 和 macOS。 ### MCP Server 未启动 检查端口 3000 是否可用。MCP server 会记录到 `LogUnrealClaude`。 ### MCP 工具不可用 / Blueprint 工具无法正常工作 如果 Claude 提示 MCP 工具在其指令中，但不在其功能列表中： 1. **安装 MCP bridge 依赖**：最常见的原因是缺少 npm 包： cd YourProject/Plugins/UnrealClaude/Resources/mcp-bridge npm install 2. **验证 HTTP server 是否正在运行**：在编辑器打开的情况下，测试： curl http://localhost:3000/mcp/status 您应该能看到带有项目信息的 JSON 响应。 3. **检查输出日志：查找 `LogUnrealClaude` 消息： - `MCP Server started on http://localhost:3000` - Server 正在运行 - `Registered X MCP tools` - 工具已加载 4. **重启编辑器**：安装 npm 依赖后，重启 Unreal Editor。 ### 请求挂起 新的 watchdog 会警告挂起的请求（60秒）。请确保所有文件都在磁盘上（禁用 OneDrive、DropBox 等）。 ### 调试 MCP Bridge MCP bridge 也可以作为一个[独立存储库](https://github.com/Natfii/ue5-mcp-bridge)使用，并拥有自己的 Vitest 测试套件。如果您遇到 bridge 级别的问题（工具列表、参数转换、上下文注入），可以独立运行 bridge 测试： ``` cd path/to/ue5-mcp-bridge npm install npm test ``` 这将测试 bridge，而无需运行 Unreal Editor。 ## 贡献 随时根据您自己的需求进行 Fork！可能需要改进的领域： - [x] Linux 支持（感谢 [@bearyjd](https://github.com/bearyjd)） - [x] Mac 支持（感谢 [@lateralsummer](https://github.com/lateralsummer)） - [ ] 更多 MCP 工具（现有工具需要重构，目前暂不添加新工具） ## 许可证 MIT License - 详见 [LICENSE](UnrealClaude/LICENSE)文件。 ## 致谢 - 为 Unreal Engine 5.7 而构建 - 集成了由 Anthropic 提供的 [Claude Code](https://claude.ai/code)

标签：AI编程助手, C++, Claude, CVE检测, MCP, MITM代理, Unreal Engine, 插件, 数据擦除