NetEmulation.PktIncomingLoss

NetEmulation.PktIncomingLoss

#Overview

name: NetEmulation.PktIncomingLoss

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

It is referenced in 9 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of NetEmulation.PktIncomingLoss is to simulate incoming packet loss in network communication for testing and debugging purposes in Unreal Engine 5.

This setting variable is primarily used by the networking subsystem of Unreal Engine, specifically within the NetDriver and NetConnection modules. It’s part of the network emulation feature set, which allows developers to simulate various network conditions for testing and development purposes.

The value of this variable is set through various means:

  1. It can be configured in the engine’s configuration files (INI files).
  2. It can be set via console commands during runtime.
  3. It can be adjusted through the LevelEditorPlayNetworkEmulationSettings in the editor.

NetEmulation.PktIncomingLoss interacts with several other network emulation variables, such as PktIncomingLagMin, PktIncomingLagMax, and PktJitter. Together, these variables provide a comprehensive set of tools for simulating different network conditions.

Developers should be aware that:

  1. This variable represents a percentage (0-100) of incoming packets that will be artificially dropped.
  2. It’s only active when network emulation is enabled (typically in development or testing environments).
  3. Overuse of this setting can significantly impact the perceived performance of the game or application.

Best practices when using this variable include:

  1. Use it in conjunction with other network emulation settings for a more realistic simulation of network conditions.
  2. Test with various values to ensure your game’s netcode is robust against different levels of packet loss.
  3. Remember to disable or reset this setting before shipping your game or when not actively testing network conditions.

Regarding the associated variable PktIncomingLoss: This is essentially the same variable as NetEmulation.PktIncomingLoss, but it’s used in different contexts within the engine. It serves the same purpose of simulating incoming packet loss. The value is shared between these variables, ensuring consistency across different parts of the engine that deal with network emulation. The same considerations and best practices apply to this variable as well.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Net/NetEmulationHelper.cpp:356

Scope (from outer to inner):

file
namespace    UE::Net::Private::NetEmulationHelper

Source code excerpt:

	BUILD_NETEMULATION_CONSOLE_COMMAND(PktIncomingLagMin, "Sets minimum incoming packet latency");
	BUILD_NETEMULATION_CONSOLE_COMMAND(PktIncomingLagMax, "Sets maximum incoming packet latency");
	BUILD_NETEMULATION_CONSOLE_COMMAND(PktIncomingLoss, "Simulates incoming packet loss");
	BUILD_NETEMULATION_CONSOLE_COMMAND(PktJitter, "Simulates outgoing packet jitter");


} // end namespace UE::Net::Private::NetEmulationHelper

#endif //#if DO_ENABLE_NET_TEST

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Settings/LevelEditorPlayNetworkEmulationSettings.cpp:34

Scope (from outer to inner):

file
namespace    NetworkEmulationSettingsHelper
function     void ConvertNetDriverSettingsToLevelEditorSettings

Source code excerpt:


		OutgoingTrafficPieSettings.PacketLossPercentage = NetDriverSettings.PktLoss;

		IncomingTrafficPieSettings.MinLatency = NetDriverSettings.PktIncomingLagMin;
		IncomingTrafficPieSettings.MaxLatency = NetDriverSettings.PktIncomingLagMax;
		IncomingTrafficPieSettings.PacketLossPercentage = NetDriverSettings.PktIncomingLoss;
	}

	FNetworkEmulationPacketSettings* GetPacketSettingsFromHandle(const TSharedPtr<IPropertyHandle>& PropertyHandle)
	{
		void* ValueData(nullptr);
		FPropertyAccess::Result Result = PropertyHandle->GetValueData(ValueData);
		if (Result != FPropertyAccess::Success)
		{
			return nullptr;
		}

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Settings/LevelEditorPlayNetworkEmulationSettings.cpp:264

Scope (from outer to inner):

file
function     void FLevelEditorPlayNetworkEmulationSettings::ConvertToNetDriverSettings

Source code excerpt:

		OutNetDriverSettings.PktLagMin = OutPackets.MinLatency;
		OutNetDriverSettings.PktLagMax = OutPackets.MaxLatency;
		OutNetDriverSettings.PktLoss = OutPackets.PacketLossPercentage;
		OutNetDriverSettings.PktIncomingLagMin = InPackets.MinLatency;
		OutNetDriverSettings.PktIncomingLagMax = InPackets.MaxLatency;
		OutNetDriverSettings.PktIncomingLoss = InPackets.PacketLossPercentage;
	}
}

FString FLevelEditorPlayNetworkEmulationSettings::BuildPacketSettingsForCmdLine() const
{
	// Empty string when disabled
	if (!bIsNetworkEmulationEnabled)
	{
		return FString();
	}

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

Scope: file

Source code excerpt:

	/**
	 * The ratio of incoming packets that will be dropped
	 * to simulate packet loss
	 */
	UPROPERTY(EditAnywhere, Category = "Simulation Settings")
	int32	PktIncomingLoss = 0;

	/**
	 * Causes sent packets to have a variable latency that fluctuates from [PktLagMin] to [PktLagMin+PktJitter]
	 * Note that this will cause packet loss on the receiving end.
	 */
	UPROPERTY(EditAnywhere, Category = "Simulation Settings")
	int32	PktJitter = 0;

	/** reads in settings from the .ini file 
	 * @note: overwrites all previous settings
	 */

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Net/NetEmulationHelper.cpp:353

Scope (from outer to inner):

file
namespace    UE::Net::Private::NetEmulationHelper

Source code excerpt:

	BUILD_NETEMULATION_CONSOLE_COMMAND(PktLagVariance, "Simulates variable network packet lag");
	BUILD_NETEMULATION_CONSOLE_COMMAND(PktLagMin, "Sets minimum outgoing packet latency");
	BUILD_NETEMULATION_CONSOLE_COMMAND(PktLagMax, "Sets maximum outgoing packet latency)");
	BUILD_NETEMULATION_CONSOLE_COMMAND(PktIncomingLagMin, "Sets minimum incoming packet latency");
	BUILD_NETEMULATION_CONSOLE_COMMAND(PktIncomingLagMax, "Sets maximum incoming packet latency");
	BUILD_NETEMULATION_CONSOLE_COMMAND(PktIncomingLoss, "Simulates incoming packet loss");
	BUILD_NETEMULATION_CONSOLE_COMMAND(PktJitter, "Simulates outgoing packet jitter");


} // end namespace UE::Net::Private::NetEmulationHelper

#endif //#if DO_ENABLE_NET_TEST

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

Scope (from outer to inner):

file
function     void UNetConnection::ReceivedPacket

Source code excerpt:

	}

#if DO_ENABLE_NET_TEST
	if (!IsInternalAck() && !bIsReinjectingDelayedPackets)
	{
		if (PacketSimulationSettings.PktIncomingLoss)
		{
			if (FMath::FRand() * 100.f < PacketSimulationSettings.PktIncomingLoss)
			{
				UE_LOG(LogNet, VeryVerbose, TEXT("Dropped incoming packet at %f"), FPlatformTime::Seconds());
				return;
			}

		}
		if (PacketSimulationSettings.PktIncomingLagMin > 0 || PacketSimulationSettings.PktIncomingLagMax > 0)
		{
			// ExtraLagInSec goes from [PktIncomingLagMin, PktIncomingLagMax]
			const double LagVarianceInMS = FMath::FRand() * double(PacketSimulationSettings.PktIncomingLagMax - PacketSimulationSettings.PktIncomingLagMin);
			const double ExtraLagInSec = (double(PacketSimulationSettings.PktIncomingLagMin) + LagVarianceInMS) / 1000.f;

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

Scope (from outer to inner):

file
function     void FPacketSimulationSettings::LoadConfig

Source code excerpt:

	
	ConfigHelperInt(TEXT("PktDup"), PktDup, OptionalQualifier);

	ConfigHelperInt(TEXT("PktIncomingLagMin"), PktIncomingLagMin, OptionalQualifier);
	ConfigHelperInt(TEXT("PktIncomingLagMax"), PktIncomingLagMax, OptionalQualifier);
	ConfigHelperInt(TEXT("PktIncomingLoss"), PktIncomingLoss, OptionalQualifier);

	ConfigHelperInt(TEXT("PktJitter"), PktJitter, OptionalQualifier);

	ValidateSettings();
#endif
}

bool FPacketSimulationSettings::LoadEmulationProfile(const TCHAR* ProfileName)
{
#if DO_ENABLE_NET_TEST
	const FString SectionName = FString::Printf(TEXT("%s.%s"), TEXT("PacketSimulationProfile"), ProfileName);

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

Scope (from outer to inner):

file
function     void FPacketSimulationSettings::ValidateSettings

Source code excerpt:


	PktDup = FMath::Clamp<int32>(PktDup, 0, 100);

	PktIncomingLagMin = FMath::Max(PktIncomingLagMin, 0);
	PktIncomingLagMax = FMath::Max(PktIncomingLagMin, PktIncomingLagMax);
	PktIncomingLoss = FMath::Clamp<int32>(PktIncomingLoss, 0, 100);
#endif
}

bool FPacketSimulationSettings::ConfigHelperInt(const TCHAR* Name, int32& Value, const TCHAR* OptionalQualifier)
{
#if DO_ENABLE_NET_TEST

	if (OptionalQualifier)
	{
		if (GConfig->GetInt(TEXT("PacketSimulationSettings"), *FString::Printf(TEXT("%s%s"), OptionalQualifier, Name), Value, GEngineIni))
		{

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

Scope (from outer to inner):

file
function     bool FPacketSimulationSettings::ParseSettings

Source code excerpt:

	if (ParseHelper(Cmd, TEXT("PktIncomingLagMax="), PktIncomingLagMax, OptionalQualifier))
	{
		bParsed = true;
		UE_LOG(LogNet, Log, TEXT("PktIncomingLagMax set to %d"), PktIncomingLagMax);
	}
	if (ParseHelper(Cmd, TEXT("PktIncomingLoss="), PktIncomingLoss, OptionalQualifier))
	{
		bParsed = true;
		UE_LOG(LogNet, Log, TEXT("PktIncomingLoss set to %d"), PktIncomingLoss);
	}
	if (ParseHelper(Cmd, TEXT("PktJitter="), PktJitter, OptionalQualifier))
	{
		bParsed = true;
		UE_LOG(LogNet, Log, TEXT("PktJitter set to %d"), PktJitter);
	}

	ValidateSettings();
#endif
	return bParsed;
}