source: code/trunk/doc/api/Groups.dox @ 7456

/*
 *   ORXONOX - the hottest 3D action shooter ever to exist
 *                    > www.orxonox.net <
 *
 *
 *   License notice:
 *
 *   This program is free software; you can redistribute it and/or
 *   modify it under the terms of the GNU General Public License
 *   as published by the Free Software Foundation; either version 2
 *   of the License, or (at your option) any later version.
 *
 *   This program is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU General Public License for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with this program; if not, write to the Free Software
 *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 *
 *   Author:
 *      Fabian 'x3n' Landau
 *   Co-authors:
 *      Damian 'Mozork' Frick
 *
 */

/**
    @defgroup Util Util

    The util library contains several functions, classes, and templates that can be used in different
    parts of the Orxonox-code. They provide functionalities for mathematical use, string manipulation,
    typeconversion, multi-types, error- and exception-handling, debug output, and many more.
*/

/**
    @defgroup Core Core

    The core library contains the framework of Orxonox - all important classes, functions, and macros
    that are used to create and manage classes and objects. Almost all classes in Orxonox need at least
    one of the core features.
*/

/**
    @defgroup Class Class management
    @ingroup Core
*/

/**
    @defgroup Object Object management
    @ingroup Core
*/

/**
    @defgroup Command Command
    @ingroup Core
*/

/**
    @defgroup Config Config
    @ingroup Core
*/

/**
    @defgroup Input Input
    @ingroup Core
*/

/**
    @defgroup Management Management
    @ingroup Core
*/

/**
    @defgroup XML XML
    @ingroup Core
*/

/**
    @defgroup Network Network

    The network library is used to connect clients and server, to synchronize objects and variables, and
    to transmit network function calls. It contains the central @ref orxonox::Server "Server" and
    @ref orxonox::Client "Client" classes as well as several functions and macros for
    @ref orxonox::Synchronisable "synchronisable" classes.
*/

/**
    @defgroup Tools Tools

    The tools are a bunch of utilities that belong to the Orxonox library, but are independent of other
    features.
*/

/**
    @defgroup Orxonox Orxonox

    The Orxonox library contains the central and most important classes of the game. Managers, interfaces,
    base-classes, and more are located in Orxonox. More specialized classes that inherit of the base-classes
    in Orxonox are often sourced out to the modules.
*/

/**
    @defgroup Modules Modules

    The modules are libraries that depend on the Orxonox library and that are loaded dynamically on runtime
    (in contrast to statically loaded libraries like util and core). Each module contains some classes that
    are usually connected to each other, but they are independent of other modules. However modules can still
    link to other modules, but only in a hierarchical order, no circular dependencies.
*/

/**
    @defgroup Designtools Designtools
    @ingroup Modules
*/

/**
    @defgroup Notifications Notifications
    @ingroup Modules

    @defgroup NotificationDispatchers Dispatchers
    @ingroup Notifications
*/

/**
    @defgroup Objects Objects
    @ingroup Modules
*/

/**
    @defgroup Overlays Overlays
    @ingroup Modules
*/

/**
    @defgroup Pickup Pickup
    @ingroup Modules

    @defgroup PickupItems Items
    @ingroup Pickup
*/

/**
    @defgroup Pong Pong
    @ingroup Modules
*/

/**
    @defgroup Questsystem Questsystem
    @ingroup Modules

    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.

    @section TechnicalDetails Technical details
    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).
    @image html questsystem.png

    @section CreatingQuests Creating Quests

    @subsection CreatingTheQuestHierarchy Creating the Quest-Hierarchy
    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.

    @subsubsection LocalQuest LocalQuest
    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.

    Creating a @ref orxonox::LocalQuest "LocalQuest" in XML goes as follows:
    @code
    <LocalQuest id="questId">
        <QuestDescription title="Title" description="Description." /> //The description of the quest.
        <subquests>
            <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.
            ...
            <Quest id="questIdn" />
        </subquests>
        <hints>
            <QuestHint id="hintId1" /> //A list of n QuestHints, see QuestHint for the full XML representation of those.
            ...
            <QuestHint id="hintIdn" />
        </hints>
        <fail-effects>
            <QuestEffect /> //A list of QuestEffects, invoked when the Quest is failed, see QuestEffect for the full XML representation.
            ...
            <QuestEffect />
        </fail-effects>
        <complete-effects>
            <QuestEffect /> //A list of QuestEffects, invoked when the Quest is completed, see QuestEffect for the full XML representation.
            ...
            <QuestEffect />
        </complete-effects>
    </LocalQuest>
    @endcode

    @subsubsection GlobalQuest GlobalQuest
    @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.

    Creating a @ref orxonox::GlobalQuest "GlobalQuest" in XML goes as follows:
    @code
    <GlobalQuest id="questId">
        <QuestDescription title="Title" description="Description." /> //The description of the quest.
        <subquests>
            <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.
            ...
            <Quest id="questIdn" />
        </subquests>
        <hints>
            <QuestHint id="hintId1" /> //A list of n QuestHints, see QuestHint for the full XML representation of those.
            ...
            <QuestHint id="hintIdn" />
        </hints>
        <fail-effects>
            <QuestEffect /> //A list of QuestEffects, invoked on all players possessing this quest, when the Quest is failed, see QuestEffect for the full XML representation.
            ...
            <QuestEffect />
        </fail-effects>
        <complete-effects>
            <QuestEffect /> //A list of QuestEffects, invoked on all players possessing this quest, when the Quest is completed, see QuestEffect for the full XML representation.
            ...
            <QuestEffect />
        </complete-effects>
        <reward-effects>
            <QuestEffect /> //A list of QuestEffects, invoked on the player completing this quest. See QuestEffect for the full XML representation.
            ...
            <QuestEffect />
        </reward-effects>
    </GlobalQuest>
    @endcode

    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.

    @subsubsection QuestHint QuestHint
    @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".

    Creating a @ref orxonox::QuestHint "QuestHint" in XML goes as follows:
    @code
    <QuestHint id="hintId">
        <QuestDesctription title="" description="" />
    </QuestHint>
    @endcode

    @subsubsection QuestDescription QuestDescription
    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.

    Creating a @ref orxonox::QuestDescription "QuestDescription" in XML goes as follows:
    @code
    <QuestDescription title="Title" description="Description Text" failMessage="You fail." completeMessage="You win!" />
    @endcode

    @subsection CreatingSideEffects Creating side effects
    @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).

    @subsubsection QuestEffect QuestEffect
    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.

    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.

    @paragraph AddQuest AddQuest
    This @ref orxonox::QuestEffect "QuestEffect" adds (respectively starts) a @ref orxonox::Quest "Quest" (identified by the given questId) to the player.
    @code
    <AddQuest questId="id" />  //Where id identifies the Quest that should be added.
    @endcode

    @paragraph FailQuest FailQuest
    This @ref orxonox::QuestEffect "QuestEffect" fails a @ref orxonox::Quest "Quest" (identified by the given questId) for the player.
    @code
    <FailQuest questId="id" />  //Where id identifies the Quest that should be added.
    @endcode

    @paragraph CompleteQuest CompleteQuest
    This @ref orxonox::QuestEffect "QuestEffect" completes a @ref orxonox::Quest "Quest" (identified by the given questId) for the player.
    @code
    <CompleteQuest questId="id" />  //Where id identifies the Quest that should be added.
    @endcode

    @paragraph AddQuestHint AddQuestHint
    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.
    @code
    <AddQuestHint hintId="id" />  //Where id identifies the QuestHint that should be added.
    @endcode

    @paragraph AddReward AddReward
    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".
    @code
    <AddReward>
        <Rewardable /> //A list of Rewardable objects to be rewarded the player, see the specific Rewardables for their respective XML representations.
        ...
        <Rewardable />
    </AddReward>
    @endcode

    @subsubsection QuestListener QuestListener
    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.

    Here is an example of the usage of @ref orxonox::QuestListener "QuestListeners" in XML:
    @code
    <BaseObject> // The object that should react to the status change of a Quest.
        <events>
            <function> // Where function is the method of the object that schould be executed. Normally this would be visibility or activity.
                <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).
            </function>
        </events>
    </BaseObject>
    @endcode

    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.

    @subsection PuttingTheQuestsInTheGameWorld Putting the Quests in the game world
    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".

    @subsubsection QuestEffectBeacon QuestEffectBeacon
    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".

    Creating a @ref orxonox::QuestEffectBeacon "QuestEffectBeacon" in XML goes as follows:
    @code
    <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.
        <effects>
            <QuestEffect /> //A list of QuestEffects, invoked when the QuestEffectBeacon is executed, see QuestEffect for the full XML representation.
            ...
            <QuestEffect />
        </effects>
        <events>
            <execute>
                <EventListener event=eventIdString />
            </execute>
        </events>
        <attached>
            <PlayerTrigger name=eventIdString /> //A PlayerTrigger triggering the execution of the QuestEffectBeacon.
        </attached>
    </QuestEffectBeacon>
    @endcode

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

    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.

    @section SampleQuest Sample quest
    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.

    @defgroup QuestEffects Effects
    @ingroup Questsystem

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

/**
    @defgroup Weapons Weapons
    @ingroup Modules
*/