HotPatcher: A open source UE resource hot patching tool

Important Notice: The author has no platforms or channels to record paid courses, and does not endorse any third-party commercial activities. Please be vigilant and beware of being deceived.
The open-source agreement for this software: It allows free use of functions in commercial projects, but does not permit any third party to charge for any form of secondary compensation based on this plugin, including but not limited to recording paid courses, redistributing the plugin and code, etc.

HotPatcher is a tool for managing hotfix versions and resource packaging, used to track changes in the original resources of the project version to create patches. It supports one-click cooking for multiple platforms, one-click packaging for multiple platform patches, and the editor supports Windows and MacOS. Writing a set of processes to download patches from the server completes a comprehensive game hotfix solution. HotPatcher has been used in many UE projects and will continue to update to support new engine versions. Issues are welcome.

HotPatcher differs from the Patch mechanism in UnrealFrontEnd, as there are some issues with UE’s Patch management project: based on the original project version, it is challenging to create exactly the same patch on different computers, and it is not possible to generate another patch based on the patch version. Additionally, the contents of the patch cannot be previewed intuitively. It is also inconvenient to package external files into pak (such as lua files, db, and other non-assets, which often reside outside the Content directory) and to manage project and patch versions easily.

This plugin aims to solve such problems, using the project’s original resources as version references, managing only the project itself without worrying about other files generated by UE. Moreover, it facilitates operations such as Cooking/generating Pak/extracting resource information from basic packages/version diffs/Patch splitting, etc. It features abundant configuration options and Commandlet support, making it easy to implement automated hot update packaging processes.

Currently supported engine versions are UE4.21-UE5, and it supports the IoStore mechanism! Many friends have privately messaged me with questions about the plugin, so I created a group to discuss UE hot updates and HotPatcher plugin issues (QQ group 958363331). You are welcome to join and exchange technical information related to UE.

To conveniently collect and manage common questions and solutions regarding hot updates and HotPatcher, I have created an article to document and organize them: UE4 Hot Update: Questions & Answers. If you encounter problems, you can check this FAQ page first. Regarding the feedback from many users about inconsistencies between the plugin configuration parameters and the previous recorded videos, it is because the plugin has undergone many updates and iterations. For details on each version’s changes, see the Update Log.

Showcase

Taris World	Yuan Meng Zhi Xing	QQ	ApexLegends Mobile	Xun Jiang OL	Ni no Kuni Intertwined World	Create! Our Planet	Karabikyu
God’s Party	WitiSports	Spirit Realm Star Move	MOSSAI	Beyond City	Sipher Odyssey Coop Roguelite	Nebula Rangers

Statistics for application project list: 1. An analysis of the game’s code, including HotPatcher’s code; 2. Feedback from project personnel. Please contact me to remove any false reports.

Resource Management Framework Based on HotPatcher

HotPatcher is no longer just a hot update packaging tool, but a comprehensive resource management framework covering hot updates, build improvements, package optimization, resource audits, and more.

Forward

Note: This plugin can only produce hotfix content that includes UE resources and externally added files (supports lua). Modified C++ code cannot be hot-updated, and you need to design the architecture yourself. If it is a pure blueprint project, you can fully use this tool for hot updates.

The HotPatcher plugin supports packaging only specified resources based on selection (can specify Include Filters and Ignore Filters, and can Specify Individual Resources), supports recursive dependency analysis of resources (e.g., only packaging a specific map and all its dependent resources). The packaging Path can choose not to include unreferenced resources and will not contain unchanged resources. It will also analyze invalid assets in the project and ignore redirected resources, achieving project asset-based version tracking without the need to manage additional content (such as DDC), requiring only one cooking process before patching to ensure that the cooked content is based on the latest project version (and it also supports automatically cooking all resources to be included during patch generation). It also supports Chunks, supports bMonolithic mode, and the configuration method supports arbitrary combinations, supports exporting resource dependency relationships, and also allows execution of cooking and patching through Commandlet, along with exporting release information; it can be freely combined with CI/CD to achieve your own packaging process.

In addition to containing UE resource files, it additionally supports:

• Adding platform-specific files for specific platforms (such as Wwise bnk files for each platform)
• Including non-resource files cooked from the project, such as AssetRegistry.bin/GlobalShaderCache*.bin/ShaderBytecode*.ushaderbytecode;
• Including ini files for engine, project, and plugins;
• Including external folders and files (such as lua files, video files, etc.), and also customizing mount points for runtime access;
• The produced pak can exclude any UE resource files (as long as no resources are added in HotPatcher), making it convenient to only update lua code or ini configuration files;
• Analyzing the differences in the basic package for different platforms, generating a unified basic package description file for subsequent hot-fix version comparison.

Other features of the plugin include:

• Supporting single resource cooking;
• Supporting importing multi-platform basic package information from PakList*.txt
• Allowing the generation of another patch version based on the previous patch version;
• Supporting detection of uncooked resources;
• Supporting version diffs, allowing you to see additions, modifications, and deletions (but deleted resources in previous versions’ pak cannot be removed, just displayed for diff);
• Supporting detection of duplicate file inclusions;
• Supporting export of all intermediate generation information and configuration of this plugin;
• Supporting custom parameters for UnrealPak (you can specify encryption parameters in line with the project);
• Supporting simultaneous generation of patches for multiple platforms;
• Supporting Chunk for patches, specifying resources in a patch version to be packaged into multiple paks;
• Supporting detection of Chunk’s file inclusions for error handling;
• Supporting packaging each resource in the Patch into an individual pak, supporting any resources (including but not limited to UE assets/external files/various cooked bin data, ini) as long as they can be added in hotpatcher;
• Supporting multithreaded pak packaging without starting UnrealPak.exe, improving execution efficiency;
• Supporting exporting dependency relationships of selected resources;
• The editor supports features like Cook/AddToPatchSettings for convenient operations in the editor;
• Supporting retrieving Shader and other metadata information while cooking;
• Supporting IoStore;
• Supporting incremental updates of Shader, AssetRegistry;
• Supporting Shader Patch.

Additionally, I have also written a batch cooking tool for one-click cooking of specified multiple platforms (of course, command line can also be used), aiming to complete tasks with minimal steps.

I recorded a video on the plugin’s usage instructions:

If you cannot bypass the Great Firewall, you can check the Bilibili link: UE4 Hot Update: HotPatcher Plugin Usage Tutorial

Plugin Usage Process

To facilitate version management, the project must use some version control tool, preferably Git.

1. Open HotPatcher, select ByRelease, and export *_Release.json, which records the information of each specified resource;
2. Use UE to directly package the project for any platform (such as windows/android/ios);
3. Modify/add/delete resources in the project, modify engine/project/plugin settings, etc.;
4. Open HotPatch, select the platform you want to patch in the Cook section and execute Cook (check bCookPatcherAssets);
5. Open HotPatcher, select ByPatch, using the previously exported *_Release.json as the base version, choose the content you need to include in the Pak based on your needs;
6. Click GeneratedPatch, which will generate the Pak file and various information (including the current version’s *_Release.json, allowing the Patch to incrementally update);
7. The generated Pak will contain all the differing content from the last produced package.

Cook Parameter Description

Important: HotPatcher implements a separate cooking process, and there is no need to execute UE’s default cooking process (the Cooker section in the plugin); simply enable bCookPatchAssets in the Patch configuration.

The cooking section in HotPatcher is designed to facilitate cooking multiple platforms when patching, as well as conveniently specifying maps (the plugin will scan all maps in the entire project and list them), so you don’t have to use the command line for every cooking process.

The cooking options are divided into Platforms/Map(s)/Settings:

• Platforms: Select the platforms to cook, multiple selections are possible;
• Map(s): Choose the Map(s) you want to cook, this option will list all maps in the current project, and multiple selections are possible (I also provided options in the code to list Maps in both engine and plugin directories; you can enable it yourself in HotPatcherEditor.build.cs by controlling the values of ENABLE_COOK_ENGINE_MAP and ENABLE_COOK_PLUGIN_MAP);
• Filter(s): You can select only directories to cook, multiple options can be added;
• Settings: Choose cook settings, default options include Iterator/UnVersioned/CookAll/Compressed, and I also provided OtherOptions to specify the parameters you want to cook.

Note: If either a map in Map(s) or CookAll in Settings is not selected, or if Filters does not have the specified directory, cooking cannot proceed. If only CookMap is selected, it will only cook the resources referenced in that Map, and unreferenced resources will not be cooked, so pay attention to this.

Clicking CookContent will output the cook log to UE’s OutputLog.

ByRelease Parameter Description

The ByRelease operation exports a json file that records the hash values of each asset resource selected at export, which allows us to know whether the resource has been modified in subsequent patches based on this hash value.

Release Settings

• VersionId: Specifies the version of the resource information being exported.
• ByPakList: To generate the release configuration from PakList.
• PlatformsPakListFiles: PakList*.txt files generated when creating the base package, multiple platforms can be specified at once to analyze file differences across platforms and record these differences for generating the project’s Release.json files across these platforms for a unified description of basic package information.

In the absence of specifying PakList*.txt to export the release, the exported release.json only contains resources referenced in the project; non-referenced resources will not be included. However, when the engine packages by default, it will include some non-referenced resources, which can lead to situations where some resources exist in the basic package but are not recorded in release.json. Using PakList*.txt avoids this issue.

• IncludeFilter: Scans which directories the current release will include.
• IgnoreFilter: Which directories the current release will ignore.
• bAnalysisFilterDependencies: Analyze dependencies of resources in the selected filters.
• AssetRegistryDependencyTypes: Types of referenced resources to include in the dependency analysis of resources in the selected filters, depending on whether bAnalysisFilterDependencies is enabled.

namespace EAssetRegistryDependencyType
{
	enum Type
	{
		// Dependencies which don't need to be loaded for the object to be used (i.e. soft object paths)
		Soft = 0x01,

		// Dependencies which are required for correct usage of the source asset, and must be loaded at the same time
		Hard = 0x02,

		// References to specific SearchableNames inside a package
		SearchableName = 0x04,

		// Indirect management references, these are set through recursion for Primary Assets that manage packages or other primary assets
		SoftManage = 0x08,

		// Reference that says one object directly manages another object, set when Primary Assets manage things explicitly
		HardManage = 0x10,

		// Note: Also update FAssetRegistryDependencyOptions when adding more flags
	};

	static const Type None = (Type)(0);
	static const Type All = (Type)(Soft | Hard | SearchableName | SoftManage | HardManage);
	static const Type Packages = (Type)(Soft | Hard);
	static const Type Manage = (Type)(SoftManage | HardManage);
}

Soft refers to resources with FSoftObjectReference, and Hard refers to direct resource references. If both Soft and Hard references are needed, you can choose Package. This option defaults to Package, unless you’re handling resource references yourself.

• IncludeHasRefAssetsOnly: Conduct dependency analysis on the selected filter’s resource files (recursive analysis to Maps). If resources are unreferenced, they will not be packaged into the Patch.
• IncludeSpecifyAssets: A structured array where you can specify a single resource in the current release; the first parameter must specify the resource, and the second parameter controls whether to analyze and include dependencies of the current specified resource in the pak.
• Add Extern Assets to Platform: Used to specify different files to include on different platforms.
  • Target Platform: The platform(s) that will include these files (AllPlatform will include for every platform);
  • AddExternFileToPak: Records non-resource files included in the release;
  • AddExternDirectoryToPak: Records non-resource files included in the release.

The AddExternFileToPak and AddExternDirectoryToPak correspond to settings like Additional Non-Asset Directories To Package in Project Settings - Packing, used to mark non-resource files included in the local package.

SaveTo

• SaveAssetDependency: Whether to store the dependency relationships of the selected resources in the current release version.
• SaveReleaseConfig: Whether to store all options information of the current release.
• bBackupMetadatas: Whether to back up the Metadata directory of the current version.
• BackupMetdataPlatforms: Select the platforms for backing up the Metadata; this option depends on bBackupMetadatas=true.
• SavePath: Directory for storing the current release information, which will create a folder with the name VersionId in the current directory where all files will be placed, supporting relative paths like [PROJECTDIR].

Note: When exporting a release, resource inclusion must align with UE’s direct packaging settings, as the release exported here records resources included in the package directly produced by UE.

ByPatch Parameter Description

ByPatch is the actual tool for packaging and generating the Pak, which can be based on a previously exported version (from the JSON file exported by ByRelease), including external files/folders and configuration files (ini), non-resource files (like AssetRegistry.bin, etc.), while supporting multiple platforms, inputting UnrealPak parameters and exporting various information about the current Patch.

Supports specifying resource filters:

HotPatcher patching options analyze as follows:

BaseVersion

• bByBaseVersion: Whether the patch is based on a specific base version. If false, only the selected filter files will be packaged (dependency analysis will still be performed) and the added external files. If true, a base version must be specified; otherwise, the Patch cannot execute. This property will also control whether Diff information is generated. If false, no Diff will be generated (diffing without a base version is meaningless).
• BaseVersion: The option that should select the version file the Patch is based on; it can be ByRelease or the last generated patch, defaulting to *_Release.json.

PatchSettings

• VersionId: The ID of the current patch version.
• IncludeFilter: Scans which directories the current Patch will track changes to.
• IgnoreFilter: Which directories the current Patch will ignore for changes (before resource dependency analysis).
• bForceSkipContent: Whether to forcibly ignore certain resources (for filtering the final results of the Patch).
• Force Skip Content Rules: Forcibly ignore resources in certain directories (for filtering the final Patch results), applicable to ignore Editor’s Content, like /Engine/Editor and /Engine/VREditor.
• Force Skip Assets: Ignore specified resources in the final results of the Patch.
• bAnalysisFilterDependencies: Perform dependency analysis on the selected resource filters.
• Recursive Widget Tree: For UserWidget resources that change in the current Patch, recursively analyze and include their parent Widget resources to resolve issues where child control modifications do not affect the parent control.
• AssetRegistryDependencyTypes: Same meaning as described in Release.
• IncludeHasRefAssetsOnly: Perform dependency analysis on the resource files in the selected filters (recursive analysis to Maps). If resources are unreferenced, they will not be packaged into the Patch.
• IncludeSpecifyAssets: Structured array that can specify individual resources to be included in the Pak; the first parameter must specify the resource, the second parameter controls whether to analyze and include dependencies of the current specified resource in the pak, and the third parameter AssetRegistryDependencyTypes corresponds to the meaning described in Release.
• IncludeAssetRegistry: Include AssetRegistry.bin file in the current Pak created from the Patch. (deprecated)
• IncludeGlobalShaderCache: Include GlobalShaderCache-*.bin file in the current Pak created from the Patch. (deprecated)
• IncludeShaderBytecode: Include PROJECT_NAME\Content\ShaderArchive*.ushaderbytecode files in the current Pak created from the Patch. (deprecated)
• IncludeEngineIni: Includes ini files in the engine directory in the current patch’s Pak, and it will also include platform-specific ini files.
• IncludePluginIni: Includes ini files from all enabled plugins (from both the engine directory and project directory) in the current patch’s Pak.
• IncludeProjectIni: Includes project ini files in the current Patch’s Pak (won’t include DefaultEditor*.ini).
• bEnableExternFilesDiff: Whether to perform diff comparisons on added external files, mainly for packaging modified or new external files only.
• Add Extern Assets to Platform: Used to specify different files to include on different platforms.
  • Target Platform: The platform(s) that will include these files (AllPlatform will include for every platform);
  • AddExternFileToPak: Add external non-resource files to the Pak, such as txt or videos;
  • AddExternDirectoryToPak: Records non-resource files in the release.

The elements of AddExternFileToPak require:

1. FilePath must specify the path of the selected file.
2. MountPath is the mount path of this file when packaged into the Pak, and defaults to ../../../PROJECT_NAME/.

During game runtime, it can be accessed via FPaths::ProjectDir. For example, if AAAAA.json’s MountPath is ../../../HotPatcherExample/AAAAA.json, the path loaded during runtime will be:

FPaths::Combine(FPaths::ProjectDir(),TEXT("AAAAAA.json"));

All files in the Pak can be accessed via IPlatformFile.

• AddExternDirectoryToPak: Structured array that adds external folders to the Pak; the first parameter (DirectoryPath) specifies the file system folder path, and the second parameter (Mount Point) specifies the directory’s mount path in the Pak. All files under the specified folder will be recursively included, and the mount paths will be relative to the specified MountPoint.

• IncludePakVersionFile: Whether to store version information in the current Patch created.

• PakVersionFileMountPoint: Controlled by IncludePakVersionFile and specifies where the *_PakVersion.json file will be mounted in the Pak file, defaulting to ../../../PROJECT_NAME/Extention/Versions.

ChunkOptions

I have added Chunk functionality to HotPatcher, supporting packaging resources from a Patch into different Paks. For example, packaging all Package resources into one pak (or packaging specified maps from the current Patch into a specific pak), packing all lua files into another pak.

The parameters supported by Chunk are as follows:

• bEnableChunk: Whether to execute Chunk on the current Patch.
• bCreateDefaultChunk: Whether to create a default Chunk to store files not found in manually specified Chunks.
• ChunkInfos: A list of chunk information used to specify which resources should be included in the Chunk.

ChunkInfos is an array of FChunkInfo structure whose members are:

• ChunkName: The name of the current chunk.
• bStorageUnrealPakList: Whether to store the PakCommand.txt of the current Chunk.
• bStorageIoStorePakList: Whether to store the IoStore paklist files for the current chunk.
• AssetIncludeFilters: Specify resource filters for the Chunk (note that selected filters won’t be subjected to dependency analysis).
• AssetIgnoreFilters: Specify ignore filters for the Chunk.
• bAnalysisFilterDependencies: Perform dependency analysis on the selected filters.
• AssetRegistryDependencyTypes: Same meaning as described in Release.
• IncludeSpecifyAssets: Specify which individual resources are included in the chunk, supporting dependency analysis.
• AddExternFileToPak: Add external files to the Chunk.
• AddExternDirectoryToPak: Add external directories to the Chunk, supports recursive analysis.
• InternalFiles: Specify whether AssetRegistry.bin and ini files will be included in the Chunk.

In essence, the parameters for Chunk are similar to those selected for Patch and can be configured as needed.

Note: The principle of Chunk is to first select resources in the Patch settings, executing a complete resource analysis of the Patch, and the analyzed results are used for Chunk configuration filters, meaning that the resources contained within the Chunk must exist within this Patch, and AssetIncludeFilters will not perform dependency analysis. If a resource in the filters from the Patch references other modules, such as the engine or plugins, the corresponding directories need to be specified in the filters for the Chunk as well.

Each resource specified in a Chunk can be repeated; a single resource can be included in both Chunk A and Chunk B.

Moreover, I added error prompts for Chunk, where if Chunk mode is enabled, but not all resources from the Patch are specified within the Chunk, a prompt will appear at the bottom of HotPatcher’s Information about which resources were not included in the Chunk, simplifying error handling.

PakOptions

• bCookPatchAssets: Whether to enable cooking for uasset in the Patch. If enabled, all uasset resources within the current Patch will be cooked when packaging (this will increase the time for generating the Patch, and requires waiting for the cooking to finish).

• Io Store Settings:

• bIoStore: Activate Io Store;

• bAllowBulkDataInIoStore: Permit bulk data to be stored in Io Store;

• IoStorePakListOptions: Parameters passed to IoStorePaklist, such as -compress;

• IoStoreCommandletOptions: Parameters passed to IoStoreCommandlet;

• PlatformContainers: Specify each platform’s global.utoc and IoStore Patch path;

• bStoragePakList: Store the IoStore paklist files;

• bStorageBulkDataInfo: Store StorageBulkDataInfo. When CookPatchAssets is enabled, cooking information will be stored in BulkDataInfo.ubulkmanifest, which can be disabled (currently does not support cooking Patch Assets compatible with IoStore).

• Unreal Pak Settings

• UnrealPakListOptions: Parameters passed to the paklist file, such as -compress;

• UnrealCommandletOptions: Parameters passed to UnrealPak.

• Encrypt Settings

• bEncrypt: Enable encryption;

• bEncrypt: Encrypt Index;

• bUseDefaultCrypt.ini: Use configurations from config/DefaultCrypt.ini in the project;

• bSign: Enable signing;

• CryptoKeys: Specify the Crypto.json file; can specify when bUseDefaultCrypt.ini is not checked.

• DefaultPakListOptions: This array allows specifying parameters for packaging each resource in the pak or IoStore, like -compress.
• DefaultCommandletOptions: This array allows specifying additional parameters for the command when executing pak/IoStore.

PakTargetPlatforms: This array allows selecting multiple platforms for which the Patch will be output, note that the selected platforms have already been cooked.

PakOptions Advanced:

• bCustomPakNameRegular: Whether to rewrite the pak naming rules, controlling whether PakNameRegular is modifiable.
• PakNameRegular: The naming convention for generating paks, you can control it using preset variable values. Currently, the preset values are: {VERSION}/{BASEVERSION}/{CHUNKNAME}/{PLATFORM}, and during generation, they are replaced with the specific values configured at the time. The default naming rule is {VERSION}_{CHUNKNAME}_{PLATFORM}_001_P; if Chunk is not enabled and {CHUNKNAME} is empty, it will process out two consecutive __.

SaveTo

• bIgnoreDelatedAssetsInfo: Clean out deleted asset/file information in the Patch information; enabling this means that deleted files will not be recorded.
• bStorageDeletedAssetsToNewReleaseJson: Control whether resources deleted in the ContentBrowser will be stored in the new ReleaseJson; for specifics, please refer to the 2020.11.07 Update.
• bStoragePakList: Whether to store the -Create parameter file for UnrealPak.exe.
• bStorageDiffAnalysisResults: Whether to store the differences of the current Patch version from the Base version.
• bStorageAssetDependencies: Whether to store the dependency relationships of the selected resources in the current Patch version.
• bStoragePatchConfig: Whether to store all options information of the current Patch.
• bBackupMetadatas: Whether to back up the Metadata directory of the current version.
• SavePath: Current Patch information storage location. A folder named VersionId will be created in the current directory to store all files.

Advanced

• bStandaloneMode: Whether to run in standalone mode; checking will launch a separate UE process to carry out Patch tasks, which will not block the current editor. This option is recommended when dealing with large resource scales.
• bScanCacheOptimize: Enabling scan cache optimization can speed up dependency analysis.

ByShaderPatch Parameter Description

ShaderPatch compares and patches by specifying the new/old version Metadata directories and reading the .ushaderbytecode files in the ShaderLibrarySource directory.

Version

• VersionID: The current version number of ShaderPatch.

Config

• ShaderPatchConfigs: Configuration for ShaderPatch, which is a structure.

USTRUCT(BlueprintType)
struct FShaderPatchConf
{
	GENERATED_USTRUCT_BODY()
	
	UPROPERTY(EditAnywhere, BlueprintReadWrite)
		ETargetPlatform Platform;
	UPROPERTY(EditAnywhere, BlueprintReadWrite)
    	TArray<FDirectoryPath> OldMetadataDir;
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    	FDirectoryPath NewMetadataDir;
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
   		bool bNativeFormat;
	// since UE 4.26 (Below 4.26 this parameter has no effect)
	UPROPERTY(EditAnywhere, BlueprintReadWrite)
		bool bDeterministicShaderCodeOrder = true;
};

Save

• bStorageConfig: Whether to store the current configuration file.
• SavePath: The generation path for the Patch and the configuration files.

Advanced

• bStandaloneMode: Launch a separate process to execute tasks without blocking the editor.

Commandlet

I have provided four Commandlets for the plugin, namely HotCooker, HotPatcher, HotRelease, and HotShaderPatch, for cooking, generating patches, exporting release information, and ShaderPatch.

These four Commandlets can specify the -wait parameter to wait for input after executing (to prevent the window from closing automatically).

The attributes in the Commandlet specified -config file can be replaced, using -PropertyName= to specify (currently does not support specifying arrays). If it is a nested structure attribute, like SavePath.Path, you can specify it using .: -savepath.path=.

HotPatcher’s Commandlet enhancement support can be found in the update log: 2021.01.14 Update

HotCooker

Important: This feature has been deprecated; simply check bCookPatchAssets.

Cooking usage:

UE4Editor.exe PROJECT.uproject -run=HotCooker -config="cook-config.json"

When exporting cook configurations from the editor, if all maps are selected, bCookAllMap will be true in the exported configuration file; executing it in the Cooking Commandlet will cook all maps, and as long as bCookAllMap is true, it will cook all maps regardless of the number of maps in the CookMaps.

HotPatcher

Patch usage:

UE4Editor.exe PROJECT.uproject -run=HotPatcher -config="patch-config.json"

HotRelease

Release Usage:

UE4Editor.exe PROJECT.uproject -run=HotRelease -config="export-release-config.json"
```#### HotShaderPatch

ShaderPatch Usage:

```cpp
UE4Editor.exe PROJECT.uproject -run=HotShaderPatch -config="export-shaderpatch-config.json"

The files received by their -config parameter can all be exported from the editor via plugins.

Editor Support (UE4.23+)

HotPatcher has added an extension to the right-click menu of selected resources in the ContentBrowser, enabling one-click Cook and adding selected resources to the Patch Setting.

Cook

AddToPatchSettings

Project Settings

The plugin supports right-clicking selected resources in the editor for Cook and packaging. To facilitate configuration, a configuration option for HotPatcher has been created in Project Settings:

This can be used to specify UnrealPak parameters, encryption configurations, storage directories for packaging, etc.

Update Log

2024.04.07 Update v82.0

Update address: v82.0, extensive optimizations and bug fixes have been made compared to the previous version.

No matter which engine version you use HotPatcher with, it is strongly recommended to update to the latest version for easier troubleshooting of issues.

Update contents are as follows:

1. Fixed bug where *.m.ubulk files were not packed in certain cases.
2. Optimized PAK packaging time, caching and multithreading optimizations for scanning many files, greatly improving packaging speed.
3. Supported Accompany COOK mode.
4. Added more performance tags.
5. Optimized log levels.
6. Supported cache-ddc-only Cook mode.
7. Modules automatically load all ShaderLibrary in ../../../PROJECT_NAME/ShaderLibs on startup.
8. Support for Nanite and WP COOK.
9. WP differential update support (due to WP’s One File Per Actor mechanism, modifying WP scenes will not cause changes to the level resources themselves; I have extended a detection mechanism to achieve differential detection for WP).
10. Optimized access to FExternFiles.
11. Optimized Release record’s external files from absolute paths to tagged paths.
12. Fixed issue causing false files when COOKing in UE5.
13. Fixed issue with paths containing // when exporting release.
14. Fixed inaccurate PackageTracker retrieval by PatcherProxy.
15. Optimized PackageTracker implementation to remove already tracked resources.
16. Optimized PackageTracker for recursive tracking analysis.
17. Unified locks for ParallelFor in CollectPakCommand to avoid contention issues.
18. Supported passing a list of LongPackageName for packaging using -AddAssetsByFile= parameter.
19. Fixed issue where ShaderLib was not packed into pak.
20. Allowed adding Pre and Post tasks in the Cmdlet during Cook.
21. Optimized plugin Slate implementation, supporting secondary menus in the Toolbar, enabling direct selection to open corresponding pages.
22. Supported listening for process crashes, storing crash files in Saved/HotPatcher/Crashs.
23. Compatible with GameFeaturePacker and ShaderPatcher mods (both need to be updated to the latest).

The v82.0 has been officially released and can be pulled and updated from hxhb/HotPatcher. The Patch page of the old version plugin will also have a new version update prompt.

2023.06.05 Update v81.0

Update address: Release v81.0

1. Fixed log output issue of CmdlHandler, DDC Backend configuration not cleaned.
2. Cmdlet supports TargetPlatformsOverride to replace the TargetPlatform in the configuration file.
3. When executing Patch, you can prohibit resource scanning through NoSearchAllAssets.
4. Optimized GC timing.
5. Fixed issue where PackageTracker tracked resources included in base version but not changed.
6. Optimized Notification output format.
7. Unified saving path rules for config/release/diff during patching.
8. Supported only cooking Shader class resources.
9. Supported CookAdvancedOptions option.
10. Supported output of PakResults.json to record all packaged resources and obtain the interface.
11. Optimized Log output, no unnecessary Error level logs.
12. Avoided cooked file check loading resources.
13. Supported ChunkAliasName as an alias for Chunk, supporting Chinese.
14. Optimized LoadShaderbytecode related code.
15. Fixed invalid AESKey issue when importing from encrypted pak.
16. Fixed ambiguity of logical operators during resource analysis on the Linux platform.
17. Added more ProfilingTags.
18. Updated MOD version.
19. Fixed UE5.1 Linux compilation errors.
20. Fixed issue where each Chunk contained all changes.
21. Fixed extra %s in GetProjectNotAssetDirConfig.
22. Fixed timing issue where TargetPlatform registration was later than CDO.

Note: This version does not support UE5.2, and this should be the last version supporting UE5.1. Due to implementation changes in the UE5.2 engine, future updates will only support the latest version of UE5.

2023.02.28 Update v80.1

Update address: Release v80.1

• Fixed ErrorLog caused by invalid paths in PackageTrackerAsCluster.
• Adjusted the output path of Metadata.
• Supported obtaining the list of resources involved in packaging.
• Optimized the tracking implementation of PackageTracker.
• Fixed bug of ForceSkip Directory/Asset filtering.
• Fixed competition issues when processing PakCommand in multithreading.
• Fixed timing issue where TargetPlatform registration was later than CDO.
• Fixed the issue where PackageTracker’s resources were not packed (resources from PackageTracker undergo ForceSkip detection).
• Set bSupportWorldComposition to default false.

2023.01.08 Update v80.0 HotPatcher Modular

Update address: Release v80.0, HotPatcher’s modular transformation and development plan。

1. Fixed issue where Regular related Categories were not displayed.
2. Optimized CmdHandler implementation to support Editor and Runtime Config Override.
3. Modular transformation of HotPatcher, see HotPatcher’s modular transformation and development plan for details.
4. Created ByShaderPatch and ByGameFeature as independent Mods.
5. Optimized the startup process and priority of the plugin, supporting module extensions.
6. Supported preview of currently installed modules and checking for updates of individual modules.

2022.12.30 Update v79.0

Update address: Release v79.0

1. Optimized basic implementation and closed unnecessary Log outputs.
2. Optimized additional Shader compilation for dependent loaded materials, supports NoPostLoadCacheDDC parameter control (this optimization requires engine modification in UE4).
3. Optimized CookCluster allocation strategy.
4. Optimized Pak file list collection.
5. Optimized resource analysis performance.
6. Optimized module extensibility.
7. Fixed compatibility issues across engine versions.
8. Fixed Shipping C4172 ERROR.
9. Fixed packaging errors due to unsupported WP (Found more than one registered Cook Package Splitter).
10. Supported PakSaveDirRegular to customize the output path of Pak.
11. Supported PakPreset/CookAndPak to execute in a unified way.
12. Supported global AllowCookPlatforms.

To support the NoPostLoadCacheDDC parameter in the source code version of the engine, the following code wrapped in [lipengzha] needs to be added:

The Launcher engine does not support this optimization by default, which may slow down Cook time but has no functional impact.

… (code omitted for brevity)

2022.11.29 Update v78.0

Update address: Release v78.0

Note: Because UE5 is still in its early stages, Epic’s updates have considerable changes to the engine. Therefore, HotPatcher’s support for UE5 only accommodates the latest engine version, and compatibility with other versions (such as UE5 EA/EA2/5.0.3, etc.) is not considered. Please upgrade to the latest version of UE5 or continue using v77.0. UE4.x can update to the latest version of the plugin.
Special Note: Currently, support for UE5 World Partition is not adapted, so do not use it for packaging such maps.

• Supported UE5.1.0 (previous versions of UE5 are no longer supported).
• Fixed issue with Patch enabling PreCachePlatformData.
• Fixed crashes caused by Cook due to GC in the Editor.
• Fixed issues causing the Commandlet workflow to hang.
• Optimized cross-version compatibility.
• LICENSE updated, see README.

2022.10.26 Update v77.0

Update address: Release v77.0

• Refactored the Cook mechanism of the plugin in UE5.
• Addressed the issue where ForceSkip was ineffective when enabling PackageTracker.
• Fixed directory scanning issues in UE5 (/All/Game).
• Fixed resource dependency analysis issues in directories.
• Optimized resource scanning, allowing the forced ignore of certain resources.
• Supported custom saving of the Cooked directory.
• Cook Cluster counting.
• Optimized Log output.
• Fixed compatibility issues across engine versions.
• Changed Chunk’s Error status from including files to Warning.
• Fixed issues where some HashCalculators did not pass.
• Various detail fixes and enhancements.

  2021.05.17 Update

• Fixed warnings in 4.26 / compilation errors in 4.22
• Added option for GScanCacheOptimize (enabled by default)
• Added ToolTips for Patch/Release/ShaderPatch buttons, showing which necessary options have not been configured.

#### 2021.05.13 Update

• Fixed crash issues
• SavePath/BaseVersion and other paths support symbol replacement

Optional symbols are:

[ENGINEDIR]
[ENGINE_CONTENT_DIR]
[PROJECTDIR]
[PROJECT_CONTENT_DIR]
[PROJECT_SAVED_DIR]
[PROJECT_CONFIG_DIR]

During execution, these will be replaced with actual local directories, allowing all paths in the configuration to be specified as relative paths, which can export completely generic configuration files.

• Optimized the efficiency of dependency scanning

Same patch configuration for the same project:

1. Using the previous plugin version, analyzing dependencies took 1m46s, optimized to 33s
2. Complete patch time reduced from 4:24 to 2:40 (including cooking resources)

There are still a few places in the plugin where execution efficiency can be optimized, to be done when time allows.

2021.04.28 Update

Ignored the -compress parameter for the ExtensionsToNotUsePluginCompression type specified in BaseEngine.ini.

BaseEngine.ini

[Pak]
+ExtensionsToNotUsePluginCompression=uplugin
+ExtensionsToNotUsePluginCompression=upluginmanifest
+ExtensionsToNotUsePluginCompression=uproject
+ExtensionsToNotUsePluginCompression=ini
+ExtensionsToNotUsePluginCompression=icu
+ExtensionsToNotUsePluginCompression=res

The purpose is that if these types of files are packaged and use automatic mounting, the corresponding compression algorithm module may not have been started, leading to failure loading these types of files. UE performed checks when packing the basic package, and the plugin also has corresponding support.

2021.04.18 Update

• Support for editing the whitelist configuration for Cook platforms via right-click in the editor
• Support for directly selecting resources in the editor to right-click and package them into Pak

In Project Settings - Plugins - HotPatcher there are configuration options:

When the whitelist is enabled, the platforms that appear when right-clicking in the editor will only show the set options:

A new Cook And Pak Actions option has been added to the right-click menu, allowing users to right-click multiple selected resources and directly cook them into Pak, with the default storage directory being Saved/HotPatcher/Paks, which can be modified through configuration.

2021.03.25 Update

• Add bDeterministicShaderCodeOrder for 4.26+

bDeterministicShaderCodeOrder is declared in UProjectPackagingSettings, added in 4.26, to control the storage order of shaders during packaging.

Editor/UnrealEd/Classes/Settings/ProjectPackagingSettings.h

/** 
 * With this option off, the shader code will be stored in the library essentially in a random order,
 * squarely the same in which the assets were loaded by the cooker. Enabling this will sort the shaders
 * by their hash, which makes the shader library more similar between the builds which can help patching, but
 * can adversely affect loading times.
 */
UPROPERTY(config, EditAnywhere, Category = Packaging, meta = (EditCondition = "bShareMaterialShaderCode"))
bool bDeterministicShaderCodeOrder;

2021.03.23 Update

• Fixed compilation errors on 4.22
• Added HotRelease to automatically back up Metadata files based on paklist information

2021.03.15 Update

• Added options to back up Metadata directories for Release/Patch

The current project’s Metadata directory will be copied to the Release/Patch directory (BackupMetadatas), making it convenient to manage DevelopmentAssetRegistry.bin and Shaderbytecode, and can be used for version asset auditing as well as Shader Patch.

2021.02.23 Update

• ShaderPatch file generation prompts
• ShaderPatch Commandlet (-run=HotShaderPatch)
• Fixed Shader Patch Reset Config errors
• Code optimization

Solution for ShaderPatch crashing in 4.25+: ShaderPatch Issue in UE4.25

2021.02.01 Update

• Fixed crash caused by stack overflow when checking Recursive Widget tree; related issues: Checking recursive widget tree may occasionally cause stack overflow deadlocks; some assets will occur every time.

2021.01.28 Update

• Fixed inability to launch a new process during DebugGame Editor runtime
• Added option bStandaloneMode, which controls whether to launch new processes to execute tasks (true will launch a new process)

2021.01.22 Update

• The Patch Commandlet of HotPatcher can specify platforms

Added by the way of -AddPatchPlatforms=WindowsNoEditor,Android_ASTC,IOS, multiple platforms can be separated by ,.

2021.01.20 Update

• Support for multiple paklist files when the basic package is divided into Chunks

2021.01.19 Update

• Support for a generic external file specification mode, which can solve the use of generic configurations across different project paths

When specifying external files/folders, you can use [PROJECTDIR] which will be replaced with the actual project directory during execution.

Optional paths are:

[ENGINEDIR]
[ENGINE_CONTENT_DIR]
[PROJECTDIR]
[PROJECT_CONTENT_DIR]
[PROJECT_SAVED_DIR]
[PROJECT_CONFIG_DIR]

Note: During the production process, the real path will be replaced in the current configuration (the configuration files generated automatically for Patch and Release are absolute paths, but you can manually export configuration files based on relative paths in the editor).

2021.01.18 Update

• Release/Patch generation does not block the Editor
• Log can be seen directly in the Editor
• Unified the method for creating notifications in UE

This update changes the previous blocking method of the Editor to launching a Commandlet process task, which will not affect the current editor process, similar to the packaging process in UE, avoiding the anxiety caused by freezing the Editor.

2021.01.14 Update

• Fixed path errors when cooking plugin resources in the Cook Engine directory
• byRelease supports command line import of PlatformPakList

Add by using -AddPlatformPakList=, followed by platform name + PakList file (supports multiple files, separated by +), multiple platforms can be separated by commas.

-run=HotRelease -byPaklist=true -AddPlatformPakList=WindowsNoEditor+D:\PakList_FGame-WindowsNoEditor.txt -savepath.path="D:\\"

• All three Commandlets support replacing parameters in the Config

• The HotRelease Commandlet can operate without specifying a config file, directly specifying values (requires specifying the imported paklist file)

2021.01.13 Update

• Fixed failure of Cook when Patch includes plugin resources
• Fixed issue where Commandlet generated Patch could not load resources
• Various other optimizations

2021.01.11 Update

• Support importing configurations from the project into Patch and Release Settings

Project Settings - Packaging - Additional Asset Directories to Cook will be added to AssetIncludeFilters.
Project Settings - Packaging - Directories to never cook will be added to AssetIgnoreFilters.
Project Settings - Packaging - Additional Non-Asset Directories To Package will be added to AddExternAssetsToPlatfotm (AllPlatform).

The AlwaysCookMaps and all maps configured under the AllMaps section in Config/DefaultEditor.ini will be added to IncludeSpecifyAssets, and bAnalysisAssetDependencies will be checked.

2021.01.08 Update

• Support adding directories to PatchSettings in ContentBrowser
• Fixed StaticFindObject crash error caused by generating Patch via Commandlet when CookAsset is checked

LogWindows:Error: Illegal call to StaticFindObject() while serializing object data!

2020.12.14 Update

• Added the UFlibPakReader function library, which allows reading files in Pak without mounting them

2020.12.11 Update

• Supports Shaderbytecode Patch, configured through the byShaderPatch page;

Requirements for Shaderbytecode Patch:

• Backup the Cooked/PLATFORM/PROJECT_NAME/Metadata directory for each packaging;
• Compare the latest version’s Cooked/PLATFORM/PROJECT_NAME/Metadata with the old version’s Metadata;
• The generated ushaderbytecode file can be packed using HotPatcher in the form of external files and loaded at runtime;

Note: This feature works normally in UE4.24 and earlier versions, but triggers exceptions in 4.25+, the specific reason analysis is here: ShaderPatch Issue in UE4.25. Solving this issue requires modifying the engine code, which can be done based on the reason analysis in the notes above.

2020.12.10 Update

• Fixed export failure issue of the HotRelease Commandlet

2020.12.04 Update

• HotPatcher supports UE4.26!
• Fixed an issue where modifying and saving after cooking resources in the editor led to failures on subsequent loads

2020.11.26 Update

• Fixed path errors when cooking resources in the Content Browser
• Fixed an issue where previews could not be displayed in new version code

2020.11.08 Update

• Supports checking for Cook failures when cooking individual resources (for newly created resources, the obtained UPackage is incomplete, cooking with it will crash)
• When right-clicking to cook resources in ContentBrowser, supports failure prompts.

Note: If new resources have been created in the project, directly cooking these resources is problematic, as the data in the Package of the newly created resource obtained through the engine is incomplete, leading to crashes during cooking. The current strategy in the plugin is to check whether the UPackage data to be cooked is correct; if it is not, those resources will be ignored.

A temporary workaround is to restart the editor after creating the resource and then cook or create a Patch for these resources, or continue to use the plugin’s provided cooking directory and specify maps to avoid the aforementioned issue, since its implementation launches a new UE process to execute the cooking task, thus the local resource information will be reloaded).

2020.11.07 Update

• Added bStorageDeletedAssetsToNewReleaseJson: controls whether deleted resources in the ContentBrowser should be stored in the new ReleaseJson.

This essentially represents two version management modes:

1. The ReleaseJson records all resources in the current game version (deleted resources still exist in UFS, as files in old Pak will not be deleted)
2. The ReleaseJson records all resources that need to be experienced by players in the game (excluding moved directories and deleted resources)

There is no difference in the actual resources in the game; the difference lies in the version information managed by HotPatcher.

2020.11.01 Update

• (UE4.23+) Supports directly adding selected resources to Patch Settings in ContentBrowser;
• Supports directly cooking resources when generating Patches (bCookPatchAssets). Note that when there are many resources in the Patch, cooking can be time-consuming and will require shader compilation, greatly increasing the generation time of the Patch, so enabling cooking during Patch generation can be used for testing packaging of resources or in CI.

2020.10.31 Update

• Supports cooking individual resources (shader code included within the resource);
• (UE4.23+) Supports right-clicking to select multiple Assets in Content Browser and cook them;

2020.10.30 Update

• PatchSetting supports bForceSkipContent for forcibly ignoring certain resources in directories
• ForceSkipContentRules specifies resource directories to ignore in the Patch, default values are /Engine/Editor and /Engine/VREditor, selecting Exclude editor content when cooking in project settings means resources in these two directories will not be cooked and thus cannot be packaged.
• ForceSkipAssets ignores specified resources in the Patch version.
• Renamed functions such as DiffPatchVersion to DiffPatchVersionWithPatchSetting, and passed the PatchSetting, facilitating option control during Diff.

These two options were added to match directories that are not cooked by default in UE packaging, and to allow for control over which resources are excluded from packaging.
Note: The difference between ForceSkipContentRules and AssetIgnoreFilters is: AssetIgnoreFilters applies to resources before dependency analysis; it can be set as subdirectories of AssetIncludeFilters; while ForceSkipContentRules filters after diff results have been processed, excluding resources with these prefixes.

2020.10.27 Update

• Support analyzing Release from the generated PakList file
• Support importing PakList from multiple platforms and analyzing file differences across different platforms
• Changed ReleaseSetting and PatchSetting classes from UObject to USTRUCT
• Unified the use of serialized USTRUCTs to handle Import/Export configurations
• Supported adding special files in the Patch for specific platforms (only included on specified platforms)
• Used CustomDetailView to add a button for importing PakList to the Detail panel
• Refactored some code to accommodate adding special files for different platforms.
• Removed additional configuration information from Release.json
• Fixed an error in MountListener in 4.24

This update involved significant code changes and is not compatible with the configuration files exported from previous versions, so it has been temporarily published to the Dev branch. After testing stability, it will be merged into the master branch. The Release/Patch/Chunk workflows have been tested with no significant issues.

2020.10.17 Update

• Support analyzing the WidgetTree of Widgets, solving the issue of child control modifications not working on parent controls

If a Widget has been modified, this option allows for recursive addition of all Widgets containing it, solving the issue of modifications on child controls not impacting parent controls when patching.

2020.08.31 Update

• Added support for exporting Release via Commandlet
• Cleaned up duplicate code and organized method
• Added options to control naming rules for generated Paks
• Fixed an issue where empty packages were produced even if the Chunk did not contain any files
• Fixed an issue with UFlibPakHelper::GetMountedPaks crashing in 4.25

2020.06.04 Update

• Added bCookAllMap property to the export configuration, which when true will cook all maps in the project directory in Commandlet mode.
• Added ByRelease support to generate configurations using PakList*.txt, thus enabling complete matching of all resources in the base package.

2020.06.03 Update

• Added the Commandlet for plugin cooking
• Added the Commandlet for plugin patching

2020.04.27 Update

• Added MonolithicPathMode under Chunk’s bMonolithic mode to specify the storage path rules for Paks.

2020.04.24 Update

• Added the option to analyze dependencies of resources in the filter

2020.04.23 Update

• Added optional resource types for referencing

2020.04.18 Update

• Added -compressionformats parameter by default for UnrealOptions.
• Added PreviewChunk option, which helps identify which resources are in which chunk when Chunk is enabled.

2020.04.10 Update

• Added ReplacePakCommandTexts option, allowing custom text to replace the text in PakCommand.txt, such as replacing the MountPath for resources being packed

2020.04.09 Update

• Fixed the issue of generating Chunk from PatchSetting when no filters were selected / for resource redirection reverals
• Fixed issues with converting Cooked paths
• Supported exporting all pak information, removing pakversion options
• Supported exporting resource dependencies for Release and Patch
• Added FScopeSlowTask progress display for ExportRelease
• Added options to specify PakCommand parameters

2020.04.08 Update

• Supports multithreaded Pak packaging, directly calling ExecuteUnrealPak instead of starting UnrealPak.exe, greatly improving efficiency.
• Fixed the issue with PreviewPatch being inconsistent with Diff information when selecting BaseVersion

2020.04.07 Update

• Supports bMonolithic mode, allowing each referenced resource to be packed into a separate pak.
• Unified the packing methods for Asset, Cooked bin, external files, ini, and all files.

2020.04.03 Update

• Completed the Chunk functionality for Patch, unifying the packaging processes for Patch and Chunk
• Code optimization and process sorting
• Removed the IncludePakVersionFile and PakVersionFileMountPoint options

2020.04.02 Update

• Added Chunk functionality for Patch
• Fixed serialization and deserialization issues with FPatcherSpecifyAsset
• Optimized organizational structure

2020.03.28 Update

• Fixed the issue of incomplete exported *Release.json when patching based on the base version.

2020.03.05 Update

• Fixed the issue when the Cook process exits abnormally without clearing task status.
• Added optional maps in Engine or Plugin during cooking, which can be enabled in HotPatcherEditor.build.cs by controlling ENABLE_COOK_ENGINE_MAP and ENABLE_COOK_PLUGIN_MAP.

2020.02.14 Update

• Added importing and exporting options for Patch and Release configurations
• Changed the default naming for generated Paks to XXX_TARGET_PLATFORM_001_P.pak
• Fixed some potential issues, recommended to update.

2019.12.08 Update

• Added an option to perform dependency scanning on resources, added diff preview.

2020.02.19 Update

• Added support for exporting release with the option to add external files and folders, corresponding to external file directories added when packaging with UE. It also supports diff comparison of external files (optional), where only modified or newly added files will be packed into pak.

2020.01.13 Update

• Added error message prompts during generation, detecting uncooked resource scans and duplicate external file additions, and allowing to specify specific resources for Pak, with optional dependency analysis.

2020.01.14 Update

• Fixed the scanning of Redirector that would prompt uncooked resource messages, added IncludeSpecifyAssets to ExportRelease, allowing specific resource specifications (such as only specifying a certain map).

2020.01.19 Update

• Added the option to specify which directories to cook.

Update Plan

To make HotPatcher more user-friendly and powerful, I will record some good update suggestions here.

1. Add support for multithreaded scanning of resource dependencies (executed by launching a separate process)
2. Add options to directly specify Pak encryption parameters under UnrealPak (opened for customizable encryption parameters)
3. Specify cooking of individual resources
4. Change the naming of packaged Paks from XX_TARGET_PLATFORM_P.pak to XX_TARGET_PLATFORM_0_P, or specify the middle number.
5. Import and export configuration files for Patch and Release, as well as quickly clear configurations.
6. Add an option to include external files for release, synchronizing with the external files included when packaging in UE.
7. Add diffs for external files, eliminating the need to pack all external files every time.
8. Allow packaging of multiple pak files in a single Patch, with options for which resources go into which Pak.
9. Add multithreaded support for the bMonolithic mode of Chunk
10. Add support for Commandlet
11. Add Commandlet support for exporting Release
12. Add options to control the naming rules for generated Paks
13. Support adding NoAssets resources for special platforms when creating Patch
14. Track modifications of UMG child controls and their references to Widget resources
15. Support analyzing Release.json from Paklist originating from multiple platforms
16. Perform filtering on the final results of the Patch
17. Set to ignore Editor resource content
18. External files added are stored in relative paths in Release.json (using Mountpath for version comparison)
19. Support generating shaderbytecode patches
20. Prevent blocking the editor during patching, implementing asynchronous tasks