Trigger

Triggers are objects which react to certain events by changing their boolean state. More...

Files
file	CheckPoint.cc
	Implementation of the CheckPoint class.
file	CheckPoint.h
	Definition of the CheckPoint class.
file	DistanceTrigger.cc
	Implementation of the DistanceTrigger class.
file	DistanceTrigger.h
	Definition of the DistanceTrigger class.
file	EventTrigger.cc
	Implementation of the EventTrigger class.
file	EventTrigger.h
	Definition of the EventTrigger class.
file	Trigger.cc
	Implementation of the Trigger class.
file	Trigger.h
	Definition of the Trigger class.

Classes
class	orxonox::CheckPoint
class	orxonox::DistanceTrigger
	The DistanceTrigger is a Trigger that triggers whenever an object (that is of the specified target type) is in a specified range of the DistanceTrigger. More...
class	orxonox::EventTrigger
	The EventTrigger class provides a way to have a Trigger triggered by any kinds of Events. More...
class	orxonox::Trigger
	A Trigger is an object that can either be active or inactive, with a specified behavior how to switch between the two. More...

Enumerations
enum	orxonox::DistanceTriggerBeaconMode { orxonox::DistanceTriggerBeaconMode::off, orxonox::DistanceTriggerBeaconMode::identify, orxonox::DistanceTriggerBeaconMode::exclude }
	Enum for the beacon mode of the DistanceTrigger. More...

Detailed Description

Triggers are objects which react to certain events by changing their boolean state.

That state is the trigger's activity orxonox::Trigger can be either active or not active.

Technical Details

A common Trigger is an object that can either be active or inactive, with a specified behavior how to switch between the two. Each time a switch occurs an Event is fired (see the Eventsystem for more information about how that works exactly), with th Trigger as the originator. This way the entity that reacts to the Trigger triggering receives information about the Trigger that created the Event. If the Trigger is also a PlayerTrigger, under some conditions, the entity that caused the Trigger to trigger can be accessed.

Also, just as with all triggers, Triggers can be nested (even with e.g. MultiTriggers).

<Trigger switch="true" delay="2">
    <DistanceTrigger position="100,0,0" distance="80" />
    <EventMultiTrigger ... />
</Trigger>

Triggers also allow for additional complexity which can be added through the choice of the parameters explained below. But first it is important to understand a small implementation detail. There is a distinction between the Trigger being triggered (there is the state triggered for that) and the Trigger being active (for that is the state activity). From the outside only the activity is visible. The state triggered tells us whether the trigger is actually triggered, but it could pretend (for some reason, some of which we will see shortly) to be active to the outside, while it in fact isn't. The standard behavior is, that the activity changes, when the Trigger transits from being triggered to being not triggered or the other way around.

The parameters of the Trigger are:

• delay The delay is the time in seconds, that the trigger waits until it reacts (i.e. changes it's state) to the triggering condition being fulfilled. Internally this is handled by a state queue coupled with a counter, for each state that is delayed. The state becomes active when the counter runs out. This allows the Trigger to work even if the delay changes at runtime. However if the delay changes it only affects newly arriving states not the ones already in the queue. The default is 0.0.
• switch Switch is a boolean, if true the Trigger is in switch-mode, meaning, that the activity changes only when the trigger is triggered, not when it is not triggered (Just like a light switch does). This means, that in switch-mode the activity only changes, when the trigger changes from being not triggered to being triggered but not the other way around. The default is false.
• stayActive Stay active is also a boolean, if true the Trigger stays active after it has been activated as many times as specified by the parameter activations. In essence this means, that after the last time it is activated it cannot be deactivated. The default is false.
• activations Activations is the number of times the Trigger can be activated until the trigger can't be triggered anymore. The default is -1, which denotes infinity.
• invert Invert is a boolean, if true the Trigger is in invert-mode, meaning, that if the triggering condition is fulfilled the Trigger will have the state not triggered and and if the condition is not fulfilled it will have the state triggered. In short it inverts the behavior of the Trigger. The default is false.
• mode The mode describes how the Trigger acts in relation to all the triggers (its children), that are appended to it. There are 3 modes: and, meaning that the Trigger can only be triggered if all the appended triggers are active. or, meaning that the Trigger can only be triggered if at least one of the appended triggers is active. And xor, meaning that the Trigger can only be triggered if one and only one appended trigger is active. Note, that I wrote 'can only be active', that implies, that there is an additional condition to the activity of the Trigger and that is the fulfillment of the triggering condition (the Trigger class itself doesn't have one, but all derived classes should). Also bear in mind, that the activity of a Trigger is still coupled to the object that triggered it. The default is and.

Sub-types of Triggers

EventTrigger

An EventTrigger can either be used to be triggered when an Event, that itself is triggering, arrives at its event port.

A common usage could look like this:

<EventTrigger invert="true" delay="1">
    <events>
        <trigger>
            <Trigger ... />
            <Trigger ... />
        </trigger>
    </events>
</EventTrigger>

DistanceTrigger

The DistanceTrigger is a Trigger that triggers whenever an object (that is of the specified target type) is in a specified range of the DistanceTrigger. The object can be specified further by setting the beaconMode and attaching a DistanceTriggerBeacon to the object. Parameters are (additional to the ones of Trigger):

• distance Which specifies the maximum distance at which the DistanceTrigger still triggers, i.e. its range. Default is 100.
• target Which specifies the class of objects that can trigger the DistanceTrigger. Default is "Pawn".
• beaconMode Which specifies, whether the DistanceTrigger operates on DistanceTriggerBeacons or not. If off the DistanceMultiTrigger works as usual. If set to identify the DistanceTrigger is only triggered by objects that have a DistanceTriggerBeacon, with the same name as specified in targetname, attached to them. If set to exclude the DistanceTrigger is only triggered by objects that don't have a DistanceTriggerBeacon, with the same name as specified in targetname, attached to them. Default is off.
• targetname Which specifies the name DistanceTriggerBeacons need to have to make the DistanceTrigger react to them if it is in beacon-mode (the beaconMode is not off).

A simple DistanceTrigger could look like this:

<DistanceTrigger position="0,0,0" switch="true" target="Pawn" distance="20" />

An implementation that only reacts to objects with a DistanceTriggerBeacon attached would look like this:

<DistanceTrigger position="0,0,0" target="Pawn" beaconMode="identify" targetname="beacon1" distance="30" />

This particular DistanceTrigger would only react if an object was in range, that had a DistanceTriggerBeacon with the name beacon1 attached.

Enumeration Type Documentation

enum orxonox::DistanceTriggerBeaconMode

strong

Enum for the beacon mode of the DistanceTrigger.

Enumerator
off
identify
exclude