p.EnableDeferredPhysicsCreation

p.EnableDeferredPhysicsCreation

#Overview

name: p.EnableDeferredPhysicsCreation

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.EnableDeferredPhysicsCreation is to control whether physics creation is deferred in Unreal Engine 5. This setting is primarily used in the physics system to optimize performance by allowing physics state creation to be batched and parallelized.

This setting variable is primarily used in the Engine module, specifically within the components and physics subsystems. It is referenced in ActorComponent.cpp and BodySetup.cpp, which are core parts of the engine’s physics and component systems.

The value of this variable is set through a console variable (CVar) named “p.EnableDeferredPhysicsCreation”. It is associated with an integer variable GEnableDeferredPhysicsCreation, which shares the same value.

The main interactions with this variable occur in the following contexts:

  1. In UActorComponent::CreatePhysicsState, where it determines whether physics creation should be deferred for certain primitive components.
  2. In UActorComponent::DestroyPhysicsState, where it influences the cleanup of deferred physics state creation.
  3. In UBodySetup::PostLoad, where it determines whether to immediately create physics meshes or defer this operation.

Developers should be aware that enabling this feature can change the timing of physics state creation, which may impact game behavior if not accounted for. It’s particularly important when working with primitive components and their physics representations.

Best practices when using this variable include:

  1. Testing thoroughly with both enabled and disabled states to ensure consistent behavior.
  2. Being mindful of potential performance implications, especially in scenes with many physics objects.
  3. Considering the impact on gameplay mechanics that rely on immediate physics state creation.

Regarding the associated variable GEnableDeferredPhysicsCreation:

The purpose of GEnableDeferredPhysicsCreation is to serve as the actual storage for the deferred physics creation setting. It is an integer variable that directly controls the behavior set by p.EnableDeferredPhysicsCreation.

This variable is used in the Engine module, specifically in the components and physics systems. It’s declared in ActorComponent.h and defined in ActorComponent.cpp.

The value of GEnableDeferredPhysicsCreation is set through the console variable p.EnableDeferredPhysicsCreation. It interacts directly with the physics creation logic in various component and physics-related functions.

Developers should be aware that this is the actual variable checked in the code, so any runtime changes to the physics deferral behavior will be reflected in this variable.

Best practices for GEnableDeferredPhysicsCreation include:

  1. Avoid directly modifying this variable in code; instead, use the console variable system to change its value.
  2. When debugging physics-related issues, check the value of this variable to understand the current state of physics creation deferral.
  3. Consider exposing this setting in debug menus or configuration files for easier testing and optimization.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/ActorComponent.cpp:104

Scope: file

Source code excerpt:

int32 GEnableDeferredPhysicsCreation = 0;
FAutoConsoleVariableRef CVarEnableDeferredPhysicsCreation(
	TEXT("p.EnableDeferredPhysicsCreation"), 
	GEnableDeferredPhysicsCreation,
	TEXT("Enables/Disables deferred physics creation.")
);

void FRegisterComponentContext::Process()
{

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Components/ActorComponent.h:34

Scope: file

Source code excerpt:

class IPrimitiveComponent;

ENGINE_API extern int32 GEnableDeferredPhysicsCreation;

class FRegisterComponentContext
{
public:
	FRegisterComponentContext(UWorld* InWorld)
		: World(InWorld)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/ActorComponent.cpp:102

Scope: file

Source code excerpt:


// Allows for CreatePhysicsState to be deferred, to batch work and parallelize.
int32 GEnableDeferredPhysicsCreation = 0;
FAutoConsoleVariableRef CVarEnableDeferredPhysicsCreation(
	TEXT("p.EnableDeferredPhysicsCreation"), 
	GEnableDeferredPhysicsCreation,
	TEXT("Enables/Disables deferred physics creation.")
);

void FRegisterComponentContext::Process()
{
	TRACE_CPUPROFILER_EVENT_SCOPE(FRegisterComponentContext::Process)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/ActorComponent.cpp:1688

Scope (from outer to inner):

file
function     void UActorComponent::CreatePhysicsState

Source code excerpt:

			if (World->GetAllowDeferredPhysicsStateCreation())
			{
				if (GEnableDeferredPhysicsCreation && bAllowDeferral && Primitive && !Primitive->GetGenerateOverlapEvents())
				{
					if (UBodySetup* Setup = Primitive->GetBodySetup())
					{
						if (!Setup->bCreatedPhysicsMeshes)
						{
							ShouldDefer = true;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/ActorComponent.cpp:1737

Scope (from outer to inner):

file
function     void UActorComponent::DestroyPhysicsState

Source code excerpt:

		checkf(!HasValidPhysicsState(), TEXT("Failed to destroy physics state (%s)"), *GetFullName());
	}
	else if(GEnableDeferredPhysicsCreation)
	{
		UPrimitiveComponent* PrimitiveComponent = Cast<UPrimitiveComponent>(this);
		if (PrimitiveComponent && PrimitiveComponent->DeferredCreatePhysicsStateScene != nullptr)
		{
			// We had to cache this scene because World ptr is null as we have unregistered already.
			PrimitiveComponent->DeferredCreatePhysicsStateScene->RemoveDeferredPhysicsStateCreation(PrimitiveComponent);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/BodySetup.cpp:1051

Scope (from outer to inner):

file
function     void UBodySetup::PostLoad

Source code excerpt:


	// If Deferring physics creation, skip so we can call CreatePhysicsMeshes in parallel.
	if (GEnableDeferredPhysicsCreation == false)
	{
		CreatePhysicsMeshes();
	}
}

void UBodySetup::UpdateTriMeshVertices(const TArray<FVector> & NewPositions)