MultiTrigger

MultiTriggers are (as they are Triggers) objects which react to certain events. More...

Files
file	DistanceMultiTrigger.cc
	Implementation of the DistanceMultiTrigger class.
file	DistanceMultiTrigger.h
	Definition of the DistanceMultiTrigger class.
file	EventMultiTrigger.cc
	Implementation of the EventMultiTrigger class.
file	EventMultiTrigger.h
	Definition of the EventMultiTrigger class.
file	MultiTrigger.cc
	Implementation of the MultiTrigger class.
file	MultiTrigger.h
	Definition of the MultiTrigger class.
file	MultiTriggerContainer.cc
	Implementation of the MultiTriggerContainer class.
file	MultiTriggerContainer.h
	Definition of the MultiTriggerContainer class.

Classes
class	orxonox::DistanceMultiTrigger
	The DistanceMultiTrigger is a MultiTrigger that triggers whenever an object (that is of the specified target type) is in a specified range of the DistanceMultiTrigger. More...
class	orxonox::EventMultiTrigger
	The EventMultiTrigger class is the equivalent of the EventTrigger class for MultiTriggers. More...
class	orxonox::MultiTrigger
	The MultiTrigger class implements a trigger that has a distinct state for each object triggering it. More...
class	orxonox::MultiTriggerContainer
	This class is used by the MultiTrigger class to transport additional data via Events. More...
struct	orxonox::MultiTriggerState
	Struct to handle MultiTrigger states internally. More...

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

Detailed Description

MultiTriggers are (as they are Triggers) objects which react to certain events.

They offer all the functionality that the common Triggers do with one significant difference. The common Trigger has just one state, it can either be active or not acive, it doesn't discriminate between who's triggering (or not triggering) it. A MultiTrigger, on the other hand, has a distinct state (active or not actve) for each entity that is defined as being able to trigger said MultiTrigger.

This difference becomes significant, when, for example, you want a DistanceTrigger to trigger a QuestEffectBeacon to hand out a Quest to any Pawn that enters its range. With a simple DistanceTrigger (as opposed to the more complex DistanceMultiTrigger) the first Pawn to be in range would trigger it an receive the Quest, however if a second Pawn would enter the range, while the first Pawn still is in the range nothing would happen and even after the first Pawn left nothing would happen, since the whole time the DistanceTrigger would just be active. In contrast with a DistanceMultiTrigger the first Pawn would enter the range and the DistanceMultiTrigger would have the state active for this exact Pawn (but for none else) and thus the Pawn would receive the Quest and when the second Pawn enters the range the state of the DistanceMultiTrigger for that second Pawn would change to active and it would receive the Quest as well.

When to use MultiTriggers

Consequentially you would use MultiTriggers (instead of common Triggers), when it is important that the trigger has different states for each triggering entity and when that fact is essential in the concept of the object that reacts to the triggering. However you should not just use MultiTrigger instead of Trigger, when in doubt, because MultiTrigger produces significantly more overhead than Trigger due to the added complexity.

How to use MultiTriggers

...

How to create a new MultiTrigger.

...

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. A MultiTrigger generalizes that behavior for multiple objects triggering the trigger. A MultiTrigger can be active or inactive for any object triggering it, with the state for each object being completely independent of the state for all other objects. Each time a switch occurs an Event is fired (see the Eventsystem for more information about how that works exactly), with a MultiTriggerContainer as the originator, containing a pointer to the MultiTrigger that caused the Event and a pointer to the object that caused the trigger to change it's activity. This way the entity that reacts to the MultiTrigger triggering receives the information it needs about the entity that triggered the MultiTrigger.

Also, just as with all triggers, MultiTriggers can be nested (even with triggers other than MultiTriggers).

<MultiTrigger switch="true" delay="2">
    <DistanceMultiTrigger position="100,0,0" distance="80" />
    <EventTrigger ... />
</Trigger>

MultiTriggers also allow for additional complexity which can be added through the choice of the parameters (some of which are also present in the common Trigger) explained (briefly) below. But first it is important to understand a small implementation detail. There is a distinction between the MultiTrigger being triggered (there is the state triggered for that) and the MultiTrigger 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 MultiTrigger transits from being triggered to being not triggered or the other way around.

The parameters of the MultiTrigger 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 MultiTrigger 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 MultiTrigger is in switch-mode, meaning, that the activity changes only when the trigger is triggered, not when it is un-triggered (Just like a light switch does). This means, that in switch-mode the activity only changes, when the trigger changes from not being triggered to being triggered but not the other way around. The default is false.
• stayActive Stay active is also a boolean, if true the MultiTrigger 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 MultiTrigger 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 MultiTrigger is in invert-mode, meaning, that if the triggering condition is fulfilled the MultiTrigger 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 MultiTrigger. The default is false.
• simultaneousTriggerers The number of simultaneous triggerers limits the number of objects that are allowed to trigger the MultiTrigger at the same time. Or more precisely, the number of distinct objects the MultiTrigger has positive triggered states for, at each point in time. The default is -1, which denotes infinity.
• mode The mode describes how the MultiTrigger acts in relation to all the triggers (its children), that are appended to it. There are 3 modes: and, meaning that the MultiTrigger can only be triggered if all the appended triggers are active. or, meaning that the MultiTrigger can only be triggered if at least one of the appended triggers is active. And xor, meaning that the MultiTrigger 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 MultiTrigger and that is the fulfillment of the triggering condition (the MultiTrigger class itself doesn't have one, but all derived classes should). Also bear in mind, that the activity of a MultiTrigger is still coupled to the object that triggered it. The default is and.
• broadcast Broadcast is a boolean, if true the MultiTrigger is in broadcast-mode, meaning, that all trigger events that are caused by no originator (originator is NULL) are broadcast as having come from every possible originator, or more precisely as having come from all objects that are specified targets of this MultiTrigger. The default is false.
• target The target describes the kind of objects that are allowed to trigger this MultiTrigger. The parameter has to be set to the class name of the class that is allowed to trigger the MultiTrigger. The default is Pawn.

Sub-types of MultiTriggers

EventMultiTrigger

An EventMultiTrigger can either be used to broadcast an Event that does not come from a MultiTrigger to all entities that are targets of the EventMultiTrigger or, more in line with its prototype the EventTrigger, to be triggered for an entity when an Event that was caused by an entity of the same type is captured.

A common usage could look like this:

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

DistanceMultiTrigger

A DistanceMultiTrigger is the MultiTrigger equivalent of the DistanceTrigger and works just the same way. It triggers (now separately for each object triggering it, since it's a MultiTrigger) whenever an object that is a target of the DistanceMultiTrigger is in the specified range.

The target object can be specified further by setting the beaconMode and attaching a DistanceTriggerBeacon to the object. Parameters are (additional to the ones of MultiTrigger):

• distance Which specifies the maximum distance at which the DistanceMultiTrigger still triggers. Default is 100.
• beaconMode Which specifies, whether the DistanceMultiTrigger operates on DistanceTriggerBeacons or not. If off the DistanceMultiTrigger works as usual. If set to identify the DistanceMultiTrigger 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 DistanceMultiTrigger 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 DistanceMultiTrigger react to them if it is in beacon-mode (the beaconMode is not off).

A simple DistanceMultiTrigger could look like this:

<@ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" 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:

<@ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" position="0,0,0" target="Pawn" beaconMode="identify" targetname="beacon1" distance="30" />

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

Enumeration Type Documentation

enum orxonox::DistanceMultiTriggerBeaconMode

strong

Enum for the beacon mode of the DistanceMultiTrigger.

Enumerator
off	The DistanceMultiTrigger is not in beacon-mode.
identify	The DistanceTrigger is in identify-mode.
exclude	The DistanceTrigger is in exclude-mode.