PackageCompressionLevel_Distribution

PackageCompressionLevel_Distribution

#Overview

name: PackageCompressionLevel_Distribution

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

It is referenced in 4 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 PackageCompressionLevel_Distribution is to specify the compression effort level used when packaging content for distribution builds in Unreal Engine 5. This setting is part of the project packaging system and affects how game assets are compressed when creating the final distribution package.

This setting variable is primarily used by the packaging subsystem of Unreal Engine 5, specifically within the ProjectPackagingSettings module. It’s also referenced in the TextureEditor module, suggesting it may have implications for texture compression during the packaging process.

The value of this variable is set in the project’s configuration files, typically in DefaultGame.ini or in the Project Settings within the Unreal Editor. It can be modified through the UProjectPackagingSettings class.

PackageCompressionLevel_Distribution interacts with other packaging-related variables, such as PackageCompressionMethod and PackageAdditionalCompressionOptions. It’s also used in conjunction with PackageCompressionLevel_TestShipping and PackageCompressionLevel_DebugDevelopment to provide different compression levels for various build configurations.

Developers must be aware that this variable expects an integer value between -128 and 127. Values outside this range will result in warnings and may cause the system to fall back to a default value. The actual compression level used is typically mapped to an enumeration value in the Oodle compression library.

Best practices when using this variable include:

  1. Carefully balancing compression level with build time and final package size.
  2. Testing different compression levels to find the optimal setting for your project.
  3. Considering platform-specific requirements, as some platforms may override or ignore this setting.
  4. Ensuring the value is within the valid range to avoid unexpected behavior.
  5. Coordinating this setting with other compression-related settings for optimal results.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseGame.ini:98, section: [/Script/UnrealEd.ProjectPackagingSettings]

Location: <Workspace>/Projects/Lyra/Config/DefaultGame.ini:111, 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:376

Scope (from outer to inner):

file
class        class UProjectPackagingSettings : public UObject

Source code excerpt:

	
	UPROPERTY(config, EditAnywhere, Category = Packaging, AdvancedDisplay, meta = (DisplayName = "Compressor Effort Level for Distribution"))
	int32 PackageCompressionLevel_Distribution;

	/**
	 * A generic setting which is used to determine whether it is worth using compression for a block of data when creating IoStore or .pak files.
	 * If the amount of saved bytes is smaller than the specified value, then the block of data remains uncompressed.
	 * The optimal value of this setting depends on the capabilities of the target platform. For instance PackageCompressionMinBytesSaved=1024
	 * Note that some compressors (for example Oodle) do their own internal worth it check and only use this value to determine the minimal size of a block which should be compressed.

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

Scope (from outer to inner):

file
function     void FTextureEditorToolkit::CreateInternalWidgets

Source code excerpt:

	{
		int8 PackageCompressionLevel_Distribution8 = 0;
		if (IntFitsIn<int8>(ProjectSettings->PackageCompressionLevel_Distribution))
		{
			PackageCompressionLevel_Distribution8 = static_cast<int8>(ProjectSettings->PackageCompressionLevel_Distribution);
		}
		else
		{
			UE_LOG(LogTextureEditor, Warning, TEXT("PackageCompressionLevel_Distribution in Project Settings is an invalid value = %d, must be [-128, 127]"), ProjectSettings->PackageCompressionLevel_Distribution);
		}
		FOodleDataCompression::ECompressionLevelFromValue(PackageCompressionLevel_Distribution8, OodleCompressionLevel);
		FOodleDataCompression::ECompressionLevelToString(OodleCompressionLevel, &LevelName);
	}

	// Grab the compression block size in the settings.

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

Scope (from outer to inner):

file
function     void FTextureEditorToolkit::PackagingSettingsChanged

Source code excerpt:

		else if (*Selection == TEXT("Distribution"))
		{
			CompressionLevelFromSettings = ProjectSettings->PackageCompressionLevel_Distribution;
		}

		if (IntFitsIn<int8>(CompressionLevelFromSettings) == false)
		{
			UE_LOG(LogTextureEditor, Warning, TEXT("PackageCompressionLevel_%s in Project Settings is an invalid value = %d, must be [-128, 127]"), **Selection, CompressionLevelFromSettings);
			CompressionLevelFromSettings = (int32)FOodleDataCompression::ECompressionLevel::Optimal3;

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

Scope: file

Source code excerpt:

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);
};


struct FOodleDataCompressionFormat : ICompressionFormat

#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:3039

			if (Params.Distribution)
			{
				PlatformGameConfig.GetInt32("/Script/UnrealEd.ProjectPackagingSettings", "PackageCompressionLevel_Distribution", out CompressionLevel);
			}
			else if (SC.StageTargetConfigurations.Any(Config => Config == UnrealTargetConfiguration.Test || Config == UnrealTargetConfiguration.Shipping))
			{
				PlatformGameConfig.GetInt32("/Script/UnrealEd.ProjectPackagingSettings", "PackageCompressionLevel_TestShipping", out CompressionLevel);
			}
			else