Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

OnCollision events

How colliders can call events when they physically collide.
Read time 3 minutesLast updated 3 days ago
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:
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