net.TrackFlushedDormantObjects

net.TrackFlushedDormantObjects

#Overview

name: net.TrackFlushedDormantObjects

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.TrackFlushedDormantObjects is to control the tracking of dormant subobjects when dormancy is flushed in Unreal Engine’s networking system. This setting is primarily used for managing network replication and object lifecycle in multiplayer games.

  1. This setting variable is used in the networking system of Unreal Engine, specifically in handling dormant objects and their replication.

  2. The Unreal Engine subsystem that relies on this setting variable is the networking module, particularly the part that deals with network connections and object replication.

  3. 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.

  4. This variable interacts with bTrackFlushedDormantObjects, which is the associated C++ variable that directly controls the behavior in the code.

  5. Developers must be aware that enabling this variable will cause the engine to track dormant subobjects when dormancy is flushed. This is important for properly deleting these objects if they are destroyed before the next ReplicateActor call.

  6. Best practices when using this variable include:

    • Keep it enabled (default) unless there’s a specific performance reason to disable it.
    • Be aware of its impact on memory usage, as it will maintain additional tracking information.
    • Use it in conjunction with other dormancy-related settings for optimal network performance.

Regarding the associated variable bTrackFlushedDormantObjects:

The purpose of bTrackFlushedDormantObjects is to implement the behavior controlled by net.TrackFlushedDormantObjects within the C++ code.

  1. This variable is used directly in the code to control the tracking logic for flushed dormant objects.

  2. It’s used in the UE::Net::Connection::Private namespace, indicating it’s part of the internal networking implementation.

  3. The value is set based on the net.TrackFlushedDormantObjects console variable.

  4. It interacts with the FDormantObjectMap data structure, which is used to store information about flushed dormant objects.

  5. Developers should be aware that this variable directly affects the behavior of the FlushDormancy function and the TrackFlushedSubObject function.

  6. Best practices for this variable include:

    • Avoid modifying it directly in code; instead, use the net.TrackFlushedDormantObjects console variable.
    • When debugging network replication issues, check the state of this variable to understand if dormant object tracking is active.

#References in C++ code

#Callsites

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

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

Scope (from outer to inner):

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

Source code excerpt:


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

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

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

Source code excerpt:

	}

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

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

Scope (from outer to inner):

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

Source code excerpt:

	void TrackFlushedSubObject(FDormantObjectMap& InOutFlushedGuids, UObject* FlushedObject, const TSharedPtr<FNetGUIDCache>& GuidCache)
	{
		if (Connection::Private::bTrackFlushedDormantObjects)
		{
			// Searching for the guid because the value on the replicator built in FlushDormancyForObject can be invalid until the next replication
			// We can then safely ignore any object that still has no guid, since it won't have ever been replicated
			FNetworkGUID ObjectNetGUID = GuidCache->GetNetGUID(FlushedObject);
			if (ObjectNetGUID.IsValid())
			{

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

Scope (from outer to inner):

file
function     void UNetConnection::FlushDormancy

Source code excerpt:


		FDormantObjectMap FlushedGuids;
		if (Connection::Private::bTrackFlushedDormantObjects)
		{
			// This doesn't reserve space for subobjects of components, but avoids iterating the component list twice.
			FlushedGuids.Reserve(ReplicatedComponents.Num() + ActorSubObjects.GetRegistryList().Num());
		}

		TStaticBitArray<COND_Max> ConditionMap;

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

Scope (from outer to inner):

file
function     void UNetConnection::FlushDormancy

Source code excerpt:

		}

		if (bTrackFlushedDormantObjects && !FlushedGuids.IsEmpty())
		{
			FDormantObjectMap& DormantObjects = DormantReplicatorSet.FindOrAddFlushedObjectsForActor(Actor);
			DormantObjects.Append(FlushedGuids);
		}
	}