p.CollisionRestitution

p.CollisionRestitution

#Overview

name: p.CollisionRestitution

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.CollisionRestitution is to control the collision restitution for all contacts in the Chaos physics system of Unreal Engine 5. It is primarily used for fine-tuning the physics behavior of collisions in the game.

This setting variable is relied upon by the Chaos physics module, which is part of Unreal Engine’s experimental physics system. It’s specifically used within the PBDCollisionConstraints component of Chaos.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of -1.0f, but can be overridden at runtime through console commands or programmatically.

The p.CollisionRestitution variable interacts directly with the CollisionRestitutionOverride variable. When p.CollisionRestitution is set to a value greater than or equal to 0, it overrides the default restitution values for all contacts in the physics simulation.

Developers must be aware that this is a global override. When set, it will affect all collision contacts in the simulation, potentially changing the behavior of all physics objects in the game. This should be used cautiously and mainly for debugging or specific gameplay effects.

Best practices when using this variable include:

  1. Use it primarily for debugging or prototyping purposes.
  2. Be cautious about setting it in production code, as it can have wide-ranging effects on game physics.
  3. Consider using object-specific restitution values for more precise control, rather than this global override.
  4. When using it, document its usage clearly to avoid confusion for other developers.

Regarding the associated variable CollisionRestitutionOverride:

The purpose of CollisionRestitutionOverride is to store the value set by p.CollisionRestitution and apply it within the physics simulation.

This variable is used directly in the Chaos physics module, specifically in the FPBDCollisionConstraints::UpdateConstraintMaterialProperties function.

The value of CollisionRestitutionOverride is set by the console variable system when p.CollisionRestitution is modified.

It interacts with the MaterialRestitution variable, overriding its value when CollisionRestitutionOverride is greater than or equal to 0.

Developers should be aware that this variable directly affects the physics material properties of all contacts when it’s set to a non-negative value.

Best practices for CollisionRestitutionOverride include:

  1. Treat it as a read-only variable in most cases, as it’s controlled by the p.CollisionRestitution console variable.
  2. Use it for debugging and testing physics behavior.
  3. Be aware of its global nature and the potential for unintended consequences when modifying it.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDCollisionConstraints.cpp:49

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:


	FRealSingle CollisionRestitutionOverride = -1.0f;
	FAutoConsoleVariableRef CVarCollisionRestitutionOverride(TEXT("p.CollisionRestitution"), CollisionRestitutionOverride, TEXT("Collision restitution for all contacts if >= 0"));
	
	FRealSingle CollisionAngularFrictionOverride = -1.0f;
	FAutoConsoleVariableRef CVarCollisionAngularFrictionOverride(TEXT("p.CollisionAngularFriction"), CollisionAngularFrictionOverride, TEXT("Collision angular friction for all contacts if >= 0"));

	FRealSingle CollisionBaseFrictionImpulseOverride = -1.0f;
	FAutoConsoleVariableRef CVarCollisionBaseFrictionImpulseOverride(TEXT("p.CollisionBaseFrictionImpulse"), CollisionBaseFrictionImpulseOverride, TEXT("Collision base friction position impulse for all contacts if >= 0"));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDCollisionConstraints.cpp:48

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	FAutoConsoleVariableRef CVarCollisionFrictionOverride(TEXT("p.CollisionFriction"), CollisionFrictionOverride, TEXT("Collision friction for all contacts if >= 0"));

	FRealSingle CollisionRestitutionOverride = -1.0f;
	FAutoConsoleVariableRef CVarCollisionRestitutionOverride(TEXT("p.CollisionRestitution"), CollisionRestitutionOverride, TEXT("Collision restitution for all contacts if >= 0"));
	
	FRealSingle CollisionAngularFrictionOverride = -1.0f;
	FAutoConsoleVariableRef CVarCollisionAngularFrictionOverride(TEXT("p.CollisionAngularFriction"), CollisionAngularFrictionOverride, TEXT("Collision angular friction for all contacts if >= 0"));

	FRealSingle CollisionBaseFrictionImpulseOverride = -1.0f;
	FAutoConsoleVariableRef CVarCollisionBaseFrictionImpulseOverride(TEXT("p.CollisionBaseFrictionImpulse"), CollisionBaseFrictionImpulseOverride, TEXT("Collision base friction position impulse for all contacts if >= 0"));

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDCollisionConstraints.cpp:511

Scope (from outer to inner):

file
namespace    Chaos
function     void FPBDCollisionConstraints::UpdateConstraintMaterialProperties

Source code excerpt:

			MaterialStaticFriction = CollisionFrictionOverride;
		}
		if (CollisionRestitutionOverride >= 0)
		{
			MaterialRestitution = CollisionRestitutionOverride;
		}
		if (CollisionRestitutionThresholdOverride >= 0.0f)
		{
			MaterialRestitutionThreshold = CollisionRestitutionThresholdOverride;
		}
		if (CollisionAngularFrictionOverride >= 0)