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

Class PhysicsSystem

java.lang.Object
com.github.stephengold.joltjni.JoltPhysicsObject
com.github.stephengold.joltjni.NonCopyable
com.github.stephengold.joltjni.PhysicsSystem
All Implemented Interfaces:
ConstJoltPhysicsObject, ConstPhysicsSystem, AutoCloseable, Comparable<JoltPhysicsObject>
public class PhysicsSystem extends NonCopyable implements ConstPhysicsSystem
Perform simulation on a collection of physics objects. Bodies are added by way of a separate interface.

  • Constructor Details

    • PhysicsSystem

      public PhysicsSystem()
      Instantiate an uninitialized physics system.

  • Method Details

    • addConstraint

      public void addConstraint(Constraint constraint)
      Add the specified constraint to the system.
      Parameters:
      constraint - the constraint to add (not null)

    • addConstraint

      public void addConstraint(TwoBodyConstraintRef constraintRef)
      Add the specified constraint to the system.
      Parameters:
      constraintRef - a counted reference to the constraint to add (not null)

    • addConstraint

      public void addConstraint(VehicleConstraintRef constraintRef)
      Add the specified constraint to the system.
      Parameters:
      constraintRef - a counted reference to the constraint to add (not null)

    • addStepListener

      public void addStepListener(PhysicsStepListener listener)
      Add the specified step listener to the system.

      Step listeners are limited in what actions they can perform.

      Parameters:
      listener - the listener to add (not null, alias created)

    • destroyAllBodies

      public int destroyAllBodies()
      Remove and destroy all bodies in the system.
      Returns:
      the number of bodies destroyed (≥0)

    • drawBodies

      public void drawBodies(BodyManagerDrawSettings settings, DebugRenderer renderer)
      Render the bodies in the system, for debugging purposes.
      Parameters:
      settings - the settings to use (not null)
      renderer - the renderer to use (not null)

    • drawConstraints

      public void drawConstraints(DebugRenderer renderer)
      Render all constraints in the system, for debugging purposes.
      Parameters:
      renderer - the renderer to use (not null)

    • drawConstraintLimits

      public void drawConstraintLimits(DebugRenderer renderer)
      Render the limits of all constraints in the system, for debugging purposes.
      Parameters:
      renderer - the renderer to use (not null)

    • drawConstraintReferenceFrame

      public void drawConstraintReferenceFrame(DebugRenderer renderer)
      Render the reference frames of all constraints in the system, for debugging purposes.
      Parameters:
      renderer - the renderer to use (not null)

    • find

      public static PhysicsSystem find(long systemVa)
      Find a pre-existing system given its virtual address.
      Parameters:
      systemVa - the address to search for
      Returns:
      the pre-existing object, or null if not found
      See Also:

    • forgetMe

      public void forgetMe()
      Make the current system un-findable, so it can be garbage collected.
      See Also:

    • getBodyInterface

      public BatchBodyInterface getBodyInterface()
      Access the system's BatchBodyInterface.
      Returns:
      the pre-existing JVM object (not null)

    • getBodyInterfaceNoLock

      public BatchBodyInterface getBodyInterfaceNoLock()
      Access a version of the system's BatchBodyInterface that does not use locks.
      Returns:
      a new JVM object with the pre-existing native object assigned

    • getBroadPhaseLayerInterface

      public ConstBroadPhaseLayerInterface getBroadPhaseLayerInterface()
      Access the (application-provided) interface for mapping object layers to broadphase layers.
      Returns:
      the pre-existing instance, or null if none

    • init

      public PhysicsSystem init(int maxBodies, int numBodyMutexes, int maxBodyPairs, int maxContactConstraints, ConstBroadPhaseLayerInterface map, ConstObjectVsBroadPhaseLayerFilter ovbFilter, ConstObjectLayerPairFilter ovoFilter)
      Initialize the system with the specified limits.
      Parameters:
      maxBodies - the desired maximum number of rigid bodies that can be added
      numBodyMutexes - the desired number of mutexes to allocate, or 0 for the default number
      maxBodyPairs - the desired maximum number of body pairs that can be queued at a time (≥3)
      maxContactConstraints - the desired capacity of the contact-constraint buffer
      map - (not null, alias created)
      ovbFilter - (not null, alias created)
      ovoFilter - (not null, alias created)
      Returns:
      the current system (for chaining)

    • optimizeBroadPhase

      public void optimizeBroadPhase()
      Improve the performance of future collision detections.

    • removeAllBodies

      public int removeAllBodies()
      Remove all bodies from the system, but don't destroy them.
      Returns:
      the number of bodies removed (≥0)
      See Also:

    • removeAllConstraints

      public int removeAllConstraints()
      Remove all constraints from the system.
      Returns:
      the number of constraints removed (≥0)

    • removeConstraint

      public void removeConstraint(Constraint constraint)
      Remove the specified constraint from the system.
      Parameters:
      constraint - the constraint to remove (not null)

    • removeStepListener

      public void removeStepListener(PhysicsStepListener listener)
      Remove the specified step listener from the system.
      Parameters:
      listener - the listener to remove (not null)

    • restoreState

      public boolean restoreState(StateRecorder recorder)
      Restore the system's state from the specified recorder, for replay.
      Parameters:
      recorder - where to read the state from (not null)
      Returns:
      true if successful, otherwise false

    • setBodyActivationListener

      public void setBodyActivationListener(BodyActivationListener listener)
      Replace the system's BodyActivationListener.
      Parameters:
      listener - the desired listener, or null for none

    • setCombineFriction

      public void setCombineFriction(CombineFunction function)
      Replace the combining function for friction.
      Parameters:
      function - the desired function (not null, default=geometricMean)

    • setCombineRestitution

      public void setCombineRestitution(CombineFunction function)
      Replace the combining function for restitutions.
      Parameters:
      function - the desired function (not null, default=max)

    • setContactListener

      public void setContactListener(ContactListener listener)
      Replace or remove the system's contact listener.
      Parameters:
      listener - the desired listener, or null for none

    • setGravity

      public void setGravity(float x, float y, float z)
      Alter the system's gravity vector.
      Parameters:
      x - the X component of the desired acceleration vector (in system coordinates)
      y - the Y component of the desired acceleration vector (in system coordinates)
      z - the Z component of the desired acceleration vector (in system coordinates)

    • setGravity

      public void setGravity(Vec3Arg gravity)
      Alter the system's gravity vector.
      Parameters:
      gravity - the desired acceleration vector (in system coordinates, not null, unaffected, default=(0,-9.81,0))

    • setPhysicsSettings

      public void setPhysicsSettings(ConstPhysicsSettings settings)
      Copy the specified settings to the system.
      Parameters:
      settings - the desired settings (not null, unaffected)
      See Also:

    • setSimCollideBodyVsBody

      public void setSimCollideBodyVsBody(SimCollideBodyVsBody bodyVsBody)
      Replace the system's body-vs-body collide function.
      Parameters:
      bodyVsBody - the desired function (not null)

    • setSimShapeFilter

      public void setSimShapeFilter(SimShapeFilter shapeFilter)
      Replace or remove the shape filter that will be used during simulation.
      Parameters:
      shapeFilter - the desired filter, or null to remove a filter previously set

    • setSoftBodyContactListener

      public void setSoftBodyContactListener(SoftBodyContactListener listener)
      Replace or remove the system's soft-body contact listener.
      Parameters:
      listener - the desired listener, or null for none

    • update

      public int update(float deltaTime, int collisionSteps, TempAllocator tempAllocator, JobSystem jobSystem)
      Advance the simulation by the specified amount.
      Parameters:
      deltaTime - the total time to advance (in seconds)
      collisionSteps - the number of simulation steps to perform
      tempAllocator - the allocator to use (not null)
      jobSystem - the job system to use (not null)
      Returns:
      a bitmask of error conditions, or-ed together
      See Also:

    • containsConstraint

      public boolean containsConstraint(ConstConstraint constraint)
      Test whether the system contains the specified constraint. The system is unaffected.
      Specified by:
      containsConstraint in interface ConstPhysicsSystem
      Parameters:
      constraint - the constraint to search for (not null, unaffected)
      Returns:
      true if found, otherwise false

    • getActiveBodies

      public void getActiveBodies(EBodyType bodyType, BodyIdVector storeResult)
      Enumerate all bodies of the specified type to the specified vector.
      Specified by:
      getActiveBodies in interface ConstPhysicsSystem
      Parameters:
      bodyType - (not null)
      storeResult - storage for the result (not null)

    • getBodies

      public void getBodies(BodyIdVector storeResult)
      Enumerate all bodies to the specified variable-length vector. The system is unaffected.
      Specified by:
      getBodies in interface ConstPhysicsSystem
      Parameters:
      storeResult - storage for the result (not null)

    • getBodyActivationListener

      public BodyActivationListener getBodyActivationListener()
      Access the system's BodyActivationListener.
      Specified by:
      getBodyActivationListener in interface ConstPhysicsSystem
      Returns:
      a new JVM object with the pre-existing native object assigned, or null if none

    • getBodyLockInterface

      public ConstBodyLockInterfaceLocking getBodyLockInterface()
      Access the system's BodyLockInterfaceLocking.
      Specified by:
      getBodyLockInterface in interface ConstPhysicsSystem
      Returns:
      a new JVM object with the pre-existing native object assigned

    • getBodyLockInterfaceNoLock

      public ConstBodyLockInterfaceNoLock getBodyLockInterfaceNoLock()
      Access the system's BodyLockInterfaceNoLock.
      Specified by:
      getBodyLockInterfaceNoLock in interface ConstPhysicsSystem
      Returns:
      a new JVM object with the pre-existing native object assigned

    • getBounds

      public AaBox getBounds()
      Generate a bounding box that contains all the bodies in the system. The system is unaffected.
      Specified by:
      getBounds in interface ConstPhysicsSystem
      Returns:
      a new box

    • getBroadPhaseQuery

      public ConstBroadPhaseQuery getBroadPhaseQuery()
      Access the system's interface for coarse collision queries.
      Specified by:
      getBroadPhaseQuery in interface ConstPhysicsSystem
      Returns:
      the pre-existing JVM object, or null if the system hasn't been initialized yet

    • getCombineFriction

      public CombineFunction getCombineFriction()
      Access the combining function for friction.
      Specified by:
      getCombineFriction in interface ConstPhysicsSystem
      Returns:
      a new JVM object with the pre-existing native object assigned

    • getCombineRestitution

      public CombineFunction getCombineRestitution()
      Access the combining function for restitutions.
      Specified by:
      getCombineRestitution in interface ConstPhysicsSystem
      Returns:
      a new JVM object with the pre-existing native object assigned

    • getConstraints

      public Constraints getConstraints()
      Enumerate all constraints in the system. The system is unaffected.
      Specified by:
      getConstraints in interface ConstPhysicsSystem
      Returns:
      a new object

    • getContactListener

      public ContactListener getContactListener()
      Access the (application-provided) contact listener.
      Specified by:
      getContactListener in interface ConstPhysicsSystem
      Returns:
      the pre-existing instance, or null if none

    • getDefaultBroadPhaseLayerFilter

      public DefaultBroadPhaseLayerFilter getDefaultBroadPhaseLayerFilter(int objectLayer)
      Generate a broad-phase layer filter using the current pair filter and the specified layer index.
      Specified by:
      getDefaultBroadPhaseLayerFilter in interface ConstPhysicsSystem
      Parameters:
      objectLayer - the index of the object layer to use
      Returns:
      a new filter

    • getDefaultLayerFilter

      public DefaultObjectLayerFilter getDefaultLayerFilter(int objectLayer)
      Generate an object layer filter using the current pair filter and the specified layer index.
      Specified by:
      getDefaultLayerFilter in interface ConstPhysicsSystem
      Parameters:
      objectLayer - the index of the object layer to use
      Returns:
      a new filter

    • getGravity

      public Vec3 getGravity()
      Copy the gravity vector. The system is unaffected.
      Specified by:
      getGravity in interface ConstPhysicsSystem
      Returns:
      a new acceleration vector (meters per second squared in system coordinates)

    • getMaxBodies

      public int getMaxBodies()
      Return the maximum number of bodies the system supports. The system is unaffected.
      Specified by:
      getMaxBodies in interface ConstPhysicsSystem
      Returns:
      the count (≥0)

    • getNarrowPhaseQuery

      public ConstNarrowPhaseQuery getNarrowPhaseQuery()
      Access the system's interface for fine collision queries.
      Specified by:
      getNarrowPhaseQuery in interface ConstPhysicsSystem
      Returns:
      the pre-existing JVM object (not null)

    • getNarrowPhaseQueryNoLock

      public ConstNarrowPhaseQuery getNarrowPhaseQueryNoLock()
      Access a version of the system's NarrowPhaseQuery that does not lock the bodies.
      Specified by:
      getNarrowPhaseQueryNoLock in interface ConstPhysicsSystem
      Returns:
      the pre-existing JVM object (not null)

    • getNumActiveBodies

      public int getNumActiveBodies(EBodyType bodyType)
      Count how many active bodies of the specified type there are in the body manager. The system is unaffected.
      Specified by:
      getNumActiveBodies in interface ConstPhysicsSystem
      Parameters:
      bodyType - which type of body to count (not null)
      Returns:
      the count (≥0, ≤maxBodies)

    • getNumBodies

      public int getNumBodies()
      Count how many bodies there are in the body manager. The system is unaffected.
      Specified by:
      getNumBodies in interface ConstPhysicsSystem
      Returns:
      the count (≥0, ≤maxBodies)

    • getObjectLayerPairFilter

      public ConstObjectLayerPairFilter getObjectLayerPairFilter()
      Access the (application-provided) interface for testing whether 2 objects can collide, based on their object layers.
      Specified by:
      getObjectLayerPairFilter in interface ConstPhysicsSystem
      Returns:
      the pre-existing instance, or null if none

    • getObjectVsBroadPhaseLayerFilter

      public ConstObjectVsBroadPhaseLayerFilter getObjectVsBroadPhaseLayerFilter()
      Access the (application-provided) interface for testing whether an object can collide with a broad-phase layer.
      Specified by:
      getObjectVsBroadPhaseLayerFilter in interface ConstPhysicsSystem
      Returns:
      the pre-existing instance, or null if none

    • getPhysicsSettings

      public PhysicsSettings getPhysicsSettings()
      Copy the system's settings. The system is unaffected.

      Different semantics from the native GetPhysicsSettings(), which returns a const reference, not a copy.

      Specified by:
      getPhysicsSettings in interface ConstPhysicsSystem
      Returns:
      a new JVM object with a new native object assigned
      See Also:

    • getSoftBodyContactListener

      public SoftBodyContactListener getSoftBodyContactListener()
      Access the (application-provided) soft-body contact listener.
      Specified by:
      getSoftBodyContactListener in interface ConstPhysicsSystem
      Returns:
      the pre-existing instance, or null if none

    • saveState

      public void saveState(StateRecorder recorder)
      Save the system's state to be replayed later.
      Specified by:
      saveState in interface ConstPhysicsSystem
      Parameters:
      recorder - where to save the state (not null)

    • saveState

      public void saveState(StateRecorder recorder, int bitmask)
      Save the aspects of the system's state to be replayed later.
      Specified by:
      saveState in interface ConstPhysicsSystem
      Parameters:
      recorder - where to save the state (not null)
      bitmask - which aspects of the simulation to save

    • saveState

      public void saveState(StateRecorder recorder, int bitmask, StateRecorderFilter filter)
      Save aspects of the system's state to be replayed later.
      Specified by:
      saveState in interface ConstPhysicsSystem
      Parameters:
      recorder - where to save the state (not null)
      bitmask - which aspects of the simulation to save
      filter - select which parts to save (unaffected) or null