PHOTONBP

# UEOS — 虚幻引擎操作系统 **版本 7.0.0 — 第 7 阶段完成：Chaos 物理 + PCG + 增强输入 + MetaSounds** 由 AI 驱动的虚幻引擎 5.4 开发系统。Claude 通过 **339 个 MCP 工具**控制 UE 编辑器，借助远程控制 API。无需 C++。纯 Python。 --- ## ⚡ 工作原理（请先阅读本节） UEOS 通过三个桥梁将 **Claude Desktop** 连接到 **虚幻引擎 5.4**： ``` Claude Desktop │ │ MCP 协议（stdio） ▼ mcp_server/server.py ← 339 个工具在此注册 │ │ HTTP PUT 端口 30010 ▼ 虚幻引擎 5.4 ← 远程控制 API + Python 脚本插件 ``` Claude 发送命令 → UEOS 将其翻译为 UE Python 脚本 → 在编辑器中实时运行。 ### 系统提示 UEOS 具有完整的行为系统提示（`UEOS_SYSTEM_PROMPT.md` — 74KB 的 UE 原则、优化规则、蓝图标准和游戏设计模式）。**Claude 不会自动加载此提示。** 您必须在每次对话开始时激活它： ``` /ueos ``` 在 Claude Desktop 聊天中输入 `/ueos` 以加载 UEOS 系统提示。没有它，Claude 可以使用所有 339 个工具，但没有 UEOS 行为指令。 > **为什么不自动注入？** `claude_desktop_config.json` 只支持 `command`、`args`、`cwd` 和 `env` 字段用于 MCP 服务器 — MCP 规范中没有系统提示字段。最干净的解决方案是 MCP Prompts API 已经实现：输入 `/ueos` 以加载它，或将 `UEOS_SYSTEM_PROMPT.md` 的内容粘贴到 Claude → 设置 → 项目说明中。 --- ## 📋 完整设置指南 — 按时间顺序 按照这些步骤 **按顺序进行**。不要跳过。 --- ### 步骤 1 — 先决条件 在开始 UEOS 之前，请确保您具备： | 要求 | 版本 | 获取位置 | |-------------|---------|-----------------| | Windows 10/11 | 任意 | — | | 虚幻引擎 | 5.4+ | Epic Games Launcher | | Python | 3.10+ | https://www.python.org/downloads/ | | Claude Desktop | 最新版 | https://claude.ai/download | > **Python 安装提示：** 在 Python 安装程序中，勾选 **"将 Python 添加到 PATH"** 然后点击安装。UEOS 没有此设置将无法工作。 --- ### 步骤 2 — 下载/克隆 UEOS **选项 A — Git：** ```bash git clone https://github.com/your-repo/ueos.git C:\UEOS ``` **选项 B — ZIP 下载：** 1. 从 GitHub 下载 ZIP 文件 2. 解压到 `C:\UEOS`（或任何无空格的路径） > 路径中不能包含空格（例如 `C:\Users\John Smith\UEOS` 将会出错）。请使用 `C:\UEOS` 或 `C:\Dev\UEOS`。 --- ### 步骤 3 — 运行设置（双击） **双击 `SETUP.bat`** 在 UEOS 根目录中。 它会自动执行以下操作： 1. 检查 Python 版本（需要 3.10+） 2. 安装所有 pip 依赖项（`mcp`、`aiohttp`、`python-dotenv` 等） 3. 将 UEOS 条目写入 `claude_desktop_config.json` 4. 如果 UE 项目已打开，则修补 UE 项目设置 5. 从模板创建 `.env` 6. 启动 GUI 仪表板 如果缺少 Python，`SETUP.bat` 将自动下载并安装 Python 3.11.9，然后重新运行。 **预期输出：** ``` [1/5] 检查 Python... OK: Python 3.11.9 [2/5] 安装依赖项... OK: 所有依赖项已安装 [3/5] 配置 Claude Desktop... OK: 已写入 Claude Desktop 配置。重启 Claude Desktop。 [4/5] 配置虚幻引擎项目... OK: 已修补 UE 项目设置。 [5/5] 完成... OK: 设置完成 ``` > 如果步骤 3 显示 `NOTE: Claude Desktop not found` — 请先安装 Claude Desktop，然后运行 `FIX_CLAUDE_CONFIG.bat`。 --- ### 步骤 4 — 配置 API 密钥 `SETUP.bat` 完成后，GUI 启动器将打开。前往 **API 密钥** 标签页。 #### 4a. Tripo API 密钥（3D 生成必填） 1. 前往 https://platform.tripo3d.ai 2. 账户 → API 密钥 → 创建密钥 3. 复制密钥（以 `tsk_` 开头） 4. 粘贴到 GUI 中的 **Tripo API 密钥** 字段 5. 点击 **验证** — 它应该显示您的信用余额 #### 4b. Huanyuan3D API 密钥（可选） 1. 前往 https://hunyuan.cloud.tencent.com 2. 创建 API 密钥 3. 粘贴到 **Huanyuan API 密钥** 字段 #### 4c. MetaTailor API 密钥（可选 — 自动绑定） 1. 前往 https://metatailor.io 2. 创建 API 密钥 3. 粘贴到 **MetaTailor API 密钥** 字段 **或通过命令行配置：** ```bash python setup/configure.py ``` 这将运行一个交互式向导，验证您输入的每个密钥。 **密钥存储位置：** 密钥保存在 `.env` 中位于 UEOS 根目录下。该文件被 git 忽略，永远不会被提交。 ```bash # .env（自动生成 — 不要提交） TRIPO_API_KEY=tsk_your_key_here HUANYUAN_API_KEY=your_key_here METATAILOR_API_KEY=your_key_here UE_REMOTE_CONTROL_HOST=127.0.0.1 UE_REMOTE_CONTROL_PORT=30010 UEOS_ASSET_TEMP_DIR=C:/UEOS/temp ``` --- ### 步骤 5 — 配置虚幻引擎 5.4 插件 打开您的虚幻引擎 5.4 项目。启用这些插件： **编辑 → 插件 → 搜索并启用每个：** | 插件 | 必需 | 备注 | |--------|----------|-------| | **Python 编辑器脚本插件** | ✅ 必需 | 在 UE 中启用 Python 执行 | | **远程控制 API** | ✅ 必需 | 在端口 30010 上启用 HTTP 控制 | | **远程控制逻辑** | ✅ 必需 | 支持远程控制预设 | | **编辑器脚本实用工具** | ✅ 必需 | 扩展编辑器脚本 | | **Niagara** | ✅ 必需 | 粒子系统工具 | 启用所有插件后，**重启 UE 编辑器**。 --- ### 步骤 6 — 配置远程控制 API （关键） 此步骤实际上允许 UEOS 与 UE 通信。**不要跳过此步骤。** 1. 在 UE 中：**编辑 → 项目设置** 2. 在左侧面板中，滚动到 **插件 → 远程控制 API** 3. 设置这些值： | 设置 | 值 | 为什么 | |---------|-------|-----| | **允许编辑器的远程控制** | ✅ 启用 | 必须打开 | | **远程控制 HTTP 服务器端口** | `30010` | 默认 UEOS 端口 | | **HTTP 服务器绑定地址** | `0.0.0.0` | **关键 — 设置此值，否则连接失败** | > **为什么是 `0.0.0.0`？** 默认情况下，UE 绑定到 `127.0.0.1`（仅限本地主机）。将其设置为 `0.0.0.0` 允许来自机器上任何地址的连接，这对于 UEOS 可靠连接 Python 环境是必需的。 4. 点击 **设为默认值** 以保存到项目配置（而不仅仅是会话） 5. 这些设置保存到您的 UE 项目中的 `Config/DefaultEngine.ini` --- ### 步骤 7 — 为 Python 启用远程执行（用于桥梁） 远程执行允许外部 Python 进程在 UE 编辑器中执行脚本。这与远程控制 API 是分开的。 1. 在 UE 中：**编辑 → 项目设置** 2. 在左侧面板中搜索 **Python** 3. 找到 **Python 远程执行**： | 设置 | 值 | |---------|-------| | **启用远程执行？** | ✅ 启用 | | **多播组端点** | `239.0.0.1:6766`（默认） | | **多播绑定地址** | `0.0.0.0` | | **多播 TTL** | `0` | 4. **重启 UE 编辑器** 以更改这些设置。 --- ### 步骤 8 — 验证 Python 桥梁是否活跃 重启 UE 并启用插件和设置后，验证 Python 桥梁是否在线。 **在 UE 中：窗口 → 开发者工具 → 输出日志** 运行此命令以确认桥梁是活跃的： ```python import unreal; unreal.log("UEOS bridge active: OK") ``` **运行它：** 在 UE 输出日志中，点击底部命令栏并输入： ``` py import unreal; unreal.log("UEOS bridge active: OK") ``` 您应该在输出日志中看到 `LogPython: UEOS bridge active: OK`。 **或者，从外部 Python：** ```python import urllib.request, json payload = json.dumps({ "objectPath": "/Script/PythonScriptPlugin.Default__PythonScriptLibrary", "functionName": "ExecutePythonScript", "parameters": {"PythonScript": "import unreal; print('UEOS_PING:OK')"} }).encode() req = urllib.request.Request( "http://127.0.0.1:30010/remote/object/call", data=payload, headers={"Content-Type": "application/json"}, method="PUT" ) with urllib.request.urlopen(req, timeout=5) as resp: print(resp.read().decode()) ``` 预期响应： `{"ReturnValue": "", "PythonScript": "import unreal; print('UEOS_PING:OK')"}` --- ### 步骤 9 — 配置 Claude Desktop `SETUP.bat` 应该已经完成了此操作。要手动验证或修复： **双击 `FIX_CLAUDE_CONFIG.bat`** — 它会自动检测 Claude Desktop 安装位置并写入正确的配置。 **手动路径：** `%APPDATA%\Claude\claude_desktop_config.json` UEOS 写入的条目如下： ```json { "mcpServers": { "ueos": { "command": "C:\\Python311\\python.exe", "args": ["C:\\UEOS\\mcp_server\\server.py"], "cwd": "C:\\UEOS\\mcp_server" } } } ``` > 路径是根据您的实际 Python 和 UEOS 位置自动生成的。不要手动硬编码这些路径 — 始终使用 `FIX_CLAUDE_CONFIG.bat` 或 `python setup/inject_claude_config.py`。 **写入配置后：** 1. **完全退出 Claude Desktop** — 右键单击托盘图标 → 退出（不仅仅是关闭窗口） 2. 重新打开 Claude Desktop 3. 在聊天输入栏中查找 🔌 MCP 图标 — 它应该显示 UEOS 工具 --- ### 步骤 10 — 验证一切正常 #### 10a. 运行 UEOS 状态 在 Claude Desktop 中，询问： ``` run ueos_status ``` 预期输出： ``` ✓ 虚幻引擎 5.4.x 已连接 项目：YourProjectName 层级：/Game/Maps/TestMap ✓ Tripo API 已连接 余额：1234 积分 ✓ UEOS MCP 服务器正在运行 工具：339 个已注册 ``` 如果 UE 未运行，UE 状态显示为断开连接 — 这是可以的。启动 UE 并再次尝试。 #### 10b. 运行 UEOS 诊断（如果 ueos_status 失败） ``` run ueos_diagnose ``` `ueos_diagnose` 直接向 UE 的远程控制 API 发送原始 HTTP PUT 并显示您 **确切** 的响应 — 状态代码、标头和正文。这可以准确告诉您哪里出了问题： | 错误 | 含义 | 修复 | |-------|---------|-----| | `Connection refused` | UE 未运行或端口错误 | 启动 UE，检查端口 30010 | | `403 Forbidden` | 远程控制未启用 | 在项目设置 → 插件 → 远程控制 API 中启用 | | `404 Not Found` | 端点错误或 UE 版本错误 | 验证 UE 5.4 | | `400 Bad Request` | Python 插件未启用 | 启用 Python 编辑器脚本插件 | | 超时 | 绑定地址错误 | 将绑定地址设置为 `0.0.0.0` | #### 10c. 加载 UEOS 系统提示 在任何 UEOS 对话的开始，输入： ``` /ueos ``` 这通过 MCP Prompts API 加载完整的 74KB UEOS 行为系统提示。您将看到 Claude 承认它并进入 UEOS 模式。 --- ## 🖥️ GUI 启动器 首次设置完成后，使用 **`UEOS.bat`**（不是 `SETUP.bat`）进行日常使用。 双击 `UEOS.bat` → 打开带有 5 个标签的 UEOS 仪表板： | 标签页 | 用途 | |-----|---------| | **仪表板** | 实时连接状态（UE、Tripo、Huanyuan3D、MetaTailor）。启动/停止 MCP 服务器。 | | **API 密钥** | 输入和验证所有 API 密钥。值默认掩盖。 | | **设置** | UE 远程控制主机/端口、下载资产的临时目录、日志级别。 | | **Claude 设置** | 自动检测 Claude Desktop 配置并写入/更新 UEOS 条目。 | | **日志** | `ueos.log` 的实时彩色编码尾部。显示所有工具调用。 | --- ## 🔧 诊断工具参考 ### `ueos_status` 高级健康检查。显示： - UE 连接状态（主机、端口、引擎版本、项目名称） - Tripo API（已连接 + 信用余额） - Huanyuan3D（已连接或未配置） - MetaTailor（已连接或未配置） - MCP 服务器工具计数 **何时使用：** 打开 Claude 后首次检查。快速进行健康检查。 ### `ueos_diagnose` 原始 HTTP 诊断。直接发送 `PUT /remote/object/call` 到 UE 并返回： - HTTP 状态码 - 响应头 - 完整响应正文 - 计时 **何时使用：** 当 `ueos_status` 显示 UE 断开连接时。显示 UE 拒绝的确切内容以及原因。 ### `ueos_run_python` 在 UE 5.4 编辑器中执行任意 Python 代码。完全访问 `unreal` 模块。 ```python # 示例：列出 /Game/Characters 中的所有资产 import unreal ar = unreal.AssetRegistryHelpers.get_asset_registry() assets = ar.get_assets_by_path('/Game/Characters', recursive=True) print(f"UEOS_RESULT:{[str(a.asset_name) for a in assets]}") ``` 使用 `UEOS_RESULT:` 前缀返回值，`UEOS_ERROR:` 前缀错误。 **何时使用：** 自定义操作未被现有工具覆盖。高级调试。 --- ## 🔑 系统提示交付 — 技术细节 ### 问题 `claude_desktop_config.json` 只支持以下 MCP 服务器字段： ```json { "mcpServers": { "ueos": { "command": "...", "args": [...], "cwd": "...", "env": {} } } ``` MCP 规范中 **没有 `systemPrompt` 字段**。Claude Desktop 不会自动从配置文件注入系统提示。 ### 当前解决方案 — MCP Prompts API UEOS 通过 **MCP Prompts API** 提供其系统提示（`@server.list_prompts` / `@server.get_prompt` 在 `server.py` 行 156–196） 在 Claude Desktop 中：输入 **`/ueos`** → Claude 在运行时获取 `UEOS_SYSTEM_PROMPT.md` 并将其作为上下文加载。 ### 永久解决方案 — 项目说明 自动加载每次对话： 1. 在 Claude Desktop：**设置 → 项目 → 新项目（或打开您的 UEOS 项目）** 2. 点击 **项目说明** 3. 粘贴 `UEOS_SYSTEM_PROMPT.md` 的内容 这使得系统提示每次对话自动加载 — 无需 `/ueos`。 ### 总结 | 方法 | 自动加载？ | 如何使用 | |--------|-------------|-----------| | `/ueos` 命令 | ❌ 手动 | 每次聊天开始时输入 `/ueos` | | 项目说明 | ✅ 自动 | 将提示粘贴到 Claude 项目一次 | | `claude_desktop_config.json` | ❌ 不可能 | MCP 规范中没有系统提示字段 | --- ## ⚠️ 常见问题与修复 ### "Claude 看不到任何 UEOS 工具" 1. 检查 `claude_desktop_config.json` 是否有 `ueos` 条目 → 运行 `FIX_CLAUDE_CONFIG.bat` 2. **完全退出并重新打开** Claude Desktop（右键单击托盘图标 → 退出） 3. 检查 🔌 MCP 图标是否出现在聊天输入栏 ### "ueos_status 显示 UE 断开连接" 1. 确保虚幻引擎 5.4 运行并打开您的项目 2. 运行 `ueos_diagnose` — 检查确切的错误 3. 验证远程控制 API 已启用：**编辑 → 项目设置 → 远程控制 API → 允许编辑器的远程控制 = ON** 4. 验证绑定地址为 `0.0.0.0`（而不是 `127.0.0.1`） 5. 验证端口为 `30010` ### "Python not found" 在 SETUP.bat 运行期间 - 从 https://www.python.org/downloads/ 重装 Python - 安装时勾选 **"将 Python 添加到 PATH"** - 再次运行 `SETUP.bat` ### "Permission denied" 写入 claude_desktop_config.json - 以管理员身份运行 `FIX_CLAUDE_CONFIG.bat`（右键单击 → 以管理员身份运行） - 或手动编辑 `%APPDATA%\Claude\claude_desktop_config.json` ### "Tripo 验证失败" - 密钥以 `tsk_` 开头 — 确保您复制了完整的密钥 - 检查您的 Tripo 账户是否有剩余积分 - 运行 `python setup/configure.py --tripo` 重新输入密钥 ### "/ueos 命令在 Claude 中未被识别" - MCP 服务器未连接 — 检查上面的步骤 - 尝试在 Claude Desktop 中输入 `/` 以查看所有可用的提示 - 运行 `ueos_status` 以确认服务器正在运行 ### "Claude 没有 UEOS 上下文 / 表现得很困惑" - 您忘记在对话开始时输入 `/ueos` - 或使用项目说明（永久解决方案 — 见上文） ## 📐 架构 ``` Claude Desktop │ │ MCP (stdio) ▼ mcp_server/server.py ← 339 个工具已注册 │ ├── tools/blueprint.py ← 17 个工具：图表编辑、编译、验证 ├── tools/material.py ← 14 个工具：PBR、溶解、 hologram、基材 ├── tools/niagara.py ← 20 个工具：火、爆炸、轨迹、魔法 ├── tools/inspection.py ← 12 个工具：任何资产的深度 JSON 检查 ├── tools/scene.py ← 16 个工具：灯光、雾、PPV、相机、演员 ├── tools/data.py ← 15 个工具：结构体、枚举、数据表、曲线 ├── tools/animation.py ← 22 个工具：AnimBP、状态机、蒙太奇、混合空间、IK ├── tools/umg.py ← 20 个工具：小部件 BP、HUD、菜单、5 个预设（第 4 阶段） ├── tools/sequencer.py ← 18 个工具：关卡序列、相机剪辑、轨道（第 4 阶段） ├── tools/behavior_tree.py ← 17 个工具：BT、黑板、任务、AI 管道（第 4 阶段） ├── tools/editor_widget.py ← 20 个工具：EUW 面板、菜单、UEOS 面板（第 5 阶段） ├── tools/gameplay_ability.py ← 20 个工具：GAS、属性集、效果、提示（第 6 阶段） ├── tools/environment_query.py ← 20 个工具：EQS 查询、生成器、测试（第 6 阶段） ├── tools/navmesh.py ← 17 个工具：NavMesh、NavAreas、链接、AI 移动（第 6 阶段） ├── tools/chaos_physics.py ← 25 个工具：几何集合、骨折、布料、场（第 7 阶段） ├── tools/pcg.py ← 21 个工具：PCG 图、采样器、生成器、体积（第 7 阶段） ├── tools/enhanced_input.py ← 18 个工具：输入动作、IMC、预设、玩家绑定（第 7 阶段） └── tools/metasound.py ← 17 个工具：MetaSound 源/补丁、衰减、LFO、总线（第 7 阶段） │ ├── remote_control/client.py ← UE 5.4 HTTP 客户端，带有重试逻辑 ├── api_clients/tripo.py ← Tripo REST API ├── api_clients/huanyuan.py ← 幻元 3D └── api_clients/metatailor.py ← MetaTailor 蒙皮 │ │ HTTP 端口 30010 ▼ 虚幻引擎 5.4 └── Python 编辑器脚本插件 ``` --- ## 📦 工具清单 ### 🔵 蓝图工具（17） | 工具 | 描述 | |------|-------------| | `blueprint_create` | 创建具有任意父类的蓝图资产 | | `blueprint_add_variable` | 添加类型变量（布尔/整数/浮点/字符串/向量/对象/结构体/枚举…） | | `blueprint_add_function` | 向蓝图中添加命名函数 | | `blueprint_add_node` | 向蓝图图表中添加任意 K2 节点 | | `blueprint_connect_pins` | 将两个节点引脚连接在一起 | | `blueprint_add_component` | 添加组件（网格、相机、灯光、物理、音频…） | | `blueprint_set_construction_script` | 完整的构造函数，带有 Leader Pose 自动连线 | | `blueprint_compile` | 编译蓝图，返回错误 | | `blueprint_validate` | 验证而不编译 | | `blueprint_add_timeline` | 添加具有浮点/向量/颜色轨道的时间线节点 | | `blueprint_set_defaults` | 设置类默认属性值 | | `blueprint_add_interface` | 实现蓝图接口 | | `blueprint_add_event_dispatcher` | 添加事件调度器 | | `blueprint_add_macro` | 添加蓝图宏 | | `blueprint_get_info` | 读取变量、函数、组件 | | `blueprint_list` | 列出路径下的所有蓝图 | | `blueprint_delete` | 删除蓝图资产 | ### 🟠材质工具（14） | 工具 | 描述 | |------|-------------| | `material_create` | 创建具有域/混合模式的空材质 | | `material_add_node` | 添加任意表达式节点（80+ 类型，包括基材） | | `material_connect` | 连接两个表达式引脚 | | `material_set_property` | 将节点连接到输出属性（基础颜色、粗糙度…） | | `material_set_param` | 设置标量/向量/纹理参数 | | `material_build_pbr` | 从纹理路径构建完整的 PBR | | `material_build_dissolve` | 基于噪声的溶解，带有边缘发射光 | | `material_build_emissive` | 发射光，带有可选的正弦波脉冲 | | `material_build_hologram` | 扫描线 + 弗雷内尔 + 闪烁全息图 | | `material_recompile` | 强制重新编译材质 | | `material_get_info` | 读取所有节点、参数、属性 | | `material_create_instance` | 从父材质创建材质实例 | | `material_set_instance_param` | 在 MI 上设置标量/向量/纹理/开关 | | `material_list` | 列出路径中的所有材质 | ### 🟡 尼agara 工具（20） | 工具 | 描述 | |------|-------------| | `niagara_create_system` | 创建空的 Niagara 系统 | | `niagara_add_emitter` | 向系统添加发射器 | | `niagara_set_parameter` | 设置系统/发射器参数 | | `niagara_set_renderer` | 配置精灵/网格/丝带渲染器 | | `niagara_set_spawn_rate` | 设置每秒粒子数 | | `niagara_set_lifetime` | 设置粒子生命周期范围 | | `niagara_set_color` | 设置颜色，带有可选的渐变 | | `niagara_set_size` | 设置初始大小 + 生命周期大小 | | `niagara_set_velocity` | 设置初始速度 | | `niagara_set_gravity` | 设置重力缩放 | | `niagara_add_module` | 添加任意 Niagara 模块 | | `niagara_build_fire` | 火焰预设：小/中/大/无尽 + 烟雾 + 火花 | | `niagara_build_trail` | 丝带武器/弹道轨迹 | | `niagara_build_explosion` | 爆炸：小/中/大/巨大，带有冲击波 | | `niagara_build_magic_effect` | 8 种魔法类型：火/冰/治愈/闪电/奥术/黑暗/风/土 | | `niagara_compile` | 编译 Niagara 系统 | | `niagara_get_info` | 读取发射器、参数、模块 | | `niagara_list` | 列出路径中的所有 Niagara 系统 | | `niagara_duplicate` | 复制系统为新资产 | | `niagara_delete` | 删除 Niagara 系统 | ### 🔍 检查工具（12） | 工具 | 描述 | |------|-------------| | `inspect_asset` | 深度 JSON 检查任意 UE 资产 | | `inspect_blueprint` | 完整的 BP 信息：变量、函数、组件、图表 | | `inspect_material` | 材质节点、参数、属性 | | `inspect_mesh` | 静态网格/骨骼网格 LOD、材质、插槽 | | `inspect_skeleton` | 骨骼层次结构、插槽位置 | | `inspect_datatable` | 所有行作为 JSON | | `inspect_anim` | 动画序列/蒙太奇/混合空间元数据 | | `inspect_niagara` | Niagara 系统结构 | | `inspect_physics_asset` | 物理资产主体和约束 | | `inspect_folder` | 浏览内容文件夹（名称、类、大小） | | `inspect_find_by_class` | 在路径中找到指定类的所有资产 | | `inspect_find_references` | 找到引用给定资产的所有资产 | ### 🌍 场景工具（16） | 工具 | 描述 | |------|-------------| | `scene_place_actor` | 在位置处生成任意演员类 | | `scene_move_actor` | 设置位置/旋转/缩放 | | `scene_delete_actor` | 按标签删除演员 | | `scene_duplicate_actor` | 复制演员并偏移 | | `scene_select_actor` | 设置编辑器选择 | | `scene_get_actors` | 列出关卡中的所有演员 | | `scene_add_point_light` | 添加具有强度/颜色/半径的点光源 | | `scene_add_spot_light` | 添加具有锥角的聚光灯 | | `scene_add_directional_light` | 添加定向光（太阳） | | `scene_add_sky_atmosphere` | 添加天空大气组件 | | `scene_add_fog` | 添加具有体积选项的指数高度雾 | | `scene_add_post_process` | 添加具有所有设置的后期处理卷 | | `scene_set_skylight` | 配置 SkyLight，带有 HDRI 捕获 | | `scene_add_decal` | 放置具有材质的 DecalActor | | `scene_add_camera` | 添加具有镜头设置的 CineCameraActor | | `scene_take_screenshot` | 捕获视口到 PNG | ### 📊 数据工具（15） | 工具 | 描述 | |------|-------------| | `data_create_struct` | 创建具有类型字段的 UStruct | | `data_create_enum` | 创建具有命名值的 UEnum | | `data_create_datatable` | 创建具有行结构的 DataTable | | `data_add_rows` | 通过 JSON 数组添加/更新行 | | `data_get_rows` | 从 DataTable 读取所有行 | | `data_delete_rows` | 按名称删除行 | | `data_create_curve` | 创建 CurveFloat/Vector/Color | | `data_add_curve_keys` | 向曲线添加关键帧 | | `data_create_primary_asset` | 创建主要数据资产 | | `data_create_save_game` | 创建 SaveGame 类 | | `data_create_game_instance` | 创建 GameInstance 子类 | | `data_set_variable` | 在蓝图 CDO 上设置变量 | | `data_get_variable` | 从蓝图 CDO 获取变量 | | `data_list` | 列出路径中的所有数据资产 | | `data_delete` | 删除数据资产 | ### 🎭 动画工具（22） | 工具 | 描述 | |------|-------------| | `anim_create_blueprint` | 为骨骼创建动画蓝图 | | `anim_add_variable` | 添加变量（浮点/布尔/整数/向量） | | `anim_create_state_machine` | 在 AnimBP 中创建状态机 | | `anim_add_state` | 添加具有动画资产的状态 | | `anim_add_transition` | 添加具有条件的过渡 | | `anim_create_blendspace` | 创建 BlendSpace1D 或 2D | | `anim_add_blendspace_sample` | 向 BlendSpace 添加样本点 | | `anim_create_montage` | 从序列创建 AnimMontage | | `anim_add_montage_section` | 添加命名部分 | | `anim_add_notify` | 在时间点添加 AnimNotify | | `anim_add_notify_state` | 添加具有开始/结束的通知状态 | | `anim_create_ikrig` | 为骨骼创建 IK Rig | | `anim_add_ik_goal` | 添加 IK 目标（脚、手、头） | | `anim_create_ikretargeter` | 创建 IK 重定向器 | | `anim_set_retarget_pose` | 设置重定向参考姿势 | | `anim_compile` | 编译 AnimBlueprint | | `anim_get_info` | 读取 AnimBP 结构 | | `anim_list` | 列出动画资产 | | `anim_set_root_motion` | 启用/配置根运动 | | `anim_add_layered_blend` | 添加每骨骼的层叠混合节点 | | `anim_add_aim_offset` | 添加 AimOffset 资产和节点 | | `anim_set_physics_blend` | 设置物理动画混合 | ### 🖼️ UMG 小部件工具（20） | 工具 | 描述 | |------|-------------| | `umg_create_widget` | 创建小部件蓝图 | | `umg_add_widget` | 添加小部件元素（按钮、文本、图像…） | | `umg_set_property` | 设置小部件属性 | | `umg_bind_event` | 将小部件事件绑定到函数 | | `umg_add_animation` | 添加 UMG 动画 | | `umg_set_anchors` | 设置小部件锚点和对齐方式 | | `umg_add_canvas_panel` | 添加 CanvasPanel 根节点 | | `umg_add_vertical_box` | 添加垂直框布局 | | `umg_add_horizontal_box` | 添加水平框布局 | | `umg_add_overlay` | 添加叠加层容器 | | `umg_add_scroll_box` | 添加滚动框 | | `umg_add_progress_bar` | 添加进度条 | | `umg_add_text_block` | 添加文本块 | | `umg_add_image` | 添加图像小部件 | | `umg_add_button` | 添加带有文本的按钮 | | `umg_build_hud` | 构建完整 HUD 预设（生命值/弹药/小地图） | | `umg_build_menu` | 构建主菜单预设（播放/设置/退出） | | `umg_build_inventory` | 构建网格库存预设 | | `umg_build_dialogue` | 构建对话框预设 | | `umg_compile` | 编译小部件蓝图 | ### 🎬 Sequencer 工具（18） | 工具 | 描述 | |------|-------------| | `seq_create` | 创建关卡序列 | | `seq_add_camera_cut` | 添加相机剪辑轨道 | | `seq_add_actor_track` | 添加演员绑定轨道 | | `seq_add_transform_track` | 添加变换关键帧轨道 | | `seq_add_property_track` | 添加属性关键帧轨道 | | `seq_add_audio_track` | 添加音频轨道 | | `seq_add_event_track` | 添加事件轨道 | | `seq_add_fade` | 添加淡入/淡出 | | `seq_set_duration` | 设置序列持续时间 | | `seq_set_fps` | 设置帧率 | | `seq_add_subsequence` | 嵌套子序列 | | `seq_add_camera` | 添加 CineCamera 演员 + 轨道 | | `seq_set_camera_lens` | 设置焦距、光圈、焦点 | | `seq_add_cine_actor` | 添加具有电影运动的演员 | | `seq_get_info` | 读取序列结构 | | `seq_render` | 触发电影渲染 | | `seq_list` | 列出路径中的序列 | | `seq_delete` | 删除序列 | ### 🤖 行为树工具（17） | 工具 | 描述 | |------|-------------| | `bt_create` | 创建行为树资产 | | `bt_create_blackboard` | 创建黑板资产 | | `bt_add_key` | 添加黑板键（对象/向量/布尔/浮点/整数/字符串/枚举） | | `bt_add_selector` | 添加选择器复合体 | | `bt_add_sequence` | 添加序列复合体 | | `bt_add_parallel` | 添加并行复合体 | | `bt_add_task` | 添加内置任务（MoveTo、Wait、PlaySound…） | | `bt_add_service` | 添加服务（更新率、激活） | | `bt_add_decorator` | 添加装饰器（条件、冷却、循环…） | | `bt_create_task` | 创建自定义 BTTask 蓝图 | | `bt_create_service` | 创建自定义 BTService 蓝图 | | `bt_create_decorator` | 创建自定义 BTDecorator 蓝图 | | `bt_set_root` | 设置根复合体 | | `bt_assign_blackboard` | 将黑板分配给行为树 | | `bt_get_info` | 读取 BT 结构 | | `bt_list` | 列出路径中的所有 BT | | `bt_build_patrol` | 完整的巡逻 + 警报模式预设 | ### 🛠️ 编辑器小部件工具（20） | 工具 | 描述 | |------|-------------| | `euw_create` | 创建编辑器实用小部件蓝图 | | `euw_add_button` | 添加带有标签和点击回调的按钮 | | `euw_add_text_input` | 添加可编辑的文本输入 | | `euw_add_dropdown` | 添加下拉选择器 | | `euw_add_checkbox` | 添加复选框 | | `euw_add_slider` | 添加带有范围的浮点滑块 | | `euw_add_label` | 添加静态文本标签 | | `euw_add_progress_bar` | 添加进度条 | | `euw_add_list_view` | 添加列表/树视图 | | `euw_add_tab_container` | 添加选项卡条容器 | | `euw_bind_event` | 将小部件事件绑定到 Python/BP 函数 | | `euw_add_menu_entry` | 添加到顶级编辑器菜单 | | `euw_add_toolbar_button` | 在编辑器工具栏中添加按钮 | | `euw_register_tab` | 注册为可停靠的选项卡面板 | | `euw_open` | 打开/生成小部件 | | `euw_post_status` | 向编辑器状态栏发布消息 | | `euw_set_progress` | 更新状态栏进度值 | | `euw_build_ueos_panel` | 构建完整的 UEOS 控制面板 | | `euw_get_info` | 读取小部件结构 | | `euw_list` | 列出路径中的所有 EUW | ### ⚡️ 游戏玩法能力系统工具（20） | 工具 | 描述 | |------|-------------| | `gas_add_asc` | 向演员添加能力系统组件 | | `gas_create_attribute_set` | 创建具有类型属性的属性集 | | `gas_create_ability` | 创建游戏玩法能力蓝图 | | `gas_create_effect` | 创建游戏效果（即时/持续/无限） | | `gas_create_cue` | 创建游戏提示处理程序 | | `gas_add_attribute` | 向属性集添加属性 | | `gas_set_effect_modifier` | 在游戏效果上配置修改器 | | `gas_set_effect_duration` | 设置持续时间和周期 | | `gas_add_tag` | 向能力/效果添加游戏标签 | | `gas_set_cost` | 设置能力成本（游戏效果） | | `gas_set_cooldown` | 设置能力冷却时间 | | `gas_grant_ability` | 在运行时授予能力给演员 | | `gas_apply_effect` | 将游戏效果应用于演员 | | `gas_remove_effect` | 从演员身上移除游戏效果 | | `gas_get_attribute` | 获取当前属性值 | | `gas_set_attribute` | 直接设置属性值 | | `gas_create_execution` | 创建游戏效果执行计算 | | `gas_create_mmc` | 创建修改器幅度计算 | | `gas_get_info` | 读取演员的 GAS 设置 | | `gas_list` | 列出路径中的所有 GAS 资产 | ### 🎯 环境查询系统工具（20） | 工具 | 描述 | |------|-------------| | `eqs_create` | 创建 EQS 查询资产 | | `eqs_add_generator` | 添加生成器（类对象、网格、甜甜圈、圆圈、锥体） | | `eqs_add_test` | 添加测试（跟踪、距离、点积、路径查找、重叠） | | `eqs_set_test_filter` | 配置测试为过滤器（通过/失败阈值） | | `eqs_set_test_score` | 配置测试为评分器（权重、钳位） | | `eqs_add_context` | 添加上下文（查询者、目标、所有演员、自定义） | | `eqs_set_generator_params` | 设置生成器参数（半径、密度、计数） | | `eqs_create_context` | 创建自定义 EnvQueryContext 蓝图 | | `eqs_create_test` | 创建自定义 EnvQueryTest 蓝图 | | `eqs_run_query` | 运行 EQS 查询，返回结果 | | `eqs_debug_query` | 运行完整的调试可视化 | | `eqs_set_run_mode` | 设置 SingleBestItem/RandomBestItem/AllMatching | | `eqs_build_cover_query` | 构建覆盖查找查询预设 | | `eqs_build_flank_query` | 构建侧翼位置查询预设 | | `eqs_build_patrol_query` | 构建巡逻点查询预设 | | `eqs_build_retreat_query` | 构建撤退/逃生位置查询预设 | | `eqs_get_info` | 读取 EQS 查询结构 | | `eqs_list` | 列出路径中的所有 EQS 资产 | | `eqs_delete` | 删除 EQS 资产 | | `eqs_duplicate` | 复制 EQS 资产 | ### 🗺️ 导航网格工具（17） | 工具 | 描述 | |------|-------------| | `nav_place_volume` | 放置 NavMeshBoundsVolume | | `nav_set_agent` | 配置代理（半径、高度、步高） | | `nav_rebuild` | 触发完整导航网格重建 | | `nav_test_path` | 测试两点之间是否存在路径 | | `nav_get_path` | 获取从 A 到 B 的路径点 | | `nav_create_area` | 创建自定义 NavArea 类 | | `nav_set_area_cost` | 在 NavArea 上设置遍历成本 | | `nav_place_modifier` | 放置具有区域类的 NavModifierVolume | | `nav_create_link` | 创建 NavLinkProxy（跳跃/梯子/门） | | `nav_set_link_endpoints` | 设置链接起点和终点以及方向 | | `nav_add_smart_link` | 添加具有自定义逻辑的 SmartNavLink | | `nav_place_invoker` | 放置具有调用者的 NavMeshBoundsVolume | | `nav_get_stats` | 获取导航网格图块计数和覆盖率统计 | | `nav_get_poly_at` | 获取世界位置处的导航网格多边形 | | `nav_find_nearest` | 找到最近的导航网格点 | | `nav_diagnostics` | 完整的导航网格诊断报告 | | `nav_list` | 列出路径中的所有导航资产 | 💥 物理混乱工具（25） | 工具 | 描述------|-------------| | `chaos_create_gc` | 从网格创建几何体集合 | | `chaos_fracture_voronoi` | 沃罗诺伊骨折，单元格数量可控 | | `chaos_fracture_uniform` | 均匀网格 `chaos_fracture_radial` | 从的径向骨折 | chaos_fracture 簇状骨折层） | | `chaos_set_damage_threshold` |级损伤阈值chaos_set_mass 设置质量和密度 | | `chaos_set_collision`碰撞配置文件 | | `cha_anchor_field` | 添加锚点场（静态基 | | `chaosrain_field` | 添加应变场（内部强度） | | `chaos_create_cloth` | 创建混乱布料组件 | | `chaos_set_cloth_params` | 设置布、阻尼、风力 | | `chaos_set_cloth_collision` | 添加布料自碰撞和世界碰撞 | chaos_create_rb` | 创建刚体模拟 | | `chaos_place_radial_force` | 放置径向力演员 | | `chaos_set_radial_params` | 设置力强度、半径、衰减 `chaos_apply_impulse` | 对模拟演员施加冲量 | | `chaos_apply_force` | 施加 | | `chaos_create_constraint` | 创建物理约束关节 | | `chaos_set_constraint_limits` | 设置角度/线性限制 | | `chaos_simulate_mesh` | 在静态网格上启用物理模拟 | | `chaos_set_break_event` | 设置断裂蓝图事件 | | `chaos_get | 读取几何体集合结构 | | `chaos_list` | 列出路径中的所有混乱资产 | | `chaos_diagnostics` | 混乱模拟诊断报告 | ### 🌿 程序化内容生成工具（21） | 工具 | 描述------|-------------| | `_create_graph` | 创建资产 | | `pcg_add_surface_sampler` | 添加表面点采样器 | | `pcg_add_mesh_sampler` | 添加网格表面采样器 | | `pcg_add_volume_sampler` | 添加体积点采样器 | | `pcg_add_static_mesh_spawner` | 添加静态网格生成节点 | | `pcg_add_actor_spawner` | 添加演员生成节点 | | `pcg_set_density` | 设置点密度 | | `pcg_set_scale` | 设置最小/最大缩放范围 | | `pcg_add_filter` |/标签/边界过滤| `pcg_add_transform` | 添加变换节点（抖动） | | `pcg_add_attribute_noise 为点添加属性噪声 | | `pcg_add_slope_filter` | 按坡度角度过滤点 | | `pcg_add_biome_filter` | 按绘制的景观层过滤 | | `pcg_connect 连接PCG图表节点pcg_place_volume 在关卡中放置体积 | | `pcg_assign_graph` | 将图表分配给体积 | pcg_generate` |G生成 | |g_clear` | 清PCG输出 | |g_get_info` | 读取PCG图表结构 | | `pcg_list` |路径中的所有PCG图表 | | `pcg` | PCG生成 | ### 🎮 增强（18） | 工具 | 描述 | -------------| | `input` | 创建输入动作| `input_set_action_type` | 设置值类型尔/轴1D2D/轴3D） | | `input_add_trigger` | 添加触发器释放/保持//脉冲） | input_add_modifier` | 添加修改器（死区/否定/交换/缩放） | | `input_create_imc` | 创建输入映射上下文 | | `input_add_mapping` | 在IMC中添加按键绑定 | | `input_set_mapping_modifiers` | 在特定映射上设置修改器 | | `input_set_mapping_triggers` | 在特定映射上设置 | | `input_assign` | 将IM玩家控制器/角色 `input_build_fps | 构建完整FPS设 | | `ps_preset` |完整TPS输入预设 | input_build_topdown_preset` | 构建俯瞰式输入预设 | | `input_build_vehicle_preset` | 构建车辆输入 | | `input_wire_to_bp` | 将输入蓝图事件 | |_get_info` | 读取输入动作/IMC结构 `input_list` | 列出路径中的所有输入资产input_delete` | 删除输入资产 | | `iagnostics` | 输入绑定诊断报告 | ### 🔊 元声音工具（17） | 工具 | 描述 | |------|-------------| | `ms_create_source` | 创建元声音源资产 | | `ms_create 创建元声音补 | | `ms_add | 添加输入引脚（触发器/浮点数/整数/布尔值/波形） | | `_output` | 添加输出引脚 | | `_node` | 添加节点（振荡器/过滤器/包络/延迟...） | | `ms_connect` | 连接元声音节点 | | `ms_set_param` | 设置参数默认值 | | `ms_add_random_select` | 添加随机波形选择节点 | | `ms_add_pitch_shift` | 添加音高偏移节点 | | `ms_add_envelope` | 添加ADSR包络 | | `ms_create_attenuation` | 创建声音衰减资产 | | `ms_set_attenuation` | 配置衰减形状、衰减、内/外半径 | | `ms_create_class` | 创建声音类（混音总线） | | `ms_create_mix` | 创建声音混音预设 | | `ms_assign_to_component` | 将元声音分配给演员的音频组件 | | `ms_get | 读取元声音图表结构 | | `ms_list` | 列出路径中的所有元声音资产 | ### 🔌 管道工具（8） | 工具 | 描述 | |------|-------------| | `tripo_generate` | 通过Tripo API将文本转换为3D模型 | | `tripo_generate_from_image` | 通过Tripo API将图像转换为模型 | | `tripo_import` | 将生成的.glb导入UE | | `huanyuan_generate` | 通过Huanyuan3D API将图像转换为3D模型 | | `metatailor_rig` | 使用MetaTailor自动绑定.fbx | | `metatailor_clothe 为绑定角色添加服装 | | `ueos_status` | 完整连接健康检查 | | `ueos_diagnose` | 原始到UE远程控制 | ### 🔍 诊断工具） | 工具 | 描述 | |------|------------- `ueos_status 所有服务的连接健康状况 | | `ueos_diagnose` | 原始HTTP探测到UE端口30010 | | `ueos_run | 在UE编辑器中执行任意Python代码 | 💬 示例提示 /Game/Characters使用SkeletalMeshComponent和Camera创建一个角色蓝图BP_Sold编译它。" "/Materials路径下_Rock_D作为基础颜色，T_Rock_N作为法线贴图，粗糙度0.85度0.0PBR材质M_RockWall。" "在路径下创建一个数据表DT_Weapons，结构体为Data，字段包括：名称（字符串）、伤害（浮点数）、射速（浮点数）、弹药（整数）。添加行：手枪（25,2.5,12），步15,8.0,30），霰弹枪（80,0.8,8）" "在FX路径下生成粒子系统NS_Bon具有大强度，并和余" "完整流程概念艺术URL → 使用生成3D模型 → 使用MetaTailor绑定 → 在/Game/Characters路径下蓝图BP_H 编译" "为/Game/Characters/SK_Hkeleton路径下的骨骼动画创建一个动画蓝图ero。添加浮点数）、alling（布尔值）、IsAiming（布）变量。构建一个/Walk/ump/Fall/Land运动状态机。/Game/Characters/BP_Hero路径下的角色设置完整的GAS栈：添加一个能力系统组件（），创建一个AS_HeroBase属性集，包含Health/MaxHealth/Mana/Stamina，创建一个GA_FireBolt和GA_Shield能力，创建一个GE_FireDamage（-30瞬间）和GE_ShieldBuff（+50护甲，持续10秒）。" "创建一个可破坏的墙壁：将/Game/Meshes路径下的SM_BrickWall转换为/Game/Chaos几何体集合。沃罗诺伊骨折，30个单元格0级损伤阈。" "在/Game/PCG路径下设置一个森林生物群落图表。使用SM_OSM_Pine网格。表面采样器密度3.0，缩放0.8.2。在世界处放置一个5000×5000的PCG立即生成。" /Game/Input路径下的第三人称角色创建一个完整的增强输入设置。生成IA_M轴2D）、ook（轴2IA_Jump（布尔值）、IA_Sprint值）。创建IMC_Default，绑定W+鼠标+游戏手柄。" ``` --- ## 文件结构 ``` ueos/ ├── .env ← 运行配置（从不├── .env.example 模板 ├── .gitignore ├── requirements.txt ├── README.md ├── UEOS_SYSTEM_PROMPT.md 74KB行为系统提示 ├── UEOS.bat ← 每日启动器（第一次设置后双击） UP.bat ← 首次设置（双击├── FIX_CLA.bat ← 重写claude_desktop_config.json ├── INSTALL_BRIDGE.ps ← PowerShell桥安装程序 ├── ui/ launcher.py ← 5选项卡tk ├── mcp_server/ │ ├── server.py MCP入口点（339个工具） │ .log ← 运行日志（自动创建） remote_control/ │ │ └── client.py ← UE 5.4 HTTP客户端，带重试 ├── api_clients/ │ │ ├── │ │ ├── huanyuan│ │ └── metatailor.py tools/ │ blueprint.py ← 工具 │ ← 工具 │ ├── niagara.py ←个工具 │ inspection.py ←个工具 │ scene.py ←工具 │ ├── data.py ← 工具 │ ├── animation.py ← 工具 第三阶段 │ ├── umg ← 20个工具 第四阶段 │ sequencer.py ← 18个工具 第四阶段 │ ├── behavior_tree.py ← 17个工具 第四阶段 │ ├── editor_widget.py ← 20个工具 第五阶段 │ ├── gameplay_ability.py ← 20个工具六阶段 │ environment_query.py ← 20个工具 第六阶段 │ ├── navmesh.py ← 17个工具 第六阶段 │ ├── chaos_physics.py ← 25个工具 第七阶段 ├── pcg.py ← 21个工具 第七阶段 │ ├── enhanced_input.py 18个工具 第七阶段 │ metasound.py ← 17个工具 第七阶段 ├── ue_scripts/ ← 在UE内运行 │ os_utils.py │ ├── animation_utils│ ├── umg_utils.py │ ├──_utils.py │ ├── editor_widget_utils│ ├── gas_utils.py │ ├── eqs_utils.py │ navmesh_utils.py │ ├── chaos_utils.py │ ├── pcg_utils.py │ _utils.py │ └── metasound_utils.py setup/ │ ├── install.py ← pip安装 + 向导启动器 │ ├── configure.py ← 交互式API密钥向导 │ _claude_config.py写入claude_desktop_config.json │ └── inject_ue_settings.py ← 自动修补UE └── config/ └── claude_desktop_config.json ← 不是实时配置） ``` --- ## 📈 | 阶段 | 状态 | 已添加工具数 | |-------|--------|-------------|-------| | 第一阶段 | ✅ | 蓝图（17），管道+3），GUI | 28 | | 第二 ✅ | 材质（14），Niagara（检查（12），场景（16），数据（ | 105 | 阶段 | ✅ | 动画（22）127 | | 第四阶段 | ✅ | UMG（20），Sequencer（18），行为树（17） | 182 | |阶段 | ✅ | 编辑器实用小工具（20） | 202 | | 第六阶段 | ✅ | GAS（20），EQS（20），导航网格（17） | 259 | | 第七阶段 | ✅ | 混乱物理（25），PCG（21），增强输入（18），元声音） | | *最近更新：第七阶段完成 — 339个工具*