Unigine::PhysicalTrigger Class

Header:	#include <UniginePhysicals.h>
Inherits:	Physical

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_baseproperty (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 theupdate()(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

Members

static PhysicalTriggerPtr create(int type, const Math::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
const Math::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

Ptr<PhysicalTrigger> cast(const Ptr<Node> & node)

Casts a PhysicalTrigger out of the Node instance.

Arguments

const Ptr<Node> & node - Pointer to Node.

Return value

Pointer to PhysicalTrigger.

Ptr<PhysicalTrigger> cast(const Ptr<Physical> & base)

Casts a PhysicalTrigger out of the Physical instance.

Arguments

const Ptr<Physical> & base - Pointer to Physical.

Return value

Pointer to PhysicalTrigger.

Ptr<Body> getBody(int num)

Returns the specified body with which a physical trigger intersects.

Arguments

int num - Body number.

Return value

Intersected body.

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 (setExclusionMask()).

Arguments

int mask - An integer value, each bit of which is used to set a mask.

int getCollisionMask()

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 (setExclusionMask()).

Return value

The integer value, each bit of which is used to set a mask.

float getContactDepth(int contact)

Returns penetration depth by the given contact.

Arguments

int contact - Contact number.

Return value

Penetration depth.

Math::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.

Ptr<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.

Math::Vec3 getContactPoint(int contact)

Returns world coordinates of the contact point.

Arguments

int contact - Contact number.

Return value

Contact point.

Ptr<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.

void setEnterCallback(const Ptr<EnterCallback> & func)

Arguments

const Ptr<EnterCallback> & func

void setEnterCallbackName(const char * name)

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

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

Arguments

const char * name - A name of the UnigineScript callback function.

const char * getEnterCallbackName()

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

Return value

The name of the UnigineScript callback function.

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. 0 is to collide with all bodies and shapes with a matching collision mask.

Arguments

int mask - An integer value, each bit of which is used to set a mask.

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

The integer value, each bit of which is used to set a mask.

void setLeaveCallback(const Ptr<LeaveCallback> & func)

Arguments

const Ptr<LeaveCallback> & func

void setLeaveCallbackName(const char * name)

Sets a UnigineScript 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

const char * name - A name of the UnigineScript callback function.

const char * getLeaveCallbackName()

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

Return value

The name of the UnigineScript 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.

void setShapeType(int type)

Sets a shape of the physical trigger.

Arguments

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

int getShapeType()

Returns the shape of the physical trigger:

0, in case of the sphere shape.
1, in case of the capsule shape.
2, in case of the cylinder shape.
3, in case of the box shape.

Return value

The shape of the physical trigger.

void setSize(const Math::vec3 & size)

Sets a size of the physical trigger.

Arguments

const Math::vec3 & size - A new size of the physical trigger:
- The radius, in case of a sphere (pass the radius in the first element of the vector).
- The radius and the height, in case of a capsule or a cylinder (pass the radius as the first vector element and the height as the second element).
- The dimensions along the X, Y and Z axes, in case of the box.

Math::vec3 getSize()

Returns the current size of the physical trigger:

The radius, in case of a sphere (pass the radius in the first element of the vector).
The radius and the height, in case of a capsule or a cylinder (pass the radius as the first vector element and the height as the second element).
The dimensions along the X, Y and Z axes, in case of the box.

Return value

The size of the physical trigger.

int type()

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 be executed only when 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)