PhysicalTrigger Class

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 theupdate() (in the next frame) — whatever comes first.

PhysicalTrigger Class

Members

---

static 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

PhysicalTrigger cast(Node node)

Casts a PhysicalTrigger out of the Node instance.

Arguments

• Node node - Node instance.

Return value

PhysicalTrigger instance.

PhysicalTrigger cast(Physical base)

Casts a PhysicalTrigger out of the Physical instance.

Arguments

• Physical base - Physical instance.

Return value

PhysicalTrigger instance.

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.

Arguments

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

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.

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.

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.

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 - Integer, each bit of which is 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

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.

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.

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

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.

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

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.

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.