1 // Copyright (C) 2003, 2004, 2005, 2006 Ulf Lorenz
2 // Copyright (C) 2004 Andrea Paternesi
3 // Copyright (C) 2007, 2008, 2009 Ben Asselstine
5 // This program is free software; you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation; either version 3 of the License, or
8 // (at your option) any later version.
10 // This program is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 // GNU Library General Public License for more details.
15 // You should have received a copy of the GNU General Public License
16 // along with this program; if not, write to the Free Software
17 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
26 #include "xmlhelper.h"
28 #include "callback-enums.h"
35 //! Base class for Quest objects.
37 * Quest objects are started by Hero objects by visiting a Temple object. The
38 * Quest has a given Quest::Type. If the Hero can successfully complete the
39 * terms of the Quest, a Reward is given. If the Hero cannot complete the
40 * Quest, because of death or because the Quest is now simply impossible, the
43 * This class adds some basic functionality for quests, mainly code concerning
46 * This object and the classes that derive from it equate to the
47 * lordsawar.questlist.quest XML entity in the saved-game file.
50 class Quest: public OwnerId
53 //! The xml tag of this object in a saved-game file.
54 static std::string d_tag;
56 //! The various kinds of Quest objects.
58 //! Find another Player's Hero and kill it.
60 //! Seek and destroy a number of another Player's armies.
62 //! Conquer and sack another Player's city.
64 //! Conquer and raze another Player's city.
66 //! Conquer and occupy another Player's city.
68 //! Find an army of the given kind and kill it.
70 //! Sack and pillage a number of gold pieces from enemies.
74 //! Standard constructor.
76 * Make a new Quest object. This object is not called directly -- it
77 * is only called by the derived classes.
79 * @param q_mgr The quest manager this quest is being associated with.
80 * @param hero The Id of the Hero object that owns this quest.
81 * @param type The type of Quest the Hero is going on.
83 Quest(QuestsManager& q_mgr, guint32 hero, Type type);
85 //! Loading constructor.
87 * Make a new quest by loading it in from an opened saved-game file.
88 * @note This only reads the data that is common to all quests.
90 * @param q_mgr The quest manager to associate the new Quest with.
91 * @param helper The opened saved-game file to load the Quest from.
93 Quest(QuestsManager& q_mgr, XML_Helper* helper);
100 //! Return the description of the Quest.
102 * This is the 'static' part of the quest description,
103 * set once the quest has been initialized. Another,
104 * dynamic part consists of the quest's status info,
105 * which is obtained by the Quest::getProgress method.
107 std::string getDescription() const { return d_description; }
109 //! Returns if the Quest will be deleted at the end of the round.
110 bool isPendingDeletion() const {return d_pending;}
112 //! Return the Id of the Hero object responsible for this Quest object.
113 guint32 getHeroId() const { return d_hero; }
115 //! Returns the name of the Hero responsible for this Quest.
116 std::string getHeroName() const {return d_hero_name;}
118 //! Return the type of the quest (one of values listed in Quest::Type).
119 guint32 getType() const { return d_type; }
121 //! Return the targets for this Quest.
123 * This method provides a list of positions that the hero is seeking.
124 * This method is called by the questmap object to assist in showing
125 * the quest on a map.
126 * Quest::PILLAGEGOLD does not have any targets.
128 * @return A list of positions on the map that the Hero is seeking.
130 std::list< Vector<int> > getTargets() const {return d_targets;}
135 //! Set the Quest as not mattering anymore.
136 void deactivate() {d_pending = true;}
139 // Methods that operate on the class data but do not modify the class.
141 //! Return a pointer to the Hero object responsible for the Quest.
142 Hero* getHero() const { return getHeroById(d_hero); }
144 //! Determine the name of the hero, even if it's dead.
145 std::string getHeroNameForDeadHero() const;
147 //! Save the Quest to an opened saved-game file.
149 * @note This function is called by the actual quests and only saves
150 * the common data. It does NOT open/close tags etc. This has to be
151 * done by the derived classes.
153 * @param helper The opened saved-game file to save the common Quest
156 virtual bool save(XML_Helper* helper) const;
159 // Methods that need to be implemented by derived classes.
161 //! Return the description of the progress the Hero has made.
162 virtual std::string getProgress() const = 0;
164 //! Return the completion text that is associated with this Quest.
166 * @param msgs A queue of strings that represents the completion
169 virtual void getSuccessMsg(std::queue<std::string>& msgs) const = 0;
172 * \brief Provide the lines of the message describing
173 the quest completion.
175 //! Return the text that is shown when the Quest has expired.
177 * @param msgs A queue of strings that represents the text to show
178 * when the Quest has expired.
180 virtual void getExpiredMsg(std::queue<std::string>& msgs) const = 0;
182 //! Callback whenever an Army dies.
184 * This method notifies the Quest that an army has died, and if the u
185 * hero responsible for this quest killed it or not.
187 * @param army An Army object that has just died in the game.
188 * @param heroIsCulprit Whether or not the Hero object associated with
189 * this Quest object is responsible for killing
190 * the given Army object.
192 virtual void armyDied(Army *army, bool heroIsCulprit)=0;
194 //! Callback whenever a city has been conquered.
196 * This method notifies the Quest that a City has fallen, and what the
197 * conquering action (pillage/sack/raze/occupy) was. It also notifies
198 * whether or not the hero responsible for this quest was involved in
199 * the conquering, and how much gold was taken as a result.
201 * @param city The City object that has been conquered.
202 * @param action What action was taken by the Player. See
203 * CityDefeatedAction for more information.
204 * @param heroIsCulprit Whether or not the Hero object associated with
205 * this Quest object is responsible for
206 * conquering the given City object.
207 * @param gold How many gold pieces were taken as a result
210 virtual void cityAction(City *city, CityDefeatedAction action,
211 bool heroIsCulprit, int gold)=0;
216 //! Determine the name of a hero, given the id.
217 static std::string getHeroNameForDeadHero(guint32 id);
219 //! Convert a Quest::Type string to an enumerated value.
220 static Quest::Type questTypeFromString(std::string str);
222 //! Convert a Quest::Type enumerated value to a string.
223 static std::string questTypeToString(const Quest::Type type);
225 //! Return the Stack and Hero of a Quest.
227 * @param hero The id of the Hero on this quest.
228 * @param stack This pointer is filled with a pointer to the stack
229 * that the Hero is in. If passed as NULL, it is not
232 * @return A pointer to the Hero object or NULL if the Hero is dead.
234 static Hero* getHeroById(guint32 hero, Stack** stack = NULL);
239 //! The QuestsManager object that this Quest object is associated with.
240 QuestsManager& d_q_mgr;
242 //! A description of the Quest (this text does not change).
244 * This value is to be filled by the derived quest objects.
246 std::string d_description;
248 //! The Id of the Hero object responsible for this Quest.
251 //! The type of the Quest (one of Quest::Type).
254 //! If set to false, this quest is deactivated and not to be processed.
257 //! The name of the hero who is on the Quest.
259 * The name of the Hero must be saved so that after the Hero dies, we
260 * can submit a history item that references the Hero's name.
262 std::string d_hero_name;
264 //! A list of targets to display on a questmap.
266 * The derived Quest classes fill in this value.
268 std::list< Vector<int> > d_targets;