Unigine.PhysicalTrigger Class
Inherits from: | Physical |
Physical triggers fire callbacks when a physical object gets inside or outside of them. To be detected by the trigger, physical objects are required to have at the same time both:
- Bodies (with matching Physical Mask)
For BodyDummy to trigger PhysicalTrigger, you need to call updateContacts() first.
- Shapes (with matching Collision mask)
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 updatePhysics() (in the current frame), or before the update() (in the next frame) — whatever comes first.
See Also#
- A video tutorial on How To Use Physical Triggers to Catch Physical Objects
- An article on Event Handling Callbacks
- A C++ API sample located in the <UnigineSDK>/source/samples/Api/Nodes/PhysicalTrigger folder
- A C# API sample located in the <UnigineSDK>/source/csharp/samples/Api/Nodes/PhysicalTrigger folder
- A set of UnigineScript API samples located in the <UnigineSDK>/data/samples/physicals/ folder:
- trigger_00
- trigger_01
- trigger_02
Usage Example#
In this example a physical trigger and two boxes, each with a body and a shape, are created. When a box with matching physical mask enters the physical trigger the trigger_enter() function is called, when it leaves the trigger - the trigger_leave() function is called.
using System;
using System.Collections;
using System.Collections.Generic;
using Unigine;
using System.Linq;
using System.Text;
#region Math Variables
#if UNIGINE_DOUBLE
using Scalar = System.Double;
using Vec2 = Unigine.dvec2;
using Vec3 = Unigine.dvec3;
using Vec4 = Unigine.dvec4;
using Mat4 = Unigine.dmat4;
#else
using Scalar = System.Single;
using Vec2 = Unigine.vec2;
using Vec3 = Unigine.vec3;
using Vec4 = Unigine.vec4;
using Mat4 = Unigine.mat4;
using WorldBoundBox = Unigine.BoundBox;
using WorldBoundSphere = Unigine.BoundSphere;
using WorldBoundFrustum = Unigine.BoundFrustum;
#endif
#endregion
[Component(PropertyGuid = "AUTOGENERATED_GUID")] // <-- this line is generated automatically for a new component
public class name : Component
{
PhysicalTrigger trigger;
ObjectMeshDynamic box1;
ObjectMeshDynamic box2;
// callback function to be fired when a physical object enters the trigger
private void trigger_enter(Body body)
{
// trying to get an object from the body
Unigine.Object obj = body.Object;
if (!obj)
return;
// enabling material emission for all object's surfaces
for (int i = 0; i < obj.NumSurfaces; i++)
obj.SetMaterialState("emission", 1, i);
// displaying the name of the object entering trigger area
Log.Message("\n {0} has entered the trigger area!", body.Object.Name);
}
// callback function to be fired when a physical object leaves the trigger
private void trigger_leave(Body body)
{
// trying to get an object from the body
Unigine.Object obj = body.Object;
if (!obj)
return;
// disabling material emission for all object's surfaces
for (int i = 0; i < obj.NumSurfaces; i++)
obj.SetMaterialState("emission", 0, i);
// displaying the name of the object leaving trigger area
Log.Message("\n {0} has left the trigger area!", body.Object.Name);
}
/// function, creating a named box having a specified size, color and transformation with a body and a shape
ObjectMeshDynamic createBodyBox(String name, vec3 size, float mass, vec4 color, Mat4 transform, int physical_mask)
{
// creating geometry and setting up its parameters (name, material and transformation)
ObjectMeshDynamic OMD = Primitives.CreateBox(size);
OMD.WorldTransform = transform;
OMD.SetMaterialParameterFloat4("albedo_color", color, 0);
OMD.Name = name;
// adding physics, i.e. a rigid body and a box shape with specified mass
BodyRigid body = new BodyRigid(OMD);
body.AddShape(new ShapeBox(size), MathLib.Translate(new vec3(0.0f)));
body.PhysicalMask = physical_mask;
body.Mass = mass;
return OMD;
}
private void Init()
{
// enabling visualizer to render bounds of the physical trigger
Unigine.Console.Run("show_visualizer 1");
// creating a physical trigger
trigger = new PhysicalTrigger(Shape.TYPE.SHAPE_BOX,new vec3(2.0f, 2.0f, 1.0f));
// setting trigger's position
trigger.Position = new Vec3(0.0f, 0.0f, 1.0f);
// setting trigger's physical mask equal to 1
trigger.PhysicalMask = 1;
// retrieving trigger size
vec3 size = trigger.Size;
// displaying trigger size and shape type
Log.Message("\n Trigger parameters size({0}, {1} , {2}) type: {3}", size.x, size.y, size.z, trigger.ShapeType);
// adding trigger enter callback function
trigger.AddEnterCallback(body => trigger_enter(body));
// adding trigger leave callback function
trigger.AddLeaveCallback(body => trigger_leave(body));
// creating a box with a body and physical mask value equal to 2 to be ignored by the trigger
box1 = createBodyBox("Box1", new vec3(0.2f), 5.0f, new vec4(1.0f, 0.0f, 0.0f, 1.0f), MathLib.Translate(new Vec3(0.0f, 0.0f, 2.22f)),2);
// creating a box with a body and physical mask value equal to 1 to affect the trigger
box2 = createBodyBox("Box2", new vec3(0.2f), 0.0f, new vec4(1.0f, 1.0f, 0.0f, 1.0f), MathLib.Translate(new Vec3(3.5f, 0.0f, 1.2f)),1);
// displaying physical masks of both boxes and the trigger
Log.Message("\n Box1 Physical mask: {0}", box1.Body.PhysicalMask);
Log.Message("\n Box2 Physical mask: {0}", box2.Body.PhysicalMask);
Log.Message("\n Trigger Physical mask: {0}", trigger.PhysicalMask);
}
private void Update()
{
// showing the bounds of the physical trigger
trigger.RenderVisualizer();
// changing the position of the second box
box2.WorldPosition = box2.WorldPosition - new vec3(0.5f * Game.IFps, 0.0f, 0.0f);
}
private void UpdatePhysics()
{
// updating information on trigger contacts
trigger.UpdateContacts();
}
private void Shutdown()
{
// clearing trigger callbacks
trigger.ClearEnterCallbacks();
trigger.ClearLeaveCallbacks();
}
}
PhysicalTrigger Class
Properties
vec3 Size#
- Radius, in case of a sphere (pass the radius in the first element of the vector).
- Radius and height, in case of a capsule or a cylinder (pass the radius as the first vector element and the height as the second element).
- Dimensions along the X, Y and Z axes, in case of the box.
int ShapeType#
int NumContacts#
int NumBodies#
string LeaveCallbackName#
int ExclusionMask#
string EnterCallbackName#
int CollisionMask#
- 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.
Members
PhysicalTrigger ( Shape.TYPE type, vec3 size ) #
Constructor. Creates a physical trigger of the specified shape and size.Arguments
- Shape.TYPE 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 that intersects the physical trigger.Arguments
- int num - Body number.
Return value
Intersected body.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 .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 .Arguments
- int contact - Contact number.
Return value
Surface number.IntPtr AddEnterCallback ( EnterDelegate func ) #
Adds a callback function to be fired when a body enters the physical trigger. The callback function must receive a Body as its first argument. In addition, it can also take 2 arguments of any type.
using Unigine;
namespace UnigineApp
{
class AppWorldLogic : WorldLogic
{
// implement the enter callback
private static void enter_callback(Body body)
{
Log.Message("\nA body named {0} has entered the trigger\n", body.Name);
}
PhysicalTrigger trigger;
public override bool Init()
{
// create a box-type physical trigger
trigger = new PhysicalTrigger(3, new vec3(3.0f));
// add the enter callback to be fired when a body enters the physical trigger
trigger.AddEnterCallback(enter_callback);
return true;
}
}
}
Arguments
- EnterDelegate func - Callback function with the following signature: void EnterDelegate(Body body)
Return value
ID of the last added enter callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.bool RemoveEnterCallback ( IntPtr id ) #
Removes the specified callback from the list of enter callbacks.Arguments
- IntPtr id - Enter callback ID obtained when adding it.
Return value
True if the enter callback with the given ID was removed successfully; otherwise false.void ClearEnterCallbacks ( ) #
Clears all added enter callbacks.IntPtr AddLeaveCallback ( LeaveDelegate func ) #
Adds a callback function to be fired when a body leaves the physical trigger. The callback function must receive a Body as its first argument. In addition, it can also take 2 arguments of any type.
using Unigine;
namespace UnigineApp
{
class AppWorldLogic : WorldLogic
{
// implement the leave callback
private static void leave_callback(Body body)
{
Log.Message("\nA body named {0} has left the trigger\n", body.Name);
}
PhysicalTrigger trigger;
public override bool Init()
{
// create a box-type physical trigger
trigger = new PhysicalTrigger(3, new vec3(3.0f));
// add the leave callback to be fired when a body leaves the physical trigger
trigger.AddLeaveCallback(leave_callback);
return 1;
}
}
}
Arguments
- LeaveDelegate func - Callback function with the following signature: void LeaveDelegate(Body body)
Return value
ID of the last added leave callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.bool RemoveLeaveCallback ( IntPtr id ) #
Removes the specified callback from the list of leave callbacks.Arguments
- IntPtr id - Leave callback ID obtained when adding it.