PhysicalTrigger Class

List of Functions:

Physical triggers fire callbacks when one of following gets inside or outside of them:

Physical objects. To be detected by the trigger, they are required to have at the same time both:
1. Bodies (with matching Physical Mask)
  Notice
  For BodyDummy to trigger PhysicalTrigger, you need to call updateContacts() first.
2. Shapes (with matching Collision mask)
Non-physical collider objects. To be detected by the trigger, they are required to have three flags at the same time:
1. Collider node flag
2. Object surface collision flag
3. Collision flag in the surface_base property (both the property and this flag are assigned by default)

To force update of the physical trigger updateContacts() can be called. After that, you can access all updated data about the contacts in the same frame. However, callback functions will still be executed only when the next engine function is called: that is, before flush() (in the current frame), or before the update() (in the next frame) — whatever comes first.

Notice

If you have moved some nodes and want to get callbacks based on changed positions in the same frame, you need to call engine.world.updateSpatial() first.

PhysicalTrigger Class

This class inherits from Physical

Members

PhysicalTrigger (int type, vec3 size)

Constructor. Creates a physical trigger of the specified shape and size.

Arguments

int type - Shape of the physical trigger:
- 0 = Sphere
- 1 = Capsule
- 2 = Cylinder
- 3 = Box
vec3 size - Size of the physical trigger:
- Radius, in case of a sphere
- Radius and height, in case of a capsule or a cylinder
- Dimensions, in case of the box

Body getBody (int num)

Returns the specified body with which a physical trigger intersects.

Arguments

int num - Body number.

Return value

Intersected body.

int getCollisionMask ()

Returns the collision bit mask for the trigger:

In case of physical objects, the trigger will be activated if the entered body will have a matching Physical Mask and at the same time its shape will have a matching Collision Mask.
In case of non-physical objects, the trigger will be activated if the surface has a matching Collision Mask.

See also details on additional collision exclusion mask.

Return value

Integer, each bit of which is a mask.

float getContactDepth (int contact)

Returns penetration depth by the given contact.

Arguments

int contact - Contact number.

Return value

Penetration depth.

vec3 getContactNormal (int contact)

Returns a normal of the contact point, in world coordinates.

Arguments

int contact - Contact number.

Return value

Normal of the contact point.

Object getContactObject (int contact)

Returns an object participating in the contact with a physical trigger (used for intersecting with physical objects).

Arguments

int contact - Contact number.

Return value

Object in contact.

vec3 getContactPoint (int contact)

Returns world coordinates of the contact point.

Arguments

int contact - Contact number.

Return value

Contact point.

Shape getContactShape (int contact)

Returns a shape that collided with a physical trigger.

Arguments

int contact - Contact number.

Return value

Shape in contact.

int getContactSurface (int contact)

Returns the surface of the current object, which is in contact (used for intersecting with non-physical objects).

Arguments

int contact - Contact number.

Return value

Surface number.

string getEnterCallbackName ()

Returns the callback function name to be fired on entering the physical trigger. This callback function is set via setEnterCallbackName().

Return value

Name of the callback function.

int getExclusionMask ()

Returns the bit mask that prevent detecting collisions with shapes and bodies. This mask is independent of the collision mask. To avoid detecting collisions by a physical trigger for bodies and shapes with matching collision masks, at least one bit in exclusion masks should match.

Return value

Integer, each bit of which is a mask.

string getLeaveCallbackName ()

Returns the callback function name to be fired on leaving the physical trigger. This callback function is set via setLeaveCallbackName()

Return value

Name of the callback function.

int getNumBodies ()

Returns the total number of bodies with which a physical trigger intersected.

Return value

The number of bodies.

int getNumContacts ()

Returns the total number of contacts with bodies, shapes and colliding surfaces in which a physical trigger participated.

Return value

The number of contacts.

int getShapeType ()

Returns the shape of the physical trigger:

0, if a sphere
1, if a capsule
2, if a cylinder
3, if a box

Return value

Shape of the physical trigger.

vec3 getSize ()

Returns the current size of the physical trigger:

Radius, in case of a sphere
Radius and height, in case of a capsule or a cylinder
Dimensions, in case of the box

Return value

Size of the physical trigger.

void setCollisionMask (int mask)

Sets the collision bit mask for the trigger:

In case of physical objects, the trigger will be activated if the entered body will have a matching Physical Mask and at the same time its shape will have a matching Collision Mask.
In case of non-physical objects, the trigger will be activated if the surface has a matching Collision Mask.

See also details on additional collision exclusion mask.

Arguments

int mask - Integer, each bit of which is a mask.

void setEnterCallbackName (string name)

Sets a callback function to be fired on entering the physical trigger.

Unlike setEnterCallback(), this callback function accepts a body that entered the physical trigger and physical trigger itself as arguments.
If collision with non-physical collider surface happens, the returned body is NULL.

Arguments

string name - Name of the callback function.

Examples

Source code (UnigineScript)

PhysicalTrigger trigger;

// Implement a two-argument callback function that takes Body and
// PhysicalTrigger as arguments.
int on_enter_callback_func(Body body, PhysicalTrigger trigger) {
	// Your callback code
	return 1;
}

// Set the callback fired when physical objects (bodies with shapes) or
// collider mesh surfaces enter the physical trigger.
trigger.setEnterCallbackName("on_enter_callback_func");

void setEnterCallback (variable name, variable arg0, variable arg1)

Sets a callback function to be fired on entering the physical trigger.

Unlike setEnterCallbackName(), this callback function accepts a body that entered the physical trigger as the first argument.
In addition, it can also take any other two arguments.
If collision with non-physical collider surface happens, the returned body is NULL.

Arguments

variable name - Name of the callback function.
variable arg0 - Argument to the function.
variable arg1 - Argument to the function.

Examples

Source code (UnigineScript)

PhysicalTrigger trigger;
MyClass arg0; // it can be an argument of any type

// Implement a callback function that takes Body as the 1-st argument.
// It can also take any other 2 arguments, if necessary.
int on_enter_callback_func(Body body, MyClass arg0) {
	// Your callback code
	return 1;
}

// Set the callback fired when physical objects (bodies with shapes) or
// collider mesh surfaces enter the physical trigger.
trigger.setEnterCallback("on_enter_callback_func", arg0);

void setExclusionMask (int mask)

Sets an bit mask to prevent detecting collisions with shapes and bodies. This mask is independent of the collision mask. To avoid detecting collisions by a physical trigger for bodies and shapes with matching collision masks, at least one bit in exclusion masks should match. The default is 0 (i.e. to collide with all bodies and shapes with a matching collision mask).

Arguments

int mask - Integer, each bit of which is a mask.

void setLeaveCallbackName (string name)

Sets a callback function to be fired on leaving the physical trigger.

Unlike setLeaveCallback(), this callback function accepts a body that left the physical trigger and physical trigger itself as arguments.
If collision with non-physical collider surface happens, the returned body is NULL.

Arguments

string name - Name of the callback function.

Examples

Source code (UnigineScript)

PhysicalTrigger trigger;

// Implement a two-argument callback function that takes Body and
// PhysicalTrigger as arguments.
int on_leave_callback_func(Body body, PhysicalTrigger trigger) {
	// Your callback code
	return 1;
}

// Set the callback fired when physical objects (bodies with shapes) or
// collider mesh surfaces leave the physical trigger.
trigger.setLeaveCallbackName("on_leave_callback_func");

void setLeaveCallback (variable name, variable arg0, variable arg1)

Sets a callback function to be fired on leaving the physical trigger.

Unlike setLeaveCallbackName(), this callback function should be able to accept a body as an argument.
In addition, it can also take two other arguments.
If collision with non-physical collider surface happens, the returned body is NULL.

Arguments

variable name - Name of the callback function.
variable arg0 - Argument to the function.
variable arg1 - Argument to the function.

Examples

Source code (UnigineScript)

PhysicalTrigger trigger;
MyClass arg0; // it can be an argument of any type

// Implement a callback function that takes Body as the 1-st argument.
// It can also take any other 2 arguments, if necessary.
int on_leave_callback_func(Body body, MyClass arg0) {
	// Your callback code
	return 1;
}

// Set the callback fired when physical objects (bodies with shapes) or
// collider mesh surfaces leave the physical trigger.
trigger.setLeaveCallback("on_leave_callback_func", arg0);

void setShapeType (int type)

Sets the shape of the physical trigger.

Arguments

int type - Shape of the physical trigger:
- 0 = Sphere
- 1 = Capsule
- 2 = Cylinder
- 3 = Box

void setSize (vec3 size)

Sets the size of the physical trigger.

Arguments

vec3 size - Size of the physical trigger:
- Radius, in case of a sphere
- Radius and height, in case of a capsule or a cylinder
- Dimensions, in case of the box

void updateContacts ()

Forces a physical trigger to be updated, i.e. to recalculate its intersections with physical objects and colliders. After that, you can access all updated data; however, callback functions themselves will still be executed not immediately, but only when the physics flush is over.

Last update: 2017-07-03

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)