Package com.jme3.bullet

Class PhysicsSpace

java.lang.Object
com.jme3.bullet.NativePhysicsObject
com.jme3.bullet.CollisionSpace
com.jme3.bullet.PhysicsSpace
All Implemented Interfaces:
ContactListener, Comparable<NativePhysicsObject>
Direct Known Subclasses:
MultiBodySpace, PhysicsSoftSpace
public class PhysicsSpace extends CollisionSpace implements ContactListener
A CollisionSpace to simulate dynamic physics, with its own btDiscreteDynamicsWorld.

  • Field Details

    • AXIS_X

      public static final int AXIS_X
      index of the X axis
      See Also:

    • AXIS_Y

      public static final int AXIS_Y
      index of the Y axis
      See Also:

    • AXIS_Z

      public static final int AXIS_Z
      index of the Z axis
      See Also:

    • logger

      public static final Logger logger
      message logger for this class

    • pQueueTL

      protected static final ThreadLocal<Queue<com.jme3.app.AppTask<?>>> pQueueTL
      first-in/first-out (FIFO) queue of physics tasks for each thread

  • Constructor Details

    • PhysicsSpace

      public PhysicsSpace(PhysicsSpace.BroadphaseType broadphaseType)
      Instantiate a PhysicsSpace with sequential-impulse solvers. Must be invoked on the designated physics thread.
      Parameters:
      broadphaseType - which broadphase accelerator to use (not null)

    • PhysicsSpace

      public PhysicsSpace(com.jme3.math.Vector3f worldMin, com.jme3.math.Vector3f worldMax)
      Instantiate a PhysicsSpace with an AXIS_SWEEP_3 broadphase accelerator and sequential-impulse solvers. Must be invoked on the designated physics thread.
      Parameters:
      worldMin - the desired minimum coordinate values (not null, unaffected)
      worldMax - the desired maximum coordinate values (not null, unaffected)

    • PhysicsSpace

      public PhysicsSpace(com.jme3.math.Vector3f worldMin, com.jme3.math.Vector3f worldMax, PhysicsSpace.BroadphaseType broadphaseType)
      Instantiate a PhysicsSpace with sequential-impulse solvers. Must be invoked on the designated physics thread.
      Parameters:
      worldMin - the desired minimum coordinate values (not null, unaffected, default=(-10k,-10k,-10k))
      worldMax - the desired maximum coordinate values (not null, unaffected, default=(10k,10k,10k))
      broadphaseType - which broadphase accelerator to use (not null)

    • PhysicsSpace

      public PhysicsSpace(com.jme3.math.Vector3f worldMin, com.jme3.math.Vector3f worldMax, PhysicsSpace.BroadphaseType broadphaseType, int numSolvers)
      Instantiate a PhysicsSpace with the specified number of sequential-impulse solvers. Must be invoked on the designated physics thread.
      Parameters:
      worldMin - the desired minimum coordinate values (not null, unaffected, default=(-10k,-10k,-10k))
      worldMax - the desired maximum coordinate values (not null, unaffected, default=(10k,10k,10k))
      broadphaseType - which broadphase accelerator to use (not null)
      numSolvers - the desired number of solvers in the thread-safe pool (≥1, ≤64, default=numThreads)

    • PhysicsSpace

      public PhysicsSpace(com.jme3.math.Vector3f worldMin, com.jme3.math.Vector3f worldMax, PhysicsSpace.BroadphaseType broadphaseType, int numSolvers, CollisionConfiguration configuration)
      Instantiate a PhysicsSpace with the specified number of sequential-impulse solvers. Must be invoked on the designated physics thread.
      Parameters:
      worldMin - the desired minimum coordinate values (not null, unaffected, default=(-10k,-10k,-10k))
      worldMax - the desired maximum coordinate values (not null, unaffected, default=(10k,10k,10k))
      broadphaseType - which broadphase accelerator to use (not null)
      numSolvers - the desired number of solvers in the thread-safe pool (≥1, ≤64, default=numThreads)
      configuration - the desired configuration (not null)

    • PhysicsSpace

      public PhysicsSpace(com.jme3.math.Vector3f worldMin, com.jme3.math.Vector3f worldMax, PhysicsSpace.BroadphaseType broadphaseType, SolverType solverType)
      Instantiate a PhysicsSpace with the specified contact-and-constraint solver. Must be invoked on the designated physics thread.
      Parameters:
      worldMin - the desired minimum coordinate values (not null, unaffected, default=(-10k,-10k,-10k))
      worldMax - the desired maximum coordinate values (not null, unaffected, default=(10k,10k,10k))
      broadphaseType - which broadphase accelerator to use (not null)
      solverType - the desired contact-and-constraint solver (not null)

    • PhysicsSpace

      public PhysicsSpace(com.jme3.math.Vector3f worldMin, com.jme3.math.Vector3f worldMax, PhysicsSpace.BroadphaseType broadphaseType, SolverType solverType, CollisionConfiguration configuration)
      Instantiate a PhysicsSpace with the specified contact-and-constraint solver. Must be invoked on the designated physics thread.
      Parameters:
      worldMin - the desired minimum coordinate values (not null, unaffected, default=(-10k,-10k,-10k))
      worldMax - the desired maximum coordinate values (not null, unaffected, default=(10k,10k,10k))
      broadphaseType - which broadphase accelerator to use (not null)
      solverType - the desired contact-and-constraint solver (not null)
      configuration - the desired configuration (not null)

  • Method Details

    • activateAll

      public void activateAll(boolean forceFlag)
      Activate all rigid bodies in the space.
      Parameters:
      forceFlag - true to force activation

    • addAll

      public void addAll(com.jme3.scene.Spatial spatial)
      Add all physics controls in the specified subtree of the scene graph to the space (e.g. after loading from disk). For compatibility with the jme3-jbullet library.

      Does not add joints unless they are managed by a PhysicsControl; the jme3-jbullet version attempts to add ALL joints.

      Note: recursive!

      Parameters:
      spatial - the root of the subtree (not null)

    • addCollisionListener

      public void addCollisionListener(PhysicsCollisionListener listener)
      Register the specified listener for new contacts.

      During distributeEvents(), registered listeners are notified of all new contacts since the previous distributeEvents().

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

    • addContactListener

      public void addContactListener(ContactListener listener)
      Register the specified listener for immediate contact notifications.
      Parameters:
      listener - the listener to register (not null, alias created)

    • addContactListener

      public void addContactListener(ContactListener listener, boolean doEnded, boolean doProcessed, boolean doStarted)
      Register the specified listener for immediate contact notifications.
      Parameters:
      listener - the listener to register (not null, alias created)
      doEnded - true to enable onContactEnded() callbacks for the listener, false to skip them (default=true)
      doProcessed - true to enable onContactProcessed() callbacks for the listener, false to skip them (default=true)
      doStarted - true to enable onContactStarted() callbacks for the listener, false to skip them (default=true)

    • addJoint

      public void addJoint(PhysicsJoint joint)
      Add the specified PhysicsJoint to the space.
      Parameters:
      joint - the joint to add (not null, alias created)

    • addOngoingCollisionListener

      public void addOngoingCollisionListener(PhysicsCollisionListener listener)
      Register the specified listener for ongoing contacts.

      During distributeEvents(), registered listeners are notified of all ongoing contacts EXCEPT Sphere-Sphere contacts.

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

    • addTickListener

      public void addTickListener(PhysicsTickListener listener)
      Register the specified tick listener with the space.

      Tick listeners are notified before and after each simulation step. A simulation step is not necessarily the same as a frame; it is more influenced by the accuracy of the PhysicsSpace.

      Parameters:
      listener - the listener to register (not null, alias created)
      See Also:

    • contains

      public boolean contains(PhysicsJoint joint)
      Test whether the specified PhysicsJoint is added to the space.
      Parameters:
      joint - the joint to test (not null, unaffected)
      Returns:
      true if currently added, otherwise false

    • countCollisionListeners

      public int countCollisionListeners()
      Count how many collision listeners are registered with the space.
      Returns:
      the count (≥0)

    • countJoints

      public int countJoints()
      Count the joints in the space.
      Returns:
      the count (≥0)

    • countManifolds

      public int countManifolds()
      Count the collision manifolds in the space.
      Returns:
      the current number of btPersistentManifolds (≥0)

    • countRigidBodies

      public int countRigidBodies()
      Count the rigid bodies in the space, including vehicles.
      Returns:
      count (≥0)

    • countTickListeners

      public int countTickListeners()
      Count how many tick listeners are registered with the space.
      Returns:
      the count (≥0)

    • distributeEvents

      public void distributeEvents()
      Distribute queued collision events to registered listeners.

    • enqueue

      public <V> Future<V> enqueue(Callable<V> callable)
      Invoke the specified callable during the next simulation step. This is useful for applying forces.
      Type Parameters:
      V - the return type of the Callable
      Parameters:
      callable - the Callable to invoke
      Returns:
      a new AppTask

    • enqueueOnThisThread

      public static <V> Future<V> enqueueOnThisThread(Callable<V> callable)
      Enqueue a callable on the currently executing thread.
      Type Parameters:
      V - the task's result type
      Parameters:
      callable - the task to be executed
      Returns:
      a new task (not null)

    • getAccuracy

      public float getAccuracy()
      Return the simulation accuracy: the time step used when maxSubSteps>0.
      Returns:
      the time step (in seconds, >0)

    • getCharacterList

      public Collection<PhysicsCharacter> getCharacterList()
      Enumerate physics characters that have been added to the space and not yet removed.
      Returns:
      a new unmodifiable collection of pre-existing instances (not null)

    • getContactManager

      public ContactManager getContactManager()
      Access the current ContactManager.
      Returns:
      the pre-existing instance (not null)

    • getGravity

      public com.jme3.math.Vector3f getGravity(com.jme3.math.Vector3f storeResult)
      Copy the gravitational acceleration for newly-added bodies.
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      the acceleration vector (in physics-space coordinates, either storeResult or a new instance, not null)

    • getJointList

      public Collection<PhysicsJoint> getJointList()
      Enumerate physics joints that have been added to the space and not yet removed.
      Returns:
      a new unmodifiable collection of pre-existing instances (not null)

    • getPhysicsSpace

      public static PhysicsSpace getPhysicsSpace()
      Access the PhysicsSpace running on this thread. For parallel physics, this may be invoked from the OpenGL thread.
      Returns:
      the pre-existing PhysicsSpace running on this thread

    • getRigidBodyList

      public Collection<PhysicsRigidBody> getRigidBodyList()
      Enumerate rigid bodies (including vehicles) that have been added to this space and not yet removed.
      Returns:
      a new unmodifiable collection of pre-existing instances (not null)

    • getSolverInfo

      public SolverInfo getSolverInfo()
      Access parameters used by the contact-and-constraint solver.
      Returns:
      the pre-existing instance (not null)

    • getSolverNumIterations

      public int getSolverNumIterations()
      Return the number of iterations used by the contact-and-constraint solver, for compatibility with the jme3-jbullet library.
      Returns:
      the number of iterations used (≥1)

    • getSolverType

      public SolverType getSolverType()
      Return the type of contact-and-constraint solver in use.
      Returns:
      an enum value (not null)

    • getVehicleList

      public Collection<PhysicsVehicle> getVehicleList()
      Enumerate physics vehicles that have been added to the space and not yet removed.
      Returns:
      a new unmodifiable collection of pre-existing instances (not null)

    • isCcdWithStaticOnly

      public boolean isCcdWithStaticOnly()
      Test whether CCD checks for collisions with static and kinematic bodies (native field: m_ccdWithStaticOnly).
      Returns:
      true if checks are limited, false if checking also for collisions with dynamic bodies

    • isUsingScr

      public boolean isUsingScr()
      Test whether the space uses Speculative Contact Restitution (native field: m_applySpeculativeContactRestitution).
      Returns:
      true if using SCR, otherwise false

    • listManifoldIds

      public long[] listManifoldIds()
      Enumerate the native IDs of all collision manifolds in the space.
      Returns:
      a new array (not null, may be empty)
      See Also:

    • maxSubSteps

      public int maxSubSteps()
      Return the maximum number of simulation steps per frame.
      Returns:
      the number of steps (>1) or 0 for a variable time step

    • maxTimeStep

      public float maxTimeStep()
      Return the maximum time step (imposed when maxSubSteps=0).
      Returns:
      the maximum time step (in seconds, >0, default=0.1)

    • removeAll

      public void removeAll(com.jme3.scene.Spatial spatial)
      Remove all physics controls in the specified subtree of the scene graph from the space (e.g. before saving to disk). For compatibility with the jme3-jbullet library.

      Does not remove joints unless they are managed by a PhysicsControl; the jme3-jbullet version attempts to remove ALL joints.

      Note: recursive!

      Parameters:
      spatial - the root of the subtree (not null)

    • removeCollisionListener

      public void removeCollisionListener(PhysicsCollisionListener listener)
      De-register the specified listener for new contacts.
      Parameters:
      listener - the listener to de-register (not null)
      See Also:

    • removeContactListener

      public void removeContactListener(ContactListener listener)
      De-register the specified listener for immediate contact notifications.
      Parameters:
      listener - the listener to de-register (not null)
      See Also:

    • removeJoint

      public void removeJoint(PhysicsJoint joint)
      Remove the specified PhysicsJoint from the space.
      Parameters:
      joint - the joint to remove (not null)

    • removeOngoingCollisionListener

      public void removeOngoingCollisionListener(PhysicsCollisionListener listener)
      De-register the specified listener for ongoing contacts.
      Parameters:
      listener - the listener to de-register (not null)
      See Also:

    • removeTickListener

      public void removeTickListener(PhysicsTickListener listener)
      De-register the specified tick listener.
      Parameters:
      listener - the listener to de-register (not null, unaffected)
      See Also:

    • setAccuracy

      public void setAccuracy(float accuracy)
      Alter the accuracy (time step used when maxSubSteps>0).

      In general, the smaller the time step, the more accurate (and compute-intensive) the simulation will be.

      Parameters:
      accuracy - the desired time step (in seconds, >0, default=1/60)

    • setCcdWithStaticOnly

      public void setCcdWithStaticOnly(boolean setting)
      Alter whether CCD checks for collisions with static and kinematic bodies (native field: m_ccdWithStaticOnly).
      Parameters:
      setting - true to limit checking, false to check also for collisions with dynamic bodies (default=false)

    • setContactManager

      public void setContactManager(ContactManager manager)
      Replace the current ContactManager with the specified one.
      Parameters:
      manager - the desired manager (not null)

    • setGravity

      public void setGravity(com.jme3.math.Vector3f gravity)
      Alter the gravitational acceleration acting on newly-added bodies.

      Typically, when a body is added to a space, the body's gravity gets set to that of the space. Thus, it is preferable to set the space's gravity before adding any bodies.

      Parameters:
      gravity - the desired acceleration vector (in physics-space coordinates, not null, unaffected, default=(0,-9.81,0))

    • setMaxSubSteps

      public void setMaxSubSteps(int steps)
      Alter the maximum number of simulation steps per frame.

      Extra simulation steps help maintain determinism when the render fps drops below 1/accuracy. For example a value of 2 can compensate for frame rates as low as 30fps, assuming the physics has an accuracy of 1/60 sec.

      Setting this value too high can depress the frame rate.

      Parameters:
      steps - the desired maximum number of steps (≥1) or 0 for a variable time step (default=4)

    • setMaxTimeStep

      public void setMaxTimeStep(float maxTimeStep)
      Alter the maximum time step (imposed when maxSubSteps=0).

      In general, the smaller the time step, the more accurate (and compute-intensive) the simulation will be.

      Parameters:
      maxTimeStep - the desired maximum time step (in seconds, >0, default=0.1)

    • setSolverNumIterations

      public void setSolverNumIterations(int numIterations)
      Alter the number of iterations used by the contact-and-constraint solver, for compatibility with the jme3-jbullet library.

      Use 4 for low quality, 20 for high quality.

      Parameters:
      numIterations - the desired number of iterations (≥1, default=10)

    • update

      public void update(float timeInterval)
      Update the space. Can be used to single-step the physics simulation, if maxSubSteps is set to 0 or 1. This method should be invoked on the thread that created the space.
      Parameters:
      timeInterval - the time interval to simulate (in seconds, ≥0)
      See Also:

    • update

      public void update(float timeInterval, int maxSteps)
      Update the space. This method should be invoked on the thread that created the space.
      Parameters:
      timeInterval - the time interval to simulate (in seconds, ≥0)
      maxSteps - the maximum number of steps of size accuracy (≥1) or 0 for a single step of size timeInterval

    • update

      public void update(float timeInterval, int maxSteps, boolean doEnded, boolean doProcessed, boolean doStarted)
      Update the space, enabling the specified callbacks. This method should be invoked on the thread that created the space.
      Parameters:
      timeInterval - the time interval to simulate (in seconds, ≥0)
      maxSteps - the maximum number of steps of size accuracy (≥1) or 0 for a single step of size timeInterval
      doEnded - true to enable onContactEnded() callbacks
      doProcessed - true to enable onContactProcessed() callbacks
      doStarted - true to enable onContactStarted() callbacks

    • update

      public void update(float timeInterval, int maxSteps, int stepFlags)
      Update the space with the specified callbacks. This method should be invoked on the thread that created the space.
      Parameters:
      timeInterval - the time interval to simulate (in seconds, ≥0)
      maxSteps - the maximum number of simulation steps of size accuracy (≥1) or 0 for a single simulation step of size timeInterval
      stepFlags - flags representing the desired callbacks, ORed together (default=0x0)
      See Also:

    • useScr

      public void useScr(boolean setting)
      Alter whether the space uses Speculative Contact Restitution (native field: m_applySpeculativeContactRestitution).
      Parameters:
      setting - true to enable SCR, false to disable it (default=false)

    • getJointMap

      protected Map<Long,PhysicsJoint> getJointMap()
      Access the map from native IDs to physics joints.
      Returns:
      the pre-existing instance (not null)

    • getWorldType

      protected static int getWorldType(long spaceId)
      Determine the type of the underlying btDynamicsWorld.
      Parameters:
      spaceId - the Bullet identifier of the space (non-zero)
      Returns:
      2 (for a discrete world) or 4 (for a soft-rigid world)

    • initSolverInfo

      protected void initSolverInfo()
      Initialize the solverInfo field during create().

    • updateSolver

      protected void updateSolver()
      Replace the existing contact-and-constraint solver with a new one of the correct type.

    • add

      public void add(Object object)
      Add the specified object to the space. For compatibility with the jme3-jbullet library.

      The jme3-jbullet version allows the argument to be null.

      Overrides:
      add in class CollisionSpace
      Parameters:
      object - the PhysicsControl, Spatial-with-PhysicsControl, collision object, or PhysicsJoint to add (not null)

    • addCollisionObject

      public void addCollisionObject(PhysicsCollisionObject pco)
      Add the specified collision object to the space.
      Overrides:
      addCollisionObject in class CollisionSpace
      Parameters:
      pco - the collision object to add (not null)

    • contains

      public boolean contains(PhysicsCollisionObject pco)
      Test whether the specified collision object is added to the space.
      Overrides:
      contains in class CollisionSpace
      Parameters:
      pco - the object to test (not null, unaffected)
      Returns:
      true if currently added, otherwise false

    • create

      protected void create()
      Must be invoked on the designated physics thread.
      Overrides:
      create in class CollisionSpace

    • destroy

      public void destroy()
      Remove all collision objects and physics joints.
      Overrides:
      destroy in class CollisionSpace

    • getPcoList

      public Collection<PhysicsCollisionObject> getPcoList()
      Enumerate collision objects that have been added to the space and not yet removed.
      Overrides:
      getPcoList in class CollisionSpace
      Returns:
      a new modifiable collection of pre-existing instances (not null)

    • isEmpty

      public boolean isEmpty()
      Test whether the space is empty.
      Overrides:
      isEmpty in class CollisionSpace
      Returns:
      true if empty, otherwise false

    • remove

      public void remove(Object object)
      Remove the specified object from the space. For compatibility with the jme3-jbullet library.

      The jme3-jbullet version allows the argument to be null.

      Overrides:
      remove in class CollisionSpace
      Parameters:
      object - the PhysicsControl, Spatial-with-PhysicsControl, collision object, or PhysicsJoint to remove, or null

    • removeCollisionObject

      public void removeCollisionObject(PhysicsCollisionObject pco)
      Remove the specified collision object from the space.
      Overrides:
      removeCollisionObject in class CollisionSpace
      Parameters:
      pco - the collision object to remove (not null)

    • onContactConceived

      public boolean onContactConceived(long pointId, long manifoldId, PhysicsCollisionObject pcoA, PhysicsCollisionObject pcoB)
      Invoked by native code immediately before a contact point is added to a manifold. Skipped if stepSimulation() was invoked without the contactConceived flag set.
      Specified by:
      onContactConceived in interface ContactListener
      Parameters:
      pointId - the native ID of the btManifoldPoint (not zero)
      manifoldId - the native ID of the btPersistentManifold (not zero)
      pcoA - the "A" collision object (not null)
      pcoB - the "B" collision object (not null)
      Returns:
      true to accept the contact, or false to reject it

    • onContactEnded

      public void onContactEnded(long manifoldId)
      Invoked by native code immediately after a contact manifold is destroyed. Skipped if stepSimulation() was invoked without the contactEnded flag set.
      Specified by:
      onContactEnded in interface ContactListener
      Parameters:
      manifoldId - the native ID of the btPersistentManifold (not zero)

    • onContactProcessed

      public void onContactProcessed(PhysicsCollisionObject pcoA, PhysicsCollisionObject pcoB, long pointId)
      Invoked by native code immediately after a contact point is refreshed without being destroyed. Skipped for Sphere-Sphere contacts. Skipped if stepSimulation() was invoked without the contactProcessed flag set.
      Specified by:
      onContactProcessed in interface ContactListener
      Parameters:
      pcoA - the first involved object (not null)
      pcoB - the 2nd involved object (not null)
      pointId - the native ID of the btManifoldPoint (not zero)

    • onContactStarted

      public void onContactStarted(long manifoldId)
      Invoked by native code immediately after a contact manifold is created. Skipped if stepSimulation() was invoked without the contactStarted flag.
      Specified by:
      onContactStarted in interface ContactListener
      Parameters:
      manifoldId - the native ID of the btPersistentManifold (not zero)