JoltPhysics/Jolt/Physics/PhysicsSettings.h

// SPDX-FileCopyrightText: 2021 Jorrit Rouwe
// SPDX-License-Identifier: MIT

#pragma once

JPH_NAMESPACE_BEGIN

/// If objects are closer than this distance, they are considered to be colliding (used for GJK) (unit: meter)
constexpr float cDefaultCollisionTolerance = 1.0e-4f;

/// A factor that determines the accuracy of the penetration depth calculation. If the change of the squared distance is less than tolerance * current_penetration_depth^2 the algorithm will terminate. (unit: dimensionless)
constexpr float cDefaultPenetrationTolerance = 1.0e-4f; ///< Stop when there's less than 1% change

/// How much padding to add around objects
constexpr float cDefaultConvexRadius = 0.05f;

/// Used by (Tapered)CapsuleShape to determine when supporting face is an edge rather than a point (unit: meter)
static constexpr float cCapsuleProjectionSlop = 0.02f;

/// Maximum amount of jobs to allow
constexpr int cMaxPhysicsJobs = 2048;

/// Maximum amount of barriers to allow
constexpr int cMaxPhysicsBarriers = 8;

struct PhysicsSettings
{
	JPH_OVERRIDE_NEW_DELETE

	/// Size of body pairs array, corresponds to the maximum amount of potential body pairs that can be in flight at any time.
	/// Setting this to a low value will use less memory but slow down simulation as threads may run out of narrow phase work.
	int			mMaxInFlightBodyPairs = 16384;

	/// How many PhysicsStepListeners to notify in 1 batch
	int			mStepListenersBatchSize = 8;

	/// How many step listener batches are needed before spawning another job (set to INT_MAX if no parallelism is desired)
	int			mStepListenerBatchesPerJob = 1;

	/// Baumgarte stabilization factor (how much of the position error to 'fix' in 1 update) (unit: dimensionless, 0 = nothing, 1 = 100%)
	float		mBaumgarte = 0.2f;

	/// Radius around objects inside which speculative contact points will be detected. Note that if this is too big 
	/// you will get ghost collisions as speculative contacts are based on the closest points during the collision detection 
	/// step which may not be the actual closest points by the time the two objects hit (unit: meters)
	float		mSpeculativeContactDistance = 0.02f;

	/// How much bodies are allowed to sink into eachother (unit: meters)
	float		mPenetrationSlop = 0.02f;

	/// Fraction of its inner radius a body must move per step to enable casting for the LinearCast motion quality
	float		mLinearCastThreshold = 0.75f;

	/// Fraction of its inner radius a body may penetrate another body for the LinearCast motion quality
	float		mLinearCastMaxPenetration = 0.25f;

	/// Max squared distance to use to determine if two points are on the same plane for determining the contact manifold between two shape faces (unit: meter^2)
	float		mManifoldToleranceSq = 1.0e-6f;

	/// Maximum distance to correct in a single iteration when solving position constraints (unit: meters)
	float		mMaxPenetrationDistance = 0.2f;

	/// Maximum relative delta position for body pairs to be able to reuse collision results from last frame (units: meter^2)
	float		mBodyPairCacheMaxDeltaPositionSq = Square(0.001f); ///< 1 mm

	/// Maximum relative delta orientation for body pairs to be able to reuse collision results from last frame, stored as cos(max angle / 2)
	float		mBodyPairCacheCosMaxDeltaRotationDiv2 = 0.99984769515639123915701155881391f; ///< cos(2 degrees / 2)

	/// Maximum angle between normals that allows manifolds between different sub shapes of the same body pair to be combined
	float		mContactNormalCosMaxDeltaRotation = 0.99619469809174553229501040247389f; ///< cos(5 degree)

	/// Maximum allowed distance between old and new contact point to preserve contact forces for warm start (units: meter^2)
	float		mContactPointPreserveLambdaMaxDistSq = Square(0.01f); ///< 1 cm

	/// Number of solver velocity iterations to run
	/// Note that this needs to be >= 2 in order for friction to work (friction is applied using the non-penetration impulse from the previous iteration)
	int			mNumVelocitySteps = 10;

	/// Number of solver position iterations to run
	int			mNumPositionSteps = 2;

	/// Minimal velocity needed before a collision can be elastic (unit: m)
	float		mMinVelocityForRestitution = 1.0f;

	/// Time before object is allowed to go to sleep (unit: seconds)
	float		mTimeBeforeSleep = 0.5f;

	/// Velocity of points on bounding box of object below which an object can be considered sleeping (unit: m/s)
	float		mPointVelocitySleepThreshold = 0.03f;

	///@name These variables are mainly for debugging purposes, they allow turning on/off certain subsystems. You probably want to leave them alone.
	///@{

	/// Whether or not to use warm starting for constraints (initially applying previous frames impulses)
	bool		mConstraintWarmStart = true;

	/// Whether or not to use the body pair cache, which removes the need for narrow phase collision detection when orientation between two bodies didn't change
	bool		mUseBodyPairContactCache = true;

	/// Whether or not to reduce manifolds with similar contact normals into one contact manifold
	bool		mUseManifoldReduction = true;

	/// If objects can go to sleep or not
	bool		mAllowSleeping = true;

	/// When false, we prevent collision against non-active (shared) edges. Mainly for debugging the algorithm.
	bool		mCheckActiveEdges = true;

	///@}
};

JPH_NAMESPACE_END