Collision Events
Collision events are an important part of the physics system, allowing scripts to respond to physical interactions between objects. The Galacean physics system provides two types of events: collision events and trigger events.
Event Types
Collision Events
Collision events are triggered when two colliders in collider mode physically interact with each other. These events provide information about the collision, such as the contact point, normal, and the other collider involved.
Trigger Events
Trigger events are triggered when a collider enters, stays in, or exits a trigger area. Triggers are collision shapes with the isTrigger property set to true. They detect overlaps without causing physical reactions.
Event Trigger Relationship
The detailed event trigger relationship between colliders and triggers is illustrated below:
Collider Mode VS Trigger Mode
| Mode | Description | Applicable Scenarios |
|---|---|---|
| Collider Mode | Triggers collider events and has actual physical collision effects | Objects requiring real physical interaction |
| Trigger Mode | Only triggers event callbacks, no physical collision | Area detection, trigger mechanisms, etc. |
Collider mode and trigger mode are properties of collision shapes. A collider can contain multiple collision shapes, each of which can be independently set as a trigger. This means: A collider can have both modes simultaneously, with some shapes set to collider mode and others to trigger mode, allowing for both physical collisions and area detection
Event Callbacks
When two colliders collide or trigger overlaps occur, callback functions in scripts attached to the entity owning the collider will be triggered.
Collider Event Callbacks
| Event Name | Trigger Timing |
|---|---|
| onCollisionEnter | Triggered when collision starts |
| onCollisionExit | Triggered when collision ends |
| onCollisionStay | Triggered when collision continues |
Trigger Event Callbacks
| Event Name | Trigger Timing |
|---|---|
| onTriggerEnter | Triggered when entering the trigger |
| onTriggerExit | Triggered when exiting the trigger |
| onTriggerStay | Triggered when staying inside the trigger |
Script Usage
class EventHandler extends Script {
// Collider events
onCollisionEnter(other: Collider) {
console.log("Collision started, object:", other.entity.name);
}
onCollisionStay(other: Collider) {
console.log("Collision ongoing, object:", other.entity.name);
}
onCollisionExit(other: Collider) {
console.log("Collision ended, object:", other.entity.name);
}
// Trigger events
onTriggerEnter(other: Collider) {
console.log("Trigger started, object:", other.entity.name);
}
onTriggerStay(other: Collider) {
console.log("Trigger ongoing, object:", other.entity.name);
}
onTriggerExit(other: Collider) {
console.log("Trigger ended, object:", other.entity.name);
}
}