Skip to content

Trigger Guide

Jump to bottom
Peter Robinson edited this page Jul 5, 2020 · 2 revisions

Introduction

All scene objects are known engine types that allow instances to be created at runtime. The "Trigger", like all other objects, is derived from a base type of "SceneObject". That means it includes all the fields from that type as well as adding its own fields specific to itself.

A Trigger is an object that has no rendering ability but augments its parent class of SceneObject with a few additional callbacks. These callbacks are related to collision contacts and are used to let you know when another object enters the trigger, stays inside the trigger, or leaves the trigger.

TorqueScript Bindings

Exposed Fields

The Trigger type exposes the following fields in addition to those it inherits. Shown are the equivalent methods available that perform the same action in setting and getting the respective field:

  • EnterCallback
  • setEnterCallback(bool)
  • getEnterCallback()
  • StayCallback
  • setStayCallback(bool)
  • getStayCallback()
  • LeaveCallback
  • setLeaveCallback(bool)
  • getLeaveCallback()

The following is a complete description of each of these fields.

EnterCallback (bool)

Sets whether the trigger checks for onEnter events. The default is true.

%object = new Trigger();
%object.EnterCallback = "false";

This simple example would turn off the onEnter callback for the newly created trigger.

StayCallback (bool)

This field sets the trigger to check for onStay events. The default is false.

LeaveCallback (bool)

Sets whether the onLeave callback is checked for the trigger. The default is true.

Callbacks

The Trigger type has the following callbacks in addition to those it inherits.

onEnter (%this, %object)

Called when a scene object enters the trigger. The trigger's EnterCallback field must be set to true for this callback to work. Note that this callback is fired off at the moment of first contact between an object and the trigger.

onStay (%this, %object)

Called every 16 ms when a scene object is in contact with or within the collision bounds of the trigger. Because this is called roughly 64 times per second, careful consideration is needed as to what exactly is scripted within this callback in order to preserve performance. The trigger's StayCallback field must be set to true for this callback to work.

onLeave (%this, %object)

Called when a scene object leaves the trigger. The trigger's LeaveCallback field must be set to true for this callback to work. Note that this callback is first fired off only after the object's collision shape is no longer in contact with any part of the Trigger's collision shape.

TAML Format

Using TorqueScript and the exposed fields or methods described in the previous section, you can programmatically create and configure a Trigger. You can then export this type to a TAML file or even create a TAML file manually and read it into your game at an appropriate time.

Here is an example Trigger TAML file in XML format:

<Trigger
    SceneGroup="15"
    Size="10 10"
    Position="30 20"
    EnterCallback="false">
    <Trigger.CollisionShapes>
        <Polygon
            Sensor="1">
            <Point>-5 -5</Point>
            <Point>5 -5</Point>
            <Point>5 5</Point>
            <Point>-5 5</Point>
        </Polygon>
    </Trigger.CollisionShapes>
</Trigger>

The same example in JSON format:

{
    "Trigger": {
        "EnterCallback": "0",
        "SceneGroup": "15",
        "Size": "10 10",
        "Position": "30 20",
        "Trigger.CollisionShapes": {
            "Polygon[0]": {
                "Sensor": "1",
                "Point[0]": [
                    "5 -5"
                ],
                "Point[1]": [
                    "5 5"
                ],
                "Point[2]": [
                    "-5 5"
                ],
                "Point[3]": [
                    "-5 -5"
                ]
            }
        }
    }
}

Additional Information

Trigger Properties

As a child of SceneObject, a trigger has all the properties available from its parent class. In order to not be affected by gravity or other forces, a trigger has the "static" body-type by default. If you wish to have a moving or rotating trigger, remember to set its body-type to "dynamic". Triggers also have the GatherContacts field set to true by default.

Collision Shapes

It's important to note that simply creating a trigger does not automaticly mean it will work and fire off callbacks when placed in a scene. Contact between two objects happens through their collision shapes and a Trigger will need a collision shape assigned to it for it to work as well. This collision shape can be of any size and type that you wish, irrespective of the actual AABB size of the trigger.

Clone this wiki locally