Physics Triggers

Overview

Physics triggers allow for the detection of objects moving in and out within a specific shape range and getting callbacks to implement the game logic.

Related Components

Click Create Game Object -> Physics to select and place these objects. Click Add Component -> Scene in the Inspector panel to select the related components to be added.

The game objects and components that currently support the Physics Trigger features are as follows:

Object Name	Description
Box Trigger	It comes with a box component after placement and turns on the trigger feature automatically.
Sphere Trigger	It comes with a sphere component after placement and turns on the trigger feature automatically.
Capsule Trigger	It comes with a capsule component after placement and turns on the trigger feature automatically.

Component Name	Description
Box Component	It detects objects moving in and out within the box shape range and generates trigger events.
Sphere Component	It detects objects moving in and out within the sphere shape range and generates trigger events.
Capsule Component	It detects objects moving in and out within the capsule shape range and generates trigger events.

Note: Triggers do not trigger events from each other.

Additionally, the Collision Enabled property of the component that enters the trigger range must be PhysicsOnly or Query And Physics for the event to be successfully triggered.

Component Properties

Property	Description
Trigger	Whether to enable the Physics Trigger feature. When Trigger is true, the Trigger feature of the component will be enabled. The default properties of triggers created with LBoxTrigger、LSphereTrigger、LCapsuleTrigger are true and not visible in the Editor.

Trigger Collision Presets

Collision Preset is the Engine's built-in collision preset type specific to physics trigger collision settings.

Click Config -> Physics -> Collision Preset to open the edit panel.

Component Name	Description
Preset Name	Trigger
Collision Enable	Physics Only
Channel	Trigger

Channel Type	Default Collision Response
World Static	Ignore
World Dynamic	Overlap
Pawn	Overlap
Vehicle	Overlap
Destructible	Overlap
Visibility	Overlap
Camera	Overlap
Trigger	Overlap

Trigger Event Collision Determination Mechanism

• The channel types of both collision objects are cross-compared with the collision response, and the event will be successfully triggered when there is no Ignore result.
• The event will not be triggered if the IgnoreTrigger property is true when the component is in range.

Trigger Channel Collision Response With Other Objects		Other Object Channels Respond To Trigger Collisions		Trigger Event
Block/Overlap	+	Block/Overlap	=	Yes
Ignore	+	Any	=	No
Any	+	Ignore	=	No

Implementing Event Triggering Logic With Script Components

Component Name
Script Component

Component Property

Property	Description
Script File	Script File Path

Script Implementation

trigger.lua

function on_begin_play(script_component)
    --param[in] script_component Script component object 
    local owner = script_component.GameObjectOwner
    --Bind the current script to owner 
    nx_bind_script(owner, nx_current()) 
    --Registering trigger events
    nx_callback(owner, "on_trigger", "on_trigger") 
end

function on_trigger(trigger_object, trigger_component, enter_object, enter_component, enter) 
    --param[in] trigger_object Trigger game object
    --param[in] trigger_component Trigger component
    --param[in] enter_object The game object that enters the trigger range
    --param[in] enter_component The component object that enters the trigger range 
    --param[in] enter In or out of trigger range
end 

Creating Convex Triggers

A rigid body file (.nxx) with a convex collision as the trigger type can be created and assigned to the Rigid File property of the model component to generate a convex trigger.

A rigid file can be imported or created as described in the Rigidbody Editor documentation or the Creating Colliders documentation.