Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Changeset 7456 for code/trunk/doc/api


Ignore:
Timestamp:
Sep 15, 2010, 7:29:16 PM (14 years ago)
Author:
dafrick
Message:

Reviewing documentation fo Questsystem, moving documentation fully into doxygen.
Added some files to modules they belong to.

Location:
code/trunk/doc/api
Files:
1 added
1 edited

Legend:

Unmodified
Added
Removed

  • code/trunk/doc/api/Groups.dox

    r7401 r7456  
    2323 *      Fabian 'x3n' Landau
    2424 *   Co-authors:
    25  *      ...
     25 *      Damian 'Mozork' Frick
    2626 *
    2727 */
    … …  
    119119    @defgroup Notifications Notifications
    120120    @ingroup Modules
     121
     122    @defgroup NotificationDispatchers Dispatchers
     123    @ingroup Notifications
    121124*/
    122125
    … …  
    134137    @defgroup Pickup Pickup
    135138    @ingroup Modules
     139
     140    @defgroup PickupItems Items
     141    @ingroup Pickup
    136142*/
    137143
    … …  
    144150    @defgroup Questsystem Questsystem
    145151    @ingroup Modules
     152
     153    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.
     154
     155    @section TechnicalDetails Technical details
     156    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).
     157    @image html questsystem.png
     158
     159    @section CreatingQuests Creating Quests
     160
     161    @subsection CreatingTheQuestHierarchy Creating the Quest-Hierarchy
     162    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.
     163
     164    @subsubsection LocalQuest LocalQuest
     165    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.
     166
     167    Creating a @ref orxonox::LocalQuest "LocalQuest" in XML goes as follows:
     168    @code
     169    <LocalQuest id="questId">
     170        <QuestDescription title="Title" description="Description." /> //The description of the quest.
     171        <subquests>
     172            <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.
     173            ...
     174            <Quest id="questIdn" />
     175        </subquests>
     176        <hints>
     177            <QuestHint id="hintId1" /> //A list of n QuestHints, see QuestHint for the full XML representation of those.
     178            ...
     179            <QuestHint id="hintIdn" />
     180        </hints>
     181        <fail-effects>
     182            <QuestEffect /> //A list of QuestEffects, invoked when the Quest is failed, see QuestEffect for the full XML representation.
     183            ...
     184            <QuestEffect />
     185        </fail-effects>
     186        <complete-effects>
     187            <QuestEffect /> //A list of QuestEffects, invoked when the Quest is completed, see QuestEffect for the full XML representation.
     188            ...
     189            <QuestEffect />
     190        </complete-effects>
     191    </LocalQuest>
     192    @endcode
     193
     194    @subsubsection GlobalQuest GlobalQuest
     195    @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.
     196
     197    Creating a @ref orxonox::GlobalQuest "GlobalQuest" in XML goes as follows:
     198    @code
     199    <GlobalQuest id="questId">
     200        <QuestDescription title="Title" description="Description." /> //The description of the quest.
     201        <subquests>
     202            <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.
     203            ...
     204            <Quest id="questIdn" />
     205        </subquests>
     206        <hints>
     207            <QuestHint id="hintId1" /> //A list of n QuestHints, see QuestHint for the full XML representation of those.
     208            ...
     209            <QuestHint id="hintIdn" />
     210        </hints>
     211        <fail-effects>
     212            <QuestEffect /> //A list of QuestEffects, invoked on all players possessing this quest, when the Quest is failed, see QuestEffect for the full XML representation.
     213            ...
     214            <QuestEffect />
     215        </fail-effects>
     216        <complete-effects>
     217            <QuestEffect /> //A list of QuestEffects, invoked on all players possessing this quest, when the Quest is completed, see QuestEffect for the full XML representation.
     218            ...
     219            <QuestEffect />
     220        </complete-effects>
     221        <reward-effects>
     222            <QuestEffect /> //A list of QuestEffects, invoked on the player completing this quest. See QuestEffect for the full XML representation.
     223            ...
     224            <QuestEffect />
     225        </reward-effects>
     226    </GlobalQuest>
     227    @endcode
     228
     229    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.
     230
     231    @subsubsection QuestHint QuestHint
     232    @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".
     233
     234    Creating a @ref orxonox::QuestHint "QuestHint" in XML goes as follows:
     235    @code
     236    <QuestHint id="hintId">
     237        <QuestDesctription title="" description="" />
     238    </QuestHint>
     239    @endcode
     240
     241    @subsubsection QuestDescription QuestDescription
     242    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.
     243
     244    Creating a @ref orxonox::QuestDescription "QuestDescription" in XML goes as follows:
     245    @code
     246    <QuestDescription title="Title" description="Description Text" failMessage="You fail." completeMessage="You win!" />
     247    @endcode
     248
     249    @subsection CreatingSideEffects Creating side effects
     250    @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).
     251
     252    @subsubsection QuestEffect QuestEffect
     253    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.
     254
     255    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.
     256
     257    @paragraph AddQuest AddQuest
     258    This @ref orxonox::QuestEffect "QuestEffect" adds (respectively starts) a @ref orxonox::Quest "Quest" (identified by the given questId) to the player.
     259    @code
     260    <AddQuest questId="id" />  //Where id identifies the Quest that should be added.
     261    @endcode
     262
     263    @paragraph FailQuest FailQuest
     264    This @ref orxonox::QuestEffect "QuestEffect" fails a @ref orxonox::Quest "Quest" (identified by the given questId) for the player.
     265    @code
     266    <FailQuest questId="id" />  //Where id identifies the Quest that should be added.
     267    @endcode
     268
     269    @paragraph CompleteQuest CompleteQuest
     270    This @ref orxonox::QuestEffect "QuestEffect" completes a @ref orxonox::Quest "Quest" (identified by the given questId) for the player.
     271    @code
     272    <CompleteQuest questId="id" />  //Where id identifies the Quest that should be added.
     273    @endcode
     274
     275    @paragraph AddQuestHint AddQuestHint
     276    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.
     277    @code
     278    <AddQuestHint hintId="id" />  //Where id identifies the QuestHint that should be added.
     279    @endcode
     280
     281    @paragraph AddReward AddReward
     282    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".
     283    @code
     284    <AddReward>
     285        <Rewardable /> //A list of Rewardable objects to be rewarded the player, see the specific Rewardables for their respective XML representations.
     286        ...
     287        <Rewardable />
     288    </AddReward>
     289    @endcode
     290
     291    @subsubsection QuestListener QuestListener
     292    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.
     293
     294    Here is an example of the usage of @ref orxonox::QuestListener "QuestListeners" in XML:
     295    @code
     296    <BaseObject> // The object that should react to the status change of a Quest.
     297        <events>
     298            <function> // Where function is the method of the object that schould be executed. Normally this would be visibility or activity.
     299                <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).
     300            </function>
     301        </events>
     302    </BaseObject>
     303    @endcode
     304
     305    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.
     306
     307    @subsection PuttingTheQuestsInTheGameWorld Putting the Quests in the game world
     308    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".
     309
     310    @subsubsection QuestEffectBeacon QuestEffectBeacon
     311    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".
     312
     313    Creating a @ref orxonox::QuestEffectBeacon "QuestEffectBeacon" in XML goes as follows:
     314    @code
     315    <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.
     316        <effects>
     317            <QuestEffect /> //A list of QuestEffects, invoked when the QuestEffectBeacon is executed, see QuestEffect for the full XML representation.
     318            ...
     319            <QuestEffect />
     320        </effects>
     321        <events>
     322            <execute>
     323                <EventListener event=eventIdString />
     324            </execute>
     325        </events>
     326        <attached>
     327            <PlayerTrigger name=eventIdString /> //A PlayerTrigger triggering the execution of the QuestEffectBeacon.
     328        </attached>
     329    </QuestEffectBeacon>
     330    @endcode
     331
     332    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".
     333
     334    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.
     335
     336    @section SampleQuest Sample quest
     337    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.
     338
     339    @defgroup QuestEffects Effects
     340    @ingroup Questsystem
     341
     342    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.
    146343*/
    147344
Note: See TracChangeset for help on using the changeset viewer.