Index: code/branches/core5/data/levels/events.oxw
===================================================================
--- code/branches/core5/data/levels/events.oxw	(revision 5882)
+++ code/branches/core5/data/levels/events.oxw	(revision 5882)
@@ -0,0 +1,187 @@
+<?lua
+  include("hudtemplates3.oxo")
+  include("stats.oxo")
+  include("templates/spaceship_assff.oxt")
+  include("templates/spaceship_H2.oxt")
+?>
+
+<Level
+ name         = "Event testing"
+ description  = "A simple level to test the event-system (with comments)"
+>
+  <Scene
+   ambientlight = "0.5, 0.5, 0.5"
+   skybox       = "Orxonox/skypanoramagen1"
+  >
+    <Light type=directional position="0,0,0" direction="0.253, 0.593, -0.765" diffuse="1.0, 0.9, 0.9, 1.0" specular="1.0, 0.9, 0.9, 1.0" />
+
+    <SpawnPoint position="0,-100,0" lookat="0,0,0" roll=180 spawnclass=SpaceShip pawndesign=spaceshipassff />
+
+    <Billboard position=" 300,100,  0" material="Examples/Flare" colour="1.0, 0.0, 0.0" />
+    <Billboard position=" 200,100,  0" material="Examples/Flare" colour="1.0, 0.5, 0.0" />
+    <Billboard position=" 200,100,100" material="Examples/Flare" colour="1.0, 0.5, 0.0" />
+    <Billboard position=" 100,100,  0" material="Examples/Flare" colour="1.0, 1.0, 0.0" />
+    <Billboard position="   0,100,  0" material="Examples/Flare" colour="0.0, 1.0, 0.0" />
+    <Billboard position="-100,100,  0" material="Examples/Flare" colour="0.0, 1.0, 1.0" />
+    <Billboard position="-100,100,100" material="Examples/Flare" colour="0.0, 1.0, 1.0" />
+    <Billboard position="-200,100,  0" material="Examples/Flare" colour="0.0, 0.0, 1.0" />
+    <Billboard position="-300,100,  0" material="Examples/Flare" colour="1.0, 0.0, 1.0" />
+
+
+    <!--
+      Note:
+      All following examples use only one subobject (in nested layouts). But of course you can add more
+      objects. They will all follow the same rules (depending on the example receive, send or pipe events).
+
+      Some examples address objects by name. Those methods always address ALL objects with this name, no
+      matter where they are in the XML-file (before or after the addressing object). Of course this also
+      works with all amounts of objects from zero to infinity. In the examples I used two objects each.
+    -->
+      
+
+    <!-- red -->
+    <!--
+      Standard:
+      Direct event-connection between an event-listener (Billboard) and an event source (DistanceTrigger).
+      Every fired event of the source is mapped to the "visibility" state of the listener.
+
+      This is a 1:1 mapping between event-listener and event-source.
+    -->
+    <Billboard position="300,150,0" material="Examples/Flare" colour="1.0, 1.0, 1.0" visible=0>
+      <events>
+        <visibility>
+          <DistanceTrigger position="300,100,0" distance=25 target="ControllableEntity" />
+        </visibility>
+      </events>
+    </Billboard>
+
+
+    <!-- orange -->
+    <!--
+      EventListener:
+      The EventListener object forwards all events from objects, whose names equal the "event" attribute
+      of the EventListener, to the enclosing object (Billboard).
+      In this case, both triggers have the name "trigger2" and thus both triggers send events to the Billboard.
+
+      The EventListener provides an 1:n mapping between one listener and multiple event-sources.
+    -->
+    <Billboard position="200,150,0" material="Examples/Flare" colour="1.0, 1.0, 1.0" visible=0>
+      <events>
+        <visibility>
+          <EventListener event="trigger2" />
+        </visibility>
+      </events>
+    </Billboard>
+    <DistanceTrigger name="trigger2" position="200,100,0" distance=25 target="ControllableEntity" />
+    <DistanceTrigger name="trigger2" position="200,100,100" distance=25 target="ControllableEntity" />
+
+
+    <!-- yellow -->
+    <!--
+      EventTarget:
+      The EventTarget object forwards the events, received from objects whithin the "events" subsection,
+      to all  objects whose names equal the "name" attribute.
+      In this case, the EventTarget forwards the event from the DistanceTrigger to all listeners with
+      name "bb3".
+
+      The EventTarget provides an n:1 mapping between several listeners and one event-source.
+    -->
+    <Billboard name="bb3" position="100,150,0" material="Examples/Flare" colour="1.0, 1.0, 1.0" visible=0 />
+    <Billboard name="bb3" position="100,150,100" material="Examples/Flare" colour="1.0, 1.0, 1.0" visible=0 />
+    <EventTarget name="bb3">
+      <events>
+        <visibility>
+          <DistanceTrigger position="100,100,0" distance=25 target="ControllableEntity" />
+        </visibility>
+      </events>
+    </EventTarget>
+
+
+    <!-- green -->
+    <!--
+      EventDispatcher:
+      The EventDispatcher catches events from objects in its "events" subsection. Those events are forwared
+      to all objects in the "targets" subsection. The EventDispatcher resembles the EventTarget, but
+      doesn't address objects with the "name" attribute. It rather places them directly inside the "targets"
+      subsection.
+      In this case, the EventDispatcher receives events from the DistanceTrigger and forwards those events
+      to the Billboard object.
+
+      The EventDispatcher provides an n:1 mapping between several targets (listeners) and one event source.
+    -->
+    <EventDispatcher>
+      <targets>
+        <Billboard position="0,150,0" material="Examples/Flare" colour="1.0, 1.0, 1.0" visible=0 />
+      </targets>
+      <events>
+        <visibility>
+          <DistanceTrigger position="0,100,0" distance=25 target="ControllableEntity" />
+        </visibility>
+      </events>
+    </EventDispatcher>
+
+
+    <!-- turquoise -->
+    <!--
+      Combination:
+      By combinding the above three classes, namely EventDispatcher, EventTarget and EventListener, you can
+      extract the event logic completely from the actual objects (Billboards and DistanceTriggers).
+      In this case, both triggers (whith names "trigger5") send events to both Billboards (with names "bb5").
+
+      This combination allows an n:n mapping between event-listeners and event-sources.
+    -->
+    <Billboard name="bb5" position="-100,150,0" material="Examples/Flare" colour="1.0, 1.0, 1.0" visible=0 />
+    <Billboard name="bb5" position="-100,150,100" material="Examples/Flare" colour="1.0, 1.0, 1.0" visible=0 />
+    <DistanceTrigger name="trigger5" position="-100,100,0" distance=25 target="ControllableEntity" />
+    <DistanceTrigger name="trigger5" position="-100,100,100" distance=25 target="ControllableEntity" />
+    <EventDispatcher>
+      <targets>
+        <EventTarget name="bb5" />
+      </targets>
+      <events>
+        <visibility>
+          <EventListener event="trigger5" />
+        </visibility>
+      </events>
+    </EventDispatcher>
+
+
+    <!-- blue -->
+      Mainstate:
+      Apart from the standard states (like activity and visibility), each object can have a mainstate.
+      You can define the mainstate with an xml-attribute: mainstate="state". "state" must be one of the
+      supported boolean states of the object. If the mainstate is set (by default that's not the case),
+      you can send events to the "mainstate" state. This allows you to hide the actually affected state
+      in the event-listener, while the event-source just sends events.
+      Note that this example is exactly like the standard case, but the event is sent to the main-state,
+      which in turn is set to "visibility".
+    <!--
+    -->
+    <Billboard position="-200,150,0" material="Examples/Flare" colour="1.0, 1.0, 1.0" visible=0 mainstate="visibility">
+      <events>
+        <mainstate>
+          <DistanceTrigger position="-200,100,0" distance=25 target="ControllableEntity" />
+        </mainstate>
+      </events>
+    </Billboard>
+
+
+    <!-- violet -->
+    <!--
+      Event forwarding:
+      As a consequence of the mainstate, events can also be sent without any explicit declaration of
+      the targets state. This allows us to forward events from an event-source directly to a bunch of
+      event-listeners. The events are automatically piped into the mainstate. Therefore the listeners
+      have to declare their main-state.
+      In this example, the DistanceTrigger forwards the events to the Billboards main-state (visibility).
+      This does the same like the example above, but instead of piping events backwards from the source
+      into the mainstate of the listener, we're forwarding the event implicitly to the mainstate.
+    -->
+    <DistanceTrigger position="-300,100,0" distance=25 target="ControllableEntity">
+      <eventlisteners>
+        <Billboard position="-300,150,0" material="Examples/Flare" colour="1.0, 1.0, 1.0" visible=0 mainstate="visibility" />
+      </eventlisteners>
+    </DistanceTrigger>
+
+  </Scene>
+</Level>
