Unreal Engine 5 Documentation has been moved to the Epic Developer Community

Unreal Engine 4.26

Unreal Engine 4.27

Unreal Engine 5.0

Unreal Engine 5.1

Unreal Engine 5.2

Unreal Engine 5.3

> Setting Up Your Production Pipeline > Build Tools > AutomationTool > BuildGraph > BuildGraph Script Tasks

Light Theme

Dark Theme

BuildGraph Script Tasks

Learn how BuildGraph can help you create custom tasks.

Choose your operating system:

Windows

macOS

Linux

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.