PktLoss

PktLoss

#Overview

name: PktLoss

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 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of PktLoss is to simulate network packet loss in Unreal Engine’s networking system. This setting is used for network emulation and testing, allowing developers to simulate unreliable network conditions during development and testing phases.

PktLoss is primarily used in the networking subsystem of Unreal Engine, specifically within the NetDriver and NetConnection components. It’s part of the packet simulation settings that help developers test their games under various network conditions.

The value of this variable is typically set through configuration files, console commands, or programmatically. It can be loaded from config files using the LoadConfig function in FPacketSimulationSettings, or set via console commands like “PktLoss” defined in the NetEmulationHelper.

PktLoss interacts with other network simulation variables such as PktLossMinSize and PktLossMaxSize, which define the size range of packets that can be dropped. It’s also used in conjunction with other network simulation settings like PktLag, PktOrder, and PktDup.

Developers must be aware that PktLoss is clamped between 0 and 100, representing a percentage. It’s only active when DO_ENABLE_NET_TEST is defined, typically in development builds.

Best practices when using this variable include:

  1. Use it in conjunction with other network simulation settings for comprehensive testing.
  2. Remember to disable it in production builds.
  3. Use it to test your game’s resilience to packet loss and ensure proper handling of lost packets.
  4. Combine it with different values of PktLossMinSize and PktLossMaxSize to simulate loss of different packet sizes.
  5. Use the console commands for quick testing and iteration during development.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:3266, section: [PacketSimulationProfile.Off]

Location: <Workspace>/Engine/Config/BaseEngine.ini:3275, section: [PacketSimulationProfile.Average]

Location: <Workspace>/Engine/Config/BaseEngine.ini:3284, section: [PacketSimulationProfile.Bad]

#References in C++ code

#Callsites

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

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

Scope (from outer to inner):

file
namespace    NetworkEmulationSettingsHelper
function     void ConvertNetDriverSettingsToLevelEditorSettings

Source code excerpt:

		{
			OutgoingTrafficPieSettings.MinLatency = NetDriverSettings.PktLagMin;
			OutgoingTrafficPieSettings.MaxLatency = NetDriverSettings.PktLagMax;
		}

		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)

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

Scope (from outer to inner):

file
function     void FLevelEditorPlayNetworkEmulationSettings::ConvertToNetDriverSettings

Source code excerpt:

	if (IsCustomProfile() || !bProfileFound)
	{
		// For custom set the settings manually from the PIE variables
		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)
	{

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

Scope: file

Source code excerpt:

	 * Clamped between 0 and 100.
	 *
	 * Works with all other settings.
	 */
	UPROPERTY(EditAnywhere, Category="Simulation Settings")
	int32	PktLoss = 0;

	/**
	* Sets the maximum size of packets in bytes that will be dropped
	* according to the PktLoss setting. Default is INT_MAX.
	*
	* Works with all other settings.
	*/
	UPROPERTY(EditAnywhere, Category = "Simulation Settings")
	int32	PktLossMaxSize = 0;

	/**
	* Sets the minimum size of packets in bytes that will be dropped
	* according to the PktLoss setting. Default is 0.
	*
	* Works with all other settings.
	*/
	UPROPERTY(EditAnywhere, Category = "Simulation Settings")
	int32	PktLossMinSize = 0;

	/**
	 * When set, will cause calls to FlushNet to change ordering of packets at random.
	 * Value is treated as a bool (i.e. 0 = False, anything else = True).
	 * This works by randomly selecting packets to be delayed until a subsequent call to FlushNet.
	 *
	 * Takes precedence over PktDup and PktLag.
	 */
	UPROPERTY(EditAnywhere, Category="Simulation Settings")
	int32	PktOrder = 0;

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

Scope (from outer to inner):

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

Source code excerpt:

			PersistentPacketSimulationSettings.GetValue().ParseSettings(*CmdParams, nullptr); \
			ApplySimulationSettingsOnNetDrivers(World, PersistentPacketSimulationSettings.GetValue()); \
		} \
	}));

	BUILD_NETEMULATION_CONSOLE_COMMAND(PktLoss, "Simulates network packet loss");
	BUILD_NETEMULATION_CONSOLE_COMMAND(PktOrder, "Simulates network packets received out of order");
	BUILD_NETEMULATION_CONSOLE_COMMAND(PktDup, "Simulates sending/receiving duplicate network packets");
	BUILD_NETEMULATION_CONSOLE_COMMAND(PktLag, "Simulates network packet lag");
	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");

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

Scope (from outer to inner):

file
function     bool UNetConnection::ShouldDropOutgoingPacketForLossSimulation

Source code excerpt:


#if DO_ENABLE_NET_TEST
bool UNetConnection::ShouldDropOutgoingPacketForLossSimulation(int64 NumBits) const
{
	return Driver->IsSimulatingPacketLossBurst() || 
		(PacketSimulationSettings.PktLoss > 0 && 
         PacketSimulationSettings.ShouldDropPacketOfSize(NumBits) && 
         FMath::FRand() * 100.f < PacketSimulationSettings.PktLoss);
}
#endif

int32 UNetConnection::IsNetReady(bool Saturate)
{
	if (IsReplay())
	{
		return 1;
	}

	// Return whether we can send more data without saturation the connection.

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

Scope (from outer to inner):

file
function     void FPacketSimulationSettings::LoadConfig

Source code excerpt:

 * @note: overwrites all previous settings
 */
void FPacketSimulationSettings::LoadConfig(const TCHAR* OptionalQualifier)
{
#if DO_ENABLE_NET_TEST
	ConfigHelperInt(TEXT("PktLoss"), PktLoss, OptionalQualifier);
	
	ConfigHelperInt(TEXT("PktLossMinSize"), PktLossMinSize, OptionalQualifier);
	ConfigHelperInt(TEXT("PktLossMaxSize"), PktLossMaxSize, OptionalQualifier);

	bool InPktOrder = !!PktOrder;
	ConfigHelperBool(TEXT("PktOrder"), InPktOrder, OptionalQualifier);
	PktOrder = int32(InPktOrder);
	
	ConfigHelperInt(TEXT("PktLag"), PktLag, OptionalQualifier);
	ConfigHelperInt(TEXT("PktLagVariance"), PktLagVariance, OptionalQualifier);

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

Scope (from outer to inner):

file
function     void FPacketSimulationSettings::ValidateSettings

Source code excerpt:


void FPacketSimulationSettings::ValidateSettings()
{
#if DO_ENABLE_NET_TEST

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

	PktOrder = FMath::Clamp<int32>(PktOrder, 0, 1);

	PktLagMin = FMath::Max(PktLagMin, 0);
	PktLagMax = FMath::Max(PktLagMin, PktLagMax);

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

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

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

Scope (from outer to inner):

file
function     bool FPacketSimulationSettings::ParseSettings

Source code excerpt:

	if (FParse::Value(Cmd, TEXT("PktEmulationProfile="), EmulationProfileName))
	{
		UE_LOG(LogNet, Log, TEXT("Applying EmulationProfile %s"), *EmulationProfileName);
		bParsed = LoadEmulationProfile(*EmulationProfileName);
	}
	if( ParseHelper(Cmd, TEXT("PktLoss="), PktLoss, OptionalQualifier) )
	{
		bParsed = true;
		UE_LOG(LogNet, Log, TEXT("PktLoss set to %d"), PktLoss);
	}
	if (ParseHelper(Cmd, TEXT("PktLossMinSize="), PktLossMinSize, OptionalQualifier))
	{
		bParsed = true;
		UE_LOG(LogNet, Log, TEXT("PktLossMinSize set to %d"), PktLossMinSize);
	}
	if (ParseHelper(Cmd, TEXT("PktLossMaxSize="), PktLossMaxSize, OptionalQualifier))
	{
		bParsed = true;
		UE_LOG(LogNet, Log, TEXT("PktLossMaxSize set to %d"), PktLossMaxSize);
	}