p.EnsureUnweldModifiesGTOnly

p.EnsureUnweldModifiesGTOnly

#Overview

name: p.EnsureUnweldModifiesGTOnly

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 p.EnsureUnweldModifiesGTOnly is to ensure that the unweld operation only modifies geometry on the game thread and not on the physics thread. This variable is used as a safeguard in the physics engine to prevent potential race conditions or inconsistencies between the game and physics threads.

This setting variable is primarily used in the Unreal Engine’s physics subsystem, specifically within the BodyInstance module. It’s referenced in the FBodyInstance class, which is responsible for managing the physical properties of individual objects in the game world.

The value of this variable is set through a console variable (CVar) system, as evidenced by the FAutoConsoleVariableRef declaration. This allows developers to modify the value at runtime or through configuration files.

The associated variable EnsureUnweldModifiesGTOnly interacts directly with p.EnsureUnweldModifiesGTOnly. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable is used as a safety check in the UnWeld function of FBodyInstance. When enabled (set to a non-zero value), it will trigger an assertion if an attempt is made to unweld a body that is already in the physics solver. This helps prevent potential issues with modifying physics objects that are actively being simulated.

Best practices when using this variable include:

  1. Enable it during development and testing to catch potential threading issues early.
  2. Be cautious when disabling it in production, as it may hide underlying problems with physics object manipulation.
  3. Use it in conjunction with proper thread synchronization techniques when working with physics objects.
  4. Monitor performance impact, as additional checks may affect performance in physics-heavy scenarios.

Regarding the associated variable EnsureUnweldModifiesGTOnly:

The purpose of EnsureUnweldModifiesGTOnly is identical to p.EnsureUnweldModifiesGTOnly. It’s an integer variable that acts as the actual storage for the console variable.

This variable is used within the Unreal Engine’s physics subsystem, specifically in the BodyInstance module.

The value of EnsureUnweldModifiesGTOnly is set through the console variable system and is directly linked to p.EnsureUnweldModifiesGTOnly.

It interacts directly with p.EnsureUnweldModifiesGTOnly and is used in the UnWeld function to perform the safety check.

Developers should be aware that modifying EnsureUnweldModifiesGTOnly directly in code might not have the intended effect, as its value is controlled by the console variable system.

Best practices for EnsureUnweldModifiesGTOnly are the same as those for p.EnsureUnweldModifiesGTOnly, as they are essentially the same variable with different access methods.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/BodyInstance.cpp:1795

Scope: file

Source code excerpt:


int32 EnsureUnweldModifiesGTOnly = 0;
FAutoConsoleVariableRef CVarEnsureUnweldModifiesGTOnly(TEXT("p.EnsureUnweldModifiesGTOnly"), EnsureUnweldModifiesGTOnly, TEXT("Ensure if unweld modifies geometry shared with physics thread"));

void FBodyInstance::UnWeld(FBodyInstance* TheirBI)
{
	check(IsInGameThread());

	bool bShapesChanged = false;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/BodyInstance.cpp:1794

Scope: file

Source code excerpt:

}

int32 EnsureUnweldModifiesGTOnly = 0;
FAutoConsoleVariableRef CVarEnsureUnweldModifiesGTOnly(TEXT("p.EnsureUnweldModifiesGTOnly"), EnsureUnweldModifiesGTOnly, TEXT("Ensure if unweld modifies geometry shared with physics thread"));

void FBodyInstance::UnWeld(FBodyInstance* TheirBI)
{
	check(IsInGameThread());

	bool bShapesChanged = false;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/BodyInstance.cpp:1809

Scope (from outer to inner):

file
function     void FBodyInstance::UnWeld
lambda-function

Source code excerpt:

		const int32 NumTotalShapes = Shapes.Num();

		if(EnsureUnweldModifiesGTOnly && Actor->GetSolverBase() != nullptr)
		{
			ensureAlwaysMsgf(false, TEXT("Tried to unweld on body already in solver %s"), *GetBodyDebugName());
		}

		// reversed since FPhysicsInterface::DetachShape is removing shapes
		for (int Idx = Shapes.Num()-1; Idx >=0; Idx--)