Serialization.RehydrateOnSave

Serialization.RehydrateOnSave

#Overview

name: Serialization.RehydrateOnSave

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of Serialization.RehydrateOnSave is to control whether virtualized payloads of FVirtualizedUntypedBulkData should be hydrated and stored locally when saving to a package. This setting is primarily used in the serialization system of Unreal Engine 5, specifically for handling bulk data.

The Unreal Engine subsystem that relies on this setting variable is the CoreUObject module, particularly the serialization component. This can be seen from the file path where the variable is referenced: Engine/Source/Runtime/CoreUObject/Private/Serialization/EditorBulkData.cpp.

The value of this variable is set through a console variable (CVar) named CVarShouldRehydrateOnSave. It’s initialized with a default value of false, meaning that by default, virtualized payloads are not rehydrated during save operations.

This variable interacts closely with LinkerSave->bRehydratePayloads. In the BuildFlagsForSerialization function, both Serialization.RehydrateOnSave and LinkerSave->bRehydratePayloads are checked to determine whether to rehydrate payloads.

Developers must be aware that enabling this variable can significantly impact save operations, especially for projects with large amounts of bulk data. Rehydrating virtualized payloads means bringing them back into local storage, which can increase save times and file sizes.

Best practices when using this variable include:

  1. Keep it disabled by default to maintain optimal performance.
  2. Enable it only when necessary, such as when you need to ensure all data is locally available in the saved package.
  3. Consider the impact on save times and file sizes when enabling this option.

Regarding the associated variable CVarShouldRehydrateOnSave:

The purpose of CVarShouldRehydrateOnSave is to provide runtime control over the Serialization.RehydrateOnSave setting. It’s implemented as a console variable, allowing developers to change its value during runtime or through configuration files.

This variable is used in the CoreUObject module, specifically in the serialization system for bulk data.

The value of CVarShouldRehydrateOnSave is set when it’s declared, with a default value of false. However, being a console variable, its value can be changed at runtime.

CVarShouldRehydrateOnSave directly controls the behavior defined by Serialization.RehydrateOnSave. It’s used in conjunction with LinkerSave->bRehydratePayloads to determine whether to rehydrate virtualized payloads during save operations.

Developers should be aware that changes to this variable will immediately affect the behavior of save operations involving virtualized bulk data.

Best practices for using CVarShouldRehydrateOnSave include:

  1. Use it for debugging or testing purposes when you need to temporarily enable rehydration.
  2. Be cautious when changing its value in a shipping build, as it can significantly impact performance and file sizes.
  3. Consider exposing this option in your project’s settings if you want to give users control over this behavior.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/CoreUObject/Private/Serialization/EditorBulkData.cpp:74

Scope (from outer to inner):

file
namespace    UE::Serialization

Source code excerpt:


static TAutoConsoleVariable<bool> CVarShouldRehydrateOnSave(
	TEXT("Serialization.RehydrateOnSave"),
	false,
	TEXT("When true FVirtualizedUntypedBulkData virtualized payloads will by hydrated and stored locally when saved to a package"));

/** Wrapper around the config file option [Core.System.Experimental]EnablePackageSidecarSaving */
static bool ShouldSaveToPackageSidecar()
{

#Loc: <Workspace>/Engine/Source/Runtime/CoreUObject/Private/Serialization/EditorBulkData.cpp:2327

Scope (from outer to inner):

file
namespace    UE::Serialization
function     FEditorBulkData::EFlags FEditorBulkData::BuildFlagsForSerialization

Source code excerpt:

				// a) We are saving to a package (LinkerSave is not null)
				// b) Either the save package call we made with the  ESaveFlags::SAVE_RehydratePayloads flag set OR
				// the cvar Serialization.RehydrateOnSave is true
				// c) We are not saving a reference to a different domain. If we are saving a reference then the goal
				// is to avoid including the payload in the current target domain if possible, rehydrating for this
				// domain would prevent this.
				if ( LinkerSave != nullptr && 
					(LinkerSave->bRehydratePayloads || CVarShouldRehydrateOnSave.GetValueOnAnyThread()) &&
					!bKeepFileDataByReference)

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/CoreUObject/Private/Serialization/EditorBulkData.cpp:73

Scope (from outer to inner):

file
namespace    UE::Serialization

Source code excerpt:

static constexpr bool bAllowVirtualizationOnSave = false;

static TAutoConsoleVariable<bool> CVarShouldRehydrateOnSave(
	TEXT("Serialization.RehydrateOnSave"),
	false,
	TEXT("When true FVirtualizedUntypedBulkData virtualized payloads will by hydrated and stored locally when saved to a package"));

/** Wrapper around the config file option [Core.System.Experimental]EnablePackageSidecarSaving */
static bool ShouldSaveToPackageSidecar()

#Loc: <Workspace>/Engine/Source/Runtime/CoreUObject/Private/Serialization/EditorBulkData.cpp:2332

Scope (from outer to inner):

file
namespace    UE::Serialization
function     FEditorBulkData::EFlags FEditorBulkData::BuildFlagsForSerialization

Source code excerpt:

				// domain would prevent this.
				if ( LinkerSave != nullptr && 
					(LinkerSave->bRehydratePayloads || CVarShouldRehydrateOnSave.GetValueOnAnyThread()) &&
					!bKeepFileDataByReference)
				{
					EnumRemoveFlags(UpdatedFlags, EFlags::IsVirtualized);
				}
			}
		}