Patching

To update your project after release, you can use the patching process available through the Project Launcher. During patching, the engine compares all the content post-cook to the originally released cooked content, and uses that to determine what is included in a patch. The smallest piece of content is a single package (like a .ulevel or .uasset), so if anything changes in a package then the entire package will be included in the patch. The method you use to get the patch's .pak file to the users will depend on your distribution platforms, but this procedure will allow you to create a much smaller .pak file that just contains the updated content.

Currently, distribution of the patches hasn't been resolved for all platforms. This procedure will walk you through creating the patch package file, as well as through testing the package file on Windows.

You can patch a project you have previously released using a versioned release. Some things to keep in mind are:

  • Lock down the serialization code paths at the time of release.

  • Keep the released cooked content as the UnrealPak tool uses this to determine which content should be in the patch package file.

  • At runtime, mount both pak files, with a higher priority for the patch file so any content within it is loaded first.

Creating a Patch

In this example, we are patching ShooterGame with a change to the weapon capacity and magazine size.

PatchExample.png

After creating a release version:

  1. Open the Project Launcher, either from the Windows menu within Unreal Editor or using Unreal Frontend .

    1.png

  2. Create a new Custom Launch Profile using the + button.

    2.png

  3. You can double-click on the name and description of the profile to edit them.

    RenamePatch.png

There are a number of settings for the patching process. The steps below break up the settings by category, and you will be able to access all needed settings either by clicking on the Advanced Settings dropdown menus or by setting the top dropdown (i.e. Cook: By the Book) which will change the available options.

PatchSettings.png

Project

  1. You can set the specific project to use, or use Any Project to patch the current project.

Build

  1. Set the build configuration to Shipping.

  2. Optionally, expand Advanced Settings if you need to build Unreal Automation Tool (UAT) as part of the patch process because you are creating the patch on a build machine.

Cook

  1. In the dropdown menu, select By the Book as the cooking method.

  2. Check the boxes for all platforms you would like to cook content for. In this example for Windows testing, we have selected WindowsNoEditor.

  3. Check the boxes for all cultures to cook localizations for.

  4. Check the boxes for all maps to cook.

    This will determine which content is cooked and then compared to the original package file.

  5. In Release/DLC/Patching Settings:

    • Enter the version number to base the patch on.

    • Check the Generate Patch checkbox.

  6. Expand Advanced Settings and make sure the following options are enabled, as well as any others you need for your specific project's distribution method. The below recommended options will minimize your patch size and are the best known defaults:

    • Compress content

    • Save packages without versions

    • Store all content in a single file (UnrealPak)

  7. Also under Advanced Settings, set the cooker configuration to Shipping.

Package

  1. Set the build to Package & store locally.

Deploy

  1. Set the build to Do Not Deploy.

  2. Navigate back to the main profile window using the Back button in the top right corner.

    9.png

  3. Click on the launch icon next to your Patching profile.

    10.png

    The project launcher will go through the building, cooking, and packaging process. This may take some time depending on the complexity of your project.

    11.png

  4. Once the operation is complete, close the window or click on Done.

    12.png

To test the patch on Windows:

  1. Copy the pak file from ShooterGame\Releases\1.0\WindowsNoEditor to ShooterGame\Saved\StagedBuilds\WindowsNoEditor\ShooterGame\Content\Paks

  2. Run ShooterGame.exe from ShooterGame\Saved\StagedBuilds\WindowsNoEditor.

Installing a Patch

The patching process creates a pak file in [ProjectName]\Saved\StagedBuilds[PlatformName][ProjectName]\Content\Paks. This pak file is the patch that should be distributed to users. For example, on Windows, you would create an installer to copy that pak file into the user's [ProjectName]\Releases[VersionNumber][PlatformName] folder, next to the original content pak file.

The patch pak file will automatically be mounted when it is located on the device in any of the pak search directories set in FPakPlatformFile::GetPakFolders. To prioritize patches, the mounting system uses a _p at the end of the filename to determine that it gets priority over other pak files. It can be renamed, but you need to include the _p.pak at the end of the file name.

If you build two patches from the same release version, they are both complete patches, so while installing the second patch, you should also remove the first.