ClusterUnion.DirtyRigidStateOnlyIfChanged

ClusterUnion.DirtyRigidStateOnlyIfChanged

#Overview

name: ClusterUnion.DirtyRigidStateOnlyIfChanged

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ClusterUnion.DirtyRigidStateOnlyIfChanged is to optimize network performance by controlling when the rigid state of a ClusterUnion component is marked as dirty and updated for replication. It’s part of the physics and networking system in Unreal Engine 5.

This setting variable is primarily used in the ClusterUnionComponent, which is part of the Engine module, specifically in the PhysicsEngine subsystem. It affects how the engine handles replication of physics states for clustered objects.

The value of this variable is set using an FAutoConsoleVariableRef, which means it can be changed at runtime through the console. By default, it is set to false.

This variable interacts closely with the ReplicatedRigidState of the ClusterUnionComponent. When set to true, it adds a check to only mark the rigid state as dirty and update the replicated data if there’s an actual change in the state.

Developers must be aware that:

  1. This variable can significantly impact network performance and behavior of physics replication.
  2. It’s part of a group of settings that control the ClusterUnion behavior, including bFlushNetDormancyOnSyncProxy and GSkipZeroStateInOnRep.

Best practices when using this variable:

  1. Enable it in scenarios where you want to reduce network traffic by only sending updates when the rigid state actually changes.
  2. Monitor its impact on gameplay, especially in multiplayer scenarios, to ensure it doesn’t cause unexpected behavior.
  3. Use it in conjunction with other ClusterUnion settings for fine-tuned control over physics replication.

Regarding the associated variable bDirtyRigidStateOnlyIfChanged:

This is the actual boolean variable that stores the value of the console variable. It’s used directly in the code to control the behavior of the ClusterUnionComponent.

The purpose of bDirtyRigidStateOnlyIfChanged is to implement the logic defined by the console variable. It’s used in the SyncClusterUnionFromProxy function to determine whether to update the replicated rigid state.

Developers should be aware that changing the console variable will directly affect this boolean, and thus the behavior of the ClusterUnionComponent. When debugging or profiling network behavior related to physics replication, this variable should be one of the first things to check.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/ClusterUnionComponent.cpp:39

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


	bool bDirtyRigidStateOnlyIfChanged = false;
	FAutoConsoleVariableRef CVarDirtyRigidStateOnlyIfChanged(TEXT("ClusterUnion.DirtyRigidStateOnlyIfChanged"), bDirtyRigidStateOnlyIfChanged, TEXT("Add a check for changed rigid state before marking it dirty and updating the replicated data. No need to flush an update if there was no change."));

	bool bFlushNetDormancyOnSyncProxy = true;
	FAutoConsoleVariableRef CVarFlushNetDormancyOnSyncProxy(TEXT("ClusterUnion.FlushNetDormancyOnSyncProxy"), bFlushNetDormancyOnSyncProxy, TEXT("When there is a new rigid state on the authority, flush net dormancy so that even if this object is net dorman the rigid state will come through to the client."));

	bool GSkipZeroStateInOnRep = true;
	FAutoConsoleVariableRef CVarSkipZeroState(TEXT("ClusterUnion.SkipZeroStateInOnRep"), GSkipZeroStateInOnRep, TEXT("Whether we skip 0 (uninitialized) states when running the onrep for the replicated rigid state of the cluster union"));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/ClusterUnionComponent.cpp:38

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	FAutoConsoleVariableRef CVarApplyReplicatedRigidStateOnCreatePhysicsState(TEXT("ClusterUnion.ApplyReplicatedRigidStateOnCreatePhysicsState"), bApplyReplicatedRigidStateOnCreatePhysicsState, TEXT("When physics state is created, apply replicated rigid state. Useful because sometimes the initial OnRep will have been called before a proxy exists, so initial properties will be unset"));

	bool bDirtyRigidStateOnlyIfChanged = false;
	FAutoConsoleVariableRef CVarDirtyRigidStateOnlyIfChanged(TEXT("ClusterUnion.DirtyRigidStateOnlyIfChanged"), bDirtyRigidStateOnlyIfChanged, TEXT("Add a check for changed rigid state before marking it dirty and updating the replicated data. No need to flush an update if there was no change."));

	bool bFlushNetDormancyOnSyncProxy = true;
	FAutoConsoleVariableRef CVarFlushNetDormancyOnSyncProxy(TEXT("ClusterUnion.FlushNetDormancyOnSyncProxy"), bFlushNetDormancyOnSyncProxy, TEXT("When there is a new rigid state on the authority, flush net dormancy so that even if this object is net dorman the rigid state will come through to the client."));

	bool GSkipZeroStateInOnRep = true;
	FAutoConsoleVariableRef CVarSkipZeroState(TEXT("ClusterUnion.SkipZeroStateInOnRep"), GSkipZeroStateInOnRep, TEXT("Whether we skip 0 (uninitialized) states when running the onrep for the replicated rigid state of the cluster union"));

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/ClusterUnionComponent.cpp:931

Scope (from outer to inner):

file
function     void UClusterUnionComponent::SyncClusterUnionFromProxy

Source code excerpt:


		// Only dirty the state if it has changed
		if (ReplicatedRigidState != NewReplicatedRigidState || bDirtyRigidStateOnlyIfChanged == false)
		{
			// Make sure that the new dirty data gets flushed through to clients even if the actor
			// has been made net dormant.
			if (bFlushNetDormancyOnSyncProxy)
			{
				if (AActor* Owner = GetOwner())