PackageAdditionalCompressionOptions

PackageAdditionalCompressionOptions

#Overview

name: PackageAdditionalCompressionOptions

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 3 C++ source files. Also referenced in 1 C# build file meaning it may affect the build system logic.

#Summary

#Usage in the C++ source code

The purpose of PackageAdditionalCompressionOptions is to provide a generic setting for controlling compression settings during .pak file and iostore compression in Unreal Engine projects. It allows developers to specify additional command-line options for package compression.

This setting variable is primarily used by the packaging and compression subsystems of Unreal Engine. Based on the provided callsites, it’s utilized in the DeveloperToolSettings module and affects the TextureEditor and Core modules.

The value of this variable is set in the project’s configuration files, typically in DefaultGame.ini. It can be accessed and modified through the ProjectPackagingSettings class.

PackageAdditionalCompressionOptions interacts with other compression-related variables such as PackageCompressionMethod, PackageCompressionLevel_Distribution, PackageCompressionLevel_TestShipping, and PackageCompressionLevel_DebugDevelopment. It works in conjunction with these variables to define the overall compression strategy for the project.

Developers must be aware that this variable accepts command-line style options. The most common usage shown in the code is setting the compression block size (e.g., “-compressionblocksize=256KB”). It’s crucial to use the correct syntax when specifying options.

Best practices when using this variable include:

  1. Carefully consider the impact on package size and loading times when adjusting compression options.
  2. Test thoroughly after changing compression settings to ensure optimal performance across different platforms.
  3. Be mindful of platform-specific limitations or requirements when setting compression options.
  4. Document any custom compression settings used in the project to maintain consistency across the development team.
  5. Consider different settings for various build configurations (Debug, Development, Shipping) to balance development speed with final package optimization.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/DefaultGame.ini:107, section: [/Script/UnrealEd.ProjectPackagingSettings]

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Developer/DeveloperToolSettings/Classes/Settings/ProjectPackagingSettings.h:354

Scope: file

Source code excerpt:

	/**
	 * A generic setting for allowing a project to control compression settings during .pak file and iostore compression.
	 * For instance PackageAdditionalCompressionOptions=-compressionblocksize=1MB -asynccompression
	 */
	UPROPERTY(config, EditAnywhere, Category = Packaging, AdvancedDisplay, meta = (DisplayName = "Package Compression Commandline Options"))
	FString PackageAdditionalCompressionOptions;
	
	/**
	 * For compressors with multiple methods, select one.  eg. for Oodle you may use one of {Kraken,Mermaid,Selkie,Leviathan}
	 */
	UPROPERTY(config, EditAnywhere, Category = Packaging, AdvancedDisplay, meta = (DisplayName = "Package Compression Method"))
	FString PackageCompressionMethod;

#Loc: <Workspace>/Engine/Source/Editor/TextureEditor/Private/TextureEditorToolkit.cpp:1296

Scope (from outer to inner):

file
function     void FTextureEditorToolkit::CreateInternalWidgets

Source code excerpt:

	{
		FString CompBlockSizeString;
		if (FParse::Value(*ProjectSettings->PackageAdditionalCompressionOptions, TEXT("-compressionblocksize="), CompBlockSizeString) &&
			FParse::Value(*ProjectSettings->PackageAdditionalCompressionOptions, TEXT("-compressionblocksize="), CompressionBlockSize))
		{
			if (CompBlockSizeString.EndsWith(TEXT("MB")))
			{
				CompressionBlockSize *= 1024 * 1024;
			}
			else if (CompBlockSizeString.EndsWith(TEXT("KB")))

#Loc: <Workspace>/Engine/Source/Runtime/Core/Private/Compression/OodleDataCompressionFormat.cpp:41

Scope: file

Source code excerpt:

bForceUseProjectCompressionFormat=False
PackageCompressionFormat=Oodle
PackageAdditionalCompressionOptions=-compressionblocksize=256KB
PackageCompressionMethod=Kraken
PackageCompressionLevel_Distribution=7
PackageCompressionLevel_TestShipping=5
PackageCompressionLevel_DebugDevelopment=4

* This can be set in DefaultGame.ini then overrides set up per-platform.
* 
* The Engine also has a veto compressionformat set up in the DataDrivenPlatformInfo.ini for each platform in the field
* "HardwareCompressionFormat"
* eg. platforms that don't want any software compressor can set "HardwareCompressionFormat=None" and this will override what you
* set in "PackageCompressionFormat".
* 
* The idea is in typical use, you set "PackageCompressionFormat" for your Game, and you get that compressor on most platforms, but on
* some platforms that don't want compression, it automatically turns off.
* 
* If you want to force use of your Game.ini compressor (ignore the HardwareCompressionFormat) you can set bForceUseProjectCompressionFormat
* in ProjectPackagingSettings.
* 
* 
* ***************************/

#include "CoreMinimal.h"
#include "CoreTypes.h"
#include "Misc/Compression.h"
#include "Misc/ICompressionFormat.h"
#include "Misc/CommandLine.h"
#include "Misc/ConfigCacheIni.h"
#include "Misc/Parse.h"

/*
#if WITH_EDITOR
#include "Settings/ProjectPackagingSettings.h"
#endif
*/

#include "HAL/PlatformProcess.h"

#include "Compression/OodleDataCompression.h"
#include "oodle2.h"


#define OODLE_DERIVEDDATA_VER TEXT("BA7AA26CD1C3498787A3F3AA53895042")

// function pointer for old DLL import :
extern "C"
{
typedef OO_SINTa (OOLINK t_fp_OodleLZ_Compress)(OodleLZ_Compressor compressor,
    const void * rawBuf,OO_SINTa rawLen,void * compBuf,
    OodleLZ_CompressionLevel selection,
    const OodleLZ_CompressOptions * pOptions,
    const void * dictionaryBase,
    const void * lrm);

typedef OO_SINTa (OOLINK t_fp_OodleSetAllocators)(
	t_fp_OodleCore_Plugin_MallocAligned* fp_OodleMallocAligned,
	t_fp_OodleCore_Plugin_Free* fp_OodleFree);
};

#References in C# build files

This variable is referenced in the following C# build files:

Location: <Workspace>/Engine/Source/Programs/AutomationTool/Scripts/CopyBuildToStagingDirectory.Automation.cs:3061

				// the settings directly on the UnrealPak commandline, and not put it into the batch file lines (plugins can't get the unrealpak command list, and
				// there's not a great way to communicate random strings down into the plugins during plugin init time)
				PlatformGameConfig.GetString("/Script/UnrealEd.ProjectPackagingSettings", "PackageAdditionalCompressionOptions", out AdditionalCompressionOptionsOnCommandLine);

				string CompressionMethod;
				PlatformGameConfig.GetString("/Script/UnrealEd.ProjectPackagingSettings", "PackageCompressionMethod", out CompressionMethod);
				if (!string.IsNullOrWhiteSpace(CompressionMethod))
				{
					CompressionFormats += " -compressmethod=" + CompressionMethod;