{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Unreal Mcp

自动化 Unreal Engine 编辑器场景、Actor 和渲染。

Skill 元数据

参考：完整 SKILL.md

Unreal Engine MCP Skill

Hermes MCP 目录里 unreal-engine 条目的配套 skill。MCP 服务器 （Epic 官方、实验性的 "Unreal MCP" 插件，内部 id ModelContextProtocol） 跑在 Unreal Editor 进程内部，把编辑器功能暴露为带类型的工具。 本 skill 教你如何用好它：发现实时工具表面、安全地排序调用、把 大白话需求翻译成真正好看的场景，并做视觉验证。用户除了启动编辑器 外永远不需要碰它。

何时使用

当用户想在 Unreal Engine 里做任何事时用：搭建或装饰关卡、生成/移动/删除 Actor、设置灯光和氛围、创建或调材质实例、框定一个镜头、抓截图或渲染、 导入资产、检视场景或 UI、跑自动化测试、或脚本化编辑器。 单个动作（"make the sun golden hour"）和完整多步项目 （"build me a moody forest clearing with a campfire and render a shot of it"）都行。

不要用于：DCC 式网格建模/雕刻（在 Blender 建模并导入结果）， 或编辑 Unreal C++ 项目源码（那是正常代码活——用终端；本 skill 管的是活编辑器）。

前置条件

两半，按此顺序：编辑器端必须先起来，Hermes 再连。

一次性，编辑器端

1. Unreal Editor 5.8+，且有项目打开。（macOS：必须装完整 Xcode 并接受其 许可——没有它编辑器首启就退出；见 pitfalls。）
2. Edit > Plugins——启用 Unreal MCP（其 Toolset Registry 依赖自动启用）。提示时重启编辑器。
3. 带类型的 toolset 与服务器分开发布：在同一 Plugins 浏览器里再启用 AllToolsets 插件。Unreal MCP 自己不发任何工具—— AllToolsets 提供发布的 toolset（SceneTools、ActorTools、 MaterialInstanceTools、ObjectTools……）；跳过它，服务器能连但 agent 没东西可调。
4. Edit > Editor Preferences > General > Model Context Protocol—— 启用 Auto Start Server。默认绑定 http://127.0.0.1:8000/mcp （端口/路径在同面板可配；服务器名 unreal-mcp）。要手动启动，在 编辑器控制台（反引号键）跑 ModelContextProtocol.StartServer。

一次性，Hermes 端

hermes mcp install unreal-engine

这会写 mcp_servers.unreal-engine HTTP 条目，指向 http://127.0.0.1:8000/mcp，并探活实时服务器的工具。在编辑器 + 服务器 起来时跑它，让探测看到真实表面。若用户在 Editor Preferences 改了端口/路径， 编辑 ~/.hermes/config.yaml 里 mcp_servers.unreal-engine 下的 url 对齐。

不要为 Hermes 用 ModelContextProtocol.GenerateClientConfig—— 那写 .mcp.json 风格文件给 Claude Code/Cursor 等。Hermes 从 config.yaml 经目录条目连接。

每次会话

1. 启动 Unreal Editor，等项目加载完；确认服务器起来了 （Output Log 显示绑定地址，或手动跑 ModelContextProtocol.StartServer）。
2. 启动 Hermes 会话。工具注册为 mcp_unreal_engine_*。若缺失： 编辑器没先起——先起它，再开新 Hermes 会话。
3. 健全检查：调 mcp_unreal_engine_list_toolsets，确认 toolset 回来了。

工具表面：发现式，非固定清单

默认插件跑在工具搜索模式：tools/list 只返回三个元工具，每个真工具 都经它们到达。经 Hermes 它们表现为：

发现走查，永远按此顺序：

1. list_toolsets → 看这个项目实际有哪些能力组 （表面依赖项目：启用的插件、Game Feature Plugins、任何自定义 toolset 都贡献）。 名字以全限定返回（editor_toolset.toolsets.scene.SceneTools、 EditorToolset.EditorAppToolset）——原样用作 toolset_name。
2. 对需要的组 describe_toolset → 读真实参数 schema。绝不猜参数名—— schema 是契约。
3. call_tool，带全限定 toolset 名、短工具名 （find_actors，不是点号形式）和匹配 schema 的参数。

会话内缓存你学到的；仅在编辑器端变化后重列（启用新插件、写了 toolset、跑了 RefreshTools）。

另一种 eager 模式（Editor Preferences 里 Enable Tool Search 关）把每个工具 广告为自己的 mcp_unreal_engine_<tool> 条目。发现则在 hermes mcp install/configure 时发生。工具搜索模式是默认、也是本 skill 假设的；它还让 schema token 不进入每次 API 调用，故优先。

发布的 toolset 目录、编写自定义 toolset、完整插件配置/控制台命令参考见 references/tool-surface.md。

操作循环

每个 Unreal 任务走同一循环：

1. 先检视。 列 toolset，然后在碰任何东西前查场景/关卡状态。 绝不假设空关卡或默认关卡。在不熟的项目里，也查项目注册的 Agent Skills （call_tool → AgentSkillToolset.ListSkills）：匹配的项目 skill 指令 覆盖本 skill 的通用默认。
2. 小而单一目的的调用。 每个 call_tool 一个逻辑步。服务器 在游戏线程串行执行工具——一个大而全的操作会冻结编辑器 UI 直到完成，并可能客户端超时。例外：对 5+ 个同质操作的循环， 一次 ProgrammaticToolset.execute_tool_script 调用在服务端批量， 不破坏串行规则（references/advanced-workflows.md）。
3. 绝不发重叠调用。 不要在一回合里批多个 mcp_unreal_engine_* 调用——Hermes 并发跑批量调用，对着游戏线程的 并行调用会死锁或失败。严格一次一调用，等结果，再下一个。这覆盖 通用的并行工具调用指引。
4. 读每个结果。 许多工具（Blueprint 编译、材质编辑、widget 创建） 在响应体里报成功/失败，无协议层异常。任何不是明确成功的都是停下诊断， 不是耸肩。属性写后读回值——好几条写路径静默 no-op（见 pitfalls）。
5. 视觉和结构验证。 每个里程碑后，通过查询你改的 Actor/属性确认状态， 构图重要时抓一张视口截图（抓取选项见 references/tool-surface.md； vision_analyze 图像——你是艺术指导，你来判）。
6. 勤保存。 编辑器编辑在内存里，直到包/关卡保存；编辑器崩溃丢失自上次保存 的一切，且 MCP 编辑不可靠可 undo。任何批量变更前后都存，每个里程碑后也存。
7. 具体报告。 Actor 标签、资产路径（/Game/...）、抓取/渲染的文件位置。

工作时的世界规则：

• 单位是厘米；轴是Z-up、X 朝前；旋转是度 （Rotator：Roll 绕 X、Pitch 绕 Y、Yaw 绕 Z）。人眼高 ≈ 165 cm； 一扇门 ≈ 210×90 cm。完整表见 references/scene-craft.md。
• 内容路径用长包名：项目内容 /Game/Folder/Asset.Asset， 引擎原语 /Engine/BasicShapes/Cube.Cube。
• Actor label（你在 Outliner 看到的，可设、非唯一）不是 Actor name（内部、唯一）。优先按 label/class 查询解析 Actor，然后 持有工具返回的句柄。
• 优先物理合理的光照值（lux/candela/Kelvin）而非任意亮度数字——但先 读现有太阳强度学场景的校准约定；模板世界常按 intensity: 10 校准， 物理值会把它们打爆（references/scene-craft.md 有数字， references/pitfalls.md #12b 有校准规则）。

从大白话到场景

用户给意图，不给规格。构建前先翻译：

1. 抽 brief。 主体、情绪、时段、室内/室外、风格、交付物 （截图？渲染？可玩关卡？）。最多问一轮澄清问题，然后定——你是技术导演； 别把 Unreal 行话弹回给用户。
2. 规划构建顺序。 可行顺序：关卡/环境壳 → blocking（主要几何/网格就位） → 灯光 + 氛围 → 材质 → set dressing/细节 → 相机 → 抓取/渲染。 多步构建把计划发成 todo 列表。
3. 用上面循环构建，一次一个里程碑，每个里程碑截图。
4. 自我艺术指导。 每张截图对照 brief 比：剪影可读？光向/强度可信？ 地平线不在正中心？对人高参考比例正确？继续前修好。
5. 交付。 截图/渲染作为文件（MEDIA: 路径），外加关卡里有什么、 存哪的简短总结。

references/recipes.md 有完整做成的构建（室外日光场景、情绪室内、 黄金时段 cinematic + 渲染、资产导入与摆放），带确切调用序列和值。

参考文件

按需加载；全程记住 SKILL.md 级规则。

常见坑（要记牢——完整表见 references/pitfalls.md）

• 启动顺序重要。 编辑器 + 服务器先起，再 Hermes 会话。缺 mcp_unreal_engine_* 工具 = 顺序错。
• 一次一调用。 串行游戏线程；不批量、不重叠。
• 每次调用期间编辑器 UI 冻结。 这是设计（游戏线程执行）。长操作时警告用户； 保持调用小。
• 模态对话框阻塞一切。 一个打开（或撞上）模态编辑器对话框的工具调用 会停到有人关掉它。若调用无限挂起，告诉用户查编辑器里有没有对话框。
• 长操作超时。 Hermes 每调用默认 120 s；资产导入、大关卡保存、渲染 可能超过。渲染/导入重的会话把 ~/.hermes/config.yaml 里 mcp_servers.unreal-engine.timeout 调高。
• 过期工具 schema。 编写/热重载 toolset 或启用插件后，在编辑器控制台跑 ModelContextProtocol.RefreshTools 并重 list_toolsets。新 C++ UFUNCTION 需完整重启编辑器——Live Coding 不会让它们出现。
• 实验性插件。 API 和工具形状会在引擎版本间变；信 describe_toolset 多于记忆，包括本 skill 的示例。文档与实时 schema 不一致时，实时 schema 赢。
• 不要把服务器暴露到 localhost 之外。 设计上仅环回、无认证。 绝不建议绑更宽。
• 许可说明。 服务器启动时日志：经插件传给已连 LLM 服务的数据是 UE EULA（§6(e））下的 Licensed Technology——用户负责确保其 LLM 供应商 不在其上训练。用户问数据处理时把这点摆出来。

验证清单

•  会话开始 list_toolsets 返回 toolset（连接健康）
•  首次编辑前查过场景状态（绝不假设空）
•  每个里程碑后：重查改过的 Actor/属性，并对照 brief 复审截图
•  每个里程碑后及结束时保存关卡/脏包
•  交付物在磁盘上（截图/渲染路径已确认），并用绝对路径报告给用户
•  编辑器留在干净状态：无待处理模态、无未保存意外、用户被明确告知 创建/改了什么、在哪