net.EnableFlushDormantSubObjects

net.EnableFlushDormantSubObjects

#Overview

name: net.EnableFlushDormantSubObjects

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 net.EnableFlushDormantSubObjects is to control the behavior of the network dormancy flushing system in Unreal Engine 5, specifically for replicated subobjects.

This setting variable is primarily used in the networking system of Unreal Engine, particularly in the dormancy flushing mechanism. It is part of the Engine module and is utilized within the UE::Net::Connection::Private namespace.

The value of this variable is set to true by default, as seen in the code:

int32 bEnableFlushDormantSubObjects = true;

It interacts with several other variables, notably:

  1. bEnableFlushDormantSubObjectsCheckConditions
  2. bFlushDormancyUseDefaultStateForUnloadedLevels
  3. bTrackFlushedDormantObjects

When enabled, this variable allows the FlushNetDormancy function to flush replicated subobjects in addition to replicated components. This only applies to objects using the replicated subobject list.

Developers must be aware that this variable significantly affects network performance and replication behavior. Enabling it can increase network traffic and processing overhead, especially in scenarios with many replicated subobjects.

Best practices when using this variable include:

  1. Only enable it when necessary, particularly in projects heavily relying on replicated subobjects.
  2. Monitor network performance when enabled, as it may impact bandwidth usage.
  3. Use in conjunction with bEnableFlushDormantSubObjectsCheckConditions for more granular control.

Regarding the associated variable bEnableFlushDormantSubObjects:

This is the actual boolean variable that controls the behavior. It shares the same value as the console variable net.EnableFlushDormantSubObjects. It is used directly in the code to conditionally execute the dormancy flushing for subobjects:

if (bEnableFlushDormantSubObjects)
{
    FlushDormancyForSubObjects(this, Actor, ActorSubObjects, FlushedGuids, ConditionMap, NetConditionGroupManager);
}

Developers should note that this variable is checked in the FlushDormancy function of UNetConnection, which is a critical part of the networking system. Changes to this variable will directly affect how dormancy is handled for networked objects, potentially impacting game performance and behavior.

#References in C++ code

#Callsites

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

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

Scope (from outer to inner):

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

Source code excerpt:


	int32 bEnableFlushDormantSubObjects = true;
	FAutoConsoleVariableRef CVarNetFlushDormantSubObjects(TEXT("net.EnableFlushDormantSubObjects"), bEnableFlushDormantSubObjects, TEXT("If enabled, FlushNetDormancy will flush replicated subobjects in addition to replicated components. Only applies to objects using the replicated subobject list."));

	int32 bEnableFlushDormantSubObjectsCheckConditions = true;
	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."));

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

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

Source code excerpt:

	FAutoConsoleVariableRef CVarNetTrackFlushedDormantObjects(TEXT("net.TrackFlushedDormantObjects"), bTrackFlushedDormantObjects, TEXT("If enabled, track dormant subobjects when dormancy is flushed, so they can be properly deleted if destroyed prior to the next ReplicateActor."));

	int32 bEnableFlushDormantSubObjects = true;
	FAutoConsoleVariableRef CVarNetFlushDormantSubObjects(TEXT("net.EnableFlushDormantSubObjects"), bEnableFlushDormantSubObjects, TEXT("If enabled, FlushNetDormancy will flush replicated subobjects in addition to replicated components. Only applies to objects using the replicated subobject list."));

	int32 bEnableFlushDormantSubObjectsCheckConditions = true;
	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."));

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

Scope (from outer to inner):

file
function     void UNetConnection::FlushDormancy

Source code excerpt:

		}

		if (bEnableFlushDormantSubObjects)
		{
			FlushDormancyForSubObjects(this, Actor, ActorSubObjects, FlushedGuids, ConditionMap, NetConditionGroupManager);
		}

		for (const FReplicatedComponentInfo& RepComponentInfo : ReplicatedComponents)
		{

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

Scope (from outer to inner):

file
function     void UNetConnection::FlushDormancy

Source code excerpt:

					TrackFlushedSubObject(FlushedGuids, ActorComp, Driver->GuidCache);

					if (bEnableFlushDormantSubObjects)
					{
						const FSubObjectRegistry* const ComponentSubObjects = FSubObjectRegistryGetter::GetSubObjectsOfActorComponent(Actor, ActorComp);
						if (ComponentSubObjects)
						{
							FlushDormancyForSubObjects(this, Actor, *ComponentSubObjects, FlushedGuids, ConditionMap, NetConditionGroupManager);
						}