Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: code/branches/usability/doc/api/Groups.dox @ 9987

Last change on this file since 9987 was 7679, checked in by dafrick, 14 years ago

Renaming levelfiles (and some other) according to our new naming conventions which is using camelCase, without '_' or spaces.

  • Property svn:eol-style set to native
File size: 63.3 KB
Line 
1/*
2 *   ORXONOX - the hottest 3D action shooter ever to exist
3 *                    > www.orxonox.net <
4 *
5 *
6 *   License notice:
7 *
8 *   This program is free software; you can redistribute it and/or
9 *   modify it under the terms of the GNU General Public License
10 *   as published by the Free Software Foundation; either version 2
11 *   of the License, or (at your option) any later version.
12 *
13 *   This program is distributed in the hope that it will be useful,
14 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
15 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 *   GNU General Public License for more details.
17 *
18 *   You should have received a copy of the GNU General Public License
19 *   along with this program; if not, write to the Free Software
20 *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
21 *
22 *   Author:
23 *      Fabian 'x3n' Landau
24 *   Co-authors:
25 *      Damian 'Mozork' Frick
26 *
27 */
28
29/**
30    @defgroup Util Util
31
32    The util library contains several functions, classes, and templates that can be used in different
33    parts of the Orxonox-code. They provide functionalities for mathematical use, string manipulation,
34    typeconversion, multi-types, error- and exception-handling, debug output, and many more.
35*/
36
37/**
38    @defgroup Core Core
39
40    The core library contains the framework of Orxonox - all important classes, functions, and macros
41    that are used to create and manage classes and objects. Almost all classes in Orxonox need at least
42    one of the core features.
43*/
44
45/**
46    @defgroup Class Class management
47    @ingroup Core
48*/
49
50/**
51    @defgroup Object Object management
52    @ingroup Core
53*/
54
55/**
56    @defgroup Command Command
57    @ingroup Core
58*/
59
60/**
61    @defgroup Config Config
62    @ingroup Core
63*/
64
65/**
66    @defgroup Input Input
67    @ingroup Core
68*/
69
70/**
71    @defgroup Management Management
72    @ingroup Core
73*/
74
75/**
76    @defgroup XML XML
77    @ingroup Core
78*/
79
80/**
81    @defgroup Network Network
82
83    The network library is used to connect clients and server, to synchronize objects and variables, and
84    to transmit network function calls. It contains the central @ref orxonox::Server "Server" and
85    @ref orxonox::Client "Client" classes as well as several functions and macros for
86    @ref orxonox::Synchronisable "synchronisable" classes.
87*/
88
89/**
90    @defgroup Tools Tools
91
92    The tools are a bunch of utilities that belong to the Orxonox library, but are independent of other
93    features.
94*/
95
96/**
97    @defgroup Orxonox Orxonox
98
99    The Orxonox library contains the central and most important classes of the game. Managers, interfaces,
100    base-classes, and more are located in Orxonox. More specialized classes that inherit of the base-classes
101    in Orxonox are often sourced out to the modules.
102*/
103
104/**
105    @defgroup Modules Modules
106
107    The modules are libraries that depend on the Orxonox library and that are loaded dynamically on runtime
108    (in contrast to statically loaded libraries like util and core). Each module contains some classes that
109    are usually connected to each other, but they are independent of other modules. However modules can still
110    link to other modules, but only in a hierarchical order, no circular dependencies.
111*/
112
113/**
114    @defgroup Designtools Designtools
115    @ingroup Modules
116*/
117
118/**
119    @defgroup Notifications Notifications
120    @ingroup Modules
121
122    @ref orxonox::Notification "Notifications" are short messages, that can be sent from anywhere in Orxonox and then are displayed on the screen to inform the user about some occurence he has to know about. Such an occurence could be, that he just shot and killed his Archnemesis Overlord3, that he just got a new Pickup or that he received a Quest and needs to have a look at the Quest-Menu.
123
124    @section NotificationsUsage Usage
125    Let's very briefly talk about what you have to do to either send @ref orxonox::Notification "Notifications" from some part of Orxonox or display Notifications on your screen.
126
127    @subsection NotifictionsSending Sending notifications
128    Sending a new @ref orxonox::Notification "Notification" from (almost) anywhere in Orxonox is fairly easy.
129    You first have to decide on a message, it shouldn't be too long but be long enough to get your point accross.
130    Then you have to decide on a sender. The sender is a string by which the different @ref orxonox::NotificationQueue "NotificationQueues" (the entities that display the @ref orxonox::Notification "Notifications") can decide whether they should display the @ref orxonox::Notification "Notification" or not. So the sender is some string that identifies a group of @ref orxonox::Notification "Notifications" that have something in common or some entity that is sending them. For example: All @ref orxonox::Notification "Notifications" sent by any part of the Questsystem have "questsystem" as sender and thus we could create a @ref orxonox::NotificationQueue "NotificationQueue" that only displays @ref orxonox::Notification "Notifications" from the Questsystem, but more to that later.
131    And lastly you have to decide to whom you want to send this @ref orxonox::Notification "Notification". You have to get the clientId of the intended recipient (e.g. trough a @ref orxonox::PlayerInfo "PlayerInfo") or you only send the @ref orxonox::Notification "Notification" locally, either by setting the clientId to Host::getPlayerID() or by setting the variable 'isLocal' to true, and setting clientId to what ever you want, since it will be ignored.
132    Once you have decided all that you can send the Notification by calling:
133    @code
134    NotificationManager::sendNotification(message, clientId, sender, isLocal); // isLocal = false can be ommitted since that is the default value.
135    @endcode
136
137    @subsection NotificationsDisplay Displaying notifications
138    Displaying @ref orxonox::Notification "Notifications" is even easier, all you need to do is to load the NotificationLayer in the level, where you want @ref orxonox::Notification "Notifications" displayed. You can either do this manually by executing the following command in the console:
139    @code
140    showGUI NotificationLayer false true
141    @endcode
142    Or automatically, by adding a @ref orxonox::Script "Script" to the levelfile that does it for you:
143    @code
144    <Script code="showGUI NotificationLayer false true" needsGraphics="true" />
145    @endcode
146
147    If you want to change the way the @ref orxonox::Notification "Notifications" are displayed, you can enter the (at this point rather rudimentary) edit mode and add new @ref orxonox::NotificationQueue "NotificationQueues" or change position and properties of the existing ones, by executing the following command in the console:
148    @code
149    enterEditMode
150    @endcode
151
152    @section NotificationsTechincalDetails Technical details
153    The Notifications module has three major parts that interact with each other. First there is the @ref orxonox::NotificationQueue "NotificationQueue", this is the entity that (logically, not effectively) displays @ref orxonox::Notification "Notifications" according to some rules, then there is the NotificationLayer, which is the GUI which (actually) displays @ref orxonox::Notification "Notifications" by visualizing the @ref orxonox::NotificationQueue "NotificationQueues" and as a result also the @ref orxonox::Notification "Notifications", that are displayed by the respective @ref orxonox::NotificationQueue "NotificationQueues" and lastly there is the @ref orxonox::NotificationManager "NotificationManager", which connects these two.
154
155    @subsection NotificationQueue NotificationQueue
156    The @ref orxonox::NotificationQueue "NotificationQueue" is the entity, that (as said earlier) logically displays @ref orxonox::Notification "Notifications". Furthermore a @ref orxonox::NotificationQueue "NotificationQueue" displays only a subset of all the @ref orxonox::Notification "Notifications". The parameters that reduce the range of displayed @ref orxonox::Notification "Notifications" are:
157    - @b senders The senders, the set of targets of a @ref orxonox::NotificationQueue "NotificationQueue" is the set of senders a @ref orxonox::NotificationQueue "NotificationQueue" displays  @ref orxonox::Notification "Notifications" from. E.g. If one would set the senders to "questsystem" then only  @ref orxonox::Notification "Notifications" from the Questsystem would be displayed in that particular queue. If you set senders to "all" then all Notifications will be displayed. Different senders can be concatinated with commas.
158    - @b size The size specifies how many @ref orxonox::Notification "Notifications" are displayed at the most, if there are more @ref orxonox::Notification "Notifications" that could be displayed, then only the most recent are displayed.
159    - @b displayTime The display time specifies how long a @ref orxonox::Notification "Notification" is displayed at the most.
160
161    @subsection NotificationLayer NotificationLayer
162    The NotificationLayer is a GUI sheet, that displays all the @ref orxonox::NotificationQueue "NotificationQueues" and their @ref orxonox::Notification "Notifications". In its normal mode of operation it is transparent to input, meaning that it only functions as a means of displaying, however if switched to edit mode the NotificationLayer no longer is transparent to input and allows for the adding, removal and modification of @ref orxonox::NotificationQueue "NotificationQueues". For every @ref orxonox::NotificationQueue "NotificationQueue" there is the equivalent representation in the NotificationLayer. So @ref orxonox::NotificationQueue "NotificationQueues" are not each represented by a GUI sheet, but thely all belong to one and the same GUI sheet, the NotificationLayer.
163
164    @subsection NotificationManager NotificationManager
165    The @ref orxonox::NotificationManager "NotificationManager" is (hence the name) the managing entity in this setting. It is responsible for the registering and unregistering of @ref orxonox::NotificationListener "NotificationListeners" (which the @ref orxonox::NotificationQueue "NotificationQueue" is) and also informs them about changes related to @ref orxonox::Notification "Notifications". It is also responsible for the creation and destruction of @ref orxonox::NotificationQueue "NotificationQueues" through the NotificationLayer and is also the point of approach for the NotificationLayer to get information it needs to display the queues. Finally the @ref orxonox::NotificationManager "NotificationManager" is responsible for sending (and in the process creating) @ref orxonox::Notification "Notifications" and is a means for the @ref orxonox::NotificationQueue "NotificationQueues" to get the information they need about @ref orxonox::Notification "Notifications".
166
167    @subsection Notification Notification
168    The @ref orxonox::Notification "Notification" class is more or less a data structure that groups the notification message and the sender, and possibly other future parameters, together to form a comprehensive structure that we call Notification.
169
170    Additionally there is another important class of objects belonging to the Notifications module. The @ref orxonox::NotificationDispatcher "NotificationDispatchers".
171
172    @subsection NotificationDispatcher NotificationDispatcher
173    @ref orxonox::NotificationDispatcher "NotificationDispatchers" are entities that are instantiated in a level file (through XML) and that dispatch (or send) a specific @ref orxonox::Notification "Notification" upon having received a triggering event.
174
175    @defgroup NotificationDispatchers Dispatchers
176    @ingroup Notifications
177
178    @ref orxonox::NotificationDispatcher "NotificationDispatchers" are entities that are instantiated in a level file (through XML) and that dispatch (or send) a specific @ref orxonox::Notification "Notification" upon having received a triggering event.
179
180    At this point there are two @ref orxonox::NotificationDispatcher "NotificationDispatchers", the @ref orxonox::SimpleNotification "SimpleNotification", which just displays a specified message, and the @ref orxonox::CommandNotification "CommandNotification" which displays a message with a binding for a specified command in it.
181*/
182
183/**
184    @defgroup Objects Objects
185    @ingroup Modules
186
187    @defgroup Collisionshapes Collisionshapes
188    @ingroup Objects
189
190    @defgroup Eventsystem Eventsystem
191    @ingroup Objects
192
193    @defgroup Triggers Triggers
194    @ingroup Objects
195
196    Triggers are objects which react to certain events. They can be combined and used as simple overlay logic in levels.
197
198    @defgroup NormalTrigger Trigger
199    @ingroup Triggers
200
201    @defgroup MultiTrigger MultiTrigger
202    @ingroup Triggers
203
204    @ref orxonox::MultiTrigger "MultiTriggers" are (as they are @ref orxonox::TriggerBase "Triggers") objects which react to certain events. They offer all the functionality that the common @ref orxonox::Trigger "Triggers" do with one significant difference. The common @ref orxonox::Trigger "Trigger" has just one state, it can either be <em>triggered</em> or <em>not triggered</em>, it doesn't discriminate between who's triggering (or not triggering) it. A @ref orxonox::MultiTrigger "MultiTrigger", on the other hand, has a distinct state (<em>triggered</em> or <em>not triggered</em>) for each entity that is defined as being able to trigger said @ref orxonox::MultiTrigger "MultiTrigger".
205
206    This difference becomes significant, when, for example, you want a @ref orxonox::DistanceTrigger "DistanceTrigger" to trigger a @ref orxonox::QuestEffectBeacon "QuestEffectBeacon" to hand out a @ref orxonox::Quest "Quest" to any @ref orxonox::Pawn "Pawn" that enters its range. With a simple @ref orxonox::DistanceTrigger "DistanceTrigger" (as opposed to the more complex @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger") the first @ref orxonox::Pawn "Pawn" to be in range would trigger it an receive the @ref orxonox::Quest "Quest", however if a second @ref orxonox::Pawn "Pawn" would enter the range, while the first @ref orxonox::Pawn "Pawn" still is in the range nothing would happen and even after the first @ref orxonox::Pawn "Pawn" left nothing would happen, since the whole time the @ref orxonox::DistanceTrigger "DistanceTrigger" would just be triggered. In contrast with a @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" the first @ref orxonox::Pawn "Pawn" would enter the range and the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" would have the state <em>triggered</em> for this exact @ref orxonox::Pawn "Pawn" (but for none else) and thus the @ref orxonox::Pawn "Pawn" would receive the @ref orxonox::Quest "Quest" and when the second @ref orxonox::Pawn "Pawn" enters the range the state of the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" for that second @ref orxonox::Pawn "Pawn" would change to <em>triggered</em> and it would receive the @ref orxonox::Quest "Quest" as well.
207
208    @section WhenToUseMultiTriggers When to use MultiTriggers
209    Consequentially you would use @ref orxonox::MultiTrigger "MultiTriggers" (instead of common @ref orxonox::Trigger "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 @ref orxonox::MultiTrigger "MultiTrigger" instead of @ref orxonox::Trigger "Trigger", when in doubt, because @ref orxonox::MultiTrigger "MultiTrigger" produces significantly more overhead than @ref orxonox::Trigger "Trigger" due to the added complexity.
210
211    @section HowToUseMultiTriggers How to use MultiTriggers
212    ...
213
214    @section MultiTriggerTechnicalDetails Technical Details
215    A common @ref orxonox::Trigger "Trigger" is an object that can either be <em>active</em> or <em>inactive</em>, with a specified behavior how to switch between the two. A @ref orxonox::MultiTrigger "MultiTrigger" generalizes that behavior for multiple objects triggering the trigger. A @ref orxonox::MultiTrigger "MultiTrigger" can be <em>active</em> or <em>inactive</em> 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 @ref orxonox::Event "Event" is fired, with a @ref orxonox::MultiTriggerContainer "MultiTriggerContainer" as the originator, containing a pointer to the @ref orxonox::MultiTrigger "MultiTrigger" that caused the @ref orxonox::Event "Event" and a pointer to the object that caused the trigger to change it's activity. This way the entity that reacts to the @ref orxonox::MultiTrigger "MultiTrigger" triggering receives the information it needs about the entity that triggered the @ref orxonox::MultiTrigger "MultiTrigger".
216
217    Also, just as with all triggers, @ref orxonox::MultiTrigger "MultiTriggers" can be nested (event with triggers other than @ref orxonox::MultiTrigger "MultiTriggers").
218    @code
219    <MultiTrigger switch="true" delay="2">
220        <DistanceMultiTrigger position="100,0,0" distance="80" />
221        <EventTrigger ... />
222    </Trigger>
223    @endcode
224
225    @ref orxonox::MultiTrigger "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 @ref orxonox::Trigger "Trigger") explained (briefly) below.
226    But first it is important to understand a small implementational detail. There is a distinction between the @ref orxonox::MultiTrigger "MultiTrigger" being triggered (there is the state <em>triggered</em> for that) and the @ref orxonox::MultiTrigger "MultiTrigger" being active (for that is the state <em>activity</em>). From the outside only the <em>activity</em> is visible (and has above been referred to as <em>triggered</em> for the sake of comprehensibility). The state <em>triggered</em> tells us whether the trigger is actually triggered, but it could pretend (for some reason, some of which we will see shortly) to be <em>triggered</em> to the outside, while it in fact isn't (but it would then be <em>active</em>). The standard behavior is, that the <em>activity</em> changes, when the @ref orxonox::MultiTrigger "MultiTrigger" transits from being triggered to not being triggered or the other way around. So to the inside a @ref orxonox::MultiTrigger "MultiTrigger" being <em>active</em> is synonymous to the @ref orxonox::MultiTrigger "MultiTrigger" being <em>triggered</em> to the outside.
227
228    The parameters of the @ref orxonox::MultiTrigger "MultiTrigger" are:
229    - @b 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 <em>active</em> when the counter runs out. This allows the @ref orxonox::MultiTrigger "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 <code>0</code>.
230    - @b switch Switch is a boolean, if <code>true</code> the @ref orxonox::MultiTrigger "MultiTrigger" is in <em>switch-mode</em>, meaning, that the <em>activity</em> changes only when the trigger is triggered, not when it is un-triggered (Just like a light switch does). This means, that in <em>switch-mode</em> the <em>activity</em> only changes, when the trigger changes from not being triggered to being triggered but not the other way around. The default is <code>false</code>.
231    - @b stayActive Stay active is also a boolean, if <code>true</code> the @ref orxonox::MultiTrigger "MultiTrigger" stays active after it has been activated as many times as specified by the parameter <em>activations</em>. In essence this means, that after the last time it is activated it cannot be deactivated. The default is <code>false</code>.
232    - @b activations Activations is the number of times the @ref orxonox::MultiTrigger "MultiTrigger" can be activated until the trigger can't be triggered anymore. The default is <code>-1</code>, which denotes infinity.
233    - @b invert Invert is a boolean, if <code>true</code> the @ref orxonox::MultiTrigger "MultiTrigger" is in <em>invert-mode</em>, meaning, that if the triggering condition is fulfilled the @ref orxonox::MultiTrigger "MultiTrigger" will have the state <em>not triggered</em> and and if the condition is not fulfilled it will have the state <em>triggered</em>. In short it inverts the behavior of the @ref orxonox::MultiTrigger "MultiTrigger". The default is <code>false</code>.
234    - @b simultaneousTriggerers The number of simultaneous triggerers limits the number of objects that are allowed to trigger the @ref orxonox::MultiTrigger "MultiTrigger" at the same time. Or more precisely, the number of distinct objects the @ref orxonox::MultiTrigger "MultiTrigger" has positive <em>triggered</em> states for, at each point in time. The default is <code>-1</code>, which denotes infinity.
235    - @b mode The mode describes how the @ref orxonox::MultiTrigger "MultiTrigger" acts in relation to all the triggers (its children), that are appended to it. There are 3 modes: <em>and</em>, meaning that the @ref orxonox::MultiTrigger "MultiTrigger" can only be triggered if all the appended triggers are active. <em>or</em>, meaning that the @ref orxonox::MultiTrigger "MultiTrigger" can only be triggered if at least one of the appended triggers is active. And <em>xor</em>, meaning that the @ref orxonox::MultiTrigger "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 <em>activity</em> of the @ref orxonox::MultiTrigger "MultiTrigger" and that is the fulfillment of the triggering condition (the @ref orxonox::MultiTrigger "MultiTrigger" class itself doesn't have one, but all derived classes should). Also bear in mind, that the <em>activity</em> of a @ref orxonox::MultiTrigger "MultiTrigger" is still coupled to the object that triggered it. The default is <em>and</em>.
236    - @b broadcast Broadcast is a boolean, if <code>true</code> the @ref orxonox::MultiTrigger "MultiTrigger" is in <em>broadcast-mode</em>, meaning, that all trigger events that are caused by no originator (originator is <code>NULL</code>) are broadcast as having come from every possible originator, or more precisely as having come from all objects that are specified targets of this @ref orxonox::MultiTrigger "MultiTrigger". The default is <code>false</code>.
237    - @b target The target describes the kind of objects that are allowed to trigger this @ref orxonox::MultiTrigger "MultiTrigger". The parameter has to be set to the class name of the class that is allowed to trigger the @ref orxonox::MultiTrigger "MultiTrigger". The default is <code>Pawn</code>.
238
239    @subsection Sub-typesOfMultiTriggers Sub-types of MultiTriggers
240
241    @subsubsection EventMultiTrigger EventMultiTrigger
242    An @ref orxonox::EventMultiTrigger "EventMultiTrigger" can either be used to broadcast an @ref orxonox::Event "Event" that does not come from a @ref orxonox::MultiTrigger "MultiTrigger" to all entities that are targets of the @ref orxonox::EventMultiTrigger "EventMultiTrigger" or, more in line with its prototype the @ref orxonox::EventTrigger "EventTrigger", to be triggered for an entity when an @ref orxonox::Event "Event" that was caused by an entity of the same type is captured.
243
244    A common usage could look like this:
245    @code
246    <EventMultiTrigger invert="true" delay="1">
247        <events>
248            <trigger>
249                <MultiTrigger ... />
250                <Trigger ... />
251            </trigger>
252        </events>
253    </EventMultiTrigger>
254    @endcode
255
256    @subsubsection DistanceMultiTrigger DistanceMultiTrigger
257    A @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" is the MultiTrigger equivalent of the @ref orxonox::DistanceTrigger "DistanceTrigger" and works just the same way. It triggers (now separately for each object triggering it, since it's a @ref orxonox::MultiTrigger "MultiTrigger") whenever an object that is a target of the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" is in the specified range.
258
259    Two additional parameters can be specified for the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" are the <em>distance</em>, which defines the maximum distance at which an object still triggers the @ref orxonox:: "DistanceMultiTrigger", and the <em>targetname</em>. Setting the <em>targename</em> puts the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" in <em>single-target mode</em>. In this mode the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger"  can only be triggered by objects that have a @ref orxonox::DistanceTriggerBeacon "DistanceTriggerBeacon" with the name specified by <em>targetname</em> directly attached. For the <em>single-target mode</em> to work the target of the @ref orxonox::DistanceMultiTrigger "DistanceMultiTrigger" has to be set to <code>DistanceTriggerBeacon</code>.
260
261    A common usage (without @ref orxonox::DistanceTriggerBeacon "DistanceTriggerBeacon") would look like this:
262    @code
263    <DistanceMultiTrigger position="0,0,0" switch="true" target="Pawn" distance="20" />
264    @endcode
265
266    With @ref orxonox::DistanceTriggerBeacon "DistanceTriggerBeacon" it would look like this:
267    @code
268    <DistanceMultiTrigger position="0,0,0" target="DistanceMultiTrigger" targetname="beacon1" distance="30" />
269    @endcode
270*/
271
272/**
273    @defgroup Overlays Overlays
274    @ingroup Modules
275*/
276
277/**
278    @defgroup Pickup Pickup
279    @ingroup Modules
280
281    The Pickup module adds a special type of object to Orxonox, the so-called @ref orxonox::Pickupable "Pickupables". @ref orxonox::Pickupable "Pickupables" are objects that can be picked up (by virtually any entity, but commonly by the @ref orxonox::Pawn "Pawn") and have some kind of effect on the entity that picked the @ref orxonox::Pickupable "Pickupable" up.
282
283    @section IncludingPickups Including pickups in a level
284    @ref orxonox::Pickupable "Pickupables" are designed so that they can be included in levels fairly easily, while also ensuring, that the pickup itself (its game-logic component) and how it is represented (e.g. in the PickupInventory (the GUI that displays @ref orxonox::Pickupable "Pickupables") or in the game) are neatly seperated.
285    To be able to use @ref orxonox::Pickupable "Pickupables" in a level one must understand some basic concepts.
286    - @ref orxonox::Pickupable "Pickupables" are entities which (by itself) have no physical (or graphical) dimension. The simply represent the effect they will have on a @ref orxonox::PickupCarrier "PickupCarrier" (the entity that can pick up @ref orxonox::Pickupable "Pickupables", @ref orxonox::Pawn "Pawn" for example inherits from @ref orxonox::PickupSpawner "PickupSpawner" and thus is able to pick up and carry @ref orxonox::Pickupable "Pickupables"), when used and the mechanism that leads to that.
287    - The physical (or graphical) dimension of a pickup is called a @ref orxonox::PickupRepresentation "PickupRepresentation".
288    - The @ref orxonox::PickupRepresentation "PickupRepresentation" of a @ref orxonox::Pickupable "Pickupable" and the @ref orxonox::Pickupable "Pickupable" itself are linked to each other, in such a way that a @ref orxonox::PickupRepresentation "PickupRepresentation" can only represent one type of @ref orxonox::Pickupable "Pickupable".
289    - A type of @ref orxonox::Pickupable "Pickupable" is a specific pickup class (inheriting from @ref orxonox::Pickupable "Pickupable") with specific values for all its relevant parameters. This means, that a pickup of the same class with the same values for all parameters except for one is a different type of pickup and will therefore have a different @ref orxonox::PickupRepresentation "PickupRepresentation". Which parameters are the ones relevant to destinguish between two types of pickups can be defined in the class description of the specific pickup.
290    - The entity that actually gives a @ref orxonox::Pickupable "Pickupable" to a @ref orxonox::PickupCarrier "PickupCarrier" is called a @ref orxonox::PickupSpawner "PickupSpawner". A @ref orxonox::PickupSpawner "PickupSpawner" creates (based on some parameters) @ref orxonox::Pickupable "Pickupables" which then is picked up by the @ref orxonox::PickupCarrier "PickupCarrier", that caused the @ref orxonox::PickupSpawner "PickupSpawner" to spawn a new pickup. How the spawner looks in the game is defined by the @ref orxonox::PickupRepresentation "PickupRepresentation" of the @ref orxonox::Pickupable "Pickupable" it spawns.
291
292    @subsection UsingPredifinedPickups Using predefined pickups
293    There is a file called <code>pickupRepresentationTemplates.oxt</code> in <code>levels/templates</code>, which holds the templates for the @ref orxonox::PickupRepresentation "PickupRepresentations" and also templates for @ref orxonox::Pickupable "Pickupables". The templates for the @ref orxonox::PickupRepresentation "PickupRepresentations" define the @ref orxonox::StaticEntity "StaticEntities" that are attached to the @ref orxonox::PickupSpawner "PickupSpawners" to make them look like the @ref orxonox::Pickupable "Pickupable" they are spawning. The templates for the @ref orxonox::Pickupable "Pickupables" can be added just for ease of use.
294    If you want to use pickups you will have to include this file in your level file, somewhere above the Level-tag.
295    @code
296    <?lua
297        include("templates/pickupRepresentationTemplates.oxt")
298    ?>
299    ...
300    <Level>
301    ...
302    @endcode
303    There is another file called <code>pickups.oxi</code> in <code>level/includes</code> which creates all @ref orxonox::PickupRepresentation "PickupRepresentations" needed for the @ref orxonox::Pickupable "Pickupable" supplied by the <code>pickupRepresentationTemplates.oxt</code> file. This file will have to be included as well. It has to be somewhere after the opening Scene-tag and your first use of a pickup.
304    @code
305    <Scene>
306    ...
307    <?lua
308        include("includes/pickups.oxi")
309    ?>
310    @endcode
311    After that all the predefined pickups specified in those two files can be used just by creating a @ref orxonox::PickupSpawner "PickupSpawner" for them in the respective level.
312    For example:
313    @code
314    <PickupSpawner position="-100,0,-100" respawnTime="30" maxSpawnedItems="10">
315        <pickup>
316            <HealthPickup
317                health = 10
318                healthType = "limited"
319                activationType = "immediate"
320                durationType = "once"
321            />
322        </pickup>
323    </PickupSpawner>
324    @endcode
325    Please be aware, that the @ref orxonox::Pickupable "Pickupable" specified for the @ref orxonox::PickupSpawner "PickupSpawner", has to be exactly the same (including all parameters) to the one specified in the <code>pickups.oxi</code> file.
326    To make things simpler, one could just use the templates specified in the <code>pickupRepresentationTemplates.oxt</code> file. Which, following the previous example, would look like this:
327    @code
328    <PickupSpawner position="-100,0,-100" respawnTime="30" maxSpawnedItems="10">
329        <pickup>
330            <HealthPickup template="smallhealthpickup" />
331        </pickup>
332    </PickupSpawner>
333    @endcode
334
335    @subsection UnsingNon-PredefinedPickups Using non-predefined pickups
336    To include a type of pickup (which, as we remember, is the class of the @ref orxonox::Pickupable "Pickupable" with specific values for all the relevant parameters) in a level file, you can just create a new @ref orxonox::PickupSpawner "PickupSpawner" and specify the @ref orxonox::Pickupable "Pickupable".
337    @code
338    <PickupSpawner position="-100,0,-100" respawnTime="30" maxSpawnedItems="10">
339    <pickup>
340        <HealthPickup
341            health = 33
342            healthType = "limited"
343            activationType = "immediate"
344            durationType = "once"
345        />
346    </pickup>
347    </PickupSpawner>
348    @endcode
349    As can be seen in the <code>pickupRepresentationTemplates.oxt</code> file and the <code>pickups.oxi</code> file there is no @ref orxonox::PickupRepresentation "PickupRepresentation" defined for this type of pickup. Thus the default representation will be used.
350
351    To create an appropriate @ref orxonox::PickupRepresentation "PickupRepresentation" for the inserted pickup above, you can just create a @ref orxonox::PickupRepresentation "PickupRepresentation" within the scene (Within the Scene-tags).
352    @code
353    <PickupRepresentation
354        name = "My new health pickup"
355        description = "This is an awesome new health pickup."
356        spawnerTemplate = "mediumhealthpickupRepresentation"
357        inventoryRepresentation = "MediumHealth"
358    >
359        <pickup>
360            <HealthPickup
361            health = 33
362            healthType = "limited"
363            activationType = "immediate"
364            durationType = "once"
365        />
366        </pickup>
367    </PickupRepresentation>
368    @endcode
369    Notice, that the type of pickup specified for the @ref orxonox::PickupRepresentation "PickupRepresentation", naturally, needs to be the same (this is the way they can be connected). Also, we just used an existing <em>spawnerTemplate</em>, to make things simpler.
370
371    The next step is to create a <em>spawnerRepresentation</em> uniquely for our new type of pickup. Lets call it <code>newhealthpickupRepresentation</code>. Thus the parameter <em>spawnerTemplate</em> of the @ref orxonox::PickupRepresentation "PickupRepresentation" has to be changed to that value.
372    @code
373    spawnerTemplate = "newhealthpickupRepresentation"
374    @endcode
375    The <em>spawnerTemplate</em> defines how the @ref orxonox::PickupSpawner "PickupSpawner" is displayed in a level.
376    In our example case it could look like this:
377    @code
378    <Template name=newhealthpickupRepresentation>
379        <PickupRepresentation>
380            <spawner-representation>
381                <StaticEntity>
382                    <attached>
383                        -- Here you can put all the objects which define the look of the spawner. --
384                    </attached>
385                </StaticEntity>
386            </spawner-representation>
387        </PickupRepresentation>
388    </Template>
389    @endcode
390    Please refer to the <code>pickupRepresentationTemplates.oxt</code> for more examples.
391
392    The @ref orxonox::PickupRepresentation "PickupRepresentation" also needs another parameter the <em>inventoryRepresentation</em>. This parameter defined how the @ref orxonox::Pickupable "Pickupable" is displayed in the PickupInventory (a menu to browse the currently equipped pickups).
393    @code
394    inventoryRepresentation = "MediumHealth"
395    @endcode
396    This is the name of an image defined in the PickupInventory imageset (<code>PickupInventory.imageset</code>), which can be found in <code>data_extern/gui/imagesets</code>.
397
398    This is all that has to be done. Now you have a new pickup type with an appropriate @ref orxonox::PickupRepresentation "PickupRepresentation" for your use. If you feel that your pickup is useful in general, please don't hesitate to create a template for the pickup and add your pickup to the <code>pickupRepresentationTemplates.oxt</code> file and the <code>pickups.oxi</code> file, so that anyone who wants to use it can do so quite easily.
399
400    There is also an additional way to create new types of pickups to be used in a level (without having to do any coding). There is a @ref orxonox::Pickupable "Pickupable" called the @ref orxonox::PickupCollection "PickupCollection", which is just a collection (hence the name) of @ref orxonox::Pickupable "Pickupables" (more precisely of @ref orxonox::CollectiblePickup "CollectiblePickups"), behaving as if it was just one @ref orxonox::Pickupable "Pickupable".
401    A @ref orxonox::PickupCollection "PickupCollection" can be created as follows:
402    @code
403    <PickupCollection>
404        <pickupables>
405            -- some pickups you want to have in your collection, e.g. --
406            <HealthPickup template=smallhealthpickup />
407            <HealthPickup health=50 healthRate=5 durationType=continuous activationType=immediate healthType=limited />
408        </pickupables>
409    </PickupCollection>
410    @endcode
411    Of which types of pickups a collection is made up is entirely up to the one creating the @ref orxonox::PickupCollection "PickupCollection", they can be mixed freely.
412
413    @section CreatingAPickup Creating a new pickup
414    Things have been fairly straightforward so far. Creating a @ref orxonox::Pickupable "Pickupable" form scratch isn't as easy. Therefore I'm just going to supply you with a recipe, or a set of steps you have to take, without which your pickup won't work and point out some common pitfalls.
415
416    @subsection CreatingAPickupClass Creating the class
417    For a new @ref orxonox::Pickupable "Pickupable" you need to create a new class in <code>>modules/pickup/items</code>. Your class needs to be derived from another pickup class, normally this would either be @ref orxonox::Pickupable "Pickupable", @ref orxonox::CollectiblePickup "CollectiblePickup" or @ref orxonox::Pickup "Pickup". @ref orxonox::Pickupable "Pickupable" is (as mentioned earlier) the base class of all things that can be picked up, thus of all pickups. @ref orxonox::CollectiblePickup "CollectiblePickup" is a (directly) derived class of @ref orxonox::Pickupable  "Pickupable" and provides the additional functionality of enabling your pickup to be used in a @ref orxonox::PickupCollection "PickupCollection". However you are probably going to want to derive your class form @ref orxonox::Pickup "Pickup", because it is a @ref orxonox::CollectiblePickup "CollectiblePickup" and provides some useful methods. So have a look at @ref orxonox::Pickup "Pickup".
418    Once you have created your new pickup class you have to insert it in the <code>PickupPrereqs.h</code> file in the <code>modules/pickup</code> folder and in the <code>CMakeList.txt</code> file in the <code>modules/pickup/items</code> folder. Also have a look at other pickups to make sure you include all the necessary files in your class.
419
420    @subsection ChoosingTheCarriers Coosing the carriers
421    You also have to choose the entities that are allowed to pick your pickup up. After you have chosen the entity that carries your pickup, you need to do the following.
422    - The enity that carries your pickup needs to be derived from the @ref orxonox::PickupCarrier "PickupCarrier" interface. And you need to implement the @ref orxonox::PickupCarrier "PickupCarriers'" virtual functions <code>getCarrierChildren()</code> and <code>getCarrierParent()</code>. These tow methods are needed, because all pickups are initially picked up by a @ref orxonox::Pawn "Pawn" and then handed down to the entity that effectively carries them. With the above mentioned two function just that is accomplished. A hierarchical structure is established with one parent and a set of children, where the @ref orxonox::Pawn "Pawn" is the root node of this hierarchical structure, the only entity with no parent.
423    - Once you have done that you will also want to specify in your pickup which carriers can pick it up, this is done via the <code>addTarget()</code> function. So you have to make sure the target is added whenever one of your pickups is created (so, most conveniently somewhere in the constructor), with the following command.
424    @code
425    this->addTarget(ClassIdentifier<MyCarrierClass>::getIdentifier());
426    @endcode
427
428    @subsection CreatingTheInnerWorkings Creating the inner workings of your pickup
429    Now that we have the skeleton of a pickup and we have defined which carriers are allowed to pick our pickup up we are going to take a look at all the methods we can (or sometimes have to) overload from @ref orxonox::Pickupable "Pickupable", for our pickup to work properly. But first I will introduce some more concepts to make the need for these methods more obvious.
430    - Since one pickup class can by itself be many pickup types, we need a way to find out whether a particular instance of a pickup is of the same type as another instance of a pickup. To that end the @ref orxonox::PickupIdentifier "PickupIdentifier" was created. The @ref orxonox::PickupIdentifier "PickupIdentifier" accounts for the type of class your pickup is of and also for the parameters (and their values) that distinguish different types of pickups of the same class. Much of the functionality of the pickup module relies on this identifier being correct, thus it is very important to initialize it correctly. (We will see, how that is done in a short while.)
431    - Every @ref orxonox::Pickupable "Pickupable" has at least two states which are very important. The first is, whether the @ref orxonox::Pickupable "Pickupable" is currently in use or not and the second is whether the pickup is currently picked up or not.
432
433    Let's have a look at the important methods.
434    - <b>changedUsed()</b> The <code>changedUsed()</code> method is called whenever the state of the @ref orxonox::Pickupable "Pickupable" transits from being used to not being used or the other way around. Which means this method is probably the most important method you have at your fingertips, since it enables you to apply the effect of your pickup when it gets used and remove the effect as soon as it is no longer in use.
435    - <b>changedPickedUp()</b> The <code>changedPickedUp()</code> method is called whenever the state of the @ref orxonox::Pickupable "Pickupable" changes from being picked up to not being picked up or the other way around. For example if you want your pickup to be used as soon as it is picked up, this is the method you have to overload to achieve that behavior (or just let your pickup be derived from @ref orxonox::Pickup "Pickup", which implements exactly that behavior, if the <em>activationType</em> is set to <em>immediate</em>). You don't have to concern yourself with destroying the pickup or creating a spawner when it changes to not picked up, since that is already implemented with the @ref orxonox::Pickupable "Pickupable" and @ref orxonox::PickupCarrier "PickupCarrier" classes. If you want a different behavior, however, once again, this is the method.
436    - <b>changedCarrier()</b> The <code>changedCarrier()</code> method is called whenever the carrier of the @ref orxonox::Pickupable "Pickupable" changes. And by that I don't mean the class that is allowed to carry the pickup, but the object that actually carries (or carried) the pickup. Please do not overload this class to implement behavior for picked up -> not picked up transitions, use <code>changedPickedUp()</code> for that. For most pickup classes this method doesn't need to be overloaded. Where it is used, however is in the @ref orxonox::PickupCollection "PickupCollection" class, where the new carrier needed to be communicated to all pickups the collection consists of, whenever the carrier was changed.
437
438    Please be aware, that these three methods are methods registered with @ref Super.h "Super", meaning, that whenever overloading them, don't forget to call <code>SUPER(MyClass, myMethod);</code>.
439    Also when implementing the above methods you should think of what should happen in unexpected situations, e.g. when your pickup is unused manually and set to used again.
440    Additionally you should use the <code>destroy()</code> method of Pickupable instead of the method provided by @ref orxonox::OrxonoxClass "OrxonoxClass", meaning <code>Pickupable::destroy()</code> instead of plain <code>destroy()</code>.
441
442    - <b>clone()</b> The <code>clone()</code> method creates a new pickup of the same type as the pickup it is cloned from. So the cloned pickup is not exactly the same, as it doesn't necessarily completely reflect the status of the pickup it is cloned from, but it reflects all the parameters and their values, that distinguish different types of this pickup class. It needs to be implemented by every pickup class. And it is best if this is done in a very specific way. Below is shown how:
443    @code
444    void MyPickup::clone(OrxonoxClass*& item)
445    {
446        if(item == NULL)
447            item = new MyPickup(this);
448
449        SUPER(MyPickup, clone, item);
450
451        MyPickup* pickup = dynamic_cast<MyPickup*>(item);
452        // Here you should set all the important parameters (that distinguish the different types of this pickup), e.g.
453        pickup->setSomeParameter(this->getSomeParameter());
454        // You must also initialize the identifier of the new pickup, this is normally done in a member function called in
455        pickup->initializeIdentifier();
456    }
457    @endcode
458    - <b>initializeIdentifier()</b> The <code>initializeIdentifier()</code> method initializes (or more simply put, creates) the @ref orxonox::PickupIdentifier "PickupIdentifier" of the instance of your pickup. Since the important values of the parameters are not yet available in the constructor of your pickup this <code>initializeIdentifier()</code> method must be called as soon as they are available, which normally is in the <code>XMLPort()</code> method, and the <code>clone()</code> method, as seen above. In the <code>initializeIdentifier()</code> method you need to register each parameter that is important for the type of your pickup to its identifier, this is normally done as follows:
459    @code
460    void Pickup::initializeIdentifier(void)
461    {
462        // If the get method returns a string.
463        std::string val1 = this->getSomeParameter();
464        std::string type1 = "someParameter";
465        this->pickupIdentifier_->addParameter(type1, val1);
466        // If the get method doesn't return a string
467        std::stringstream stream;
468        stream << this->getSomeOtherParameter();
469        std::string type2 = "someOtherParameter";
470        std::string val2 = stream.str();
471        this->pickupIdentifier_->addParameter(type2, val2);
472    }
473    @endcode
474
475    Be aware, this only works for parameters that are simple enough, meaning with pointers for example it will, naturally, not work, and other ways must be found (this is for example done in @ref orxonox::PickupCollection "PickupCollection" with a derived class of the @ref orxonox::PickupIdentifier "PickupIdentifier", the @ref orxonox::PickupCollectionIdentifier "PickupCollectionIdentifier") or in the @ref orxonox::DronePickup "DronePickup" class by using a @ref orxonox::Template "Template".
476    - <b>createSpawner()</b> The <code>createSpawner()</code> method needs to be implemented by any pickup directly inheriting from @ref orxonox::Pickupable "Pickupable" (or directly from @ref orxonox::CollectiblePickup "CollectiblePickup"), so if you inherit from @ref orxonox::Pickup "Pickup", you don't need to implement this. It is used to create a @ref orxonox::PickupSpawner "PickupSpawner", when the pickup is dropped. A standard implementation would look like this.
477    @code
478    bool MyPickup::createSpawner(void)
479    {
480        new DroppedPickup(this, this, this->getCarrier());
481        return true;
482    }
483    @endcode
484
485    @section PickupTechnicalDetails Technical details
486
487    @image html pickupmodule.png
488
489    @defgroup PickupItems Items
490    @ingroup Pickup
491
492    The actual pickups can be found here.
493*/
494
495/**
496    @defgroup Pong Pong
497    @ingroup Modules
498*/
499
500/**
501    @defgroup Questsystem Questsystem
502    @ingroup Modules
503
504    The Questsystem is a module that enhances Orxonox with @ref orxonox::Quest "Quests". @ref orxonox::Quest "Quests" are objects that challenge the player that receives such an object to fulfill some specific task (e.g. Rescue a princess, fetch some rare metal alloy, destroy the evil pirates den, ...). Upon having fulfilled that task the player can be rewarded with some kind of reward. Quests can be hierarchically structured, meaning that to fulfill some @ref orxonox::Quest "Quest" you first have to fulfill all (or some, depending on the quest) sub-quests.
505
506    @section QuestsystemTechnicalDetails Technical details
507    The Questsystem essentially consists of the @ref orxonox::Quest "Quest" entity which is the quest itself (and sub- or helper-entities, such as @ref orxonox::QuestHint "QuestHint" (hints for quests) or @ref orxonox::QuestDescription "QuestDescription" (descriptions for quests and hints, to separate content from function)), the @ref orxonox::QuestEffect "QuestEffect" and @ref orxonox::QuestListener "QuestListener" entities which are the only tools for quests to have any influence on the game world. By enabling quests to have @ref orxonox::QuestEffect "QuestEffects" they are able to (for example) fail or complete other quests, activate hints, give rewards or even add a quest to a player. @ref orxonox::QuestListener "QuestListeners" on the other hand can be used by any object to react to a status change of a quest. The @ref orxonox::QuestEffectBeacon "QuestEffectBeacon" is the physical entity which finally makes quests available for the player in the game, by being able to invoke a @ref orxonox::QuestEffect "QuestEffect" on a player (under some conditions).
508    @image html questsystem.png
509
510    @section CreatingQuests Creating Quests
511
512    @subsection CreatingTheQuestHierarchy Creating the Quest-Hierarchy
513    To start you have to create a Quest-Hierarchy in the XML-Levelfile by hierarchically nesting your quests. There are two types of Quests you can use, the LocalQuest and the GlobalQuest.
514
515    @subsubsection LocalQuest LocalQuest
516    A @ref orxonox::LocalQuest "LocalQuest" is a @ref orxonox::Quest "Quest" which has different states for each player, that means each @ref orxonox::LocalQuest "LocalQuest" can be obtained and completed (or failed) by each player in parallel. A questId is some string that uniquely identifies the quest, this can either be a name or, to ensure uniqueness, you can use a GUID generator (<a href="http://www.google.com/search?q=guid+generator">google</a> or you can use this <a href="http://www.famkruithof.net/uuid/uuidgen">generator</a>). The advantage of GUID is, that you can be quite sure that your id is unique, the drawback is, that it provides less overview and can be quite confusing when looking at the level file. So make your own choice.
517
518    Creating a @ref orxonox::LocalQuest "LocalQuest" in XML goes as follows:
519    @code
520    <LocalQuest id="questId">
521        <QuestDescription title="Title" description="Description." /> //The description of the quest.
522        <subquests>
523            <Quest id ="questId1" /> //A list of n subquest, be aware, each of the <Quest /> tags must have a description and so on and so forth as well.
524            ...
525            <Quest id="questIdn" />
526        </subquests>
527        <hints>
528            <QuestHint id="hintId1" /> //A list of n QuestHints, see QuestHint for the full XML representation of those.
529            ...
530            <QuestHint id="hintIdn" />
531        </hints>
532        <fail-effects>
533            <QuestEffect /> //A list of QuestEffects, invoked when the Quest is failed, see QuestEffect for the full XML representation.
534            ...
535            <QuestEffect />
536        </fail-effects>
537        <complete-effects>
538            <QuestEffect /> //A list of QuestEffects, invoked when the Quest is completed, see QuestEffect for the full XML representation.
539            ...
540            <QuestEffect />
541        </complete-effects>
542    </LocalQuest>
543    @endcode
544
545    @subsubsection GlobalQuest GlobalQuest
546    @ref orxonox::GlobalQuest "GlobalQuests" are different, they can be obtained by every player but the changes made to the @ref orxonox::Quest "Quest" (e.g. completion of the quest) affect all owners of the quest. A short example: There are 3 Players, A, B and C. Player A obtains the quest, a while later player B obtains the quest and completes it. Since it is a @ref orxonox::GlobalQuest "GlobalQuest" it is completed for all players having obtained the Quest which means it is also completed for player A. Player C though, never having obtained the quest, can now never complete it.
547
548    Creating a @ref orxonox::GlobalQuest "GlobalQuest" in XML goes as follows:
549    @code
550    <GlobalQuest id="questId">
551        <QuestDescription title="Title" description="Description." /> //The description of the quest.
552        <subquests>
553            <Quest id ="questId1" /> //A list of n subquest, be aware, each of the <Quest /> tags must have a description and so on and so forth as well.
554            ...
555            <Quest id="questIdn" />
556        </subquests>
557        <hints>
558            <QuestHint id="hintId1" /> //A list of n QuestHints, see QuestHint for the full XML representation of those.
559            ...
560            <QuestHint id="hintIdn" />
561        </hints>
562        <fail-effects>
563            <QuestEffect /> //A list of QuestEffects, invoked on all players possessing this quest, when the Quest is failed, see QuestEffect for the full XML representation.
564            ...
565            <QuestEffect />
566        </fail-effects>
567        <complete-effects>
568            <QuestEffect /> //A list of QuestEffects, invoked on all players possessing this quest, when the Quest is completed, see QuestEffect for the full XML representation.
569            ...
570            <QuestEffect />
571        </complete-effects>
572        <reward-effects>
573            <QuestEffect /> //A list of QuestEffects, invoked on the player completing this quest. See QuestEffect for the full XML representation.
574            ...
575            <QuestEffect />
576        </reward-effects>
577    </GlobalQuest>
578    @endcode
579
580    As you may see that another difference between a @ref orxonox::GlobalQuest "GlobalQuest" and a @ref orxonox::LocalQuest "LocalQuest" is, that with a @ref orxonox::GlobalQuest "GlobalQuest" having @ref orxonox::AddReward "RewardEffects", the RewardEffects are only executed on the player completing the quest. Additionally @ref orxonox::CompleteQuest "CompleteEffects" are executed on all players having obtained the quest before it was completed, when it is completed., while with a @ref orxonox::LocalQuest "LocalQuest" each player that completes a quest, completes it for himself alone, but also gets the reward, regardless whether another player completed the quest before him.
581
582    @subsubsection QuestHint QuestHint
583    @ref orxonox::QuestHint "QuestHints" can be used to give a player useful information for @ref orxonox::Quest "Quests" he is working on completing. @ref orxonox::QuestHint "QuestHints" cannot have any side effects, but also have an identifier which follows the same form as in the @ref orxonox::Quest "Quests".
584
585    Creating a @ref orxonox::QuestHint "QuestHint" in XML goes as follows:
586    @code
587    <QuestHint id="hintId">
588        <QuestDesctription title="" description="" />
589    </QuestHint>
590    @endcode
591
592    @subsubsection QuestDescription QuestDescription
593    Each @ref orxonox::Quest "Quest" (and also each @ref orxonox::QuestHint "QuestHint") must have a @ref orxonox::QuestDescription "QuestDescription" consisting of a title and description, and for @ref orxonox::Quest "Quests" also messages for the event the quest is either failed or completed. Of course these are (as is the title and the description) optional.
594
595    Creating a @ref orxonox::QuestDescription "QuestDescription" in XML goes as follows:
596    @code
597    <QuestDescription title="Title" description="Description Text" failMessage="You fail." completeMessage="You win!" />
598    @endcode
599
600    @subsection CreatingSideEffects Creating side effects
601    @ref orxonox::Quest "Quests" can have side effects, in fact that is mostly what they are about. This means that they can have an influence on the game world. @ref orxonox::Quest "Quests" do that through two distinct devices, @ref orxonox::QuestEffect "QuestEffects" (active) and @ref orxonox::QuestListener "QuestListeners" (passive).
602
603    @subsubsection QuestEffect QuestEffect
604    A @ref orxonox::QuestEffect "QuestEffect" is the first (and probably most important) device for @ref orxonox::Quest "Quests" to have side effects. There are two entities that can have @ref orxonox::QuestEffect "QuestEffects": @ref orxonox::Quest "Quests" and @ref orxonox::QuestEffectBeacon "QuestEffectBeacons" (which will be explained later on). @ref orxonox::QuestEffect "QuestEffects", for example, can start a @ref orxonox::Quest "Quest" for a player, complete/fail @ref orxonox::Quest "Quests" for a player, add a @ref orxonox::QuestHint "QuestHint" or a @ref orxonox::Rewardable "Reward" to a player, and potentially much, much more.
605
606    These @ref orxonox::QuestEffect "QuestEffects" are implemented so far, but feel free to <a href="http://www.orxonox.net/wiki/DamianFrick">contact me</a> if you have suggestions for new @ref orxonox::QuestEffect "QuestEffects" or if you need help implementing a new one yourself.
607
608    @paragraph AddQuest AddQuest
609    This @ref orxonox::QuestEffect "QuestEffect" adds (respectively starts) a @ref orxonox::Quest "Quest" (identified by the given questId) to the player.
610    @code
611    <AddQuest questId="id" />  //Where id identifies the Quest that should be added.
612    @endcode
613
614    @paragraph FailQuest FailQuest
615    This @ref orxonox::QuestEffect "QuestEffect" fails a @ref orxonox::Quest "Quest" (identified by the given questId) for the player.
616    @code
617    <FailQuest questId="id" />  //Where id identifies the Quest that should be added.
618    @endcode
619
620    @paragraph CompleteQuest CompleteQuest
621    This @ref orxonox::QuestEffect "QuestEffect" completes a @ref orxonox::Quest "Quest" (identified by the given questId) for the player.
622    @code
623    <CompleteQuest questId="id" />  //Where id identifies the Quest that should be added.
624    @endcode
625
626    @paragraph AddQuestHint AddQuestHint
627    This @ref orxonox::QuestEffect "QuestEffect" adds a @ref orxonox::QuestHint "QuestHint" to a @ref orxonox::Quest "Quest" (identified by the given questId) of a player.
628    @code
629    <AddQuestHint hintId="id" />  //Where id identifies the QuestHint that should be added.
630    @endcode
631
632    @paragraph AddReward AddReward
633    This @ref orxonox::QuestEffect "QuestEffect" adds a @ref orxonox::Rewardable "Rewardable" (@ref orxonox::Rewardable "Rewardable" is an Interface which can be implemented by an object that its creator thinks should be able to be rewarded a player for completing (or failing for that matter) a @ref orxonox::Quest "Quest") to the player. @ref Pickup Pickups for example wold be good @ref orxonox::Rewardable "Rewardables".
634    @code
635    <AddReward>
636        <Rewardable /> //A list of Rewardable objects to be rewarded the player, see the specific Rewardables for their respective XML representations.
637        ...
638        <Rewardable />
639    </AddReward>
640    @endcode
641
642    @subsubsection QuestListener QuestListener
643    The @ref orxonox::QuestListener "QuestListener" is the second device you can use to create side effects. As opposed to @ref orxonox::QuestEffect "QuestEffects" (that are executed (or invoked) either as a result of failing or completing a Quest or by a @ref orxonox::QuestEffectBeacon "QuestEffectBeacon"), @ref orxonox::QuestListener "QuestListeners" are passive, meaning that they relay information regarding status changes of @ref orxonox::Quest "Quests" rather than enforcing status changes. @ref orxonox::QuestListener "QuestListeners" have a certain mode (all, start, complete or fail) and a @ref orxonox::Quest "Quest" which they belong to (resp. to which they react). You then can use @ref orxonox::QuestListener "QuestListeners" to make basically any object aware of when the status of the given @ref orxonox::Quest "Quest" changes (the way you defined through the mode) and take any action you may think of.
644
645    Here is an example of the usage of @ref orxonox::QuestListener "QuestListeners" in XML:
646    @code
647    <BaseObject> // The object that should react to the status change of a Quest.
648        <events>
649            <function> // Where function is the method of the object that schould be executed. Normally this would be visibility or activity.
650                <QuestListener questId="someQuestId" mode="someMode" /> // Where someQuestId is the identifier for the Quest the QuestListener is reacting to, and someMode is the kind of status change the QUestListener reacts to (all, start, complete or fail).
651            </function>
652        </events>
653    </BaseObject>
654    @endcode
655
656    I hope this example has made the usage of @ref orxonox::QuestListener "QuestListeners" a little clearer. The @ref orxonox::QuestListener "QuestListener" actually reacts exactly as any @ref orxonox::Trigger "Trigger" or @ref orxonox::EventListener "EventListener" would (although the @ref orxonox::QuestListener "QuestListener" is really neighter the one nor the other) which means you can use it in exactly the same way you would use one of the above, it just reacts to a different thing. Namely to the change in a @ref orxonox::Quest "Quests" status.
657
658    @subsection PuttingTheQuestsInTheGameWorld Putting the Quests in the game world
659    As of now we know how to create @ref orxonox::Quest "Quests" and @ref orxonox::QuestHint "QuestHints", we have a way for quests to add new quests, or even complete/fail other quests. We also have a way of reacting to a status change in a @ref orxonox::Quest "Quest". In short we know how quests can be created, how they can influence other quests and how we can react to changes in quests. But our @ref orxonox::Quest "Quests" have no ties (well, not really at least) to the game world as of yet, meaning, that the game world cannot influence quests. For this we have @ref orxonox::QuestEffectBeacon "QuestEffectBeacons".
660
661    @subsubsection QuestEffectBeacon QuestEffectBeacon
662    The @ref orxonox::QuestEffectBeacon "QuestEffectBeacon" is a @ref orxonox::StaticEntity "StaticEntity" and has the ability to (when triggered trough some circumstance) invoke a specified list of @ref orxonox::QuestEffect "QuestEffects" on the player triggering the @ref orxonox::QuestEffectBeacon "QuestEffectBeacon".
663
664    Creating a @ref orxonox::QuestEffectBeacon "QuestEffectBeacon" in XML goes as follows:
665    @code
666    <QuestEffectBeacon times=n> //Where 'n' is either a number >= 0, which means the QuestEffectBeacon can be executed n times. Or n = -1, which means the QuestEffectBeacon can be executed an infinite number of times.
667        <effects>
668            <QuestEffect /> //A list of QuestEffects, invoked when the QuestEffectBeacon is executed, see QuestEffect for the full XML representation.
669            ...
670            <QuestEffect />
671        </effects>
672        <events>
673            <execute>
674                <EventListener event=eventIdString />
675            </execute>
676        </events>
677        <attached>
678            <PlayerTrigger name=eventIdString /> //A PlayerTrigger triggering the execution of the QuestEffectBeacon.
679        </attached>
680    </QuestEffectBeacon>
681    @endcode
682
683    The @ref orxonox::QuestEffectBeacon "QuestEffectBeacon" can only be executed a defined number of times (where -1 times stands for an infinite number of times) and the @ref orxonox::QuestEffect "QuestEffects" are invoked whenever the method 'execute' is called, which is (indirectly through an @ref orxonox::EventListener "EventListener", because I wanted to attach the @ref orxonox::PlayerTrigger "PlayerTrigger" so that its position is always relative to the @ref orxonox::QuestEffectBeacon "QuestEffectBeacons" position) done by the @ref orxonox::PlayerTrigger "PlayerTrigger".
684
685    A @ref orxonox::PlayerTrigger "PlayerTrigger" is a special sort of @ref orxonox::Trigger "Trigger" that knows the player that triggered it and therefore can be asked who that was. This allows the @ref orxonox::QuestEffect "QuestEffects" to be executed on the right player.
686
687    @section SampleQuest Sample quest
688    To get your head around all of this and see some of the things mentioned here in action you might want to check out the "The Tale of Princess Aeryn"-Quest (Levelfile: princessAeryn.oxw) in the level-folder.
689*/
690
691/**
692    @defgroup QuestEffects Effects
693    @ingroup Questsystem
694
695    A @ref orxonox::QuestEffect "QuestEffect" is a device for @ref orxonox::Quest "Quests" to have side effects. There are two entities that can have @ref orxonox::QuestEffect "QuestEffects": @ref orxonox::Quest "Quests" and \ref orxonox::QuestEffectBeacon "QuestEffectBeacons". @ref orxonox::QuestEffect "QuestEffects", for example, can start a @ref orxonox::Quest "Quest" for a player, complete/fail @ref orxonox::Quest "Quests" for a player, add a @ref orxonox::QuestHint "QuestHint" or a @ref orxonox::Rewardable "Reward" to a player, and potentially much, much more.
696*/
697
698/**
699    @defgroup Weapons Weapons
700    @ingroup Modules
701*/
Note: See TracBrowser for help on using the repository browser.