BuildGraph Script Tasks

Learn how BuildGraph can help you create custom tasks.

Windows
MacOS
Linux

Typically, project-specific utility scripts are implemented as AutomationTool BuildCommand classes. There are times, however, when you'll want to automate custom tasks for your project. This is where BuildGraph can help. BuildGraph can be extended with any number of tasks, enabling you to customize your build automation tasks in ways that suit your specific needs. The following section goes over ways of creating custom tasks using BuildGraph, including a listing of predefined tasks that'll give you a great starting point for creating custom tasks.

Custom Tasks

To create a new custom task, implement a class derived from the CustomTask class and apply the [TaskElement] attribute to it. The TaskElement constructor takes two arguments; the name of the XML element that it's represented by, and the type of class containing its parameters (which is passed to the constructor at load time).

If you want to read parameter class fields from an XML file, attach the [TaskParameter] attribute to the task. Attaching the TaskParameter attribute indicates if the parameter is required or optional, including additional validation that should be applied to the argument.

Predefined Tasks

If you'd like to have a starting point for creating tasks, we're providing a variety of predefined tasks as templates for you to work from. If you're looking for a simple predefined task to start from, we recommend using LogTask as a good starting point. If you want to keep up with our latest improvements to BuildGraph; bookmark this page, because the following list of predefined tasks will be updated periodically.

BuildCookRun is a powerful and commonly used command for packaging tasks. For more information, read the overview that covers Build Operations .

AgeStore

Task that strips symbols from a set of files. This task is named after the AGESTORE utility that comes with the Microsoft debugger tools SDK, but is actually a separate implementation. The main difference is that it uses the last modified time rather than last access time to determine which files to delete.

Platform

UnrealTargetPlatform

Required

The target platform to age symbols for.

StoreDir

String

Required

The symbol server directory.

Days

Int32

Required

Number of days worth of symbols to keep.

BuildDir

String

Optional

The root of the build directory to check for existing buildversion named directories.

Filter

String

Optional

A substring to match in directory file names before deleting symbols. This allows the "age store" task to avoid deleting symbols from other builds in the case where multiple builds share the same symbol server. Specific use of the filter value is determined by the symbol server structure defined by the platform toolchain.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Command

Invokes an AutomationTool child process to run the given command.

Name

String

Required

The command name to execute.

Arguments

String

Optional

Arguments to be passed to the command.

MergeTelemetryWithPrefix

String

Optional

If non-null, instructs telemetry from the command to be merged into the telemetry for this UAT instance with the given prefix. May be an empty (non-null) string.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Commandlet

Spawns the editor to run a commandlet.

Name

String

Required

The commandlet name to execute.

Project

File Spec

Optional

The project to run the editor with.

Arguments

String

Optional

Arguments to be passed to the commandlet.

EditorExe

FileReference

Optional

The editor executable to use. Defaults to the development UE4Editor executable for the current platform.

ErrorLevel

Int32

Optional

The minimum exit code, which is treated as an error.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Compile

Compiles a target with UnrealBuildTool.

Target

String

Required

The target to compile.

Configuration

UnrealTargetConfiguration

Required

The configuration to compile.

Platform

UnrealTargetPlatform

Required

The platform to compile for.

Project

String

Optional

The project to compile with.

Arguments

String

Optional

Additional arguments for UnrealBuildTool.

AllowXGE

Boolean

Optional

Whether to allow using XGE for compilation.

AllowParallelExecutor

Boolean

Optional

Whether to allow using the parallel executor for this compile.

Clean

Nullable`1

Optional

Whether to allow cleaning this target. If unspecified, targets are cleaned if the -Clean argument is passed on the command line.

Tag

Tag List

Optional

Tag to be applied to build products of this task.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Cook

Cook a selection of maps for a certain platform

Project

String

Required

Project file to be cooked.

Platform

String

Required

The cook platform to target (for example, WindowsNoEditor).

Maps

String

Optional

List of maps to be cooked, separated by '+' characters.

Versioned

Boolean

Optional

Additional arguments to be passed to the cooker.

Arguments

String

Optional

Additional arguments to be passed to the cooker.

Tag

Tag List

Optional

Tag to be applied to build products of this task.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Copy

Copies files from one directory to another.

Files

File Spec

Optional

Optional filter to be applied to the list of input files.

From

File Spec

Required

The pattern(s) to copy from (for example, Engine/*.txt).

To

File Spec

Required

The directory to copy to.

Overwrite

Boolean

Optional

Whether or not to overwrite existing files.

Tag

Tag List

Optional

Tag to be applied to build products of this task.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

CsCompile

Compiles C# project files, and their dependencies.

Project

String

Required

The C# project file to compile. Using semicolons, more than one project file can be specified.

Configuration

String

Optional

The configuration to compile.

Platform

String

Optional

The platform to compile.

Target

String

Optional

The target to build.

Arguments

String

Optional

Additional options to pass to the compiler.

EnumerateOnly

Boolean

Optional

Only enumerate build products -- do not actually compile the projects.

Tag

Tag List

Optional

Tag to be applied to build products of this task.

TagReferences

Tag List

Optional

Tag to be applied to any non-private references the projects have. (for example, those that are external and not copied into the output directory).

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Delete

Delete a set of files.

Files

File Spec

Required

List of file specifications separated by semicolons (for example, .cpp;Engine/.../.bat), or the name of a tag set

DeleteEmptyDirectories

Boolean

Optional

Whether to delete empty directories after deleting the files. Defaults to true.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Log

Print a message (and other optional diagnostic information) to the output log.

Message

String

Optional

Message to print out.

Files

File Spec

Optional

If specified, causes the given list of files to be printed after the given message.

IncludeContents

Boolean

Optional

If specified, causes the contents of the given files to be printed out.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

ModifyConfig

Modifies a config file

File

File Spec

Required

Path to the config file

Section

String

Required

The section name to modify

Key

String

Required

The property name to set

Value

String

Required

The property value to set

Tag

Tag List

Optional

Tag to be applied to the extracted files

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Move

Moves files from one directory to another.

Files

File Spec

Optional

Optional filter to be applied to the list of input files.

From

File Spec

Required

The pattern(s) to copy from (for example, Engine/*.txt).

To

File Spec

Required

The directory to copy to.

Tag

Tag List

Optional

Tag to be applied to build products of this task.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

MsBuild

Executes MsBuild

Project

String

Required

The C# project file to compile. Using semicolons, more than one project file can be specified.

Configuration

String

Optional

The configuration to compile.

Platform

String

Optional

The platform to compile.

Arguments

String

Optional

Additional options to pass to the compiler.

Verbosity

String

Optional

The MSBuild output verbosity.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

PakFile

Creates a PAK file from a given set of files.

Files

File Spec

Required

List of files, wildcards, and tag sets to add to the pak file, separated by ';' characters.

Output

FileReference

Required

PAK file to output.

ResponseFile

FileReference

Optional

Path to a Response File that contains a list of files to add to the pak file -- instead of specifying them individually.

RebaseDir

HashSet`1

Optional

Directories to rebase the files relative to. If specified, the shortest path under a listed directory will be used for each file.

Order

FileReference

Optional

Script that gives the order of files.

Sign

FileReference

Optional

Encryption keys for this pak file.

Compress

Boolean

Optional

Whether to compress files.

Arguments

String

Optional

Additional arguments to pass to UnrealPak.

Tag

Tag List

Optional

Tag to be applied to build products of this task.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Rename

Renames a file, or group of files.

Files

File Spec

Required

The file or files to rename.

From

String

Optional

The current file name, or pattern to match (for example, *.txt). Should not include any path separators.

To

String

Required

The new name for the file(s). Should not include any path separators.

Tag

Tag List

Optional

Tag to be applied to the renamed files.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

SanitizeReceipt

Task that tags build products and/or runtime dependencies by reading from *.target files.

Files

File Spec

Required

Set of receipt files (*.target) to read, including wildcards and tag names, separated by semicolons.

EngineDir

DirectoryReference

Optional

Path to the Engine folder, used to expand $(EngineDir) properties in receipt files. Defaults to the Engine directory for the current workspace.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

SetVersion

Updates the local version files (Engine/Source/Runtime/Launch/Resources/Version.h, Engine/Build/Build.version, and Engine/Source/Programs/DotNETCommon/Metadata.cs) with the given version information.

Change

Int32

Required

The changelist to set in the version files.

CompatibleChange

Int32

Optional

The engine compatible changelist to set in the version files.

Branch

String

Required

The branch string.

Build

String

Optional

The build version string.

Licensee

Boolean

Optional

Whether to set the IS_LICENSEE_VERSION flag to true.

Promoted

Boolean

Optional

Whether to set the ENGINE_IS_PROMOTED_BUILD flag to true.

SkipWrite

Boolean

Optional

If set, do not write to the files -- just return the version files that would be updated. Useful for local builds.

Tag

Tag List

Optional

Tag to be applied to build products of this task.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Sign

Signs a set of executable files with an installed certificate.

Files

File Spec

Required

List of file specifications separated by semicolons (for example, .cpp;Engine/.../.bat), or the name of a tag set.

Tag

Tag List

Optional

Tag to be applied to build products of this task.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Spawn

Spawns an external executable and waits for it to complete.

Exe

String

Required

Executable to spawn.

Arguments

String

Optional

Arguments for the newly created process.

ErrorLevel

Int32

Optional

The minimum exit code, which is treated as an error.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Stage

Stages files listed in a build receipt to an output directory.

Project

FileReference

Optional

The project that this target belongs to.

Target

String

Required

Name of the target to stage.

Platform

UnrealTargetPlatform

Required

Platform to stage.

Configuration

UnrealTargetConfiguration

Required

Configuration to be staged.

Architecture

String

Optional

Architecture to be staged.

ToDir

DirectoryReference

Required

Directory that the receipt files should be staged to.

Overwrite

Boolean

Optional

Whether to overwrite existing files.

Tag

Tag List

Optional

Tag to be applied to build products of this task.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Strip

Strips debugging information from a set of files.

Platform

UnrealTargetPlatform

Required

The platform toolchain to strip binaries.

BaseDir

DirectoryReference

Optional

The directory to find files in.

Files

File Spec

Required

List of file specifications separated by semicolons (for example, Engine/.../*.pdb), or the name of a tag set.

OutputDir

DirectoryReference

Optional

Output directory for the stripped files. Defaults to the input path, overwriting the input files.

Tag

Tag List

Optional

Tag to be applied to build products of this task.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Submit

Creates a new changelist and submits a set of files to a Perforce stream.

Description

String

Required

The description for the submitted changelist.

Files

File Spec

Required

The files to submit.

FileType

String

Optional

The Perforce file type for the submitted files (for example, binary+FS32).

Workspace

String

Optional

The workspace name. If specified, a new workspace will be created using the given stream and root directory to submit the files. If not, the current workspace will be used.

Stream

String

Optional

The stream for the workspace -- defaults to the current stream. Ignored unless the Workspace attribute is also specified.

RootDir

DirectoryReference

Optional

Root directory for the stream. If not specified, defaults to the current root directory.

RevertUnchanged

Boolean

Optional

Whether to revert unchanged files before attempting to submit.

Force

Boolean

Optional

Force the submit to happen -- even if a resolve is needed (always accept current version).

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

SymStore

Task that strips symbols from a set of files.

Platform

UnrealTargetPlatform

Required

The platform toolchain required to handle symbol files.

Files

String

Required

List of output files. PDBs will be extracted from this list.

StoreDir

String

Required

Output directory for the compressed symbols.

Product

String

Required

Name of the product for the symbol store records.

BuildVersion

String

Optional

BuildVersion associated with these symbols. Used for clean-up in AgeStore by matching this version against a directory name in a build share.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Tag

Applies a tag to a given set of files. The list of files is found by enumerating the tags and file specifications given by the 'Files' parameter. From this list, any files not matched by the 'Filter' parameter are removed, followed by any files matched by the 'Except' parameter.

BaseDir

DirectoryReference

Optional

Set the base directory to resolve relative paths and patterns against. If set, any absolute patterns (for example, /Engine/Build/...) are taken to be relative to this path. If not, they are taken to be truly absolute.

Files

File Spec

Optional

Set of files to work from, including wildcards and tag names, separated by semicolons. If set, resolved relative to BaseDir, otherwise resolved to the branch root directory.

FileLists

File Spec

Optional

Set of text files to add additional files from. Each file list should have one file per line.

Filter

File Spec

Optional

Patterns to filter the list of files by, including tag names or wildcards. If set, may include patterns that apply to the base directory. If not specified, defaults to all files.

Except

File Spec

Optional

Set of patterns to exclude from the matched list. May include tag names of patterns that apply to the base directory.

With

Tag List

Required

Name of the tag to apply.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

TagReceipt

Task that tags build products and/or runtime dependencies by reading from *.target files.

Files

File Spec

Required

Set of receipt files (*.target) to read, including wildcards and tag names, separated by semicolons.

EngineDir

DirectoryReference

Optional

Path to the Engine folder, used to expand $(EngineDir) properties in receipt files. Defaults to the Engine directory for the current workspace.

ProjectDir

DirectoryReference

Optional

Path to the project folder, used to expand $(ProjectDir) properties in receipt files. Defaults to the Engine directory for the current workspace -- DEPRECATED.

BuildProducts

Boolean

Optional

Whether to tag the Build Products listed in receipts.

BuildProductType

String

Optional

Which type of Build Products to tag (see TargetReceipt.cs - UnrealBuildTool.BuildProductType for valid values).

RuntimeDependencies

Boolean

Optional

Whether to tag the Runtime Dependencies listed in receipts.

StagedFileType

String

Optional

Which type of Runtime Dependencies to tag (see TargetReceipt.cs - UnrealBuildTool.StagedFileType for valid values).

With

Tag List

Required

Name of the tag to apply.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Unzip

Extract files from a zip archive.

ZipFile

File Spec

Required

Path to the zip file to extract.

ToDir

DirectoryReference

Required

Output directory for the extracted files.

Tag

Tag List

Optional

Tag to be applied to the extracted files.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

WriteTextFile

Writes text to a file.

File

FileReference

Required

Path to the file to write.

Append

Boolean

Optional

Optional, whether or not to append to the file rather than overwrite.

Text

String

Optional

The text to write to the file.

Files

File Spec

Optional

If specified, causes the given list of files to be printed after the given message.

Tag

Tag List

Optional

Tag to be applied to build products of this task.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Zip

Compresses files into a zip archive.

FromDir

DirectoryReference

Required

The directory to read compressed files from.

Files

File Spec

Optional

List of file specifications separated by semicolons (for example, .cpp;Engine/.../.bat), or the name of a tag set. Relative paths are taken from FromDir.

ZipFile

FileReference

Required

The zip file to create.

Tag

Tag List

Optional

Tag to be applied to the created zip file.

If

Condition

Optional

Whether to execute this task. It is ignored if this condition evaluates to false.

Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback