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. This method should be invoked from 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, false to skip them
      doProcessed - true to enable onContactProcessed() callbacks, false to skip them
      doStarted - true to enable onContactStarted() callbacks, false to skip them

    • 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)

    • onContactEnded

      public void onContactEnded(long manifoldId)
      Invoked by native code immediately after a contact manifold is destroyed. Skipped if stepSimulation() was invoked with doEnded=false.
      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 with doProcessed=false.
      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 with doStarted=false.
      Specified by:
      onContactStarted in interface ContactListener
      Parameters:
      manifoldId - the native ID of the btPersistentManifold (not zero)