2D Contact Callback

Besides the engine tells us when a collision happens, we also need a way to get these collision information. The physics engine provides contact callback when the collision happens. In the callback we can get the information from callback argument that we can determine what happened and what action needs to be done next.

There are two ways to register a collision callback function, either through the specified collider or through a global callback function registered with the 2D physics system.

The above code example demonstrates how to add all the collision callback functions to a script. There are four types of callbacks, each callback function has three parameters, see Callback parameters below for details. The role of each callback function is shown in the comments, and developers can implement their own callback functions according to their needs.

The callback order and timing of a collision callback function can be viewed by splitting a simple example collision. Assume that two rigid bodies are moving towards each other, the triangle to the right and the box to the left, and are about to collide.

Collision Procedure

The callback parameters contain all the collision contact information, and each callback function provides three parameters:

selfCollider: refers to the collider on the node of the callback script.
otherCollider: refers to the other collider.
contact: it’s an interface of the class . Contains the most important information about the collision. Some useful information in contact object are location of the collision and the normal vector. contact store location information according to rigidbody’s local coordinate system. What we need however is information from world coordinate system. We can use to get these information. Note that the builtin physics module parameter is null.

worldManifold has the following:

points

The array of contact points, they are not necessarily at the exact place where the collision happens as shown below (unless you set the rigidbody to use the bullet type, but will be more performance costing). By for general usage these points are accurate enough for us to write game logic upon.
normal

The lines shown in the figure is the normal vectors on the contact point. In this collision, the quickest way to solve the collision is to add the impulse to push the triangle to the top and push the box down to the right. The normal vector here is only about the direction, not with the location properties, nor with connection to any of these contact points.

It is also necessary to understand that the collision normal vector is not the same as the angle in which two object collides. It will only be able to point the direction which can solve the two colliders intersecting with each other. For example, in the above example, if the triangle moves a little faster, the intersection will be shown below:

Then the quickest way would be to push the triangle to the right, so using the normal vector as the direction of collision is not a good idea. To know the true direction of the collision, use the following to get the relative velocities of two colliding bodies at the point of collision when they collide with each other.
```
const vel1 = triangleBody.getLinearVelocityFromWorldPoint(worldManifold.points[0]);
const vel2 = squareBody.getLinearVelocityFromWorldPoint(worldManifold.points[0]);
const relativeVelocity = vel1.sub(vel2);
```

Disabling the contact will cause the physics engine to ignore the contact when calculating the collision. Disabling will continue until the collision is completely resolved unless the contact is enabled in other callbacks.

To disable contact in the current time step, use disabledOnce.

contact.disabledOnce = true;

To modify the contact information in onPreSolve because onPreSolve is called before the physics engine handles the contact information. Changes to the contact information will affect the subsequent collision calculations.