Module org.dyn4j

Package org.dyn4j.world.listener

Interface ContactListener<T extends PhysicsBody>

Type Parameters:

T - the PhysicsBody type

All Superinterfaces:

WorldEventListener

All Known Implementing Classes:

ContactListenerAdapter

public interface ContactListener<T extends PhysicsBody>
extends WorldEventListener

Represents an object that is notified of contact events.

Implement this interface and register it with a PhysicsWorld to be notified when contact events occur. Contact events occur after all CollisionListener events have been raised.

Since:

1.0.0

Version:

5.0.1

Author:

William Bittle

Method Summary

Modifier and Type	Method	Description
void	begin(ContactCollisionData<T> collision, Contact contact)	Called when two BodyFixtures begin to overlap, generating a contact point.
void	collision(ContactCollisionData<T> collision)	Called after the ContactConstraint has been updated after collision detection, but before it's added to the solver to be solved.
void	destroyed(ContactCollisionData<T> collision, Contact contact)	Called when a body or fixture is removed from the world that had existing contacts.
void	end(ContactCollisionData<T> collision, Contact contact)	Called when two BodyFixtures begin to separate and the contact point is no longer valid.
void	persist(ContactCollisionData<T> collision, Contact oldContact, Contact newContact)	Called when two BodyFixtures remain in contact.
void	postSolve(ContactCollisionData<T> collision, SolvedContact contact)	Called after contacts have been solved.
void	preSolve(ContactCollisionData<T> collision, Contact contact)	Called before contact constraints are solved.

Method Detail

begin

void begin(ContactCollisionData<T> collision,
           Contact contact)

Called when two BodyFixtures begin to overlap, generating a contact point.

NOTE: The ContactConstraint stored in the collision parameter is being updated when this method is called. As a result, the data stored in the contact constraint may not be accurate. If you need to access the final state of the contact constraint, use the collision(ContactCollisionData) method.

Parameters:

collision - the collision data

contact - the contact

persist

void persist(ContactCollisionData<T> collision,
             Contact oldContact,
             Contact newContact)

Called when two BodyFixtures remain in contact.

For a Contact to persist, the Settings.isWarmStartingEnabled() must be true and the ManifoldPointIds must match.

For shapes with vertices only, the manifold ids will be identical when the features of the colliding fixtures are the same. For rounded shapes, the manifold points must be within a specified tolerance defined in Settings.getMaximumWarmStartDistance().

NOTE: The ContactConstraint stored in the collision parameter is being updated when this method is called. As a result, the data stored in the contact constraint may not be accurate. If you need to access the final state of the contact constraint, use the collision(ContactCollisionData) method.

Parameters:

collision - the collision data

oldContact - the old contact

newContact - the new contact

end

void end(ContactCollisionData<T> collision,
         Contact contact)

Called when two BodyFixtures begin to separate and the contact point is no longer valid.

This can happen in one of two ways. First, the fixtures in question have separated such that there's no longer any collision between them. Second, the fixtures could still be in collision, but the features that are in collision on those fixtures have changed.

NOTE: The ContactConstraint stored in the collision parameter is being updated when this method is called. As a result, the data stored in the contact constraint may not be accurate. If you need to access the final state of the contact constraint, use the collision(ContactCollisionData) method.

Parameters:

collision - the collision data

contact - the contact

destroyed

void destroyed(ContactCollisionData<T> collision,
               Contact contact)

Called when a body or fixture is removed from the world that had existing contacts.

This is different than the end(ContactCollisionData, Contact) event. This will only be called when a user removes a fixture or body that's currently in collision. The end(ContactCollisionData, Contact) applies when the fixtures separate and are no longer in collision.

This is called before the DestructionListener.destroyed(org.dyn4j.dynamics.contact.ContactConstraint) method in the event processing needed to occur by both listeners. There's no requirement that it must be processed in both (or at all) though.

Parameters:

collision - the collision data

contact - the contact

collision

void collision(ContactCollisionData<T> collision)

Called after the ContactConstraint has been updated after collision detection, but before it's added to the solver to be solved.

This method is only called if CollisionData.isManifoldCollision() returns true.

This listener is the place to use the ContactConstraint.setEnabled(boolean), and ContactConstraint.setTangentSpeed(double) methods. You can get access to the ContactConstraint via the ContactCollisionData.getContactConstraint() method.

Parameters:

collision - the collision data

Since:

4.1.0

preSolve

void preSolve(ContactCollisionData<T> collision,
              Contact contact)

Called before contact constraints are solved.

Parameters:

collision - the collision data

contact - the contact

postSolve

void postSolve(ContactCollisionData<T> collision,
               SolvedContact contact)

Called after contacts have been solved.

NOTE: This method will be called for SolvedContacts even when the SolvedContact.isSolved() is false. This should only occur in situations with multiple contact points that produce a linearly dependent system. These contacts are thus ignored during solving, but still reported here.

Parameters:

collision - the collision data

contact - the contact