Overview
Creating Triggers
When it comes to creating a trigger object you can use boxes and spheres. Note that trigger objects use their own identification numbers so it is perfectly valid to have a rigid body with an ID of 1 and a trigger with an ID of 1.
To create a box trigger use the command phy make trigger box passing in an ID number, the position, the size and rotation.
To create a sphere trigger use the command phy make trigger sphere passing in an ID number, position and radius.
Deleting Triggers
To delete an existing trigger call phy delete trigger using an ID number as the parameter. Note that if an ID number is used and no trigger exists then this command will fail and display an error message.
Utility Commands
To determine if a trigger exists with the given ID use the command phy trigger exists and to determine the type of trigger call phy trigger type.
Trigger Information
When an event takes place in a trigger object such as a rigid body being pushed into the space a trigger box occupies then data regarding this event will be placed into a stack ready for access with the commands:
phy get trigger data
phy get trigger object a
phy get trigger object b
phy get trigger action
Given that event data is pushed into a stack it is necessary to set up code to extract this data in a specific way using some kind of loop. For example, we have a trigger box with an ID of 1 and in one frame of a program we have 4 rigid bodies poised to enter this trigger zone, the simulation is processed and it is determined that in order objects 2, 4, 3, 1 enter the trigger zone. Internally this data would be stored in the stack like this:
Top 1
3
4
Bottom 2
Notice how object 2 that entered the trigger zone first is at the bottom of the stack, this is because as collision data is added to the stack it gets pushed onto the top of the stack.
For us to extract the data in the stack we need to call phy get trigger data. This command returns a value of 1 when collision data is in the stack. In our example we know that there are 4 items in the stack so with this in mind we have to think about how we can get this data. We could implement code like this in our main loop:
do
if phy get trigger data ( ) = 1
a = phy get trigger object a ( )
b = phy get trigger object b ( )
endif
sync
phy update
loop
Given the data in the stack the first time phy get trigger data is called it will return 1 and then phy get trigger object a will return the ID number of the trigger and phy get trigger object b will return the ID number of the object that entered the trigger zone. This will result in the variable a being assigned the value 1 from the ID of the trigger box and the variable b will store the item at the top of the stack – a value of 1. At this stage we have determined that object 1 has entered trigger zone 1 and the stack has been altered to:
Top 3
4
Bottom 2
This is because when phy get trigger data is called and it returns a value of 1 the top item off the stack is popped off and made available for the other commands such as phy get trigger object a.
The code progresses into calling sync and phy update and our do loop runs on another cycle. We find that phy get trigger data again returns a value of 1 because we still have 3 items in the trigger stack because as we know objects 3, 4 and 2 also entered the trigger zone. The variables a and b are assigned to 1 and 3 leaving the stack as:
Top 4
Bottom 2
Again sync and phy update are called and the do loop must run for another cycle. We still have data left in the stack to report that objects 4 and 2 entered the trigger zone so the if statement checking phy get trigger data returns a value of 1 again. The two command calls inside the if statement assign a value of 1 to the variable a and a value of 4 to the variable b. This leaves the stack with just one value left in – 2. After the if statement sync and phy update are called and the do loop is run again.
On the fourth iteration of the do loop we know data still exists in the trigger stack. The if statement is true and we end up with a being assigned 1 and b being assigned 2 which leaves the stack completely empty and at this point we have found that objects 1, 2, 3 and 4 all entered the trigger zone.
On the next cycle of the do loop the command phy get trigger data returns a value of 0 as no more events have taken place and all of the information about objects 1, 2, 3 and 4 entering the zone has been discovered.
While this code worked it is certainly not optimal as while objects 1, 2, 3 and 4 entered the zone in one frame it took us four frames to find this out and while this doesn't seem like such a big issue for our simple example it is worth remembering that on a large scale this may cause us issues. For example, imagine having 10,000 objects in a scene and wanting to know that objects 5 and 500 entered a specific trigger. While these objects may enter a trigger zone early on in the simulation it may be that we don't find out about this happening until later on as a result of our code dealing with only one piece of collision data each frame.
The solution to this problem is quite simple and it is important that your code follows the same procedure and that is to extract data about trigger collisions using a while loop. This will allow you to get data as soon as collisions take place and will result in the stack being emptied each frame when required. The previous code example can be modified quite easily:
do
while phy get trigger data ( ) = 1
a = phy get trigger object a ( )
b = phy get trigger object b ( )
endwhile
sync
phy update
loop
This simple modification will enable us to find out about collisions when they happen. Going back to our initial stack :
Top 1
3
4
Bottom 2
Our new modified code will find this information out all in one go which is exactly what we want and is the optimal approach and by using some kind of loop to get the data you can ensure you know about events as soon as they happen.
That is an excerpt from the documentation, I should be able to post it here so I hope this is not wrong of me...
But you can see at the top that the trigger objects have their own numbering ID system
