Changes between Version 8 and Version 9 of code/doc/Questsystem

Timestamp:

Dec 8, 2008, 2:53:12 PM (16 years ago)

Author:

dafrick

Comment:

—

code/doc/Questsystem

@@ -103 +103 @@
 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 ==
+==== QuestHint ====
 QuestHints can be used to give a player useful (or just funnily unuseful) information for Quests he is working on completing. The cannot have any sideeffects but also have an identifier which follows the same form as in the Quests.
 
@@ -112 +112 @@
     <QuestDesctription title="" description="" />
 </QuestHint>
-}}}}
-
-=== QuestDescription ===
+}}}
+
+==== 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.
 
@@ -122 +122 @@
 }}}
 
+=== Creating Sideeffects ===
+Quests can have sideeffects, 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) divice for Quests to have sideeffects. There are two entities that can have QuestEffects: Quests and QuestEffectBeacons (which will be explained later on).
+QuestEffects and 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 is a GUID, see http://en.wikipedia.org/wiki/Globally_Unique_Identifier#Basic_structure for more information, and 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 is a GUID, see http://en.wikipedia.org/wiki/Globally_Unique_Identifier#Basic_structure for more information, and 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 is a GUID, see http://en.wikipedia.org/wiki/Globally_Unique_Identifier#Basic_structure for more information, and 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 is a GUID, see http://en.wikipedia.org/wiki/Globally_Unique_Identifier#Basic_structure for more information, and identifies the QuestHint that should be added.
+}}}
+
+==== AddReward =====
+This QuestEffect adds a Rewardable (Rewardable is an Interface which can be implemented by and object that its creator thinks schould 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 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 sideeffects. 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 (allthough the QuestListener is really neighter the one nor the other) whcih 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 ina 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 theQuestEffects 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).