Module com.github.stephengold.joltjni
Package com.github.stephengold.joltjni

Class PhysicsSettings

java.lang.Object
com.github.stephengold.joltjni.JoltPhysicsObject
com.github.stephengold.joltjni.PhysicsSettings
All Implemented Interfaces:
ConstJoltPhysicsObject, ConstPhysicsSettings, AutoCloseable, Comparable<JoltPhysicsObject>
public class PhysicsSettings extends JoltPhysicsObject implements ConstPhysicsSettings
A component of a PhysicsSystem, used to configure simulation parameters.

  • Constructor Details

    • PhysicsSettings

      public PhysicsSettings()
      Instantiate default settings.

    • PhysicsSettings

      public PhysicsSettings(ConstPhysicsSettings original)
      Instantiate a copy of the specified settings.
      Parameters:
      original - the settings to copy (not null, unaffected)

  • Method Details

    • setAllowSleeping

      public void setAllowSleeping(boolean allow)
      Alter whether objects can fall asleep. (native member: mAllowSleeping)
      Parameters:
      allow - true to allow sleeping, false to disallow it (default=true)

    • setBaumgarte

      public void setBaumgarte(float fraction)
      Alter the Baumgarte stabilization factor, the fraction of position error to correct in each update. (native member: mBaumgarte)
      Parameters:
      fraction - the desired factor (≥0, ≤1, default=0.2)

    • setBodyPairCacheCosMaxDeltaRotationDiv2

      public void setBodyPairCacheCosMaxDeltaRotationDiv2(float cosineOfHalfAngle)
      Return the maximum rotation to reuse collision results from the previous step. The settings are unaffected. (native member: mBodyPairCacheCosMaxDeltaRotationDiv2)
      Parameters:
      cosineOfHalfAngle - the cosine of half the desired maximum rotation angle (≥0, ≤1, default=cos(pi/180))

    • setBodyPairCacheMaxDeltaPositionSq

      public void setBodyPairCacheMaxDeltaPositionSq(float squaredDistance)
      Alter the maximum translation to reuse collision results from the previous step. (native member: mBodyPairCacheMaxDeltaPositionSq)
      Parameters:
      squaredDistance - the desired squared distance (in square meters, ≥0, default=1e-6)

    • setCheckActiveEdges

      public void setCheckActiveEdges(boolean check)
      Enable or disable collision checking with non-active (shared) edges. (native member: mCheckActiveEdges)
      Parameters:
      check - true to enable checking, or false to disable it (default=true)

    • setConstraintWarmStart

      public void setConstraintWarmStart(boolean enable)
      Alter whether warm starting for constraints (initially applying previous frames impulses) should be used. (native member: mConstraintWarmStart)
      Parameters:
      enable - true to enable warm start, or false to disable it (default=true)

    • setContactNormalCosMaxDeltaRotation

      public void setContactNormalCosMaxDeltaRotation(float cosine)
      Alter the maximum angle between normals to allow combining manifolds. (native member: mContactNormalCosMaxDeltaRotation)
      Parameters:
      cosine - the cosine of the desired rotation threshold (≥-1, ≤1, default=cos(pi/36))

    • setContactPointPreserveLambdaMaxDistSq

      public void setContactPointPreserveLambdaMaxDistSq(float squaredDistance)
      Alter the maximum translation of a contact point for warm starting. (native member: mContactPointPreserveLambdaMaxDistSq)
      Parameters:
      squaredDistance - the square of the desired threshold distance (in meters squared, ≥0, default=1e-4)

    • setDeterministicSimulation

      public void setDeterministicSimulation(boolean setting)
      Alter whether physics simulation is deterministic. (native member: mDeterministicSimulation)
      Parameters:
      setting - true to be deterministic, false to relax this policy (default=true)

    • setLinearCastMaxPenetration

      public void setLinearCastMaxPenetration(float distance)
      Alter the amount of penetration tolerated by a LinearCast cast. (native member: mLinearCastMaxPenetration)
      Parameters:
      distance - the penetration distance to tolerate (as a fraction of the body's inner radius, ≥0, default=0.25)

    • setLinearCastThreshold

      public void setLinearCastThreshold(float threshold)
      Alter the amount of translation to activate casting for LinearCast motion quality. (native member: mLinearCastThreshold)
      Parameters:
      threshold - the desired translation threshold (as a fraction of the body's inner radius, ≥0, default=0.75)

    • setManifoldTolerance

      public void setManifoldTolerance(float tolerance)
      Alter the tolerance for 2 points to be considered coplanar when determining the contact manifold between two faces. (native member: mManifoldTolerance)
      Parameters:
      tolerance - the distance (in meters, ≥0, default=1e-3)

    • setMaxInFlightBodyPairs

      public void setMaxInFlightBodyPairs(int maxPairs)
      Alter the capacity of the in-flight body pairs array. (native member: mMaxInFlightBodyPairs)
      Parameters:
      maxPairs - the number of pairs to allocate (≥0, default=16384)

    • setMaxPenetrationDistance

      public void setMaxPenetrationDistance(float distance)
      Alter the maximum correction when solving position constraints. (native member: mMaxPenetrationDistance)
      Parameters:
      distance - the desired distance threshold (in meters per iteration, ≥0, default=0.2)

    • setMinVelocityForRestitution

      public void setMinVelocityForRestitution(float speed)
      Alter the minimum normal speed for elastic collision. (native member: mMinVelocityForRestitution)
      Parameters:
      speed - the desired threshold speed (in meters per second, ≥0, default=1)

    • setNumPositionSteps

      public void setNumPositionSteps(int numSteps)
      Alter the number of solver position iterations per simulation step. (native member: mNumPositionSteps)
      Parameters:
      numSteps - the desired number (≥0, default=2)

    • setNumVelocitySteps

      public void setNumVelocitySteps(int numSteps)
      Alter the number of velocity steps. (native member: mNumVelocitySteps)
      Parameters:
      numSteps - the desired number (≥0, default=10)

    • setPenetrationSlop

      public void setPenetrationSlop(float slop)
      Alter the penetration slop. (native member: mPenetrationSlop)
      Parameters:
      slop - the desired slop distance (in meters, default=0.02)

    • setPointVelocitySleepThreshold

      public void setPointVelocitySleepThreshold(float speed)
      Alter the point-motion threshold, below which an object can fall asleep. (native member: mPointVelocitySleepThreshold)
      Parameters:
      speed - the desired speed threshold (in meters per second, ≥0, default=0.03)

    • setSpeculativeContactDistance

      public void setSpeculativeContactDistance(float distance)
      Alter the speculative contact distance. (native member: mSpeculativeContactDistance)
      Parameters:
      distance - the desired distance (in meters, ≥0, default=0.02)

    • setStepListenerBatchesPerJob

      public void setStepListenerBatchesPerJob(int numBatches)
      Alter the number of step-listener batches that can be notified by a single job. (native member: mStepListenerBatchesPerJob)
      Parameters:
      numBatches - the desired number of batches, or INT_MAX to serialize step listeners (≥0, default=1)

    • setStepListenersBatchSize

      public void setStepListenersBatchSize(int numListeners)
      Alter the maximum number of step listeners notified in a single batch. (native member: mStepListenersBatchSize)
      Parameters:
      numListeners - the desired number of listeners (≥0, default=8)

    • setTimeBeforeSleep

      public void setTimeBeforeSleep(float interval)
      Alter the time interval before a body can fall asleep. (native member: mTimeBeforeSleep)
      Parameters:
      interval - the desired time interval (in seconds, ≥0, default=0.5)

    • setUseBodyPairContactCache

      public void setUseBodyPairContactCache(boolean enable)
      Enable or disable the body-pair cache. (native member: mUseBodyPairContactCache)
      Parameters:
      enable - true to enable the cache, or false to disable it (default=true)

    • setUseLargeIslandSplitter

      public void setUseLargeIslandSplitter(boolean setting)
      Enable or disable island splitting. (native member: mUseLargeIslandSplitter)
      Parameters:
      setting - true to enable splitting, or false to disable it (default=true)

    • setUseManifoldReduction

      public void setUseManifoldReduction(boolean setting)
      Enable or disable manifold reduction. (native member: mUseManifoldReduction)
      Parameters:
      setting - true to enable reduction, or false to disable it (default=true)

    • getAllowSleeping

      public boolean getAllowSleeping()
      Test whether objects can fall asleep. The settings are unaffected. (native member: mAllowSleeping)
      Specified by:
      getAllowSleeping in interface ConstPhysicsSettings
      Returns:
      true if sleeping is allowed, otherwise false

    • getBaumgarte

      public float getBaumgarte()
      Return the Baumgarte stabilization factor, the fraction of position error that is corrected in each iteration. The settings are unaffected. (native member: mBaumgarte)
      Specified by:
      getBaumgarte in interface ConstPhysicsSettings
      Returns:
      the fraction (≥0, ≤1)

    • getBodyPairCacheCosMaxDeltaRotationDiv2

      public float getBodyPairCacheCosMaxDeltaRotationDiv2()
      Return the maximum rotation for reusing collision results from the previous step. The settings are unaffected. (native member: mBodyPairCacheCosMaxDeltaRotationDiv2)
      Specified by:
      getBodyPairCacheCosMaxDeltaRotationDiv2 in interface ConstPhysicsSettings
      Returns:
      the cosine of half the maximum rotation angle (≥0, ≤1)

    • getBodyPairCacheMaxDeltaPositionSq

      public float getBodyPairCacheMaxDeltaPositionSq()
      Return the maximum translation for re-using collision results from the previous step. The settings are unaffected. (native member: mBodyPairCacheMaxDeltaPositionSq)
      Specified by:
      getBodyPairCacheMaxDeltaPositionSq in interface ConstPhysicsSettings
      Returns:
      the square of the maximum displacement (in square meters, ≥0)

    • getCheckActiveEdges

      public boolean getCheckActiveEdges()
      Test whether collisions with non-active (shared) edges are checked. The settings are unaffected. (native member: mCheckActiveEdges)
      Specified by:
      getCheckActiveEdges in interface ConstPhysicsSettings
      Returns:
      true if checked, otherwise false

    • getConstraintWarmStart

      public boolean getConstraintWarmStart()
      Test whether warm starting is enabled for constraints. The settings are unaffected. (native member: mConstraintWarmStart)
      Specified by:
      getConstraintWarmStart in interface ConstPhysicsSettings
      Returns:
      true if enabled, otherwise false

    • getContactNormalCosMaxDeltaRotation

      public float getContactNormalCosMaxDeltaRotation()
      Return the maximum angle between normals for which manifolds from different sub shapes of the same body pair will be combined. The settings are unaffected. (native member: mContactNormalCosMaxDeltaRotation)
      Specified by:
      getContactNormalCosMaxDeltaRotation in interface ConstPhysicsSettings
      Returns:
      the cosine of the threshold angle (≥-1, ≤1)

    • getContactPointPreserveLambdaMaxDistSq

      public float getContactPointPreserveLambdaMaxDistSq()
      Return the maximum translation of a contact point for warm starting. The settings are unaffected. (native member: mContactPointPreserveLambdaMaxDistSq)
      Specified by:
      getContactPointPreserveLambdaMaxDistSq in interface ConstPhysicsSettings
      Returns:
      the square of the threshold distance (in meters squared, ≥0)

    • getDeterministicSimulation

      public boolean getDeterministicSimulation()
      Test whether physics simulation is deterministic. The settings are unaffected. (native member: mDeterministicSimulation)
      Specified by:
      getDeterministicSimulation in interface ConstPhysicsSettings
      Returns:
      true if it is deterministic, otherwise false

    • getLinearCastMaxPenetration

      public float getLinearCastMaxPenetration()
      Return the amount of penetration tolerated by a LinearCast cast. The settings are unaffected. (native member: mLinearCastMaxPenetration)
      Specified by:
      getLinearCastMaxPenetration in interface ConstPhysicsSettings
      Returns:
      the penetration distance (as a fraction of the body's inner radius, ≥0)

    • getLinearCastThreshold

      public float getLinearCastThreshold()
      Return the amount of translation that triggers casting for LinearCast motion quality. The settings are unaffected. (native member: mLinearCastThreshold)
      Specified by:
      getLinearCastThreshold in interface ConstPhysicsSettings
      Returns:
      the translation distance per step (as a fraction of the body's inner radius, ≥0)

    • getManifoldTolerance

      public float getManifoldTolerance()
      Return the tolerance used to determine whether 2 points are coplanar when calculating the contact manifold between 2 faces. The settings are unaffected. (native member: mManifoldTolerance)
      Specified by:
      getManifoldTolerance in interface ConstPhysicsSettings
      Returns:
      the distance (in meters, ≥0)

    • getMaxInFlightBodyPairs

      public int getMaxInFlightBodyPairs()
      Return the maximum number of in-flight body pairs. The settings are unaffected. (native member: mMaxInFlightBodyPairs)
      Specified by:
      getMaxInFlightBodyPairs in interface ConstPhysicsSettings
      Returns:
      the limit (≥0)

    • getMaxPenetrationDistance

      public float getMaxPenetrationDistance()
      Return the maximum distance to correct in a single iteration when solving position constraints. The settings are unaffected. (native member: mMaxPenetrationDistance)
      Specified by:
      getMaxPenetrationDistance in interface ConstPhysicsSettings
      Returns:
      the distance per iteration (in meters, ≥0)

    • getMinVelocityForRestitution

      public float getMinVelocityForRestitution()
      Return the minimum normal speed for elastic collision. The settings are unaffected. (native member: mMinVelocityForRestitution)
      Specified by:
      getMinVelocityForRestitution in interface ConstPhysicsSettings
      Returns:
      the speed threshold (in meters per second, ≥0)

    • getNumPositionSteps

      public int getNumPositionSteps()
      Return the number of solver position iterations per simulation step. The settings are unaffected. (native member: mNumPositionSteps)
      Specified by:
      getNumPositionSteps in interface ConstPhysicsSettings
      Returns:
      the number (≥0)

    • getNumVelocitySteps

      public int getNumVelocitySteps()
      Return the number of velocity iterations per simulation step. The settings are unaffected. (native member: mNumVelocitySteps)
      Specified by:
      getNumVelocitySteps in interface ConstPhysicsSettings
      Returns:
      the number (≥0)

    • getPenetrationSlop

      public float getPenetrationSlop()
      Return the penetration slop. The settings are unaffected. (native member: mPenetrationSlop)
      Specified by:
      getPenetrationSlop in interface ConstPhysicsSettings
      Returns:
      the slop distance (in meters)

    • getPointVelocitySleepThreshold

      public float getPointVelocitySleepThreshold()
      Return the point-motion threshold, below which objects can fall asleep. The settings are unaffected. (native member: mPointVelocitySleepThreshold)
      Specified by:
      getPointVelocitySleepThreshold in interface ConstPhysicsSettings
      Returns:
      the speed threshold (in meters per second, ≥0)

    • getSpeculativeContactDistance

      public float getSpeculativeContactDistance()
      Return the speculative contact distance. The settings are unaffected. (native member: mSpeculativeContactDistance)
      Specified by:
      getSpeculativeContactDistance in interface ConstPhysicsSettings
      Returns:
      the distance (in meters, ≥0)

    • getStepListenerBatchesPerJob

      public int getStepListenerBatchesPerJob()
      Return the maximum number of step-listener batches notified by a single job. The settings are unaffected. (native member: mStepListenerBatchesPerJob)
      Specified by:
      getStepListenerBatchesPerJob in interface ConstPhysicsSettings
      Returns:
      the number of batches per job (>0), or INT_MAX to serialize step listeners

    • getStepListenersBatchSize

      public int getStepListenersBatchSize()
      Return the maximum number of step listeners notified in a single batch. The settings are unaffected. (native member: mStepListenersBatchSize)
      Specified by:
      getStepListenersBatchSize in interface ConstPhysicsSettings
      Returns:
      the number of listeners (>0)

    • getTimeBeforeSleep

      public float getTimeBeforeSleep()
      Return the time interval before a body can fall asleep. The settings are unaffected. (native member: mTimeBeforeSleep)
      Specified by:
      getTimeBeforeSleep in interface ConstPhysicsSettings
      Returns:
      the interval (in seconds, ≥0)

    • getUseBodyPairContactCache

      public boolean getUseBodyPairContactCache()
      Test whether the body-pair cache is enabled. The settings are unaffected. (native member: mUseBodyPairContactCache)
      Specified by:
      getUseBodyPairContactCache in interface ConstPhysicsSettings
      Returns:
      true if it is enabled, otherwise false

    • getUseLargeIslandSplitter

      public boolean getUseLargeIslandSplitter()
      Test whether island splitting is enabled. The settings are unaffected. (native member: mUseLargeIslandSplitter)
      Specified by:
      getUseLargeIslandSplitter in interface ConstPhysicsSettings
      Returns:
      true if enabled, otherwise false

    • getUseManifoldReduction

      public boolean getUseManifoldReduction()
      Test whether manifold reduction is enabled. The settings are unaffected. (native member: mUseManifoldReduction)
      Specified by:
      getUseManifoldReduction in interface ConstPhysicsSettings
      Returns:
      true if enabled, otherwise false