= Trigger =
[[TOC]]
''This documentation refers to revision r7301 be aware that some things may have changed if your revision number differs too much.''

Triggers are objects which react on certain events. You can combine triggers to use them as simple overlay logic in the levels. All triggers inherit from their main class Trigger and each implement a special functionality. The main class has no special functionality.

If a trigger gets triggered it will change its state from active to inactive or the other way around. Triggers can be combined in a tree structure with a well defined parent-child relationship. You will be able to tell the parent who it should react on state changes from its children.

At the beginning the Trigger is not triggered and not active.

An extension of Triggers is the [wiki:MultiTrigger] class, which has a distinct state for each object that can trigger it.

== Basic Functionality ==

Following functionality is implemented in the main class and therefore usable by all triggers.

=== XML Port ===
All triggers can be added into the level file. They can be nested like the XML-tags you know already. This will look like this for example:

{{{
<Trigger position="0,200,0" scale="2" delay="2">
  <DistanceTrigger position="100,0,0" scale="2" distance="80">
  <DistanceTrigger position="150,0,0" scale="2" distance="80">
</Trigger>
}}}

You may noticed that it doesn't matter what kind of trigger is nested. The two DistanceTriggers are children of the Trigger object. Also note that position and scale are inherited properties of WorldEntity.

=== Number of Activations ===
A trigger may have a limited number of activations. This option overrules any other option which would hinder the trigger to be activated that many times. This means that the Stay Active-option cannot be used with a limited number of activations. The default value is -1 meaning that the number of activations is unlimited.

Set the number of activations in the level file by using the parameter ''activations="5"''.

=== Stay Active ===
Once the trigger is active it cannot be deactivated anymore. This option is overruled by the Number of Activations-option.

Use the parameter ''stayactive'' to turn this option on. This is turned off by default.

=== Switch ===
If a trigger is a switch it only changes its state when it is triggered, but not when it is un-triggered. Without the Switch-option the trigger is only active during the time it is triggered. With the Switch-option turned on the trigger stays active until the next time it is triggered.
Imagine pressing a light switch. The lamp will be lit even after you released your finger from the light switch. To turn it of you have to press (trigger) the switch a second time.

To turn on this property use ''switch'' in the level file. It is turned off by default.

=== Delay ===
Introduces a delay until the trigger reacts. Inside the trigger there is a FIFO queue which stores state changes. If a delay is set, each state change will wait for the chosen time until it will leave the queue and changes the state of the trigger.
You can alter the delay at runtime. However a state change which occurred before the alteration of the delay will wait the amount of time which was set when it entered the queue. It is also not possible to put a state change somewhere between waiting states by changing the delay, because the queue is a FIFO queue. Trying to do that will result in two state changes at the same time.

Set the delay by using ''delay="2.3"'' in the Trigger tag (the value is the delay in seconds). Default is ''0''.

=== Mode ===
This mode refers to how the trigger should behave when its children are becoming active. There are three different modes:

==== AND ====
The trigger is only activated when all children are active and the trigger is also triggered by its special functionality.

==== OR ====
The trigger is activated when any child is active or it is triggered by its special functionality.

==== XOR ====
The trigger is only activated when there is only one child active or it is only triggered by its special functionality.

Set the modes using ''mode'' in the level file (use lower case). Default value is ''and''.

=== Invert ===
This option inverts the mode to NAND, NOR or XNOR.

Use ''invert'' to invert the mode. This is turned off by default.

== Distance Trigger ==
A distance trigger is triggered when certain objects are in its vicinity.

=== Distance ===
The maximum distance between a certain object and the trigger so it is still triggered.

Set the distance in the level file using parameter ''distance="50"''. Default distance is ''100'' units.

=== Targets ===
You have two possibilities to set the target of the distance trigger. Specify a [wiki:Identifier class name] and the distance trigger will react on every object which belongs to this class either directly or inherited. This is established by using a ClassTreeMask.

Just add an object to the trigger and the trigger will react on exactly this object and no other. This second possibility is however not supported fully and you shouldn't use it. In both cases you can change the targets by adding and removing them.

To set the class name of targets use ''target="!BaseObject"''. Default is ''ControllableEntity''. Note that distance triggers always exclude the Trigger class so it won't trigger itself. You can therefore set the target to a parent class of Trigger without experiencing strange behavior.

=== Targetname ===
Setting the 'targename' puts the DistanceTrigger in single-target mode. In this mode the DistanceTrigger can only be triggered by objects that have a DistanceTriggerBeacon with the name specified by 'targetname' directly attached. For the single-target mode to work the target of the DistanceMultiTrigger has to be set to 'DistanceTriggerBeacon'. 

== Event Trigger ==

An event trigger is triggered by an event that comes in through its event interface.

{{{
<EventTrigger>
    <events>
        <trigger>
            <EventListener ... />
            <DistanceTrigger ... />
        </trigger>
    </events
</EventTrigger>
}}}