BuildPatch Tool Instructions (Recommended - 1.5.0)

The BuildPatch tool (BPT) is a command line tool that allows you to securely upload binary files for your product to the Dev sandbox for your product. You can then use the Artifacts and Binaries section of the Dev Portal to attach binaries to the correct artifact for your product offer and conduct testing. (For some organizations, this section may be labeled as Builds.) Using the Release Management process, you can promote binaries uploaded via the BuildPatch tool between sandboxes.

Before you begin, review the sections below to gather the information needed in preparation for using the BuildPatch tool.

You can download the BuildPatch tool (BPT) from the Artifacts and Binaries page of the Dev Portal.

1. In the Dev Portal, navigate to Your Product > Epic Games Store > Artifacts and Binaries.
2. To the top right, click Download Tool.
3. After the download finishes, install the tool on your local machine.

To ensure you have the information needed to use the BPT, retrieve the following IDs from the Dev Portal.

Client ID and Client Secret for the Product

Any user in your organization with Owner, Admin, or Store roles can retrieve the following credentials:

1. In the Dev Portal, navigate to Your Product > Product Settings.
2. Select the General tab.
3. Locate the Build Patch Tool Credentials section and save the client ID and secret.

Artifact Name and ID for the Offer

1. Navigate to Your Product > Epic Games Store > Artifacts and Binaries.
2. From the list, click the name of the offer for which you wish to retrieve credentials.
3. On the Manage Artifact screen, click the arrow icon to the right of Edit Details.
4. Save the artifact name and ID.
5. Repeat as needed for additional offers.

Offer IDs for the Offer

1. Navigate to Your Product > Epic Games Store > Offers.
2. From the list, click the name of the offer for which you wish to retrieve credentials.
3. On the Offer Details screen, locate the IDs section and save the offer ID.
4. Repeat as needed for additional offers.

Due to the way the command prompt interprets \" (a backslash directly followed by a double quote) on the command line, you need to follow at least one of the following pieces of guidance when specifying paths in BuildPatchTool arguments:

• Do not append a trailing slash to your directory names.
• Use forward slashes for directory separators.
• Do not enclose paths in quotes (this is not possible if your path contains one or more spaces).
• Escape only the trailing backslash with another backslash if it is double-quote enclosed (not recommended, as is error prone)

Examples of Valid Path Syntax

• -BuildRoot="D:/MyFolder/"
• -BuildRoot=D:\MyFolder\
• -BuildRoot=D:\MyFolder
• -BuildRoot=D:/MyFolder/
• -BuildRoot=D:/MyFolder
• -BuildRoot="D:\MyFolder\\"

Invalid Path Syntax

The following syntax does not work when defining a path on the Command Line:

-BuildRoot="D:\MyFolder\"

Extract the contents of the BuildPatchTool ZIP file to a machine that has access to the binary you want to upload. The machine will also need Internet access to communicate with the Epic backend.

Authentication is carried out by supplying a Client ID and Client Secret to BuildPatchTool. These must be provided for every operation using command line arguments. These credentials are available in the Dev Portal under Your Product > Product Settings > General tab > Build Patch Tool Credentials.

The ClientId parameter must be provided with every operation that interacts with Epic's backend services. The client secret must be provided by using either of the ClientSecret or ClientSecretEnvVar parameters.

If using the ClientSecret parameter, then your client secret should be passed verbatim as the value of the parameter:

If using the ClientSecretEnvVar parameter, then you pass the name of an OS environment variable which contains the client secret:

We recommend using the ClientSecretEnvVar parameter whenever possible, as this prevents the value of your secret appearing in system logs and command line history. It is a best practice to store your client secret in a secrets management system (such as Hashicorp Vault), and securely inject into your build machine's environment during each run.

Navigate to the Engine/Binaries/Win64/ directory. From a command line, run BuildPatchTool.exe in UploadBinary mode, and point it at your binary (see CLI argument details below).

This will process your binary , upload it to our cloud storage, and register the binary with our backend:

Descriptions for each of the parameters that you have to specify are below. You can also add the "-help" option after any mode (e.g. "BuildPatchTool.exe -mode=PatchGeneration -help") to get information about the required arguments.

You can use the optional -FileAttributeList parameter with the PatchGeneration mode to apply special attributes to files within your binary, such as executable, or tagging groups of files. Note that the launch app (as specified by the -AppLaunch argument) is automatically marked as executable and does not need to be explicitly included in this configuration file. If you do not need to set any special attributes, the -FileAttributeList argument can be omitted.

Your custom FileAttributeList file must be a text file with one or more newline-separated entries. Each line must contain a quoted (BuildRoot-relative) filepath, followed by one or more space-delimited attributes to be applied to the referenced file:

"<QuotedRelativePathToFile>" <list of attributes>

"Relative/Path/To/My/file.bin" executable tag:my_tag "Second/Path/To/A/file.txt" tag:txt_files

The following file attribute flags are supported:

• executable
• tag:my_tag

File tagging is used for providing input to Epic Games Launcher's selective download feature, exposed in installation options screens. If you feel you need to use this feature, please contact an Epic Games representative, as the feature is still in beta.

By default, the desktop shortcut icon will be set to the icon of the app executable indicated by the AppLaunch argument. There are two ways of updating this icon:

• Updating the icon embedded in the app executable
• Adding a separate .ico file with same file name as the app executable (for example: launch.ico should be used if the executable is launch.exe)

After the chunking and upload process has completed, you must apply a label to your binary to make it accessible from the Epic Games Launcher. Applying a label to a binary associates a label name (e.g. "Live") and a platform (e.g. "Win32") with a single binary version. Multiple labels can be assigned to the same binary.

The EpicGamesLauncher client will only ever query for binaries associated with the platform on which it is currently running. For example, the Win32 Launcher client will only ever query with a platform of Win32, so it will never receive binaries labeled with Windows or Mac. A Windows x64 client will only query for binaries using the Windows platform, and so on. If you do actually have a single binary that is compatible with multiple platforms (for example, one compatible with both Windows and Win32), then you can apply two labels (one for each platform) to the same binary to make it available for both platforms without having to re-upload it.

Note: When you remove all labels from a binary, the binary is deleted automatically in seven days. If you want to prevent this deletion, locate the binary in the Inactive binaries section and add at least one label to it.

To remove previously set label you can use UnlabelBinary Mode with the same parameters that were used for LabelBinary Mode:

You can also query our backend to retrieve the list of binaries that you have already registered using the ListBinaries Mode:

To delete a binary, remove all labels from the binary. The binary is deleted automatically in seven days.

The CopyBinary mode allows you to copy binaries from one artifact to another without having to re-upload the binary. This is useful when you want to move a final binary from a Staging artifact to a Live artifact.

The DiffBinaries Tool Mode calculates the difference between two binaries that were already uploaded and outputs statistics for applying the update between them.

Requires v1.4.0 and above

BuildPatchTool uses a general patching system for all binaries uploaded using the UploadBinary mode. The system allows the Epic Games store to update any version of your binary on a user's machine to any other version, minimising the download size to do so.

The BinaryDeltaOptimise mode is designed to take two binaries already uploaded to the Epic Services and produce a smaller download for users who are updating between these two specific versions. We call this an A-to-B patch. Running this command is an optional step that can be taken to improve the user experience when releasing a larger than usual patch, with the majority of your players known to be on a specific binary version (binary "A").

The following is a sample command line to improve delta patching between two binaries:

When running in BinaryDeltaOptimise mode, BuildPatchTool will stream the existing binary data from our cloud network, re-analyze, and upload new A-to-B specific patch data. This process can take longer than the standard PatchGeneration mode if the original download size between BuildVersionA and BuildVersionB is large.

It is generally advised to run BinaryDeltaOptimise mode using your current Live binary as BuildVersionA, and a binary you will release next as BuildVersionB. Ideally, plan to complete this process several days before your release in case of any issues running the tool, such as network loss.

To check on your current Live binary version, you can make use of the ListBinaries mode. If BinaryDeltaOptimise was already run between the two provided BuildVersion values, the process will succeed short circuiting the operation, indicated in the output.

Once the processing is completed, the output will show the improvement achieved.

• "Final unknown compressed bytes, plus meta [Bytes]"
  • This will refer to the new download size achieved for patching between BuildVersionA and BuildVersionB.
• "Original unknown compressed bytes [Bytes]"
  • This will refer to the download size for patching between BuildVersionA and BuildVersionB before the optimisation was run.
• "Improvement: [Percentage]"
  • This will show the improvement that was achieved. The percentage refers to the size of the reduction, larger is better.

The Epic Games store provides full support for Downloadable Content (DLC). The operation of BuildPatchTool is exactly the same for DLC as it is for full games, with the following additional notes:

Each item of DLC will be given its own, unique Artifact ID. Accordingly, each item of DLC will need its own patch generation process to be executed with the appropriate Artifact ID specified. Because each is generated separately, then it is important when performing patch generation for a DLC item that the base game, and all other DLC items are not present at the same time in the folder specified in the BuildRoot parameter during the patch generation process. Alternatively, if the BuildRoot folder does contain the main game or other DLC items, then a -FileIgnoreList parameter can be specified on the BuildPatchTool command line to exclude them from being included in the generated binary (see the ::How to Upload a Binary:: for more details).

When installed on end users’ machines, the main game and all items of related DLC will be installed into the same directory. This leads to the restriction that there must be no files within the main game or any item of DLC which share a common file path. The BuildPatchTool will perform checks on this and prevent the patch generation process from occurring if there are any files which violate this rule. This means that the base game must be able to locate installed DLC by relative path from its install location.

In the short-term, Artifact IDs for DLC items will be allocated to you by Epic, and the association between the main game and the DLC item will be provisioned as part of that process. Longer term, we will look to incorporate this provisioning into a self-service operation on the Developer Portal.

When troubleshooting an error, review the following potential issues first:

• Check Path syntax - BuildRoot="D:\MyFolder\" - WILL NOT WORK
• Ensure spaces have been added between all arguments.
• Files included in the build are subject to Windows MAX_PATH limits (limit of 260 characters); if the upload process is failing unexpectedly, ensure all file path locations do not exceed this limit.
• Most BuildPatchTool arguments are typically provided as absolute paths or relative to the working directory, but the AppLaunch argument must be provided only relative to the BuildRoot location.
• CloudDir contents will grow over time as more builds are processed on the same machine. However, this folder can be cleared at any time without negative impact.

When using the BPT, Make sure your command lines are exact. If you do not use exact commands, you will receive a specific error message.

Please be aware these are only the common errors.

What it means This means that the Client credentials you are using do not grant access to upload to the specified artifact. This could be a typo in the credentials or another parameter, or an issue with the permissions granted to the Client.

What it means This simply means that the BPT is not detecting one or more of the parameters that are listed above. This could simply be that they are missing, or that they were added incorrectly.

What it means This simply means that the BPT is not detecting one or more of the parameters that are listed above. This could simply be that they are missing, or that they were added incorrectly.

What it means This means that the Client credentials you are using do not match our records. This could be a typo in the credentials or another parameter, or an issue with the permissions granted to the Client.

What it means This means that the Client credentials you are using do not have access to the artifact you have specified. This is usually the result of an issue with the permissions granted to the Client, and can be addressed by Service Delivery.

• Ensure you entered the specific BuildPatchTool Client ID and Client Secret; these credentials can be found in the Dev Portal under Your Product > Product Settings > General tab > Build Patch Tool Credentials. EOS SDK credentials cannot be used.
• All required parameters are provided
• Parameters are free of typos, including incorrect capitalization or spacing issues
• Missing quotation marks for a parameter that includes spaces