Command Line Tool for Unreal Engine

What is UCT?

UCT (Unreal Commandline Tool) is a powerful command line tool to buid, test and run unreal engine based project easier.

Let's see a demo.

Used in windows and UE 4.27:

NOTE: These videos were recorded earlier, so some information may be outdated. Please refer to the document for the most accurate information.

Background

Usually development on EU is done in Visual Studio and Editor on Windows systems. But sometimes,

When traveling or at home, without access to the Windows workstation in the office, I have to develop, build, and test on a Mac system.
Even on the Windows workstation, I often use Visual Studio Code to open projects because it is more lightweight, rich in plug-ins, fast to start, and has better git integration.

In these cases, you need to use command line tools, such as UBT, UAT and Editor.

And in many cases, it is more convenient to use command line tools because they are easy to batch and automate. Additionally, some UE features can only be accessed from the command line, such as implicit tests in the low level tests.

But the command line interfaces in UE systems are very boring.

For example, to build a program:

G:\MyGame> G:\UnrealEngine-5.1\Engine\Build\BatchFiles\Build.bat Benchmark Win64 Development -Project="G:\MyGame\MyGame.uproject"

To run tests from command line:

G:\MyGame>G:\UnrealEngine-5.1\Engine\Binaries\Win64\UnrealEditor-Cmd.exe %CD%/MyGame.uproject -ExecCmds="Automation RunAll"

To packing is insanely more complicated:

E:\UE_5.2\Build\BatchFiles\RunUAT.bat ^
BuildCookRun -project=E:/AllProject/UE_5_2_0/BuildTest/BuildTest.uproject ^
-ScriptsForProject=E:/AllProject/UE_5_2_0/BuildTest/BuildTest.uproject ^
Turnkey -command=VerifySdk -platform=Android -UpdateIfNeeded ^
BuildCookRun -nop4 -utf8output -nocompileeditor -skipbuildeditor -cook ^
-project=E:/AllProject/UE_5_2_0/BuildTest/BuildTest.uproject -target=BuildTest ^
-unrealexe=E:\UE\UE_4.27_Source\UnrealEngine\Engine\Binaries\Win64\UnrealEditor-Cmd.exe ^
-platform=Android -cookflavor=ASTC -stage -archive -package -build -pak -iostore -compressed -prereqs ^
-archivedirectory=E:/AllProject/UE_5_2_0/BuildTest/PakOutputX -clientconfig=Development -nocompile -nocompileuat

These user interface has the following problems:

You must use the UBT in the correct engine directory to build the game project. There are several versions of the engine on my workstation, and they are all in use, so I can not add the UBT path to the PATH environment variable. I have to use the full path.
The path and suffix of UBT and other scripts are different between Windows and Mac/Linux.
The file name of the editor also have different suffix for different configurations, for example UnrealEditor-Win64-Debug.exe.
The path of the -Project argument must be a absolute path, it's boring, we can use %CD% to simplify it but it still need the project file name.
Some options such as Development are so long.

So, I developed this handy tool, to simplify my life, and, maybe yours.

With this tool, you needn't:

Type the the full path of UBT. UCT can find it automatically if your current directory is under the game project or the engine directory.
Pass the -Project=/Full/Path/To/YourGame.uproject. UCT can find it automatically if your current directory is under the game project.
Type Win64. UCT assume the target platform is also the host platform by default, of cause you can also change it.
Type Development. UCT use Development by default. Even if you want to specify it, using -c dev is also easier.

Supported Systems

UCT supports running in Win64, Linux and Mac, and tested on UE 5.1, 5.2, 5.3 and 4.27.

Install

Just use git to clone the code, and execute the install command:

git clone https://github.com/chen3feng/uct
cd uct
install

The path of UCT is registered into your PATH environment, you can call it from any where in you system.

On Linux or Mac, the install command is ./install.

Basic Concepts

See UE documents for the following concepts:

Target Each .Target.cs file describes a target.
Target Platform UE Support Win64, Linux, Mac and some other such as Hololens.
Configuration, Such as Debug, Development, Shipping and Test.
Module Each .Build.cs file describes a module.

Command Line Interface

The basic interface is:

uct <command> options...

For example:

uct build -c dbg -p linux Benchmark

build is the command, -c dbg and -p linux are options, Benchmark is a target.

Just like the git command. easy?

UCT support the following commands:

Setup

Execute the Setup.bat or Setup.sh in the engine root directory.

$ uct setup
...

Generate Project Files

Generate project files for the engine or game project.

$ uct generate project
...

switch engine

When this command is executed, UCT generates a menu listing all installed engines and engines built from source code on the current system. Use the up and down arrows to select, press Enter to confirm, and ESC to cancel.

G:\MyGame>switch engine
Switch engine
Installed engines:
[ ] 5.1.1    D:\Game\UE_5.1
[ ] 5.3.2    D:\Game\UE_5.3
[ ] 5.2.1    D:\Game\UE_5.2
Source build engines:
[x] 5.1.1    G:\UnrealEngine-5.1
[ ] 4.27.2   G:\UnrealEngine-4.27.2
[ ] 5.3.1    G:\UnrealEngine-5.3.1
Engine is switched to {750E0EB6-4428-07C4-DFB6-888F4E6452A6}  5.1.1    G:\UnrealEngine-5.1

List

list target

List all targets:

$ uct list target
BaseTextureBuildWorker
BenchmarkTool
BlankProgram
BuildPatchTool
...

List all engine targets:

$ uct list target --engine
BaseTextureBuildWorker
BenchmarkTool
BlankProgram
BuildPatchTool
...

List all project targets:

$ uct list target --project
MyGameTest
MyGameClient
MyGameEditor
MyGameServer
MyGameBenchmark

Make verbose output with the --verbose option:

$ uct list target --verbose
Type      Name                            Path
------------------------------------------------------------------------------------------------------------------------
Program   BaseTextureBuildWorker          G:\UnrealEngine-5.1\Engine\Source\Programs\BaseTextureBuildWorker\BaseTextureBuildWorker.Target.cs
Program   BenchmarkTool                   G:\UnrealEngine-5.1\Engine\Source\Programs\BenchmarkTool\BenchmarkTool.Target.cs
Program   BlankProgram                    G:\UnrealEngine-5.1\Engine\Source\Programs\BlankProgram\BlankProgram.Target.cs

list engine

List all unreal engines in the current system.

$ uct list engine
Installed engines:
UE_5.1  5.1.1    /Volumes/SSD/software/EpicGames/UE_5.1
UE_5.2  5.2.1    /Volumes/SSD/software/EpicGames/UE_5.2
UE_5.3  5.3.2    /Volumes/SSD/software/EpicGames/UE_5.3

Registered source build engines:
{46E95257-8C4E-4D80-C21A-AB88D9179249}  5.1.0    /Volumes/SSD/code/UnrealEngine-5.1
{CCB0C841-B544-47A2-A486-C3908D365428}  5.2.1    /Volumes/SSD/code/UnrealEngine-5.2
{3BC4DCDD-7743-67E3-8361-5D90FEB4A5B2}  4.27.2   /Volumes/SSD/code/UnrealEngine-4.27

Build

Build specified targets.

Targets Syntax

Build one target:

$ uct build UnrealEditor
...

Build multiple targets:

$ uct build Benchmark UnrealEditor
...

This command supports wildcard target names:

uct build MyProject*
uct build *Editor
uct build MyProject* *Editor

On Linux or Mac, in some cases wildcards need to be quoted in order to work properly, see below for details.

Target patterns are case insensitive, so you can also use unrealeditor to build UnrealEditor:

$ uct build unrealeditor
...

The targets will be matched in both project and engine by default. You can use --project or --engine option to limit the matching scope.

uct build --project "*"

build all targets in the game project.

Target Platform and Configuration

This command supports specifying build configuration and target platform:

uct build -c debug -p linux

Option values for target platforms are all lower case:

Win64: win64
Linux: linux
Mac: mac

Other platforms are all lower case such as linuxarm64, android, ios, tvos, hololens.

Option values for build configurations:

Debug: dbg or debug
DebugGame： dbgm or debuggame
Development: dev or develop
Shipping: ship
Test: test

To simplify typing, in UCT, all these values are lowercase.

Compile Single File

The build command also supports -f or --files to specify files to comile only. It is useful to verify the syntax and non-unity build correctness quickly. Bucause in the single file compile mode unity build is always disabled.

This option supports the following formats:

An absolute path: /Work/MyGame/Source/MyGame/HelloWorldGreeterImpl.cpp.
A relative path: MyGame/HelloWorldGreeterImpl.cpp from current directory.
A path with @engine prefix: @engine/Source/Runtime/Engine/Private/NetDriver.cpp means under the engine directory.

All above format supports wildcard pattern: Source/**/*Test.cpp, ** means any layer of subdirectories. The rules for using quotes are the same as in build targets.

Example:

# Build all source files.
uct build MyGame -f "Source/**/HelloWorldGreeterImpl.cpp"

# Compile NetDriver.cpp and DataChannel.cpp under the engine directory.
uct build MyGame -f "@engine/Source/**/NetDriver.cpp" "@engine/Source/**/DataChannel.cpp"

# Build all source files under MyModule.
uct Build MyGame -f "Source/MyModule/**/*.cpp"

Pass UBT flags

UCT will generate appropriate UBT commands based on the command line parameters for the actual build.

UBT has many options, Some useful usecases:

Enable Clang Sanitizers
Enable Static Code Analysis

To pass extra options to UBT, put them after a bare -- like this:

uct build MyGame -- -StaticAnalyzer=VisualCpp

Clean

Clean one or more targets, example:

$ uct clean Benchmark UnrealEditor
...

The supported options are similar to build, See the above build for reference.

Rebuild

Clean and build.

Run

Run one or more programs:

$ uct run Benchmark
Run G:\MyGame\Binaries\Win64\Benchmark.exe
LogBenchmark: Display: Running 'BM_Serialize<FFieldTest>'...
LogBenchmark: Display: Running 'BM_Serialize<FBenchmarkTest>'...
LogBenchmark: Display: Running 'BM_Deserialize<FFieldTest>'...
LogBenchmark: Display: Serialized size=109
...

All arguments after the first -- is passed to the program:

uct run Benchmark -- --help --help

The program got --help -- --help aruguments.

Test

UCT use -ExecCmds Automation ... to execute automation tests.

Options:

--list: list all tests
--run-all: Run all test
--run: Run specified tests, separted by space
--cmds: Any extra test commands you want to run

Examples:

# List all tests
uct test --list

# Run all tests
uct test --run-all

# Run all tests starts with 'System.Core'
uct test --run System.Core

The --cmds option can be used to pass more test commands to the system.

Example:

uct test --cmds List RunAll "RunTests System" Quit

The -ExecCmd command is Automation List; RunAll; "RunTests System"; Quit.

According to the source code of UE, you can use the following test commands:

Automation List
Automation RunTests <test string>
Automation RunAll
Automation RunFilter <filter name>
Automation SetFilter <filter name>
Automation Quit

open

Open specified file.

According to your terminal environment:

If you in the integrated terminal in Visual Studio or Visual Studio Code, it will be opened in the according text editor.
Otherwise, it will be opend in file explorer.

This command supports the --engine and --project option.

open file

Open specified source file.

Examples:

# Open Engine/Source/Runtime/Core/Private/Containers/String.cpp
uct open file string.cpp

# Open Engine/Source/Runtime/Core/Public/Containers/UnrealString.h
uct open file unrealstring.h

# Open Engine/Source/Runtime/Core/Core.Build.cs
uct open file "core.*.cs"

open module

Open the .Build.cs file for the specified module in your workspace.

Example:

uct open module MyGameModule
uct open module Core
uct open module Engine

open plugin

Similar to open module, but open the .uplugin file.

Example:

uct open plugin Paper2D
uct open plugin OnlineSubsystem

pack

Pack specific objects.

pack target

Pack the target to specified output directory.

Arguments:

--output Output directory of the packed result.

Example:

$ uct pack --config=ship --output=pack_dir MyGame
...
Archive command time: 1.13 s
********** ARCHIVE COMMAND COMPLETED **********
BuildCookRun time: 58.27 s
BUILD SUCCESSFUL
AutomationTool executed for 0h 0m 59s
AutomationTool exiting with ExitCode=0 (Success)

pack plugin

Build and pack a unreal plugin into specified directory.

uct pack plugin pb4uerpc --output ..\pbp

The --output or -o option is used to specify the output directory.

The --platforms or -p option is used to specify the target platforms:

uct pack plugin pb4uerpc --output ..\pbp --platforms win64 linux

Any arguments after the first -- are passed to UAT.

uct pack plugin pb4uerpc --output ..\pbp --platforms win64 linux -- -nocompile -nocompileuat

runubt and runuat

Building and packaging are performed by calling UBT or UAT, which are their specific usage modes. UCT also provides the ability to fully use them by calling them directly:

runubt: Run UnrealBuildTool
runuat: Run AutomationTool

All options after the first bare -- are passed to the tool.

Example:

$ uct runuat -- -help
...
$ uct runubt -- -help
...

The advantage compared to directly calling the corresponding script in the engine is that there is no need to specify the path and extension (.bat or .sh).

help

To view help, use the --help parameter. To view help for a command, add --test after the command.

# View help
uct --help

# View help for the build command
uct build --help

Wildcards

Many commands supports wildcards:

uct build MyProject*
uct build *Editor
uct build MyProject* *Editor

On Linux and Mac, since wildcards are expanded by the shell, add quotes if necessary to avoid expansion into matching project file names:

uct build "MyProject*"
uct build *Editor
uct build "MyProject*" *Editor

On Linux and Mac, both single and double quotes are OK. On Windows, since wildcards are expanded by the program itself rather than by the shell, quotation marks are not necessary, but if they are used, they must be double quotation marks and not single quotation marks.

Command Line Completion

UCT support command auto completion in bash and zsh by using the argcomplete library, see its document to enable it.

How it works

Understanding how UCT works is helpful, and code contributions are welcome.

Startup

UCT must be run under the project or engine directory. When UCT is called, it will first search for the .uproject file from the current directory upwards. If it is found, it is considered to be in the project directory. Parse the uproject file to get the engine ID associated with the project. Depending on the system, use different methods to get the directory where the engine is located.

On Windows, read the registry key HKEY_CURRENT_USER\Software\Epic Games\Unreal Engine\Builds
On Mac and Linux, read configuration files ~/.config/Epic/UnrealEngine/Install.ini.

If the project file cannot be found, use a similar method to find the feature file of the UE engine (GenerateProjectFiles.bat) and obtain the root directory of the engine.

Under Linux and Mac, the above lookup process is performed in python.

On Windows, the above search process is batch processed, and then passed to UE's built-in python interpreter (Engine\Binaries\ThirdParty\Python3\Win64\python.exe) through environment variables. This is because Windows systems lack a unified Python installation, and the Python interpreter is already built into the engine.

Once the project and engine directories were found, Other paths such as UBT, are no longer a problem.

`list-targets`

Use the -Mode=QueryTargets parameter to call UBT to generate the Intermediate/TargetInfo.json file, and parse it to get the result.

`build` and `clean`

Use UBT's Build and Clean functionality.

`run`

UBT will generate a <target name>.target file in JSON format for each target, and parse its Launch field to get the path to the executable file.

`test`

Currently only Automation testing in the editor is supported. The working principle is to find the executable file of the engine command version (UnrealEditor-Cmd), generate test commands and pass them to it for execution.

Planned Features

# Run explicit test
uct test MyGameTest

# Create a new module
uct new module

# Create a new C++ class
# Create a ExamEventLoop.h in the Public directory and ExamEventLoop.cpp in the Private directory
cltue new class --public FExamEventLoop

chen3feng/uct

Command Line Tool for Unreal Engine

What is UCT?

Background

Supported Systems

Install

Basic Concepts

Command Line Interface

Setup

Generate Project Files

switch engine

List

list target

list engine

Build

Targets Syntax

Target Platform and Configuration

Compile Single File

Pass UBT flags

Clean

Rebuild

Run

Test

open

open file

open module

open plugin

pack

pack target

pack plugin

runubt and runuat

help

Wildcards

Command Line Completion

How it works

Startup

list-targets

build and clean

run

test

Planned Features

`list-targets`

`build` and `clean`

`run`

`test`