Package.Relocation

Package.Relocation

#Overview

name: Package.Relocation

This variable is created as a Console Variable (cvar).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of Package.Relocation is to control when the relocation logic for package dependencies should be applied. This setting is crucial for managing asset references and resolving dependencies in Unreal Engine 5.

This setting variable is primarily used by the CoreUObject module, specifically within the package relocation system. It’s part of the UE::Package::Relocation::Private namespace, indicating its importance in handling package dependencies and references.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 0, but can be changed at runtime through console commands or configuration files.

Package.Relocation interacts directly with an associated variable named CVarRelocationMode. They share the same value and are used interchangeably in the code.

Developers must be aware of several important aspects when using this variable:

  1. Changing the value at runtime won’t update the cached dependencies in the asset registry.
  2. The setting has two modes:
    • 0: Off (never apply relocation)
    • 1: Relocate assets saved after EUnrealEngineObjectUE5Version::ADD_SOFTOBJECTPATH_LIST (5.1)
  3. When set to 0, references to other relocated packages will give errors and fail to resolve.
  4. The default value for new projects is 1.

Best practices when using this variable include:

  1. Carefully consider the implications of changing this value, especially in production environments.
  2. Be consistent with its usage across your project to avoid reference resolution issues.
  3. If you’re working with assets created before UE5.1, be cautious when enabling relocation.
  4. Document any custom settings for this variable in your project configuration.

Regarding the associated variable CVarRelocationMode:

CVarRelocationMode is the actual TAutoConsoleVariable object that controls the Package.Relocation setting. It’s used internally by the engine to check the current relocation mode and determine whether to apply relocation logic.

The CVarRelocationMode variable is accessed using the GetValueOnAnyThread() method, which allows for thread-safe retrieval of its value. This is particularly important in the ShouldApplyRelocation function, where the relocation behavior is determined based on the variable’s value and the package’s file version.

Developers should be aware that any changes to CVarRelocationMode will directly affect the behavior of the package relocation system. When modifying or querying this variable, ensure you’re doing so in a thread-safe manner, preferably using the provided GetValueOnAnyThread() method.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/CoreUObject/Private/UObject/PackageRelocation.cpp:15

Scope (from outer to inner):

file
namespace    UE::Package::Relocation::Private

Source code excerpt:

{
	static TAutoConsoleVariable<int32> CVarRelocationMode(
			TEXT("Package.Relocation"),
			0,
			TEXT("Define when we should run the relocation logic for the dependencies of a package. Note changing this value at runtime won't update the cached depencencies in the asset registry.\n")
			TEXT("  0: Off (never apply relocation. References to other relocated packages will give errors and fail to resolve.)\n")
			TEXT("  1: Relocate any asset saved after EUnrealEngineObjectUE5Version::ADD_SOFTOBJECTPATH_LIST (5.1). Default value for the new projects.\n")
		);

#Associated Variable and Callsites

This variable is associated with another variable named CVarRelocationMode. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Runtime/CoreUObject/Private/UObject/PackageRelocation.cpp:14

Scope (from outer to inner):

file
namespace    UE::Package::Relocation::Private

Source code excerpt:

namespace UE::Package::Relocation::Private
{
	static TAutoConsoleVariable<int32> CVarRelocationMode(
			TEXT("Package.Relocation"),
			0,
			TEXT("Define when we should run the relocation logic for the dependencies of a package. Note changing this value at runtime won't update the cached depencencies in the asset registry.\n")
			TEXT("  0: Off (never apply relocation. References to other relocated packages will give errors and fail to resolve.)\n")
			TEXT("  1: Relocate any asset saved after EUnrealEngineObjectUE5Version::ADD_SOFTOBJECTPATH_LIST (5.1). Default value for the new projects.\n")
		);

#Loc: <Workspace>/Engine/Source/Runtime/CoreUObject/Private/UObject/PackageRelocation.cpp:33

Scope (from outer to inner):

file
namespace    UE::Package::Relocation::Private
function     bool ShouldApplyRelocation

Source code excerpt:

		}

		switch (CVarRelocationMode.GetValueOnAnyThread())
		{
		case 1:
			if (PackageSummary.GetFileVersionUE() < EUnrealEngineObjectUE5Version::ADD_SOFTOBJECTPATH_LIST)
			{
				return false;
			}