= QuestSystem =

== Author ==
[wiki:DamianFrick "Damian Frick"]

== Description ==
This project aims at implementing a system capable of handling quests.

== Status ==
The QuestSystem in itself is reasonably complete (though still extendable, but what project is ever complete? ;) ). But there are still some parts missing to make the QuestSystem a full feature of Orxonox:

* Integration for Network-Games. As of yet the QuestSystem can't be sent over a Network thus not yet enabling Multiplayer Quests.

== Classtree ==
[[Image(questsystem5.png)]] 

== More details ==
The project essentially consists of the Quest entity which is the quest itself (and sub- or helper-entities, such as QuestHint (hints for quests) or QuestDescription (descriptions for quests and hints, to separate content from function)) and the QuestEffect and QuestListener entities which are the only tools for quests to have any influence on the game world. By enabling quests to have QuestEffects their are able to (for example) fail or complete other quests, activate hints give rewards or even add a quest to a player. QuestListeners on the other hand can be used by any object to react to a status change of a Quest.
The QuestEffectBeacon is the physical entity which finally makes quests available for the player in the game, by being able to invoke a QuestEffect on a player (under some conditions).

== Creating Quests ==

=== Creating the Quest-Hierarchy ===
You firstly have to create a Quest-Hierarchy in the XML-Levelfile by nesting many quests.
There are two types of Quests you can use, the LocalQuest and the GlobalQuest.

==== LocalQuest ====
A LocalQuest is a Quest which has different states for each player, that means each 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 ([http://www.google.com/search?q=guid+generator google] or you can use this [http://www.famkruithof.net/uuid/uuidgen generator]. The advantage of GUID is, that you can be quite sure that your id is unique, the drawback is, that it provides less overview can can be quite confusing when looking at the level file.

Creating a LocalQuest in XML goes as follows:
{{{
<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>
}}}

==== GlobalQuest ====
GlobalQUests are different, they can be obtained by every player but the changes made to the Quest (i.e. completion of the Quest) affect all owners of the Quest. In short. 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 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 this Quest.

Creating a GlobalQuest in XML goes as follows:
{{{
<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>
}}}

As you may see, the difference between a GlobalQuest also lies in the fact of the GlobalQuest having RewardEffects. RewardEffects are only executed on the completing player, while CompleteEffects are executed on all player having obtained the Quest before it is completed, when it is completed.

==== QuestHint ====
QuestHints can be used to give a player useful information for Quests he is working on completing. The cannot have any side effects but also have an identifier which follows the same form as in the Quests.


Creating a QuestHint in XML goes as follows:
{{{
<QuestHint id="hintId">
    <QuestDesctription title="" description="" />
</QuestHint>
}}}

==== QuestDescription ====
Each Quest (and also each QuestHint) mus have a QuestDescription consisting of a title and description, and for 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 QuestDescription in XML goes as follows:
{{{
<QuestDescription title="Title" description="Description Text" failMessage="You fail." completeMessage="You win!" />
}}}

=== Creating side effects ===
Quests can have side effects, this means that they can have an influence on the game world. Quests can do that through two distinct devices, QuestEffects and QuestListeners (active and passive).

==== QuestEffect ====
A QuestEffect is the first (and probably most important) device for Quests to have side effects. There are two entities that can have QuestEffects: Quests and QuestEffectBeacons (which will be explained later on).
QuestEffects, for example, start a Quest for a player, complete/fail Quests for a player, add a QuestHint or a Reward to a player.

These QuestEffects are implemented so far, but feel free to [wiki:DamianFrick contact me] if you have suggestions for new QuestEffects or if you need help implementing a new one yourself.

===== AddQuest =====
This QuestEffect adds (respectively starts) a Quest (identified by the given questId) to the player.

{{{
<AddQuest questId="id" />  //Where id identifies the Quest that should be added.
}}}

===== FailQuest =====
This QuestEffect fails a Quest (identified by the given questId) for the player.

{{{
<FailQuest questId="id" />  //Where id identifies the Quest that should be added.
}}}

===== CompleteQuest =====
This QuestEffect completes a Quest (identified by the given questId) for the player.

{{{
<CompleteQuest questId="id" />  //Where id identifies the Quest that should be added.
}}}

===== AddQuestHint =====
This QuestEffect adds a QuestHint to a Quest (identified by the given questId) of a player.

{{{
<AddQuestHint hintId="id" />  //Where id identifies the QuestHint that should be added.
}}}

===== AddReward =====
This QuestEffect adds a 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 Quest) to the player. Pickups for example wold be good Rewardables (this is not yet implemented, though).

{{{
<AddReward>
    <Rewardable /> //A list of Rewardable objects to be rewarded the player, see the specific Rewardables for their respective XML representations.
    ...
    <Rewardable />
</AddReward>
}}}

==== QuestListener ====
The QuestListener is the second device you can use to create side effects. But other than QuestEffects (that are executed (or invoked) eighter as a result of failing or completing a Quest or by a QuestEffectBeacon) QuestListeners are passive. QuestListeners have a certain mode (all, start, complete or fail) and a Quest to which they belong to (resp. to which they react). You then can use QuestListeners to make basically any object aware of when the status of the given Quest changes (the way you defined through the mode) and take any action you may think of.

{{{
<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>
}}}

I hope this example has made the QuestListener a little clearer. The QuestListener actually reacts exactly as any Trigger or EventListener would (although the QuestListener is really neighter the one nor the other) which means you can use it in exactly the same as you would use one of the above, it just reacts to a different thing. Namely to the change in a Quests status.

=== Putting the Quests in the game world ===
As of now we have a way for Quests to initiate new Quests of even complete/fail other Quests. We also have a way of reacting to a status change in Quest. But our Quests have no bound (well, not really at least) to the game world as of yet. For this we have QuestEffectBeacons.

==== QuestEffectBeacon ====
The QuestEffectBeacon is a PositionableEntity (so you can position it anywhere in the game world) and it has the ability to (when triggered trough some circumstance) invoke a specified list of QuestEffects on the player triggering the QuestEffectBeacon.

Creating a QuestEffectBeacon in XML goes as follows:
{{{
<QuestEffectBeacon times=n> //Where 'n' is eighter 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>
}}}

The QuestEffectBeacon can only be executed a defined number of times (where -1 times stands for an infinite number of times) and the QuestEffects are invoked whenever the method 'execute' is called, which is (indirectly through an EventListener, because I wanted to attach the PlayerTrigger so that his position is always relative to the QuestEffectBeacons position) done by the PlayerTrigger.
A PlayerTrigger is a special sort of Trigger that knows the player that triggered the Trigger and therefore can be asked who triggered him and that way allows the QuestEffects to be executed on the right player. So far only DistanceTrigger is a PlayerTrigger and the target of the DistanceTrigger is a ControllableEntity (or an object that is derived form the ControllableEntity).

== Example 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 Princess Aeryn"-Quest (Levelfile: princessaeryn.oxw) in the level-folder of the media repository.