Use unrealhub

UseUnrealHub — Agent 驱动 UE 开发综合技能

维护规约：本文件随 UnrealMCPHub 仓库发布。对 Hub 的任何功能变更（新工具、参数修改、行为变化） 都必须同步更新本文件。同步检查清单见 skills/unrealhub-developer/SKILL.md。

---

Part 1: 核心工作流

1.1 决策流程

每次涉及 UE 操作前，按此流程决策：

项目已配置? ──No──> setup_project(uproject_path="...")
      │Yes
      ▼
编辑器在线? ──No──> 需要编译? ─Yes─> launch_editor()   # launch_editor 会先编译再启动
      │Yes              │No
      │                 ▼
      │            launch_editor()
      ▼
正常使用 UE 工具
      │
遇到崩溃? ──Yes──> get_log(source="crash") → launch_editor(action="restart")
      │No
      ▼
继续工作

1.2 工具速查表

类别	工具	关键参数	用途
项目	setup_project	uproject_path, install_plugin	一站式项目配置
	get_project_config	—	查看配置
	hub_status	—	Hub 全局状态
编译	build_project	action, target, configuration	UBT 编译/打包
启动	launch_editor	action, exec_cmds, build_config	编辑器生命周期；start/restart 会先编译再启动（build_config: Development/DebugGame/Debug）
	get_editor_status	—	进程状态
实例	discover_instances	rescan	发现 Unreal MCP 实例（两阶段端口扫描 + serverInfo 验证 + MCP 自识别 + 自动注册 + 孤儿进程扫描）
	manage_instance	action, instance, url, port	注册/注销/切换实例（instance 支持 key/port/项目名）
监控	get_instance_health	instance	健康检查
	get_log	source, tail_lines	日志读取
代理	ue_status	—	UE 实例状态
	ue_list_domains	—	列出所有 domain 及描述
	ue_list_tools	domain	列出 UE 工具（含参数 schema）
	ue_call	tool_name, arguments, domain	调用 UE 工具
	ue_run_python	script	执行 Python 脚本
会话	add_note	content	添加笔记
	get_session	scope, format	查看会话
帮助	help	topic	获取使用指南（按 topic 分段：compile, launch, pie, slate, umg, full 等）

1.3 Domain 工具

UE 端工具按领域（domain）分组。Domain 列表随 UE 插件扩展而动态增长，不要假设固定的 domain 集合。 已知 domain 仅供参考：level, blueprint, umg, edgraph, behaviortree, slate —— 实际可用 domain 以运行时查询结果为准。

# ⚠ 每次会话开始或不确定时，先动态发现可用 domain
ue_list_domains()                                     # 列出所有 domain 及描述
ue_list_tools(domain="level")                         # 查看某个 domain 下的工具和参数
ue_call("spawn_actor", {...}, domain="level")          # 调用域工具

关键原则：永远通过 ue_list_domains() 动态发现，不要硬编码 domain 名称。 新的 domain 可能在 UE 插件更新、用户安装扩展模块后出现。

1.4 实例管理

唯一标识：(project_name, port) 复合键

每个实例由 项目名:端口 唯一标识，例如 Develop57:8422。同一项目同一端口重启 = 同一实例（自动更新 PID/状态）。

port=0 是特殊值，表示"UE 进程在运行但未启用 MCP"。当该进程后续启用 MCP 并被发现时，ProjectName:0 会自动升级为 ProjectName:8422。

实例状态

仅两态：online / offline。没有中间态。

discover_instances(rescan=True) 流程

Phase 1: 扫描优先端口 [8422, 8423, 8424, 8425]（<1 秒）
Phase 2: 若 Phase 1 未发现任何实例 → 扩展扫描 8000-8999（3-5 秒）
Phase 3: 标记未响应端口的在线实例为 offline
Phase 4: 对每个响应端口执行 identify + upsert
Phase 5: psutil 扫描所有 UE 进程，未被注册的以 port=0 status=offline 纳入管理

对每个响应端口（Phase 4）:
  1. probe_unreal_mcp: 验证 serverInfo.name 包含 "Unreal"（排除非 UE 的 MCP）
  2. _identify_instance: 通过 MCP call_tool("get_unreal_state") 获取项目路径
     （fallback: psutil 查端口归属进程）
  3. state.upsert: 自动注册或更新实例

对未启用 MCP 的 UE 进程（Phase 5）:
  1. psutil 枚举所有 UnrealEditor 进程
  2. 过滤掉已通过 PID 或 project_path 关联的进程
  3. state.upsert(port=0, status="offline"): 注册为不可联通
  4. 后续该进程启用 MCP 后，discover 会自动升级 ProjectName:0 → ProjectName:{port}

行为要点：

• 任何运行中的 Unreal MCP 实例都会被自动发现并注册，无论是 Hub 启动的还是手动启动的
• 没有启用 MCP 的 UE 编辑器也会被发现，标记为 [NO MCP] offline 状态
• 通过 MCP 协议直接问实例"你是谁"（get_unreal_state），获取准确项目路径
• 复合键天然去重：同项目同端口不会产生重复条目
• 离线超过 1 小时的实例自动清理
• ProcessWatcher 后台每 5 秒健康检查在线实例

实例切换

实例可通过完整 key、端口号或项目名查找：

manage_instance(action="use", instance="Develop57:8422")  // 完整 key
manage_instance(action="use", instance="8422")             // 按端口
manage_instance(action="use", instance="Develop57")        // 按项目名

崩溃后：编辑器崩溃重启后，upsert 自动更新同 key 的实例，活跃实例通常自动指向正确实例。

---

Part 2: 编译策略

2.1 Live Coding vs 外部编译

方式	工具	前提	适用场景
Live Coding	ue_call("livecoding_compile_and_get_ubt_log")	编辑器运行中	增量 C++ 修改
外部 UBT	build_project()	编辑器必须关闭	全量编译、Live Coding 失败时

决策路径：

1. 优先 Live Coding（快速、不中断工作流）
2. Live Coding 失败且不是代码错误 → 关闭编辑器 → 重新 launch_editor()（会先编译再启动）

2.1.1 编译流式进度

build_project() 和 launch_editor() 会通过 MCP progress notification 实时推送编译进度：

• Progress：解析 UBT 输出中的 [x/y] 标记，通过 report_progress(current, total, line) 推送进度与日志文本
• Log：每一行非空输出都即时推送——[x/y] 编译行 → ctx.info，错误 → ctx.error，警告 → ctx.warning，其他 → ctx.info
• 最终返回值：仍包含完整的错误/警告摘要和输出尾部，不受流式影响

2.2 PCH 内存不足 (C3859 / C1076)

c1xx: error C3859: 未能创建 PCH 的虚拟内存
c1xx: fatal error C1076: 编译器限制: 达到内部堆限制

这不是代码错误。处理策略按优先级：

优先级 1：降低并行编译数（首选，最有效）

修改 %APPDATA%/Unreal Engine/UnrealBuildTool/BuildConfiguration.xml：

<?xml version="1.0" encoding="utf-8" ?>
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
    <BuildConfiguration>
        <MaxParallelActions>6</MaxParallelActions>
    </BuildConfiguration>
</Configuration>

关键：编译完成后必须恢复原值（清空文件内容），避免影响用户正常使用。

优先级 2：要求用户释放内存

如果降低并行度后仍失败，告知用户关闭其他大型程序。不要自行反复重试。

优先级 3：释放编辑器内存

import gc, unreal
gc.collect()
unreal.SystemLibrary.collect_garbage()

禁止行为

• 禁止在内存不足时反复重建场景
• 禁止无意义地循环重试编译（>3 次相同失败就要换策略）

2.3 UBA 缓存

Unreal Build Accelerator 缓存成功的 .obj。即使部分文件因内存失败，下次重试会自动跳过已缓存的文件。降低并行度后重试通常极快。

---

Part 3: 编辑器启动与弹窗处理

3.1 常见阻塞弹窗

弹窗	触发条件	处理方式
Shader Compilation 进度条	首次打开/引擎变更	等待，不可跳过
"Saved with older version"	切换引擎版本	Slate 确认
Source Control 提示	版控配置异常	Slate 关闭
New Plugin 面板	插件首次安装	slate_close_dock_tab
Unable to Check Out	版控检出失败	Slate 点击 Ok

3.2 处理方法

方法 A：静默启动参数（推荐）

launch_editor(exec_cmds="-nosplash -unattended -nopause")

参数	效果
-nosplash	跳过启动画面
-unattended	无人值守，自动确认部分弹窗
-nopause	不暂停等待用户

方法 B：Slate 工具关闭

ue_call("slate_send_key_press", {"key": "Enter"}, domain="slate")        // 确认对话框
ue_call("slate_close_dock_tab", {"tab_label": "Plugins"}, domain="slate") // 关闭 Tab
ue_call("slate_safe_close", {"tab_label": "Plugins"}, domain="slate")    // 安全关闭（优先 Tab，必要时关窗口）
ue_call("slate_get_all_dock_tabs", {}, domain="slate")                    // 先查看已打开的 Tab 列表

注意：所有 Slate 工具都在 slate domain 中，调用时必须指定 domain="slate"。

方法 C：弹窗阻塞 MCP 连接时

MCP 在编辑器初始化后才启动。如果弹窗阻塞导致 launch_editor() 超时：

1. 通知用户手动关闭弹窗
2. 或 launch_editor(action="stop") → 加静默参数重新启动

---

Part 4: PIE 测试

4.1 启动与停止

les = unreal.get_editor_subsystem(unreal.LevelEditorSubsystem)
les.editor_request_begin_play()   # 异步启动
import time; time.sleep(3)        # 等待初始化
les.is_in_play_in_editor()        # 检查状态
les.editor_request_end_play()     # 停止

4.2 PIE 世界查询（重要）

编辑器 Python 脚本无法直接访问 PIE 世界：

# ❌ PIE 期间全部返回 None
unreal.EditorLevelLibrary.get_editor_world()
les.get_world()
unreal.GameplayStatics.get_player_pawn(None, 0)

正确做法：使用控制台命令 getall

ue_call("run_console_command", {"command": "getall ArenaMonster Name"})
ue_call("run_console_command", {"command": "getall ArenaMonster MonsterType MaxHP MoveSpeed"})
ue_call("run_console_command", {"command": "getall ArenaPlayerCharacter Name"})

getall ClassName PropertyName 枚举 PIE 世界中所有实例及属性，结果输出到日志。

4.3 GameMode 配置

通过 Python 设置关卡的 GameMode Override：

world = unreal.EditorLevelLibrary.get_editor_world()
ws = world.get_world_settings()
gm_class = unreal.load_class(None, '/Script/ProjectName.MyGameMode')
ws.set_editor_property('default_game_mode', gm_class)
unreal.EditorLevelLibrary.save_current_level()

---

Part 5: AI 寻路与 NavMesh

5.1 完整流程

1. Build.cs 添加 "NavigationSystem" 依赖
2. 放置 NavMeshBoundsVolume（Python）
3. 构建 NavMesh（控制台命令）
4. 验证构建成功（检查日志）

5.2 代码

# 放置 NavMeshBoundsVolume
nav_class = unreal.load_class(None, '/Script/NavigationSystem.NavMeshBoundsVolume')
nav = unreal.EditorLevelLibrary.spawn_actor_from_class(nav_class, unreal.Vector(0, 0, 200))
nav.set_actor_scale3d(unreal.Vector(100, 100, 10))

# 构建 NavMesh
unreal.SystemLibrary.execute_console_command(
    unreal.EditorLevelLibrary.get_editor_world(), 'RebuildNavigation')

5.3 验证

日志中应出现：

• ✅ UNavigationSystemV1::Build started...
• ✅ Build total execution time
• ❌ Unable to find RecastNavMesh instance → NavMeshBoundsVolume 配置有误

---

Part 6: 关卡构建

6.1 程序化关卡搭建模式

import unreal
el = unreal.EditorLevelLibrary
cube = unreal.EditorAssetLibrary.load_asset('/Engine/BasicShapes/Cube')
plane = unreal.EditorAssetLibrary.load_asset('/Engine/BasicShapes/Plane')
cyl = unreal.EditorAssetLibrary.load_asset('/Engine/BasicShapes/Cylinder')

def spawn_mesh(asset, x, y, z, sx, sy, sz, label=''):
    a = el.spawn_actor_from_class(unreal.StaticMeshActor, unreal.Vector(x, y, z))
    if a:
        a.static_mesh_component.set_static_mesh(asset)
        a.set_actor_scale3d(unreal.Vector(sx, sy, sz))
        if label: a.set_actor_label(label)
    return a

6.2 关卡要素清单

要素	典型实现
地面	Plane 缩放 80×80
围墙	Cube 围成八边形
掩体	L 形 Cube 组合
柱子	Cylinder 散布
高台	Cube 加厚抬高
灯光	DirectionalLight + SkyLight + PointLight×N
玩家出生	PlayerStart

---

Part 7: 行为准则

1. 配置优先：任何 UE 操作前确认 get_project_config() 有配置
2. 代理优先：ue_run_python > ue_call > ue_list_tools 按频率排序
3. 崩溃韧性：离线/崩溃时不放弃，按流程恢复
4. 内存意识：编译失败时先诊断是内存还是代码问题
5. 弹窗预防：启动时加 -unattended 参数
6. PIE 查询：用 run_console_command + getall，不用 Python world context
7. NavMesh 前置：有 AI 寻路需求时先配 NavMesh
8. 保持笔记：add_note 记录关键决策，崩溃后 get_session 恢复
9. 质量导向：代码架构清晰、数值可配置、核心循环闭合
10. 编译后恢复：修改 BuildConfiguration.xml 后必须恢复原值
11. Domain 动态发现：不要假设固定的 domain 列表，每次会话用 ue_list_domains() 发现当前可用 domain
12. Widget Tree 优先：查找 UI 元素时优先用 slate_find_widgets_by_type 或 slate_get_all_text_blocks，而非盲目点击坐标
13. UMG 路径约束：UMG 工具的 C++ 后端硬编码资产路径为 /Game/Widgets/，Python path 参数当前被忽略
14. 崩溃后实例自动复用：编辑器崩溃重启后，upsert 自动更新同 (project_name:port) 的实例，通常无需手动切换。可用 manage_instance(action="use", instance="端口号或项目名") 手动切换

---

Part 8: Slate UI 操控

Slate 工具在 slate domain 中，共 22 个，所有调用需指定 domain="slate"。

8.1 工具速查

分类	工具	关键参数	用途
查询	slate_get_all_windows	—	列出所有顶层窗口（索引、标题、位置、大小）
	slate_get_widget_tree	window_index, max_depth(1-12)	获取窗口 Widget 树（嵌套 JSON）
	slate_get_widget_under_cursor	—	鼠标下的 Widget 路径和几何信息
	slate_get_widget_at_position	x, y	指定坐标处的 Widget 路径
	slate_find_widgets_by_type	type_name, max_depth	按类型名搜索（SButton, STextBlock 等）
	slate_get_all_text_blocks	window_index	快速获取所有非空文本
	slate_get_editor_ui_summary	—	UI 全貌摘要（窗口列表 + 激活窗口）
	slate_get_active_window	—	当前激活窗口信息
	slate_get_focused_widget	—	键盘焦点 Widget
	slate_get_all_dock_tabs	—	所有打开的 DockTab 列表
窗口	slate_move_window	x, y, window_index	移动窗口
	slate_resize_window	width, height	调整窗口大小
	slate_close_window	window_index/title	关闭窗口
	slate_close_dock_tab	tab_label/tab_id	关闭 DockTab
	slate_safe_close	tab_label, window_title	安全关闭（优先 Tab）
焦点	slate_set_keyboard_focus	x, y	将焦点设到指定坐标 Widget
Tab	slate_invoke_tab	tab_id	打开/切换编辑器面板
交互	slate_click_at_position	x, y, button	模拟鼠标点击
	slate_send_text_input	text	向焦点控件输入文本
	slate_send_key_press	key, shift, ctrl, alt	发送键盘按键
	slate_scroll_at_position	x, y, delta	模拟滚轮滚动
通知	slate_show_notification	message, type, duration	编辑器右下角通知

8.2 Widget Tree 查询流程

1. ue_call("slate_get_all_windows", {}, domain="slate")
   → 获取窗口列表，记录目标 window_index

2. ue_call("slate_get_widget_tree", {"window_index": 0, "max_depth": 5}, domain="slate")
   → 获取嵌套 Widget 树，每节点含 type/tag/visibility/children

3. ue_call("slate_find_widgets_by_type", {"type_name": "SButton"}, domain="slate")
   → 按类型搜索，返回匹配 Widget 列表（含 depth/in_window）

4. ue_call("slate_get_all_text_blocks", {}, domain="slate")
   → 快速收集所有 STextBlock 文本（非空）

8.3 坐标定位与交互

通过 Widget Tree 的 geometry 信息获取坐标，再用交互工具操作：

# 查找目标 Widget 位置
ue_call("slate_get_widget_at_position", {"x": 500, "y": 300}, domain="slate")

# 点击
ue_call("slate_click_at_position", {"x": 500, "y": 300}, domain="slate")

# 聚焦 + 输入文本
ue_call("slate_set_keyboard_focus", {"x": 500, "y": 300}, domain="slate")
ue_call("slate_send_text_input", {"text": "Hello"}, domain="slate")

# 发送按键
ue_call("slate_send_key_press", {"key": "Enter"}, domain="slate")

8.4 常用 Tab ID

Tab ID	面板
OutputLog	输出日志
ContentBrowser1	内容浏览器
LevelEditor	关卡编辑器视口
WorldOutliner	世界大纲
DetailsView	详情面板
MessageLog	消息日志
Sequencer	序列器

ue_call("slate_invoke_tab", {"tab_id": "OutputLog"}, domain="slate")

---

Part 9: UMG Widget 创建

UMG 工具在 umg domain 中，用于程序化创建 Widget Blueprint 并添加 UI 控件。

9.1 工具速查

工具	关键参数	用途
create_umg_widget_blueprint	widget_name	创建 Widget Blueprint
add_text_block_to_widget	widget_name(蓝图名), text_block_name, text, position	添加文本块
add_button_to_widget	widget_name(蓝图名), button_name, text, position	添加按钮
bind_widget_event	widget_name(蓝图名), widget_component_name, event_name	绑定事件
add_widget_to_viewport	widget_name(蓝图名), z_order	添加到视口
set_text_block_binding	widget_name(蓝图名), text_block_name, binding_property	设置属性绑定

9.2 创建流程

1. ue_call("create_umg_widget_blueprint", {"widget_name": "MyHUD"}, domain="umg")
2. ue_call("add_text_block_to_widget", {"widget_name": "MyHUD", "text_block_name": "Title", "text": "Score: 0", "position": [100, 50]}, domain="umg")
3. ue_call("add_button_to_widget", {"widget_name": "MyHUD", "button_name": "StartBtn", "text": "Start", "position": [100, 150]}, domain="umg")
4. ue_call("bind_widget_event", {"widget_name": "MyHUD", "widget_component_name": "StartBtn", "event_name": "OnClicked"}, domain="umg")
5. ue_call("add_widget_to_viewport", {"widget_name": "MyHUD"}, domain="umg")

9.3 已知问题

C++ 后端 Bug（截至 2026-03-07）：

• create_umg_widget_blueprint C++ 层使用 UBlueprint::StaticClass() 而非 UWidgetBlueprint::StaticClass()，导致 Cast 失败，Widget Blueprint 无法正确创建
• 创建的蓝图缺少 CanvasPanel 根节点，后续添加控件会报 "Root Canvas Panel not found"
• 临时绕过方案：用 ue_run_python 通过 WidgetBlueprintFactory 创建

import unreal
factory = unreal.WidgetBlueprintFactory()
factory.set_editor_property('parent_class', unreal.UserWidget)
asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
wb = asset_tools.create_asset('MyHUD', '/Game/Widgets', None, factory)

注意：即使通过 Python 创建，WidgetBlueprintFactory 可能不自动添加 CanvasPanel 根节点， 导致后续 add_text_block_to_widget 仍会失败。此问题需要在 RemoteMCP C++ 层修复。

9.4 路径约束

C++ 后端硬编码资产保存路径为 /Game/Widgets/，Python 层的 path 参数当前被忽略。 所有 UMG 资产统一创建在 /Game/Widgets/<widget_name> 下。