DefaultDegreesOfFreedom

DefaultDegreesOfFreedom

#Overview

name: DefaultDegreesOfFreedom

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of DefaultDegreesOfFreedom is to constrain the movement of physics objects in the game world. It is used to set the default degrees of freedom for physics simulations, which can be particularly useful for creating 2D games using 3D environments or for limiting object movement along specific planes.

This setting variable is primarily used by the physics engine subsystem in Unreal Engine 5. It is referenced in the PhysicsSettings, MovementComponent, and BodyInstance modules, indicating its importance in controlling physics behavior across the engine.

The value of this variable is set in the UPhysicsSettings class, which is part of the engine’s configuration system. It can be modified through the engine’s project settings interface or programmatically.

DefaultDegreesOfFreedom interacts with other variables and enums, such as EDOFMode and EPlaneConstraintAxisSetting. It is used to resolve the final degrees of freedom mode for physics bodies and to determine plane constraints for movement components.

Developers must be aware that changing this variable will affect the global physics behavior of all objects in the game world unless overridden locally. It’s crucial to understand the implications of each setting (Full3D, YZPlane, XZPlane, XYPlane) on gameplay and performance.

Best practices when using this variable include:

  1. Consider the needs of your game carefully before changing the default setting.
  2. Test thoroughly after modifying this variable, as it can have wide-ranging effects on gameplay.
  3. Use local overrides for specific objects when possible, rather than changing the global setting.
  4. Be consistent in its usage across your project to avoid unexpected behavior.
  5. Document any changes to this setting for your development team, as it can significantly impact physics simulations and gameplay mechanics.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/DefaultEngine.ini:326, section: [/Script/Engine.PhysicsSettings]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/PhysicsEngine/PhysicsSettings.h:158

Scope (from outer to inner):

file
class        class UPhysicsSettings : public UPhysicsSettingsCore

Source code excerpt:

	/** Useful for constraining all objects in the world, for example if you are making a 2D game using 3D environments.*/
	UPROPERTY(config, EditAnywhere, Category = Simulation)
	TEnumAsByte<ESettingsDOF::Type> DefaultDegreesOfFreedom;
	
	/**
	*  If true, the internal physx face to UE face mapping will not be generated. This is a memory optimization available if you do not rely on face indices returned by scene queries. */
	UPROPERTY(config, EditAnywhere, Category = Optimization)
	bool bSuppressFaceRemapTable;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/MovementComponent.cpp:418

Scope (from outer to inner):

file
function     FVector UMovementComponent::GetPlaneConstraintNormalFromAxisSetting

Source code excerpt:

	if (AxisSetting == EPlaneConstraintAxisSetting::UseGlobalPhysicsSetting)
	{
		ESettingsDOF::Type GlobalSetting = UPhysicsSettings::Get()->DefaultDegreesOfFreedom;
		switch (GlobalSetting)
		{
		case ESettingsDOF::Full3D:	return FVector::ZeroVector;
		case ESettingsDOF::YZPlane:	return FVector(1.f, 0.f, 0.f);
		case ESettingsDOF::XZPlane:	return FVector(0.f, 1.f, 0.f);
		case ESettingsDOF::XYPlane:	return FVector(0.f, 0.f, 1.f);

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

Scope (from outer to inner):

file
function     EDOFMode::Type FBodyInstance::ResolveDOFMode

Source code excerpt:

	if (DOFMode == EDOFMode::Default)
	{
		ESettingsDOF::Type SettingDefaultPlane = UPhysicsSettings::Get()->DefaultDegreesOfFreedom;
		if (SettingDefaultPlane == ESettingsDOF::XYPlane) ResultDOF = EDOFMode::XYPlane;
		if (SettingDefaultPlane == ESettingsDOF::XZPlane) ResultDOF = EDOFMode::XZPlane;
		if (SettingDefaultPlane == ESettingsDOF::YZPlane) ResultDOF = EDOFMode::YZPlane;
		if (SettingDefaultPlane == ESettingsDOF::Full3D) ResultDOF  = EDOFMode::SixDOF;
	}

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/PhysicsSettings.cpp:48

Scope (from outer to inner):

file
function     void UPhysicsSettings::PostInitProperties

Source code excerpt:

		if (LockedAxis_DEPRECATED == ESettingsLockedAxis::None)
		{
			DefaultDegreesOfFreedom = ESettingsDOF::Full3D;
		}
		else if (LockedAxis_DEPRECATED == ESettingsLockedAxis::X)
		{
			DefaultDegreesOfFreedom = ESettingsDOF::YZPlane;
		}
		else if (LockedAxis_DEPRECATED == ESettingsLockedAxis::Y)
		{
			DefaultDegreesOfFreedom = ESettingsDOF::XZPlane;
		}
		else if (LockedAxis_DEPRECATED == ESettingsLockedAxis::Z)
		{
			DefaultDegreesOfFreedom = ESettingsDOF::XYPlane;
		}

		LockedAxis_DEPRECATED = ESettingsLockedAxis::Invalid;
	}

	// Temporarily override dedicated thread to taskgraph. The enum selection for dedicated

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/PhysicsSettings.cpp:105

Scope (from outer to inner):

file
function     void UPhysicsSettings::PostEditChangeProperty

Source code excerpt:

		UPhysicalMaterial::RebuildPhysicalMaterials();
	}
	else if (PropertyName == GET_MEMBER_NAME_CHECKED(UPhysicsSettings, DefaultDegreesOfFreedom))
	{
		UMovementComponent::PhysicsLockedAxisSettingChanged();
	}

	const FName MemberName = PropertyChangedEvent.MemberProperty ? PropertyChangedEvent.MemberProperty->GetFName() : NAME_None;
	if(MemberName == GET_MEMBER_NAME_CHECKED(UPhysicsSettings, ChaosSettings))