Orxonox  0.0.5 Codename: Arcturus
Files | Classes | Enumerations

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


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.


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...


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 ... />

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:

Sub-types of MultiTriggers


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">
<MultiTrigger ... />
<Trigger ... />


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):

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 for the beacon mode of the DistanceMultiTrigger.


The DistanceMultiTrigger is not in beacon-mode.


The DistanceTrigger is in identify-mode.


The DistanceTrigger is in exclude-mode.