NetBlobHandlerDefinitions

NetBlobHandlerDefinitions

#Overview

name: NetBlobHandlerDefinitions

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of NetBlobHandlerDefinitions is to define and manage a collection of network blob handler definitions used in Unreal Engine’s replication system. It is primarily used for handling network object attachments and object splitting in the context of network replication.

This setting variable is primarily relied upon by the Iris Core module, which is part of Unreal Engine’s experimental replication system. It is also used in the ReplicationSystemTestPlugin for testing purposes.

The value of this variable is set in the UNetBlobHandlerDefinitions class, which is derived from UObject. It is defined as a UPROPERTY with the Config specifier, indicating that its values can be set in configuration files.

NetBlobHandlerDefinitions interacts with other parts of the replication system, particularly the FNetBlobHandlerManager class, which uses these definitions to initialize and register network blob handlers.

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

  1. The number of NetBlobHandlerDefinitions is limited to 127 (must be less than 128) to ensure proper serialization.
  2. Each definition in the array corresponds to a specific network blob handler class.
  3. The order of definitions in the array is important, as it determines the NetBlobType index assigned to each handler.

Best practices when using this variable include:

  1. Ensure that all necessary network blob handlers are defined in the configuration.
  2. Keep the number of handlers below the 127 limit to avoid serialization issues.
  3. Maintain consistency between the defined handlers and the actual implementation of those handler classes.
  4. When adding custom handlers, follow the naming convention and structure used by existing handlers.
  5. Use the provided APIs (like AddNetBlobHandlerDefinitions) when modifying the definitions, especially in test scenarios.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:1298, section: [/Script/IrisCore.NetBlobHandlerDefinitions]

Location: <Workspace>/Engine/Config/BaseEngine.ini:1299, section: [/Script/IrisCore.NetBlobHandlerDefinitions]

Location: <Workspace>/Engine/Config/BaseEngine.ini:1300, section: [/Script/IrisCore.NetBlobHandlerDefinitions]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/ReplicationSystemTestPlugin/Source/Private/Tests/ReplicationSystem/TestObjectSplitting.cpp:95

Scope (from outer to inner):

file
namespace    UE::Net::Private
class        class FSplitObjectTestFixture : public FNetBlobTestFixture
function     void AddNetBlobHandlerDefinitions

Source code excerpt:

	{
		AddMockNetBlobHandlerDefinition();
		const FNetBlobHandlerDefinition NetBlobHandlerDefinitions[] = 
		{
			{TEXT("MockNetObjectAttachmentHandler"),},
			// The proper partial attachment and net object blob handlers are needed for splitting huge objects and attachments.
			{TEXT("PartialNetObjectAttachmentHandler"),}, 
			{TEXT("NetObjectBlobHandler"),}, 
		};
		Super::AddNetBlobHandlerDefinitions(NetBlobHandlerDefinitions, UE_ARRAY_COUNT(NetBlobHandlerDefinitions));
	}


protected:
	TStrongObjectPtr<UMockNetObjectAttachmentHandler> ServerMockNetObjectAttachmentHandler;
	TStrongObjectPtr<UMockNetObjectAttachmentHandler> ClientMockNetObjectAttachmentHandler;

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Iris/Core/Private/Iris/ReplicationSystem/NetBlob/NetBlobHandlerDefinitions.h:37

Scope (from outer to inner):

file
class        class UNetBlobHandlerDefinitions : public UObject

Source code excerpt:


	UPROPERTY(Config)
	TArray<FNetBlobHandlerDefinition> NetBlobHandlerDefinitions;

#if WITH_AUTOMATION_WORKER
public:
	TArray<FNetBlobHandlerDefinition>& ReadWriteHandlerDefinitions() { return NetBlobHandlerDefinitions; }
#endif
};

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Iris/Core/Private/Iris/ReplicationSystem/NetBlob/NetBlobHandlerManager.cpp:17

Scope (from outer to inner):

file
namespace    UE::Net::Private
function     void FNetBlobHandlerManager::Init

Source code excerpt:

	const UNetBlobHandlerDefinitions* BlobHandlerDefinitions = GetDefault<UNetBlobHandlerDefinitions>();
	// Check if FNetBlob::SerializeCreationInfo needs to use more bits for blob type.
	checkf(BlobHandlerDefinitions->NetBlobHandlerDefinitions.Num() < 128, TEXT("Excessive amount of NetBlobHandlers: %d. This breaks net serialization."), BlobHandlerDefinitions->NetBlobHandlerDefinitions.Num());
	Handlers.SetNum(BlobHandlerDefinitions->NetBlobHandlerDefinitions.Num());
}

bool FNetBlobHandlerManager::RegisterHandler(UNetBlobHandler* Handler)
{
	if (Handler == nullptr)
	{

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Iris/Core/Private/Iris/ReplicationSystem/NetBlob/NetBlobHandlerManager.cpp:35

Scope (from outer to inner):

file
namespace    UE::Net::Private
function     bool FNetBlobHandlerManager::RegisterHandler

Source code excerpt:

	const FString& ClassName = Handler->GetClass()->GetName();
	const UNetBlobHandlerDefinitions* BlobHandlerDefinitions = GetDefault<UNetBlobHandlerDefinitions>();
	for (const FNetBlobHandlerDefinition& Definition : MakeArrayView(BlobHandlerDefinitions->NetBlobHandlerDefinitions))
	{
		if (Definition.ClassName.ToString() == ClassName)
		{
			const uint32 Index = static_cast<uint32>(&Definition - BlobHandlerDefinitions->NetBlobHandlerDefinitions.GetData());
			Handler->NetBlobType = Index;
			Handlers[Index] = Handler;
			return true;
		}
	}