Programming
Fundamentals
Setting Up Development Environment
UnigineScript
High-Level Systems
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Plugins-Related Classes
Rendering-Related Classes

Unigine::PhysicalTrigger Class

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

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)

Arguments

  • const Ptr<Node> & node

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

Arguments

  • const Ptr<Physical> & base

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