OnCollision events

Collision events occur when two non-trigger colliders make contact.

Example uses for collision events include:

• When a projectile hits a target, destroy both the projectile and the enemy.
• When a player character touches a door, trigger an animation to open the door.
• When a player character touches a power-up, increase the player’s size.

Working with collision events primarily involves the following API functions:

• Collider.OnCollisionEnter: Unity calls this function on each collider when two colliders first make contact.
• Collider.OnCollisionStay: Unity calls this function on each collider once per physics update while two colliders are in contact.
• Collider.OnCollisionExit: Unity calls this function on each collider when two colliders cease contact.

For collision events, at least one of the objects involved must have a dynamic physics body (that is, a Rigidbody or ArticulationBody that has Is Kinematic disabled). If both GameObjects in a collision are kinematic physics bodies, the collision does not call OnCollision functions.

The following example prints a message to the console when Unity calls each function.

using UnityEngine;
using System.Collections;

public class DoorObject : MonoBehaviour
{
    // “other” refers to the collider that is touching this collider
    void OnCollisionEnter (Collision other)
    {
        Debug.Log ("A collider has made contact with the DoorObject Collider");
    }

    void OnCollisionStay (Collision other)
    {
        Debug.Log ("A collider is in contact with the DoorObject Collider");
    }
    
    void OnCollisionExit (Collision other)
    {
        Debug.Log ("A collider has ceased contact with the DoorObject Collider");
    }
}

For examples of practical applications for OnCollision events, refer to example scripts for collider events.

Detect colliders that are destroyed or disabled during contact

If you disable or destroy a collider while it touches another collider, Unity doesn’t call OnCollisionExit for that pair of colliders.

Physics backends report collision enter, stay, and exit, so Unity calls OnCollisionExit when the two colliders separate. Deactivation and destruction don’t produce an exit event for two different reasons:

• If you disable a collider, or the GameObject it belongs to, the event would report a collider that’s no longer in the simulation. Deactivating a GameObject also stops its scripts from receiving messages at all, unlike disabling a MonoBehaviour, which still receives collision events.
• If you destroy a collider, there’s nothing left to report to. The destroyed object can’t receive the event, and the Collision that OnCollisionExit supplies describes a collider that no longer exists.

Unity does not call OnCollisionExit to store and maintain a record of every touching pair of colliders in the scene. Maintaining that record would cost CPU time and memory in every project and even in projects that would not need that record.

To handle these cases, do one of the following:

• Clean up in MonoBehaviour.OnDisable or MonoBehaviour.OnDestroy on the object that leaves the scene.
• Record the contacts your project cares about and check them each physics update, in the same way as OnTrigger events.
• Subscribe to Physics.ContactEvent to read contacts from each simulation step, instead of relying on per-object messages, and decide for yourself how to interpret contacts that begin and end. Unity doesn’t report every contact in the scene through this event: a collider contributes contacts only if you set Collider.providesContacts to true on it, or it has a MonoBehaviour with an OnCollisionStay method attached. Enable providesContacts on the colliders you want to track. Otherwise, your record is incomplete. Each ContactPair identifies its colliders by EntityId, which lets you match contacts against your own records even after Unity destroys a collider.

Additional resources

• Collider interactions
• CollisionA collision occurs when the physics engine detects that the colliders of two GameObjects make contact or overlap, when at least one has a Rigidbody component and is in motion. More info
  See in Glossary
• ColliderAn invisible shape that is used to handle physical collisions for an object. A collider doesn’t need to be exactly the same shape as the object’s mesh - a rough approximation is often more efficient and indistinguishable in gameplay. More info
  See in Glossary