net.EnableFlushDormantSubObjectsCheckConditions

net.EnableFlushDormantSubObjectsCheckConditions

#Overview

name: net.EnableFlushDormantSubObjectsCheckConditions

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of net.EnableFlushDormantSubObjectsCheckConditions is to control the behavior of dormancy flushing for replicated subobjects in Unreal Engine’s networking system. Specifically, it determines whether additional condition checks should be performed when flushing dormant subobjects.

This setting variable is primarily used by the networking subsystem of Unreal Engine, particularly in the context of actor replication and dormancy management.

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

This variable interacts closely with another variable named “net.EnableFlushDormantSubObjects”. When both are true, dormancy flushing will perform additional checks on replicated subobject conditions.

Developers should be aware that enabling this variable may introduce additional computational overhead during dormancy flushing, as it requires checking conditions for each subobject. However, it provides more fine-grained control over which subobjects are flushed.

Best practices when using this variable include:

  1. Only enable it if you need the additional condition checks for subobjects.
  2. Monitor performance impact, especially in scenarios with many dormant actors or subobjects.
  3. Use in conjunction with “net.EnableFlushDormantSubObjects” for full control over subobject dormancy flushing.

Regarding the associated variable bEnableFlushDormantSubObjectsCheckConditions:

This is the actual boolean variable that stores the state controlled by the console variable. It’s used directly in the C++ code to determine whether to perform the additional condition checks during dormancy flushing.

The purpose of bEnableFlushDormantSubObjectsCheckConditions is the same as net.EnableFlushDormantSubObjectsCheckConditions, as they are directly linked.

This variable is used in the UE::Net::Connection::Private namespace, specifically in the FlushDormancyForSubObjects and UNetConnection::FlushDormancy functions.

The value of this variable is set by the console variable system when net.EnableFlushDormantSubObjectsCheckConditions is modified.

Developers should be aware that this is the actual variable checked in the code, so any runtime changes to the console variable will be reflected here.

Best practices for this variable are the same as for the console variable, with the addition that developers should not modify this variable directly in code, but instead use the console variable system to ensure consistency.

#References in C++ code

#Callsites

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

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

Scope (from outer to inner):

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

Source code excerpt:


	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."));

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

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

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

Source code excerpt:

	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."));

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

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

Scope (from outer to inner):

file
namespace    UE::Net::Connection::Private
function     void FlushDormancyForSubObjects

Source code excerpt:

			if (ensureMsgf(IsValid(SubObject), TEXT("Found invalid subobject (%s) registered in %s"), *GetNameSafe(SubObject), *Actor->GetName()))
			{
				if (!bEnableFlushDormantSubObjectsCheckConditions ||
					!NetConditionGroupManager ||
					UActorChannel::CanSubObjectReplicateToClient(Connection->PlayerController, SubObjectInfo.NetCondition, SubObjectInfo.Key, ConditionMap, *NetConditionGroupManager))
				{
					Connection->FlushDormancyForObject(Actor, SubObject);
					TrackFlushedSubObject(InOutFlushedGuids, SubObject, Connection->Driver->GuidCache);
				}

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

Scope (from outer to inner):

file
function     void UNetConnection::FlushDormancy

Source code excerpt:

		const FNetConditionGroupManager* NetConditionGroupManager = nullptr;

		if (bEnableFlushDormantSubObjectsCheckConditions)
		{
			// Fill in the flags used by conditional subobjects
			FReplicationFlags RepFlags;
		
			// Since a dormant object won't necessarily have an FObjectReplicator or channel, we can't check for
			// initial replication in the normal way. So always flush for NetInitial to be safe, it may create

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

Scope (from outer to inner):

file
function     void UNetConnection::FlushDormancy

Source code excerpt:

			if (ensureMsgf(IsValid(ActorComp), TEXT("Found invalid replicated component (%s) registered in %s"), *GetNameSafe(ActorComp), *Actor->GetName()))
			{
				if (!bEnableFlushDormantSubObjectsCheckConditions ||
					!NetConditionGroupManager ||
					UActorChannel::CanSubObjectReplicateToClient(PlayerController, RepComponentInfo.NetCondition, RepComponentInfo.Key, ConditionMap, *NetConditionGroupManager))
				{
					FlushDormancyForObject(Actor, ActorComp);
					TrackFlushedSubObject(FlushedGuids, ActorComp, Driver->GuidCache);