AbilitySystem.PredictionKey.StaleKeyBehavior

AbilitySystem.PredictionKey.StaleKeyBehavior

#Overview

name: AbilitySystem.PredictionKey.StaleKeyBehavior

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

• type: Var
• help: How do we handle stale keys? 0 = CaughtUp. 1 = Reject. 2 = Drop

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of AbilitySystem.PredictionKey.StaleKeyBehavior is to control how the Unreal Engine’s Gameplay Ability System handles stale prediction keys. This setting is crucial for managing network prediction and synchronization in multiplayer games using the Gameplay Ability System.

This setting variable is primarily used by the Gameplay Abilities plugin, which is a part of Unreal Engine’s runtime systems. Specifically, it’s used within the GameplayPrediction module, which handles prediction and synchronization for networked gameplay abilities.

The value of this variable is set through a console variable (CVar) named “AbilitySystem.PredictionKey.StaleKeyBehavior”. It’s initialized with a default value of 0 and can be changed at runtime through console commands or configuration files.

The associated variable CVarStaleKeyBehaviorValue directly interacts with AbilitySystem.PredictionKey.StaleKeyBehavior. It holds the integer value that determines the behavior for handling stale keys.

Developers must be aware that this variable significantly impacts how the prediction system behaves when dealing with outdated or stale prediction keys. The possible values and their meanings are: 0 = CaughtUp (Legacy behavior) 1 = Reject 2 = Drop

Best practices when using this variable include:

1. Understanding the implications of each behavior option on your game’s networking and prediction systems.
2. Testing thoroughly with different values to ensure optimal performance and synchronization in various network conditions.
3. Considering the trade-offs between consistency (CaughtUp) and potential exploitation (Reject or Drop).
4. Documenting the chosen value and the reasoning behind it for future reference.

Regarding the associated variable CVarStaleKeyBehaviorValue:

• It’s an integer that directly holds the value set by the console variable.
• It’s used in conditional statements to determine the behavior when handling stale prediction keys.
• Developers should not modify this variable directly but instead use the console variable to change its value.
• When reading this variable in code, developers should be aware that its value can change at runtime, potentially affecting the behavior of the prediction system.

In summary, proper use of this variable is critical for maintaining smooth and accurate gameplay in networked environments using the Gameplay Ability System.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/GameplayAbilities/Source/GameplayAbilities/Private/GameplayPrediction.cpp:23

Scope (from outer to inner):

file
namespace    UE::AbilitySystem::Private

Source code excerpt:

	// What should we do with these old stale FPredictionKeys?  Prior to UE5.5, we always CaughtUp.  I believe it's actually safer to drop.
	int32 CVarStaleKeyBehaviorValue = 0;
	FAutoConsoleVariableRef CVarStaleKeyBehavior(TEXT("AbilitySystem.PredictionKey.StaleKeyBehavior"), CVarStaleKeyBehaviorValue,
		TEXT("How do we handle stale keys? 0 = CaughtUp. 1 = Reject. 2 = Drop"));

	// How should we deal with dependent keys (in a chain)?  Prior to UE5.5, old keys implied new keys.  We introduced some new functionality (explained in the help text).
	// 0 (no bitmask) is legacy behavior.  Logically, (0x1 | 0x2) = 3 is the correct value. The long-term fix will be a value of 3.
	int32 CVarDependentChainBehaviorValue = 0;
	FAutoConsoleVariableRef CVarDependentChainBehavior(TEXT("AbilitySystem.PredictionKey.DepChainBehavior"), CVarDependentChainBehaviorValue,

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/GameplayAbilities/Source/GameplayAbilities/Private/GameplayPrediction.cpp:22

Scope (from outer to inner):

file
namespace    UE::AbilitySystem::Private

Source code excerpt:

	// What should we do with these old stale FPredictionKeys?  Prior to UE5.5, we always CaughtUp.  I believe it's actually safer to drop.
	int32 CVarStaleKeyBehaviorValue = 0;
	FAutoConsoleVariableRef CVarStaleKeyBehavior(TEXT("AbilitySystem.PredictionKey.StaleKeyBehavior"), CVarStaleKeyBehaviorValue,
		TEXT("How do we handle stale keys? 0 = CaughtUp. 1 = Reject. 2 = Drop"));

	// How should we deal with dependent keys (in a chain)?  Prior to UE5.5, old keys implied new keys.  We introduced some new functionality (explained in the help text).
	// 0 (no bitmask) is legacy behavior.  Logically, (0x1 | 0x2) = 3 is the correct value. The long-term fix will be a value of 3.
	int32 CVarDependentChainBehaviorValue = 0;
	FAutoConsoleVariableRef CVarDependentChainBehavior(TEXT("AbilitySystem.PredictionKey.DepChainBehavior"), CVarDependentChainBehaviorValue,

#Loc: <Workspace>/Engine/Plugins/Runtime/GameplayAbilities/Source/GameplayAbilities/Private/GameplayPrediction.cpp:596

Scope (from outer to inner):

file
function     void FReplicatedPredictionKeyItem::OnRep

Source code excerpt:

			UE_LOG(LogPredictionKey, Warning, TEXT("UnAck'd PredictionKey %d in DelegateMap while OnRep %s. This indicates keychains are created w/o being sent to & ack'd by the server. Last ack'd key in that slot was %s."), Key, *PredictionKey.ToString(), *ExistingKeyInSlot.ToString());
			
			if (CVarStaleKeyBehaviorValue == 0)
			{
				// This is legacy functionality.
				FPredictionKeyDelegates::CatchUpTo(Key);
			}
			else if (CVarStaleKeyBehaviorValue == 1)
			{
				// Alternatively, this may be more appropriate as the server didn't specifically acknowledge us.
				FPredictionKeyDelegates::Reject(Key);
			}
			else
			{