r.GeometryCollection.CustomRenderer.ForceBreak

r.GeometryCollection.CustomRenderer.ForceBreak

#Overview

name: r.GeometryCollection.CustomRenderer.ForceBreak

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

• type: Var
• help: Force the specified number of pieces to render individually, replacing their root proxy mesh.

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.GeometryCollection.CustomRenderer.ForceBreak is to control the rendering of individual pieces in a Geometry Collection, specifically for debugging and testing purposes in non-shipping builds of Unreal Engine 5.

This setting variable is primarily used in the Geometry Collection Engine module, which is part of Unreal Engine’s experimental features for handling complex, breakable objects in games.

The value of this variable is set through a console command, as it’s defined as a TAutoConsoleVariable. It’s initialized with a default value of -1.

The associated variable CVarNumToForceBreak interacts directly with r.GeometryCollection.CustomRenderer.ForceBreak. They share the same value and purpose.

Developers must be aware that:

1. This variable is only active in non-shipping builds (wrapped in #if !(UE_BUILD_SHIPPING) blocks).
2. It affects the rendering performance and behavior of Geometry Collections.
3. Changing this value at runtime will trigger a refresh of all GeometryCollectionComponents in the scene.

Best practices when using this variable include:

1. Use it only for debugging and testing purposes.
2. Be cautious when setting high values, as it may impact performance.
3. Reset the value to -1 when not actively debugging to ensure normal rendering behavior.

Regarding the associated variable CVarNumToForceBreak:

• It’s a static TAutoConsoleVariable that directly represents r.GeometryCollection.CustomRenderer.ForceBreak in the code.
• It’s used to determine how many pieces of a Geometry Collection should be rendered individually, replacing their root proxy mesh.
• The variable is checked in the Break function to decide whether to continue breaking down the geometry.
• A delegate is set up to reset the ForcedBroken state and refresh all GeometryCollectionComponents when the variable changes.
• In the RefreshCustomRenderer function, it’s used to determine if forced breaking should occur.

Developers should treat CVarNumToForceBreak with the same considerations as r.GeometryCollection.CustomRenderer.ForceBreak, as they are essentially the same variable represented in different contexts within the code.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/GeometryCollectionEngine/Private/GeometryCollection/GeometryCollectionComponent.cpp:522

Scope: file

Source code excerpt:

#if !(UE_BUILD_SHIPPING)
static TAutoConsoleVariable<int> CVarNumToForceBreak(
	TEXT("r.GeometryCollection.CustomRenderer.ForceBreak"),
	-1,
	TEXT("Force the specified number of pieces to render individually, replacing their root proxy mesh.")
);

struct _ForcedBroken
{

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/GeometryCollectionEngine/Private/GeometryCollection/GeometryCollectionComponent.cpp:521

Scope: file

Source code excerpt:

#if !(UE_BUILD_SHIPPING)
static TAutoConsoleVariable<int> CVarNumToForceBreak(
	TEXT("r.GeometryCollection.CustomRenderer.ForceBreak"),
	-1,
	TEXT("Force the specified number of pieces to render individually, replacing their root proxy mesh.")
);

struct _ForcedBroken

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/GeometryCollectionEngine/Private/GeometryCollection/GeometryCollectionComponent.cpp:541

Scope (from outer to inner):

file
function     bool Break

Source code excerpt:

			return true;

		if (TotalTransforms + CompSpaceTransforms.Num() > (uint32)CVarNumToForceBreak->GetInt())
			return false;

		TotalTransforms += CompSpaceTransforms.Num();
		Components.Add(t);
		return true;
	}

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/GeometryCollectionEngine/Private/GeometryCollection/GeometryCollectionComponent.cpp:692

Scope (from outer to inner):

file
function     UGeometryCollectionComponent::UGeometryCollectionComponent

Source code excerpt:

#if !(UE_BUILD_SHIPPING)
	static auto ForcedBrokenDelegate = CVarNumToForceBreak->OnChangedDelegate().Add(FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* CVar)
	{
		ForcedBroken.Reset();

		for (TObjectIterator<UGeometryCollectionComponent> It; It; ++It)
		{
			It->RefreshCustomRenderer();

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/GeometryCollectionEngine/Private/GeometryCollection/GeometryCollectionComponent.cpp:6355

Scope (from outer to inner):

file
function     void UGeometryCollectionComponent::RefreshCustomRenderer

Source code excerpt:

				#if !(UE_BUILD_SHIPPING)
					if (CVarNumToForceBreak->GetInt() >= 0)
					{
						bIsBroken = ForcedBroken.Break(this, ComponentSpaceTransforms.RequestAllTransforms());
					}
				#endif						

					const bool bRenderRootProxy = bEnableRootProxyForCustomRenderer && !bIsBroken && (RestCollection->RootProxyData.ProxyMeshes.Num() > 0);