ChannelDefinitions

ChannelDefinitions

#Overview

name: ChannelDefinitions

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ChannelDefinitions is to specify available channel types and their associated UClass in Unreal Engine’s networking system. This variable is crucial for defining and managing network communication channels between server and client in multiplayer games.

ChannelDefinitions is primarily used by the networking subsystem of Unreal Engine, specifically within the UNetDriver class. This class is a core component of Unreal’s networking architecture, responsible for managing network connections and communication.

The value of this variable is set through configuration files, as indicated by the UPROPERTY(Config) decorator in the UNetDriver class definition. This allows developers to customize channel definitions without modifying engine source code.

ChannelDefinitions interacts closely with ChannelDefinitionMap, which is used for faster lookup of channel definitions by name. Both variables work together to manage and access channel information efficiently.

Developers must be aware of several important aspects when using this variable:

1. Channel names must be unique to avoid conflicts.
2. Static channel indices must also be unique to prevent overlapping.
3. Channel definitions can specify whether they should be initialized for clients, servers, or both.
4. The channel class specified in the definition must be valid and inherit from the appropriate base class.

Best practices for using ChannelDefinitions include:

1. Carefully plan your channel structure before defining them.
2. Use meaningful and descriptive channel names.
3. Ensure that required channels are properly configured, especially when using features like ObjectReplication.
4. Regularly review and update channel definitions as your project evolves.
5. Be mindful of performance implications when adding new channels, as each channel consumes network resources.
6. Use the ChannelDefinitionMap for efficient lookups rather than searching through the ChannelDefinitions array directly.

By properly managing ChannelDefinitions, developers can create robust and efficient networking systems in their Unreal Engine projects.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:1618, section: [/Script/Engine.NetDriver]

• INI Section: /Script/Engine.NetDriver
• Raw value: (ChannelName=Control, ClassName=/Script/Engine.ControlChannel, StaticChannelIndex=0, bTickOnCreate=true, bServerOpen=false, bClientOpen=true, bInitialServer=false, bInitialClient=true)
• Is Array: True

Location: <Workspace>/Engine/Config/BaseEngine.ini:1619, section: [/Script/Engine.NetDriver]

• INI Section: /Script/Engine.NetDriver
• Raw value: (ChannelName=Voice, ClassName=/Script/Engine.VoiceChannel, StaticChannelIndex=1, bTickOnCreate=true, bServerOpen=true, bClientOpen=true, bInitialServer=true, bInitialClient=true)
• Is Array: True

Location: <Workspace>/Engine/Config/BaseEngine.ini:1620, section: [/Script/Engine.NetDriver]

• INI Section: /Script/Engine.NetDriver
• Raw value: (ChannelName=DataStream, ClassName=/Script/Engine.DataStreamChannel, StaticChannelIndex=2, bTickOnCreate=true, bServerOpen=true, bClientOpen=true, bInitialServer=true, bInitialClient=true)
• Is Array: True

Location: <Workspace>/Engine/Config/BaseEngine.ini:1621, section: [/Script/Engine.NetDriver]

• INI Section: /Script/Engine.NetDriver
• Raw value: (ChannelName=Actor, ClassName=/Script/Engine.ActorChannel, StaticChannelIndex=-1, bTickOnCreate=false, bServerOpen=true, bClientOpen=false, bInitialServer=false, bInitialClient=false)
• Is Array: True

Location: <Workspace>/Engine/Config/BaseEngine.ini:1804, section: [/Script/Engine.DemoNetDriver]

• INI Section: /Script/Engine.DemoNetDriver
• Raw value: CLEAR_ARRAY
• Is Array: True

Location: <Workspace>/Engine/Config/BaseEngine.ini:1805, section: [/Script/Engine.DemoNetDriver]

• INI Section: /Script/Engine.DemoNetDriver
• Raw value: (ChannelName=Control, ClassName=/Script/Engine.ControlChannel, StaticChannelIndex=0, bTickOnCreate=true, bServerOpen=false, bClientOpen=true, bInitialServer=false, bInitialClient=true)
• Is Array: True

Location: <Workspace>/Engine/Config/BaseEngine.ini:1806, section: [/Script/Engine.DemoNetDriver]

• INI Section: /Script/Engine.DemoNetDriver
• Raw value: (ChannelName=Actor, ClassName=/Script/Engine.ActorChannel, StaticChannelIndex=-1, bTickOnCreate=false, bServerOpen=true, bClientOpen=false, bInitialServer=false, bInitialClient=false)
• Is Array: True

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Engine/NetDriver.h:980

Scope (from outer to inner):

file
class        class UNetDriver : public UObject, public FExec

Source code excerpt:

	/** Used to specify available channel types and their associated UClass */
	UPROPERTY(Config)
	TArray<FChannelDefinition> ChannelDefinitions;

	/** Used for faster lookup of channel definitions by name. */
	UPROPERTY()
	TMap<FName, FChannelDefinition> ChannelDefinitionMap;

	/** @return true if the specified channel definition exists. */

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Net/Iris/ReplicationSystem/ActorReplicationBridge.cpp:925

Scope (from outer to inner):

file
function     void UActorReplicationBridge::SetNetDriver

Source code excerpt:

		if (!RequiredChannelName.IsNone())
		{
			const bool bRequiredChannelIsConfigured = InNetDriver->ChannelDefinitions.FindByPredicate([RequiredChannelName](const FChannelDefinition& rhs)
				{
					return rhs.ClassName == RequiredChannelName;
				}) != nullptr;

			checkf(bRequiredChannelIsConfigured, TEXT("ObjectReplication needs the netdriver channel %s to work. Add this channel to the netdriver channel definitions config"), *RequiredChannelName.ToString());
		}

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/NetDriver.cpp:692

Scope (from outer to inner):

file
function     void UNetDriver::LoadChannelDefinitions

Source code excerpt:

		ChannelDefinitionMap.Reset();

		for (FChannelDefinition& ChannelDef : ChannelDefinitions)
		{
			UE_CLOG(!ChannelDef.ChannelName.ToEName() || !ShouldReplicateAsInteger(*ChannelDef.ChannelName.ToEName(), ChannelDef.ChannelName),
				LogNet, Warning, TEXT("Channel name will be serialized as a string: %s"), *ChannelDef.ChannelName.ToString());
			UE_CLOG(ChannelDefinitionMap.Contains(ChannelDef.ChannelName), LogNet, Error, TEXT("Channel name is defined multiple times: %s"), *ChannelDef.ChannelName.ToString());
			UE_CLOG(StaticChannelIndices.Contains(ChannelDef.StaticChannelIndex), LogNet, Error, TEXT("Channel static index is already in use: %s %i"), *ChannelDef.ChannelName.ToString(), ChannelDef.StaticChannelIndex);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/NetDriver.cpp:7564

Scope (from outer to inner):

file
function     void UNetDriver::CreateInitialClientChannels

Source code excerpt:

	if (ServerConnection != nullptr)
	{
		for (const FChannelDefinition& ChannelDef : ChannelDefinitions)
		{
			if (ChannelDef.bInitialClient && (ChannelDef.ChannelClass != nullptr))
			{
				ServerConnection->CreateChannelByName(ChannelDef.ChannelName, EChannelCreateFlags::OpenedLocally, ChannelDef.StaticChannelIndex);
			}
		}

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/NetDriver.cpp:7578

Scope (from outer to inner):

file
function     void UNetDriver::CreateInitialServerChannels

Source code excerpt:

	if (ClientConnection != nullptr)
	{
		for (const FChannelDefinition& ChannelDef : ChannelDefinitions)
		{
			if (ChannelDef.bInitialServer && (ChannelDef.ChannelClass != nullptr))
			{
				ClientConnection->CreateChannelByName(ChannelDef.ChannelName, EChannelCreateFlags::OpenedLocally, ChannelDef.StaticChannelIndex);
			}
		}