net.FlushDormancyUseDefaultStateForUnloadedLevels

net.FlushDormancyUseDefaultStateForUnloadedLevels

#Overview

name: net.FlushDormancyUseDefaultStateForUnloadedLevels

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 net.FlushDormancyUseDefaultStateForUnloadedLevels is to control how dormancy flushing initializes replicators when the client doesn’t have the actor’s level loaded. This setting variable is part of Unreal Engine’s networking system, specifically related to object replication and dormancy.

This setting variable is primarily used in the Engine module, specifically within the networking subsystem. It’s referenced in the NetConnection.cpp file, which is a core component of Unreal Engine’s networking infrastructure.

The value of this variable is set using an FAutoConsoleVariableRef, which means it can be modified at runtime through console commands. By default, it’s set to true.

The associated variable bFlushDormancyUseDefaultStateForUnloadedLevels directly interacts with this console variable. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable affects how dormant objects are initialized when their levels are not loaded on the client. When enabled, it forces the use of default object state for initialization instead of the current state.

Best practices when using this variable include:

  1. Consider the implications on network performance and gameplay when enabling or disabling this feature.
  2. Test thoroughly with various network conditions and level loading scenarios to ensure desired behavior.
  3. Be mindful of how this setting interacts with level streaming and object replication in your game.

Regarding the associated variable bFlushDormancyUseDefaultStateForUnloadedLevels:

The purpose of this variable is the same as the console variable - to control dormancy flushing behavior for unloaded levels.

It’s used directly in the UNetConnection::FlushDormancyForObject function to determine whether to use the default state for initializing replicators when the client hasn’t loaded the actor’s level.

The value of this variable is set by the console variable net.FlushDormancyUseDefaultStateForUnloadedLevels.

This variable interacts closely with other networking concepts like level loading, actor replication, and dormancy.

Developers should be aware that this variable directly affects the behavior of dormancy flushing and can impact how objects are replicated when levels are not loaded.

Best practices include carefully considering the implications of changing this value, especially in games with complex level streaming or large open worlds where not all levels may be loaded at once.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/NetConnection.cpp:214

Scope (from outer to inner):

file
namespace    UE::Net::Connection::Private

Source code excerpt:


	int32 bFlushDormancyUseDefaultStateForUnloadedLevels = true;
	FAutoConsoleVariableRef CVarFlushDormancyUseDefaultStateForUnloadedLevels(TEXT("net.FlushDormancyUseDefaultStateForUnloadedLevels"), bFlushDormancyUseDefaultStateForUnloadedLevels, TEXT("If enabled, dormancy flushing will init replicators with default object state if the client doesn't have the actor's level loaded."));

	// Tracking for dormancy-flushed subobjects for correct deletion, see UE-77163
	void TrackFlushedSubObject(FDormantObjectMap& InOutFlushedGuids, UObject* FlushedObject, const TSharedPtr<FNetGUIDCache>& GuidCache)
	{
		if (Connection::Private::bTrackFlushedDormantObjects)
		{

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/NetConnection.cpp:213

Scope (from outer to inner):

file
namespace    UE::Net::Connection::Private

Source code excerpt:

	FAutoConsoleVariableRef CVarNetFlushDormantSubObjectsCheckConditions(TEXT("net.EnableFlushDormantSubObjectsCheckConditions"), bEnableFlushDormantSubObjectsCheckConditions, TEXT("If enabled, when net.EnableFlushDormantSubObjects is also true a dormancy flush will also check replicated subobject conditions"));

	int32 bFlushDormancyUseDefaultStateForUnloadedLevels = true;
	FAutoConsoleVariableRef CVarFlushDormancyUseDefaultStateForUnloadedLevels(TEXT("net.FlushDormancyUseDefaultStateForUnloadedLevels"), bFlushDormancyUseDefaultStateForUnloadedLevels, TEXT("If enabled, dormancy flushing will init replicators with default object state if the client doesn't have the actor's level loaded."));

	// Tracking for dormancy-flushed subobjects for correct deletion, see UE-77163
	void TrackFlushedSubObject(FDormantObjectMap& InOutFlushedGuids, UObject* FlushedObject, const TSharedPtr<FNetGUIDCache>& GuidCache)
	{
		if (Connection::Private::bTrackFlushedDormantObjects)
		{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/NetConnection.cpp:5134

Scope (from outer to inner):

file
function     void UNetConnection::FlushDormancyForObject

Source code excerpt:

		// Init using the object's current state if the client has this actor's level loaded. If the level
		// is unloaded, we need to use the default state since the client has no current state.
		if (bFlushDormancyUseDefaultStateForUnloadedLevels && !ClientHasInitializedLevel(DormantActor->GetLevel()))
		{
			bUseDefaultState = true;
		}

		ObjectReplicatorRef->InitWithObject(ReplicatedObject, this, bUseDefaultState);