net.AllowAsyncLoading

net.AllowAsyncLoading

#Overview

name: net.AllowAsyncLoading

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

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

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of net.AllowAsyncLoading is to control the async loading behavior of unloaded assets referenced in network packets. This setting variable is primarily used in the networking and replication systems of Unreal Engine 5.

The Unreal Engine subsystems that rely on this setting variable are:

  1. The networking system, specifically the PackageMapClient module
  2. The Iris replication system, which is an experimental feature in UE5

The value of this variable is set through a console variable (CVar) named CVarAllowAsyncLoading. It is initialized with a default value of 0, meaning async loading is disabled by default.

This variable interacts with another enum called EAsyncLoadMode, which determines how the async loading behavior should be handled. The enum has three modes: UseCVar (which uses the net.AllowAsyncLoading value), ForceDisable, and ForceEnable.

Developers must be aware of the following when using this variable:

  1. When set to 0 (false), the client will hitch and immediately load the asset, which may cause performance issues.
  2. When set to 1 (true), the packet will be delayed while the asset is async loaded, which may introduce latency but improve overall performance.
  3. This setting works in conjunction with another setting, net.DelayUnmappedRPCs, which can be enabled to delay RPCs that rely on async loading assets.

Best practices when using this variable include:

  1. Consider enabling it (set to 1) for better performance, especially in scenarios with many assets being loaded during gameplay.
  2. Monitor and balance the trade-off between immediate loading (potential hitches) and delayed loading (potential latency).
  3. Test thoroughly with both settings to determine the best option for your specific game requirements.

Regarding the associated variable CVarAllowAsyncLoading:

The purpose of CVarAllowAsyncLoading is to provide a console-accessible way to modify the net.AllowAsyncLoading setting at runtime. It is defined as a TAutoConsoleVariable, which allows it to be changed via console commands.

This variable is used in the FNetGUIDCache and FObjectReferenceCache classes to determine whether async loading should be performed. The ShouldAsyncLoad() functions in these classes check the value of CVarAllowAsyncLoading when the AsyncLoadMode is set to UseCVar.

Developers should be aware that changing CVarAllowAsyncLoading at runtime will affect the async loading behavior of the game. It’s important to consider the potential performance implications of modifying this value during gameplay.

Best practices for using CVarAllowAsyncLoading include:

  1. Use it for debugging and testing different async loading configurations without recompiling the game.
  2. Consider exposing it as a configurable option in development builds for easier testing and optimization.
  3. Be cautious when changing its value in a shipping game, as it may have significant performance impacts.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/DefaultEngine.ini:150, section: [ConsoleVariables]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PackageMapClient.cpp:123

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarAllowAsyncLoading(
	TEXT("net.AllowAsyncLoading"),
	0,
	TEXT("Allow async loading of unloaded assets referenced in packets."
		" If false the client will hitch and immediately load the asset,"
		" if true the packet will be delayed while the asset is async loaded."
		" net.DelayUnmappedRPCs can be enabled to delay RPCs relying on async loading assets.")
);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/PackageMapClient.h:192

Scope (from outer to inner):

file
class        class FNetGUIDCache

Source code excerpt:

	enum class EAsyncLoadMode : uint8
	{
		UseCVar			= 0,		// Use CVar (net.AllowAsyncLoading) to determine if we should async load
		ForceDisable	= 1,		// Disable async loading
		ForceEnable		= 2,		// Force enable async loading
	};

	ENGINE_API void			CleanReferences();
	ENGINE_API bool			SupportsObject( const UObject* Object, const TWeakObjectPtr<UObject>* WeakObjectPtr=nullptr /** Optional: pass in existing weakptr to prevent this function from constructing one internally */ ) const;

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Iris/Core/Private/Iris/ReplicationSystem/ObjectReferenceCache.cpp:1980

Scope (from outer to inner):

file
namespace    UE::Net::Private
function     void FObjectReferenceCache::SetAsyncLoadMode

Source code excerpt:

{
	AsyncLoadMode = NewMode;
	if (const IConsoleVariable* CVarAllowAsyncLoading = IConsoleManager::Get().FindConsoleVariable(TEXT("net.AllowAsyncLoading"), false /* bTrackFrequentCalls */))
	{
		bCachedCVarAllowAsyncLoading = CVarAllowAsyncLoading->GetInt() > 0;
	}
}

bool FObjectReferenceCache::ShouldAsyncLoad() const

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Iris/Core/Private/Iris/ReplicationSystem/ObjectReferenceCache.h:122

Scope (from outer to inner):

file
namespace    UE::Net::Private
class        class FObjectReferenceCache

Source code excerpt:

	enum class EAsyncLoadMode : uint8
	{
		UseCVar			= 0,		// Use CVar (net.AllowAsyncLoading) to determine if we should async load
		ForceDisable	= 1,		// Disable async loading
		ForceEnable		= 2,		// Force enable async loading
	};

	void SetAsyncLoadMode(const EAsyncLoadMode NewMode);
	bool ShouldAsyncLoad() const;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PackageMapClient.cpp:122

Scope: file

Source code excerpt:

}

static TAutoConsoleVariable<int32> CVarAllowAsyncLoading(
	TEXT("net.AllowAsyncLoading"),
	0,
	TEXT("Allow async loading of unloaded assets referenced in packets."
		" If false the client will hitch and immediately load the asset,"
		" if true the packet will be delayed while the asset is async loaded."
		" net.DelayUnmappedRPCs can be enabled to delay RPCs relying on async loading assets.")

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PackageMapClient.cpp:3927

Scope (from outer to inner):

file
function     bool FNetGUIDCache::ShouldAsyncLoad

Source code excerpt:

	switch ( AsyncLoadMode )
	{
		case EAsyncLoadMode::UseCVar:		return CVarAllowAsyncLoading.GetValueOnAnyThread() > 0;
		case EAsyncLoadMode::ForceDisable:	return false;
		case EAsyncLoadMode::ForceEnable:	return true;
		default: ensureMsgf( false, TEXT( "Invalid AsyncLoadMode: %i" ), (int32)AsyncLoadMode ); return false;
	}
}

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Iris/Core/Private/Iris/ReplicationSystem/ObjectReferenceCache.cpp:1980

Scope (from outer to inner):

file
namespace    UE::Net::Private
function     void FObjectReferenceCache::SetAsyncLoadMode

Source code excerpt:

{
	AsyncLoadMode = NewMode;
	if (const IConsoleVariable* CVarAllowAsyncLoading = IConsoleManager::Get().FindConsoleVariable(TEXT("net.AllowAsyncLoading"), false /* bTrackFrequentCalls */))
	{
		bCachedCVarAllowAsyncLoading = CVarAllowAsyncLoading->GetInt() > 0;
	}
}

bool FObjectReferenceCache::ShouldAsyncLoad() const
{
	if (!bIrisAllowAsyncLoading)