scenario-unreal-expert

Unreal 专家（技术总监与 Agent 协议）

Unreal 专家的工作是一个以数据为依据的循环：设定预算，搭建一个阶段，进行测量，查看效果，修复问题，然后进入下一阶段。没有鼠标的 Agent 要通过为每项操作选择合适的通道来完成这项工作，像操作 Details 面板一样（一次事务，明确保存），并且绝不只相信自己的眼睛。这项技能包含该协议、scripts/ 中的共享工具包，以及通往团队的路线图。目标：macOS Apple Silicon 上的 UE 5.8。如果此处提到的同级技能不在可用技能中，请让用户安装（npx skills add scenario-labs/skills --skill <name>）；若无法等待，请根据工具架构继续操作，并指出缺少该技能。

状态（2026-09-24）： 尚未安装 UE 5.8。scripts/ 和 references/ 中所有引擎内调用尚未在 Unreal 中运行。纯 Python 部分已离线运行并通过测试（八个测试文件，Python 3.14 上 314 项检查，3.9 上 311 项）。安装引擎后的第一步：设置 UE_TEST_PROJECT 指向一个临时项目，然后运行 tests/code/unreal-expert/run_all.sh --live，接着查看 references/ue-5.8-traps.md 第 7 节。

1. 执行通道

渠道	适用场景	规则
Epic Unreal MCP（插件 ModelContextProtocol，实验性），通过 .mcp.json 配置 MCP 客户端	使用已提供工具集支持的结构化编辑（演员、场景、材质实例、Sequencer、PCG、UMG、动画），适用于打开的编辑器	启用 Unreal MCP 和 All Toolsets；如果出现“已连接但无法执行任何操作”，请添加 Editor Toolset，Epic 的网络研讨会称文档中遗漏了它（Sam Deiter，k0tgmrBuIJc [00:18:13]）。使用 -ModelContextProtocolStartServer -ModelContextProtocolPort=8000 或 ModelContextProtocol.StartServer 启动；ModelContextProtocol.GenerateClientConfig ClaudeCode 会写入 .mcp.json；先启动编辑器，再启动 Agent。调用会在游戏线程上串行执行：切勿重叠调用。仅对当前需要的工具集调用 describe_toolset：Niagara 的工具集有“将近四分之一百万”项（k0tgmrBuIJc [00:46:04]）。仅限回环连接，无身份验证。
运行中的编辑器内使用 Editor Python（ue_remote.PythonRemote，或 MCP 服务上的自定义 Python 工具集）	循环操作、审计、工具集不支持的操作、屏幕截图	启用 Python Remote Execution（Project Settings > Plugins > Python）。提供完整的 unreal API；编辑器会在调用之间逐帧运行。每次调用对应一个有名称的事务，并报告执行内容。
无头命令行程序（ue_run.run_python，UnrealEditor-Cmd <uproject> -run=pythonscript）	审计、导入、批量编辑、验证、CI，以及没有编辑器打开该项目时	未加载关卡（map= 可加载关卡），模块较少，不进行渲染。启动时会等待 Asset Registry（get_asset_registry().wait_for_completion()，参见 5.8 批处理示例）；任务只有在启动日志中出现对应 job-id 的 UE_RESULT 行才算通过，绝不能依据退出代码判断。执行保存操作的命令行程序不得触碰已被打开的编辑器加载的项目：编辑器持有写入锁（Jamie Dale，0guOMTiwmhk [01:17:18]）。
完整编辑器，单次运行（mode="editor"：-ExecutePythonScript；mode="latent"：逐帧运行后退出的启动方式）	需要完整模块的任务；latent：无需运行中的编辑器即可截图和渲染	-ExecutePythonScript 会在脚本执行后立即关闭，因此不会逐帧运行；ue_run 会添加 -ScriptErrorsAreFatal（5.5），使失败的脚本导致进程失败。Latent 任务是生成器：yield = 一帧。
Remote Control API（ue_remote.RemoteControl，127.0.0.1:30010）	对已知对象批量写入属性、实时预设、-game 构建	默认关闭，直到运行 WebControl.StartServer。5.8 默认禁用远程 UFUNCTION 调用，需使用允许列表（5.8 发行说明）。仅支持 C++ 名称、用于撤销的 WRITE_TRANSACTION_ACCESS，以及公开的 EditAnywhere 属性。
控制台和 cvars	统计信息、视图模式、画质开关、HighResShot	在 Python 中使用 unreal.SystemLibrary.execute_console_command(world, cmd) [verify]；启动时使用 -DPCVars=（初始化前设置，可覆盖只读 cvars；Profiling with Purpose，C-AjCqjKRSs [00:14:13]），而不是 -ExecCmds。恢复所有更改。
命令行程序和 UAT（ue_run.run_commandlet，run_uat）	DataValidation、ResavePackages -fixupredirects、WorldPartitionBuilderCommandlet、BuildCookRun	无头运行；解析日志（ue_run.scan_log）。
能力矩阵（根据 5.8 文档和演讲整理；tests/code/unreal-expert/jobs/job_00_probe.py
确认或修正每一行）：

操作	MCP	Python，运行中的编辑器	无头命令let	Remote Control
读取和编辑 Actor、资产、属性	工具集	可以	可以（先加载关卡）	public EditAnywhere 属性
材质实例和参数	MaterialInstanceTools	可以	可以	仅限属性
材质图表	工具集（大型架构）	MaterialEditingLibrary，部分支持：有些引脚未公开（Matt Oztalay，m6mJ9r7ytks [00:13:39]）	同左	不支持
Blueprint 图表、AnimGraph [待验证]	Blueprint 工具集 [待验证范围]	5.8 BlueprintGraphEditor [待验证范围]	同左	不支持
Niagara 发射器和模块	工具集，架构庞大	不支持编辑发射器或模块	不支持	用户参数
PCG 图表	PCG 工具集、基元、即发即弃调用	图表 API [待验证]	可以	不支持
截图、MRG 静帧、PIE	通过 Python 工具集	可以	不支持（使用 mode="latent" 或 -game 渲染 CLI）	不支持
Landscape 雕刻、Foliage 绘制、Fracture Mode	不支持	不支持	不支持	不支持
Cook、打包、验证	不支持	不支持 Cook（5.9 中已移除编辑器内 Cook）	可以，使用 UAT	不支持

**图表编辑器和视口工具的替代方案：**Blueprint：用 C++ 编写逻辑（代码项目、Xcode）， 搭配纯数据 Blueprint；复制模板 Blueprint 并设置其默认值；切勿使用 150 个 Delay 节点或没有充分理由的 Event Tick（k0tgmrBuIJc [00:56:45]，[00:57:19]）。材质：使用 已批准主材质的实例；使用节点图表，除非确有需要，否则切勿使用包含全部 HLSL 的 Custom 节点（k0tgmrBuIJc [00:39:27]）。Niagara：复制模板系统，设置用户参数。PCG：组合 Epic 的基元和示例图表（lDf_y-YPELo [00:05:20]）。Control Rig：使用其“Copy Python Script”。 雕刻、绘制、破碎：使用高度图导入、PCG、Dataflow 图表，或明确说明需要人工操作。 写入锁和源代码管理：ue_run 会列出占用项目的 UnrealEditor 进程 （ps）；对于会保存的任务，传入 lock_check="refuse"。5.8 的 PythonScript 命令列工具会在脚本运行前启用源代码管理，因此保存时可以签出 [需通过 Perforce 验证]；ResavePackages 需要 -autocheckout（参见 redirectors 文档）。如果必须编辑的文件尚未签出，请停止（Bardoux，MjjkWH0eT3U [00:55:27]）。OFPA 变更列表必须在编辑器内提交：部分提交会留下悬空引用（参见 World Partition 文档）。构建器会重新生成的内容（例如 PCG 分区 Actor）不要放入变更列表（TbNZ4GKaTow [00:26:23]）。

2. 专家工作循环

说明每次工具包调用背后的引擎调用，计划和报告中都要如此：即使读者没有 scripts/，也必须能核查每一步。写出 ue_review.screenshot(p, 1920, 1080) （AutomationLibrary.take_high_res_screenshot，回退方案为 HighResShot 1920x1080）、cvar 和控制台命令的原文，并以 已验证（运行了什么，以及能证明结果的数字、日志行或帧）和 假设（未在 Unreal 中运行的内容、标注为 [需验证] 的名称、采用的默认值）收尾。 映射和模板：references/toolkit-map.md。

1. **用数字描述需求。**平台和设备类别；每个线程和 GPU 的帧预算（毫秒）（60 fps 时为 16.67，30 fps 时为 33.3；Ari Arnbjörnsson，GuIav71867E [00:03:53]）；输出分辨率和升频器；规模（世界大小、Actor、NPC）；游戏玩法或电影内容；参考资料。若未说明，则采用领域技能的默认值并记录下来。
2. 预检。ue_env.preflight()（芯片、macOS、Xcode）、ue_env.find_project()（插件、路径中的空格），以及会改变计划的项目设置：r.Substrate、Lumen、VSM、Nanite、硬件光线追踪（使用 ue_env.read_ini_value 或探测工具）。升级后的项目会保留旧的渲染器设置 [新增]。
3. 构建一个阶段，使用小型幂等脚本：按路径获取或创建，标记创建的内容，每个逻辑操作使用一个事务，并显式保存。
4. **测量。**对内容使用 ue_audit.verdict；使用 stat unit 分类（Frame、Game、Draw、GPU、RHIT），然后使用 Insights（轻量采集用于判断“是否符合预算”，使用 -statnamedevents 进行详细采集以查明“原因”，开销约 20%，C-AjCqjKRSs [00:11:27]）；对 CSV profiler 或 TraceQuery JSONL 使用 ue_stat.budget_check。在目标硬件上对 Cooked Development 或 Test 构建进行分析；这台 Mac 只能作为游戏主机的替代测试环境。任何重写之前都要先测量（VMZftEVDuCE [00:16:33]）；如果 Insights 无法解释卡顿，则添加采样分析器（C-AjCqjKRSs [00:17:30]）。
5. **查看并检查。**从固定的摄像机书签或 MRG 静帧获取截图，用图像阅读器打开，再使用 ue_review.image_checks：Epic 的灯光 Agent 曾认可一张全白画面（lDf_y-YPELo [00:17:29]）。review_images 一次调用即可提供标记和联系表。使用领域技能的 references/critique.md 进行评判。渲染后，检查 5.8 屏幕上显示的曝光范围警告；如果 MRG 帧与视口不同，首先怀疑 Game Overrides（fVg5ihB8Wdc [00:03:33]）。
6. 修复后再继续，一次只改一处，并使用 ue_review.compare 比较相同视图的前后效果是否一致。
7. 交付证据，采用上述格式：已保存的资源和关卡、审计与统计 JSON、查看过的帧及其检查结果，以及已验证和假设清单。

没有数字和亲自查看过的帧，绝不要声称关卡、材质、镜头或构建已完成。

3. Persona 工作流

简述	工作链	交付内容
开放世界或关卡	scenario-unreal-world-building, scenario-unreal-materials（landscape, RVT）, scenario-unreal-lighting-rendering, scenario-unreal-performance	流式加载关卡、HLOD、预算报告
材质套件	scenario-unreal-materials，然后是 scenario-unreal-lighting-rendering（测试台）、scenario-unreal-performance（着色器成本）	主材质、材质实例、排列组合审计
已打光的室内场景或主视觉静帧	scenario-unreal-lighting-rendering（发光材质使用 scenario-unreal-materials）、scenario-unreal-cinematics 输出 MRG	符合预算的游戏内灯光、EXR 静帧
游戏玩法原型	scenario-unreal-gameplay, scenario-unreal-animation, scenario-unreal-vfx（用于技能）, scenario-unreal-performance	可玩的地图、自动化测试
来自 Maya 的角色	scenario-unreal-pipeline-automation（导入）, scenario-unreal-animation, scenario-unreal-gameplay	已重定向、可用于移动系统的角色
预告片	scenario-unreal-cinematics（scenario-unreal-animation, scenario-unreal-lighting-rendering）	Sequencer 镜头、审核通过的渲染
VFX 或破坏效果	scenario-unreal-vfx, scenario-unreal-performance	符合预算的系统
批量导入和构建	scenario-unreal-pipeline-automation, scenario-unreal-performance（打包）	报告、已验证的软件包
帧率优化	scenario-unreal-performance，将问题转交给对应负责人	验证截图、帧对比

**交接约定：**将已保存的资产放在命名明确的文件夹中；针对接收方配置文件的 ue_audit.verdict 不得包含错误；性能相关时提供 stat 或 trace 数值；提供发送方查看过的帧及其 image_checks；列出每次工具调用及其引擎调用；并提供 Verified 和 Assumed 列表。单位为厘米，Z 轴朝上 [添加]。协作团队：scenario-maya-expert（1 单位 = 1 厘米，Maya 中 Y 轴朝上）、scenario-zbrush-expert、scenario-blender-expert（通过 scenario-blender-export 使用 FBX）；生成的网格交由 scenario-3d 完成。

4. 共享工具集（scripts/，尚未在 Unreal 中运行的引擎部分）

导入：import sys; sys.path.insert(0, "<this skill>/scripts")。PythonRemote.call 会在编辑器中为单次调用添加该文件夹。

• ue_env.py：find_engine(version=None)（editor、editor_cmd、uat、version；UE_ROOT 覆盖项）， find_project(path)、preflight()、plan_plugins / enable_plugins（带时间戳的备份）， read_ini_value、xcode_status。
• ue_run.py： run_python(uproject, script, args=None, map=None, timeout=1800, mode="commandlet"|"editor"|"latent", strict=False, lock_check="warn") 返回 UE_RESULT 信封以及日志扫描结果和 warnings；作业端函数包括 result(obj)、args()、 in_commandlet()、to_jsonable()、wait_for_registry()；run_commandlet(uproject, name, args)、 run_uat、build_buildcookrun、launch_editor(mcp_port=)、stop_editor、editor_processes、 scan_log、parse_ue_result。
• ue_remote.py： RemoteControl(host, port).info/describe/get_property/set_property/call/batch/search_assets/console， 错误会附带修复提示；PythonRemote().open/exec/call/close；McpHttp().health()（可达性、 工具搜索）；loopback_only(port)、pie_path、cdo_path、python_cdo_path。
• ue_review.py：编辑器内函数 set_camera、screenshot、wait_screenshot、screenshot_views、 camera_views_from_actors、render_still（MRG 或 MRQ 预设，独立队列）、wait_render；离线 函数 image_checks（直方图、过曝、死黑、类似 EV 的检查、中心与周边对比、全白、全黑、 均匀、Alpha）、image_verdict、compare、contact_sheet、review_images、wait_for_file、 build_render_command。
• ue_audit.py：编辑器内函数 audit_assets(paths, rules, profile)、collect_facts；任意环境均可使用 evaluate、build_report、verdict(report, "game"|"cinematic"|"mobile"|"prototype")；检查 Epic 前缀、纹理尺寸和压缩、Nanite、碰撞、LOD、槽位、实例父项、自定义 HLSL、景深后半透明、 重定向器。
• ue_stat.py：parse_stat_unit、parse_csv_profile + csv_frames、parse_jsonl + sniff_schema + trace_frames + timer_totals、budget_check(frames, target_ms)、bound_by、 summarize。

领域技能会添加 scripts/ue_<domain>.py，不会复制这些脚本。每个函数背后的引擎调用见： references/toolkit-map.md。

5. Top 5.8 注意事项（完整列表：references/ue-5.8-traps.md）

• EditorLevelLibrary 和 EditorAssetLibrary 是旧 API：使用 EditorActorSubsystem、 LevelEditorSubsystem、UnrealEditorSubsystem、EditorAssetSubsystem，通过 unreal.get_editor_subsystem 获取。Epic 自己的 5.8 示例仍使用旧名称。load_level 会丢弃未保存的更改； delete_asset 会强制删除，并可能清除撤销记录；Interchange 下会忽略 destination_name。
• Substrate 默认设置取决于项目创建时间：5.7 及之后创建的项目默认启用；升级的项目则默认使用旧版， 直到主动启用；关闭 Substrate 时，Substrate 材质会渲染为黑色；没有 Metallic 引脚；Mac 被列为存在已知问题。 编写材质前先读取 r.Substrate。
• Mac 功能支持：仅支持 Apple Silicon；M2 及更新芯片支持 Nanite 和 VSM Beta；M2 及更新芯片支持 Lumen HWRT 和 MegaLights Experimental；通过 Metal 支持路径追踪，macOS 26.4 及更高版本支持。 Xcode：Epic 列出的最低版本为 26.0，推荐 26.1.1，26.4 不兼容；这台 Mac 使用 26.6，未列出： 请验证 C++ 构建。
• MRG 更名：Movie Render Graph 已达到正式可用状态，新功能仅支持图表，MRQ 预设为旧版， 队列默认值为 “Basic”；使用 MoviePipelinePrimaryConfig（而非 Master）；图表作业使用 set_graph_preset()；结束帧不包含在范围内；H.264 节点仅支持 Windows。
• Remote Control 默认设置：服务器在启动前处于关闭状态，5.8 默认拒绝远程 UFUNCTION 调用， 且仅绑定 127.0.0.1；将 DefaultBindAddress 开放到局域网，很可能也会暴露未经过身份验证的 MCP 服务 [新增推断]。

6. macOS 相关说明

• 启动器安装位置为 /Users/Shared/Epic Games/UE_5.8/；编辑器位于 Engine/Binaries/Mac/UnrealEditor.app/Contents/MacOS/UnrealEditor；-Cmd 的位置为 [verify]，find_engine 会回退到编辑器并使用 -run=；UAT 为 RunUAT.sh；烘焙 平台为 Mac。
• Unreal 项目应放在不含空格的路径中（Allar 风格指南）[verify impact]；工具包无论如何都会将 作业暂存到不含空格的文件夹中。
• 仅支持 Metal：DX11、DX12 和 Vulkan 的提示不适用；RenderDoc 不支持 Metal，请使用 Xcode 的 Metal 调试器 [added]。Metal System Trace 可显示着色器编译和热降频，这些会导致捕获失效 （ufPtQEtk-RQ [00:14:06]、[00:18:17]）。Insights 中未列出 Mac 的内存调用栈。在 Insights 之外，Mac 的采样分析器是 Instruments Time Profiler [added]。
• 文档中使用了 Ctrl 快捷键和 Windows 路径：请转换为 Cmd [verify] 和 POSIX 路径。MacBook 没有数字键盘：请重新绑定 Gameplay Debugger 的数字键盘类别按键（tranek GAS 指南 6.2，见版本差异）。
• 绝不要结束由你未启动的编辑器；停止自己启动的编辑器之前，请先保存。

参考资料

• references/ue-5.8-traps.md：所有会导致记忆中的代码或旧教程失效的 5.8 变更及其来源，还有首次运行检查清单。根据记忆编写代码前请先加载。
• references/toolkit-map.md：每个工具包功能背后的引擎调用、命令或 cvar，以及报告格式（每个步骤的引擎调用、Verified 和 Assumed）。
• references/python-reliability.md：unreal 模块的惯用写法和操作流程（子系统、路径、事务、保存、获取或创建、标记所创建的内容、写锁和源代码管理、潜在工作、导入、原始截图循环）。
• references/sources.md：所有来源，以及凭据、URL 和最佳时间戳。