source: code/branches/doc/data/levels/events.oxw @ 7318

<?lua
  include("hudtemplates3.oxo")
  include("stats.oxo")
  include("templates/spaceship_assff.oxt")
  include("templates/spaceship_H2.oxt")
  include("templates/lodinformation.oxt")
?>

<Level
 name         = "Event testing"
 description  = "A simple level to test the event-system (with comments)"
>
  <templates>
    <Template link=lodtemplate_default />
  </templates>

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



    <!--
      Begin of the tutorial section.
    -->



    <!--
      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 target="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 target="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 states of the object (except states which need the originator as a second argument). 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>



    <!--
      End of the tutorial section.
    -->



    <!--
      The following example shows again the red (standard layout) and the violet (event forwarding) example,
      but this time with a memoryless state (spawn) from the ParticleSpawner instead of the boolean state
      (visibility) in the other examples.
    -->
    <Billboard position=" 300,100,300" material="Examples/Flare" colour="1.0, 0.0, 0.0" />
    <Billboard position="-300,100,300" material="Examples/Flare" colour="1.0, 0.0, 1.0" />
    <ParticleSpawner position="300,150,300" source="Orxonox/BigExplosion1part1" lifetime=3.0 autostart=0>
      <events>
        <spawn>
          <DistanceTrigger position="300,100,300" distance=25 target="ControllableEntity" />
        </spawn>
      </events>
    </ParticleSpawner>
    <DistanceTrigger position="-300,100,300" distance=25 target="ControllableEntity">
      <eventlisteners>
        <ParticleSpawner position="-300,150,300" source="Orxonox/BigExplosion1part1" lifetime=3.0 autostart=0 mainstate="spawn" />
      </eventlisteners>
    </DistanceTrigger>

  </Scene>
</Level>