Physical Event

Trigger and Collider

Collider property IsTrigger determines whether the component is a trigger or a collider. When IsTrigger is set to true, the component is a trigger. Triggers are only used for collision detection and triggering events, and are ignored by the physics engine. With false set by default, the component is a collider and can be combined with Rigidbody to produce collision effects.

The difference between the two is as follows.

• Triggers do not do more detailed detection with other triggers or colliders.
• Colliders will do finer detection with colliders and will generate collision data such as collision points, normals, etc.

Trigger events

Trigger events currently include the following three types:

Event	Description
onTriggerEnter	Triggered when the trigger starts
onTriggerStay	Triggered frequently when the trigger is held
onTriggerExit	Triggered at the end of a trigger

The collision pairs that can generate trigger events are

type	Static	Kinematic	Dynamic
Static		✔	✔
Kinematic	✔	✔	✔
Dynamic	✔	✔	✔

Note: To receive a trigger event, both must have a Collider component and at least one of them must be a trigger type. When using a physics engine that is not builtin physics engine, you also need to make sure that at least one object with a non-static rigid body (objects with only collider components and no rigid body components are considered to hold a static rigid body), whereas the builtin physics engine does not have this restriction.

Listening to Trigger Events

// Make sure that the BoxCollider component is added to the node here
import { BoxCollider, ITriggerEvent } from 'cc'

public start () {
    let collider = this.node.getComponent(BoxCollider);
    collider.on('onTriggerStay', this.onTriggerStay, this);
}

private onTriggerStay (event: ITriggerEvent) {
    console.log(event.type, event);
}

Collision Events

Collision events are generated based on collision data, and no collision data is generated between rigid bodies of static types.

Currently collision events include the following three types:

Event	Description
onCollisionEnter	Triggered when collision starts
onCollisionStay	Triggered continuously when the collision is held.
onCollisionExit	triggered when collision ends

Where the collision pairs that can generate collision events are

type	Static	Kinematic	Dynamic
Static		✔	✔
Kinematic	✔	✔	✔
Dynamic	✔	✔	✔

Note: The collision event must be received if both have a collider component, at least one is a non-static rigid body, and a non-builtin physics engine is used.

Listening to Collision Events

import { Collider, ICollisionEvent } from 'cc'

public start () {
    let collider = this.node.getComponent(Collider);
    // Listening to 'onCollisionStay' Events
    collider.on('onCollisionStay', this.onCollision, this);
}

private onCollision (event: ICollisionEvent) {
    console.log(event.type, event);
}

Note: Currently collision events are in physical elements, and all collider components on that element receive collision events.

Difference between Trigger Events and Collision Events

• Trigger events are generated by triggers, collision events are generated based on collision data.
• Trigger events can be generated by a trigger and another trigger/collider.
• Collision events need to be generated by two colliders, and at least one of them is a dynamic rigid body.

Continuous Collision Detection

Compared to the continuous real world, the physics engine simulation is actually discrete, which means that the physics engine takes 1/60th of a second or some other defined time to sample once. Therefore, for faster objects, the physics engine may not be able to detect the collision results correctly, to solve this phenomenon, you can turn on continuous physics detection (CCD).

Turn on continuous collision detection in the engine as follows：

const rigidBody = this.getComponent(RigidBody);
rigidBody.useCCD = true;

Refer to Continuous Collision Detection for a more detailed description.

Event Trigger Rules

The generation of collision events will vary depending on the type of rigid body, collider or trigger, the results are organized here as shown below.

Note: The rigid bodies marked here all carry collider and are configured to allow collisions within the collision matrix.

-	Static	Kinematic	Dynamical	Collider	Trigger
Static		✔	✔
Kinematic	✔	✔	✔	✔	✔
Dynamic	✔	✔	✔	✔	✔
Collider	✔	✔	✔
Trigger	✔	✔	✔

Note: The collision event between two triggers is not supported in the PhysX backend.