Automation Tool (UAT)

UAT(Unreal Automation Tool)是 UE 自带的一个 C# 写的工具集合,用来脚本化处理那些"无人值守"的流程:编译代码、Cook 内容、打包游戏、跑 automation test,以及在 build farm 上调度各种操作。源码在 Engine/Source/Programs/AutomationTool——即使你是从 Epic Launcher 装的引擎(没下 GitHub 源码),这部分 UAT 源码也是有的。

官方一句话定义:

AutomationTool is a host program and a set of utility libraries you can use to script unattended processes related to Unreal Engine when using C#.

UAT 支持 Windows / Mac / Linux(基本就是能跑 Unreal Editor 的那几个平台)。它是纯命令行工具,没有 GUI,得在终端里跑。

官方文档:Unreal Automation Tool Overview。

RunUAT 入门

跑 UAT 靠引擎 Engine/Build/BatchFiles 下的 RunUAT.bat(Mac 是 RunUAT.command,Linux 是 RunUAT.sh)。运行时当前目录要在引擎根目录(能看到 Engine 文件夹的那层)或 Engine/Build/BatchFiles 里。Epic Launcher 装的话根目录类似 C:\Program Files\Epic Games\UE_4.26。

不带命令直接跑:

Engine\Build\BatchFiles\RunUAT.bat

会报错,因为没给有效命令:

Running AutomationTool...
Parsing command line:
ERROR: Failed to find scripts to execute in the command line params.
AutomationTool exiting with ExitCode=1 (Error_Unknown)
BUILD FAILED

用 -List 列出所有支持的命令(一百来个,顺序乱的,得自己找):

Engine\Build\BatchFiles\RunUAT.bat -List

里面常用的有 BuildCookRun、BuildEditor、BuildGame、BuildServer、BuildTarget、BuildPlugin、BuildGraph、UBT 等。

给具体命令加 -Help 看用法:

Engine\Build\BatchFiles\RunUAT.bat BuildGame -Help

注意一个细节:UAT 总会带一个 ExitCode 退出,0 是 Success。比如 BuildGame 底层调 UBT 编译代码,编译失败 UBT 返回非 0,UAT 也跟着返回非 0——批处理 / CI 就靠这个判断构建成败。

还有个坑:如果你用的是源码版引擎(GitHub 或 P4),RunUAT.bat 会自动给命令行加上 -compile,每次运行前先重编自己。因为源码版假设你可能改过 UAT 源码(或加了自定义命令),需要重新编译。装机版则不会。

Build 系命令

C++ 工程 / 源码版引擎可以用 Build 系命令自动化编译:

• BuildEditor:编译编辑器。这里有个区别——编译整个 UE 工程的编辑器会编所有 Engine / Plugin 模块,不管你游戏用不用;只编你游戏工程的编辑器(-project=)只编游戏需要的模块,更快,但代价是之后想在编辑器里启用一个新插件、不重编就重启会失败。
• BuildGame:编译游戏 C++ 代码,产出加载运行 cooked 内容的可执行文件。发版用 Shipping(去掉大量日志、最高优化),测试包用 Development(保留日志、优化低些)。源码版还能编 Debug / Test。
• BuildServer / BuildTarget:BuildEditor/BuildGame/BuildServer 其实都是 BuildTarget 的子类。BuildTarget -Help 列的参数更全(比如 -clean、-NoXGE、-DisableUnity 这些)。

同时编多个配置:

Engine\Build\BatchFiles\RunUAT.bat BuildGame -project="%USERPROFILE%\Documents\Unreal Projects\MyAwesomeGame\MyAwesomeGame.uproject" -platform=Win64 -configuration=Development+Shipping

编完在工程 Binaries/Win64 下会看到两个 exe:一个是工程名(MyAwesomeGame.exe),一个带 Shipping(MyAwesomeGame-Win64-Shipping.exe),后者是发给玩家的。

Clean(清理后重编)

UAT 没有专门的 clean 命令。BuildEditor / BuildGame 可以加 -clean(help 里没写但能用),会先删干净再编。但要注意:用 BuildEditor -clean 编了 UE 工程编辑器,再 BuildEditor -clean -project=<你的工程>,会把刚编好的 UE 工程编辑器文件全删了重编,纯浪费时间。

更干净的做法是用 Engine/Build/BatchFiles/Clean.bat(它底层跑 UBT 的 -clean):

Engine\Build\BatchFiles\Clean.bat -Target="MyAwesomeGameEditor Win64 Development" -Project="%USERPROFILE%\Documents\Unreal Projects\MyAwesomeGame\MyAwesomeGame.uproject" -WaitMutex -FromMSBuild

-Target= 格式是"工程名 平台 配置"。-WaitMutex 让 UBT 用 mutex 防止多进程同时碰同一文件,-FromMSBuild 标记错误信息来自 MSBuild(Windows 专用)。Mac / Linux 把 Clean.bat 换成直接跑 Engine/Binaries/DotNET/UnrealBuildTool。

什么时候需要 clean:UBT 靠依赖关系判断要重编什么,通常很准,但有时改了头文件(尤其第三方库的头文件)它没察觉到依赖它的东西需要重编,这时就得手动 clean 一次。

Engine Programs 一览

UE 这套构建 / 工具链程序很多,平时打交道的核心几个:

名称	作用
UnrealAutomationTool (UAT)	构建 / Cook / 运行 / 测试 / build farm 调度的总入口。流程分 Build → Cook → Stage → Package → Deploy → Run 几个阶段
UnrealHeaderTool (UHT)	UE 的自定义解析 + 代码生成工具(处理 UCLASS/UPROPERTY 等宏)
UnrealBuildTool (UBT)	管理跨各种构建配置编译 UE 源码的自定义工具
Horde	(UE5.4 Beta)远程执行(配 Unreal Build Accelerator 做 C++ 分布式编译)、CI/CD、测试自动化前端、Studio 分析、UGS 元数据服务、设备管理
Unreal Frontend (UFE)	简化日常打包 / 部署 / 启动测试的 GUI 工具,内含 Project Launcher
UnrealGameSync (UGS)	协作开发里同步代码 + 内容的工具,让分布的团队在同一工程上协作
UnrealPak	pak 文件的打 / 解包工具
Unreal Swarm	通用任务分发系统:coordinator 派活,agent 用本机资源干活。Windows 上常用于光照 Cook
Turnkey	自动化 SDK 安装管理,简化平台搭建。SDK 文件可放在 P4、本机或共享盘
CrashReportClient	崩溃后提示用户填注释并把崩溃报告交给 Epic
LowLevelTests (LLT)	轻量、模块级的测试框架
NetworkProfiler	独立工具,展示游戏运行时的网络流量和性能信息
SwitchboardListener	跑在每台设备上的 TCP 服务,配合 Switchboard 控制多台远程设备
UnrealAndroidFileTool / AndroidFileServer	Android 上的文件服务(随包内嵌)+ 连接它管理文件的命令行工具
UnrealMultiUserServer	多人在不同机器进同一个编辑器会话协作做内容
UnrealTraceServer	后台单实例运行的结构化日志 / trace 服务,可被多工程 / 分支共享(供 Unreal Insights 用)

官方文档参考:UHT、Horde、UnrealFrontend、UGS、Swarm、Turnkey。

BuildPlugin:打包插件

一行命令把插件打成可分发的预编译包:

RunUAT.bat BuildPlugin -Rocket -Plugin=path\xx.uplugin -TargetPlatforms=Win64 -Package=PackagePath

-Plugin= 指向 .uplugin,-TargetPlatforms= 指目标平台,-Package= 是输出目录,-Rocket 表示按装机版方式编。

-PGOOptimize 踩坑

PGO(Profile-Guided Optimization)优化构建有个坑:BuildCookRun 不支持 -PGOOptimize。要开 PGO 优化,得直接用 Engine/Build/BatchFiles 下的 build.bat(注意链接阶段会很慢):

cd /d <ProjectRoot>\Engine\Build\BatchFiles
.\build.bat MyProject <Platform> Test -Project="F:\MyProject\MyProject\MyProject.uproject" -WaitMutex -FromMsBuild -PGOOptimize -Clean

.\build.bat MyProject <Platform> Test+Shipping -Project="F:\MyProject\MyProject\MyProject.uproject" -WaitMutex -FromMsBuild -PGOOptimize

工作流里跑 swarm test 时,build 步骤仍建议走 BuildCookRun(只是不带 PGO):

.\RunUAT.bat BuildCookRun -project="F:\MyProject/MyProject/MyProject.uproject" -noP4 -clientconfig="Test" -nocompileeditor -utf8output -platform=<Platform> -build -CrashReporter -skipcook

Installed Build(旧称 Rocket Build)

Installed Build 是编译好的引擎版本——从 Epic Launcher 下的引擎其实就是个 Installed Build。自己做 Installed Build 的主要动机:用自定义 / 未编译的引擎时,提前编一份能加快后续编译。

用 BuildGraph 制作:

RunUAT.bat BuildGraph -target="Make Installed Build Win64" -script=Engine/Build/InstalledEngineBuild.xml -set:WithClient=true -set:WithServer=true -AllowParallelExecutor=false -set:WithDDC=true -set:WithLinux=false -set:WithWin64=true -set:WithWin32=false -set:WithMac=false -set:WithAndroid=false -set:WithIOS=false -set:WithTVOS=false -set:WithLumin=false -set:WithLinuxAArch64=false -set:WithHoloLens=false -set:WithLuminMac=false -set:WithFullDebugInfo=true

-set:WithXXX=true/false 控制要不要带某平台。主机平台(PS5/XSX/Switch 等)按需用对应的 -set:WithXXX=true/false 开启即可,这里不列具体平台名和 SDK。参考:Unreal Installed Builds。

清理 UE 中间文件

源码版引擎在 P4 上协作时,经常要把中间产物从版本控制里清掉(Saved、obj、Intermediate、Binaries 等),避免它们被误提交。用 p4 delete / p4 revert 批量处理:

p4 delete //depot/.../Saved/...
p4 delete //depot/.../obj/...
p4 delete //depot/.../Intermediate/...
p4 delete //depot/.../Engine/Source/Programs/Shared/EpicGames*/bin/...
p4 delete //depot/.../Engine/Binaries/DotNET/AutomationTool/...
p4 delete //depot/.../Engine/Binaries/DotNET/UnrealBuildTool*/...
p4 delete //depot/.../Engine/Platforms/.../Binaries/DotNET/AutomationTool/...

p4 delete //depot/.../Engine/Plugins/.../Binaries/...
p4 revert //depot/.../Engine/Plugins/Editor/PluginBrowser/Templates/ThirdPartyLibrary/Binaries/...
p4 revert //depot/.../Engine/Plugins/Enterprise/AxFImporter/Binaries/...
p4 revert //depot/.../Engine/Plugins/Enterprise/DatasmithCADImporter/Binaries/...
p4 revert //depot/.../Engine/Plugins/Enterprise/MDLImporter/Binaries/...
p4 revert //depot/.../Engine/Plugins/Experimental/NNERuntimeIREE/Binaries/...
p4 revert //depot/.../Engine/Plugins/Experimental/NNERuntimeRDG/Binaries/...
p4 revert //depot/.../Engine/Plugins/Media/AppleProResMedia/Binaries/...
p4 revert //depot/.../Engine/Plugins/Media/BlackmagicMedia/Binaries/...
p4 revert //depot/.../Engine/Plugins/Media/MediaIOFramework/Binaries/...
p4 revert //depot/.../Engine/Plugins/NNE/NNERuntimeORT/Binaries/ThirdParty/...
p4 revert //depot/.../Engine/Plugins/Runtime/AR/Google/GoogleARCore/Binaries/...
p4 revert //depot/.../Engine/Plugins/Runtime/OpenCV/Binaries/...

p4 delete //depot/.../Engine/....csproj.props
p4 revert //depot/.../Engine/Source/Programs/Shared/UnrealEngine.csproj.props

p4 delete //depot/.../UE5.sln

主机平台(Engine/Platforms/<平台>/Binaries/...)下也有一批平台专属的工具二进制需要同样处理,按各平台实际目录 p4 delete / p4 revert 即可,这里不展开具体路径。

清完之后重新生成工程文件、编一遍验证没问题:

set ws=<DirRoot>
cd /d %ws%
call GenerateProjectFiles.bat
cd /d C:/Program Files/Microsoft Visual Studio/2022/Professional/Common7/IDE
devenv.com %ws%/UE5.sln /build "Development Editor|Win64" /Project %ws%/Engine/Intermediate/ProjectFiles/<ProjectName>.vcxproj

另外,在 P4 stream 的 branch view 里把这几个目录设为 ignore,从源头避免它们进版本控制:

/Saved/...
/obj/...
/Intermediate/...