BuildPatch Tool Instructions (1.4.0)

There are a number of IDs you will need to locate in the Developer Portal.

Client ID and Client Secret for the product

1. Go to Developer Portal Dashboard > Product > Games Services > Product Settings.
2. View the credentials in Product Settings > SDK Credentials > BPT Credentials.

Artifact Name and ID for the offer

• Go to Product > Artifacts page > Offer Artifact > Edit Details drop-down.

• The Artifact Name and ID display on Manage Artifact modal > Edit Details drop-down.

Offer IDs for the Offer

• Go to Product > Offers page > Offer.

• The Offer IDs are located at the bottom of the Edit Offer modal.

Any user in your Organization with Owner, Admin or Store roles can view your BuildPatch Tool credentials for a product. They can also copy the credentials to the clipboard.

To view your organization’s BuildPatch Tool credentials:

1. Sign in to the Dev Portal.
2. Select the product for which you want to view credentials.
3. Select Product Settings.
4. Scroll down to SDK Credentials > BPT Credentials.
5. To copy the credentials to the clipboard, click Copy:

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)

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

The following syntax will 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 build you want to upload. The machine will also need Internet access to communicate with the Epic backend.

Note: The ZIP file link is always kept up to date with the newest version of the BPT. If you cannot access the file, create a private discussion on our Developer Support site for assistance.

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.

Note: BuildPatchTool uses a unique Client ID and Client Secret, separate from any EOS Client IDs your game may use. EOS Client IDs (which typically begin with xyza) cannot be used with the BuildPatchTool.

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.

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

When 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. Best practice would be to store your client secret in a secrets management system (such as Hashicorp Vault), and having this securely injected into your build machine's environment during each run. How to set this up lies outside of the scope of this document.

Navigate to the Engine/Binaries/Win64/ directory. From a command line, run BuildPatchTool.exe in PatchGeneration mode, and point it at your build (see CLI argument details below). This will process your build, upload it to our cloud storage, and register the build 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.

• OrganizationID – Use the Organization ID string that was provided along with your credentials.

• ProductID – Use the Product ID string that was provided along with your credentials.

• ArtifactID – Specify the Artifact ID string that was provided along with your credentials.

• ClientId – See Authentication.

• ClientSecretEnvVar – See Authentication.

• BuildRoot – The path to the directory containing the build to be read and processed. This should be an absolute path from the drive root, not a relative path. Additionally, it is recommended that this path be located near the drive root, to avoid any files exceeding the OS MAX_PATH limit (typically 260 characters).

• CloudDir – The directory where any existing processed build data will be recognized, and new data added to.

  • As with the BuildRoot, this should be an absolute path from the drive root. This location is used to cache information about existing builds, and should be a different directory from the BuildRoot parameter. It is OK if this directory is initially empty; BuildPatchTool will download information as needed from the Epic backend and store it in the CloudDir.

• BuildVersion – The version string for the build. This needs to be unique for each build of a specific artifact, independent of platform. For example, BuildVersion-1.0 can only exists for Windows or Mac, not both. The build version string has the following restrictions: Must be between 1 and 100 chars in length, whitespace is not allowed, should only contain characters from the following sets a-z, A-Z, 0-9, or .+-_

• AppLaunch – The path to the app executable that should be launched when running your game, relative to (and inside of) the BuildRoot. For Mac builds, this should be the executable file contained within the .app folder, usually in the location Game.app/Contents/MacOS/Game.

• AppArgs – The commandline to send to the app on launch. This can be set to “” when no additional arguments are needed.

• FileAttributeList (Optional) – An absolute path to a text file containing a list of files and corresponding special attributes (e.g. executable bit) that should be set. See Setting Special File Attributes for a description of the file contents.

  • Note that the attributes file should not be inside your BuildRoot to ensure that it does not get erroneously included with your actual build content.

• FileIgnoreList (Optional) – An absolute path to a text file containing a list of files that should be excluded from the generated patch data. Each entry should be on a new line, and be a relative path from BuildRoot. A forward slash ("/") separator should be used.

  • Note that if the ignore file is located inside BuildRoot then its own relative file path needs to be included in the ignore list to avoid it being included in the patch data.

You can use the optional -FileAttributeList parameter with the PatchGeneration mode to apply special attributes to files within your build, 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:

Example entries:

The following file attribute flags are supported:

• executable

• tag:my_tag

File tagging is primarily used to explicitly indicate executable files when uploading Mac builds on Windows machines. The feature is also used by the Epic Games Launcher's selective download feature, which reduces download sizes for a limited number of games with a significant amount of localized assets.

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)

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

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

Run the -help command to generate a list of all required args for the mode.

Example: C:\Users\Name.Name\Desktop\Engine\Binaries\Win64>BuildPatchTool.exe -help -mode=CopyBinary

Most of the required arguments are the same used in the modes listed above.

SourceArtifactId="" — Specifies the ID of the artifact the binary is being copied from

DestArtifactId="" — Specifies the ID of the artifact the binary is being copied to

Requires v1.4.0 and above

BuildPatchTool uses a general patching system for all binaries uploaded using the PatchGeneration 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 ChunkDeltaOptimise 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 build version (build "A").

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

When running in ChunkDeltaOptimise 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 ChunkDeltaOptimise 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 ChunkDeltaOptimise 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.

Example output:

The Epic Games store provides full support for Downloadable Content (DLC).

You can enable artifact download for your add-on offer by selecting Product > Artifacts > Create New Artifact and then associating the new artifact with the add-on offer in question. 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 How to Process a Build for 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.

When using the BPT, make sure your command lines are exact. If they are off, you will get a message about the error you are encountering.

Please be aware these are only the common errors. You can run the -help command in the BPT with the specific mode to get more info on what may be causing the error.

• Error - Failed to retrieve list of binaries from Epic services

• Error - Missing parameters

• Error - Missing credentials

• Error - Authentication error

• Error - Unexpected error

The Client ID and Client Secret being used are specifically indicated for BuildPatchTool use; the correct client is listed as a BPT Client in the Clients section of the Product Settings page. Other clients may exist to interface with EOS features, but will not have BuildPatchTool permissions.

• 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

What it means – 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 – 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 – 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 – 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 – The Client credentials you are using do not have access to the artifact you have specified. Ensure you are using the correct BPT Client as indicated on your Product Settings page.