1 // Copyright (C) 2007, 2008, 2009 Ben Asselstine
3 // This program is free software; you can redistribute it and/or modify
4 // it under the terms of the GNU General Public License as published by
5 // the Free Software Foundation; either version 3 of the License, or
6 // (at your option) any later version.
8 // This program is distributed in the hope that it will be useful,
9 // but WITHOUT ANY WARRANTY; without even the implied warranty of
10 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 // GNU Library General Public License for more details.
13 // You should have received a copy of the GNU General Public License
14 // along with this program; if not, write to the Free Software
15 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
35 //! A little something nice for the Player.
37 * Reward objects are given to the Player upon completion of a difficult
38 * task. Rewards are awarded when a ruin is successfully searched, or when a
39 * Hero completes a Quest, or visits a sage.
41 * Rewards come in 5 flavours (Reward::Type): an amount of gold pieces, a
42 * number of powerful allies, a useful item, a map that exposes part of a
43 * hidden map when playing with fog-of-war, and also a hidden ruin that only
44 * that Player who is awarded the Reward can search.
46 * This is the base class for each of the different kinds of rewards. It
47 * holds the kind of reward and the name of the reward.
54 //! The xml tag of this object in a saved-game file.
55 static std::string d_tag;
57 //! The different kinds of Reward objects.
59 //! A number of gold pieces.
61 //! A number of powerful allies.
65 //! A hidden ruin that only the rewarded Player can see.
67 //! A portion of the hidden map to expose to the rewarded player.
71 //! Default constructor.
73 * Make a new constructor of the given type and name.
75 * @param type The kind of reward.
76 * @param name The name of the reward.
78 * @note This constructor is only used in the constructors of other
79 * Reward objects, and shouldn't be called directly.
81 Reward(Type type, std::string name = "");
83 //! Loading constructor.
85 * Make a new Reward by reading it in from the opened saved-game file.
87 * @param helper The opened saved-game file to read the Reward from.
89 * @note This constructor is only used within the constructors of
90 * other Reward objects, and shouldn't be called directly.
91 * It only loads the parts common to all Reward objects.
93 Reward(XML_Helper* helper);
97 * Make a new Reward by copying it from another Reward object.
99 * @param orig The Reward object to copy it from.
101 * @note This constructor is only used within the constructors of
102 * other Reward objects, and shouldn't be called directly.
103 * It only copies the parts common to all Reward objects.
105 Reward (const Reward& orig);
113 //! Get the type of the reward.
114 Type getType() const { return d_type; }
116 //! Returns the name of the reward.
117 std::string getName() const {return d_name;}
122 //! Sets the name of the reward.
123 void setName(std::string name) {d_name = name;}
126 // Methods that operate on the class data but do not modify the class.
128 //! Generates a description of this reward.
130 * This method inspects the underlying reward and generates an
131 * appropriate description.
133 std::string getDescription() const;
135 //! Saves the data elements common to all rewards.
137 * @note This function is called by the actual reward and only saves
138 * the common data. It does NOT open/close tags etc. This has to be
139 * done by the derived classes.
141 * @param helper The opened saved-game file to save the Reward object
144 virtual bool save(XML_Helper* helper) const = 0;
149 //! Assist in the loading of Rewards of all kinds.
151 * Whenever an reward item is loaded, this function is called. It
152 * examines the stored id and calls the constructor of the appropriate
155 * @param helper The opened saved-game file to load the Reward from.
157 static Reward* handle_load(XML_Helper* helper);
159 //! Convert a Reward::Type enumerated value to a string.
160 static std::string rewardTypeToString(const Reward::Type type);
162 //! Convert a Reward::Type string to an enumerated value.
163 static Reward::Type rewardTypeFromString(const std::string str);
165 //! deep copy a reward into another one
166 static Reward* copy(const Reward* r);
172 //! Type of the reward.
175 //! The name of the reward.
180 //! A Reward of some gold pieces.
182 * Gold pieces are added to the Player's treasury.
184 class Reward_Gold : public Reward
187 //! Default constructor.
189 * @param gold The number of gold pieces to award the Player.
191 Reward_Gold(guint32 gold);
193 //! Loading constructor.
194 Reward_Gold(XML_Helper *helper);
196 //! Copy constructor.
197 Reward_Gold(const Reward_Gold& orig);
204 //! Return the number of gold pieces associated with this reward.
205 guint32 getGold() const {return d_gold;}
208 // Methods that operate on the class data but do not modify the class.
210 //! Save the gold reward to the opened saved-game file.
211 bool save(XML_Helper* helper) const;
216 //! Return a random number of gold pieces.
218 * This method provides a random number of gold pieces suitable for a
219 * reward in the game.
221 static guint32 getRandomGoldPieces();
226 //! The number of gold pieces to award the player.
230 //! A number of powerful allies.
232 * Up to 8 allies are awarded to the Player's stack being given the Reward.
233 * Allies are Army prototypes that have `Awardable' ability set.
235 class Reward_Allies: public Reward
238 //! Default constructor. Make a new reward of allies.
240 * @param army The Army prototype to create allies from.
241 * @param count The number of Army units to create from the prototype.
243 Reward_Allies(const ArmyProto *army, guint32 count);
245 //! Alternative constructor. Make a new reward of allies.
247 * @param army_type The Id of the Army prototype to create allies from.
248 * @param army_set The Id of the Armyset that the type belongs to.
249 * @param count The number of Armies to create from the prototype.
251 Reward_Allies(guint32 army_type, guint32 army_set, guint32 count);
253 //! Make a new reward of allies from another one.
254 Reward_Allies(const Reward_Allies& orig);
256 //! Loading constructor. Load the allies reward from a saved-game file.
257 Reward_Allies(XML_Helper *helper);
264 //! Return the army prototype of the allies associated with this reward.
265 const ArmyProto * getArmy() const {return d_army;}
267 //! Return the number allies that this reward will create.
268 guint32 getNoOfAllies() const {return d_count;}
271 // Methods that operate on the class data and do not modify the class.
273 //! Save the allies reward to the opened saved-game file.
274 bool save(XML_Helper* helper) const;
279 //! A static method that returns a random awardable Army prototype.
280 static const ArmyProto* randomArmyAlly();
282 //! A static method that returns a number of allies between 1 and 8.
283 static const guint32 getRandomAmountOfAllies();
285 //! A static method for adding allies to the game map.
287 * Place the given number of the given allies onto the map at the given
290 * @param p The player to make the new stack for, if the
291 * stack can't take all of the allies.
292 * @param pos The place on the map to add the allies.
293 * @param army The Army prototype that defines the allies.
294 * @param alliesCount The number of allies to add.
296 * @return True if the armies could successfully be added to the game
297 * map. Returns false otherwise.
299 static bool addAllies(Player *p, Vector<int> pos, const ArmyProto *army, guint32 alliesCount);
301 //! A static method for adding allies to the game map.
303 * Place the given number of the given allies onto the map at the given
306 * @param p The player to make the new stack for, if the
307 * stack can't take all of the allies.
308 * @param loc The place on the map to add the allies.
309 * @param army The Army prototype that defines the allies.
310 * @param alliesCount The number of allies to add.
312 * @note This method tries to add the armies to the various tiles of
313 * the location first, before placing it outside of the location.
315 * @return True if the armies could successfully be added to the game
316 * map. Returns false otherwise.
318 static bool addAllies(Player *p, Location *l, const Army *army, guint32 alliesCount);
323 //! The Army prototype that represents the allies to give the Player.
324 const ArmyProto *d_army;
326 //! The army type of the given prototype.
329 //! The army set of the given prototype.
332 //! The number of allies to give the Player.
336 //! A useful item to be awarded to a Hero.
338 * Item objects are given to a Hero who has completed a Quest or searched a
341 class Reward_Item: public Reward
344 //! Default constructor.
346 * @param item A pointer to the item to give to the Hero.
348 Reward_Item (Item *item);
350 //! Loading constructor.
352 * Make a new reward item by loading it from an opened saved-game file.
354 * @param helper The opened saved-game file to load the item reward
357 Reward_Item(XML_Helper *helper);
359 //! Copy constructor.
361 * Make a new reward item by copying it from another one.
363 * @param orig The reward item to copy from.
365 Reward_Item(const Reward_Item& orig);
373 //! Get the Item object associated with this reward.
374 Item *getItem() const {return d_item;}
377 // Methods that operate on the class data but do not modify the class.
379 //! Save the reward item to a file.
381 * @param helper The opened saved-game file to save the reward item to.
383 bool save(XML_Helper* helper) const;
388 //! Return a random Item object.
390 * @note This method does not return an Reward_Item object.
392 * @note This method does not remove the Item object from the Itemlist.
394 * @return A pointer to a random Item object in the Itemlist.
396 static Item *getRandomItem();
399 //! Callback to load the Item object in the Reward_Item object.
400 bool loadItem(std::string tag, XML_Helper* helper);
404 //! A pointer to the Item object associated with this Reward_Item.
408 //! A hidden ruin to be awarded to a Player.
410 * Hidden Ruin objects are only visitable by a single Player.
411 * Hidden ruins are not given out as a reward when a Hero searched it and is
412 * successful. Hidden ruins are given out as a reward for a completed Quest.
414 class Reward_Ruin: public Reward
417 //! Default constructor.
419 * Make a new Reward_Ruin.
421 * @param ruin A pointer to the hidden Ruin object to present to the
424 Reward_Ruin(Ruin *ruin);
426 //! Loading constructor.
428 * Make a new Reward_Ruin by loading it from an opened saved-game file.
430 * @param helper The opened saved-game file to load the reward ruin
433 Reward_Ruin(XML_Helper *helper);
435 //! Copy constructor.
437 * Make a new reward ruin by copying it from another one.
439 * @param orig The reward ruin to copy from.
441 Reward_Ruin(const Reward_Ruin& orig);
448 //! Return the Ruin object associated with this Reward_Ruin.
449 Ruin* getRuin() const
450 {return Ruinlist::getInstance()->getObjectAt(d_ruin_pos);}
452 // Methods that operate on the class data but do not modify the class.
454 //! Save the reward ruin to an opened saved-game file.
456 * @param helper The opened saved-game file to write the ruin reward
459 bool save(XML_Helper* helper) const;
464 //! Go get a random hidden ruin to give to the Player.
466 * Scan all of the Ruin objects in the game and find one that is
467 * hidden but only visible by Neutral. Pick a random Ruin object
468 * out of the ones that qualify.
469 * It is up to the caller to change the owner of the hidden Ruin
472 * @return A pointer to a Ruin object in the Ruinlist that is a hidden
473 * ruin and is owned by the neutral Player. This method will
474 * return NULL if there are no more Ruin objects that meet
477 static Ruin *getRandomHiddenRuin();
483 //! The position of the Ruin object associated with this reward.
484 Vector<int> d_ruin_pos;
487 //! A portion of a hidden map to reveal to a Player.
489 * When playing on a hidden map, the Player can receive a map that uncovers a
490 * portion of the game map. It only reveals a portion of the map for one
492 * The map has a position (from the derived Location class), and as well as a
493 * height and a width.
495 class Reward_Map: public Reward
498 //! Default constructor.
500 * Make a new Reward_Map from the given parameters.
502 * @param pos The position of the top left corner tile of the map.
503 * @param name The name of this map.
504 * @param height The height of the revealed portion of the game map.
505 * @param width The width of the revealed portion of the game map.
507 Reward_Map(Vector<int> pos, std::string name,
508 guint32 height, guint32 width);
510 //! Loading constructor.
512 * Make a new Reward_Map by loading it from an opened saved-game file.
514 * @param helper The opened saved-game file to load the reward map
517 Reward_Map(XML_Helper *helper);
519 //! Copy constructor.
521 * Make a new reward map by copying it from another one.
523 * @param orig The reward map to copy from.
525 Reward_Map(const Reward_Map& orig);
533 //! Set the name of the map in this reward.
534 void setMapName(std::string name) {d_sightmap->setName(name);};
539 //! Return the top left corner of the map in this reward.
540 Vector<int> getLocation() const {return d_sightmap->pos;};
542 //! Return the map in this reward.
543 SightMap * getSightMap() {return d_sightmap;};
545 //! Return the name of the map in this reward.
546 std::string getMapName() const {return d_sightmap->getName();};
548 //! Get the height of the revealed portion of the game map.
549 guint32 getHeight() const {return d_sightmap->h;}
551 //! Get the width of the revealed portion of the game map.
552 guint32 getWidth() const {return d_sightmap->w;}
555 // Methods that operate on the class data and modify the class.
557 bool loadMap(std::string tag, XML_Helper* helper);
560 // Methods that operate on the class data and do not modify the class.
562 //! Save the reward map to an opened saved-game file.
564 * @param helper The opened saved-game file to write the ruin map to.
566 bool save(XML_Helper* helper) const;
571 //! Return a description of a random map.
573 * @note This will produce random maps that overlap each other.
574 * @note x,y defines the top-left-most tile of the map.
576 * @param x The number of tiles down in the vertical axis from the
577 * topmost edge of the map.
578 * @param y The number of tiles right in the horizontal axis from
579 * the leftmost edge of the map.
580 * @param width The width of the revealed portion of the game map.
581 * @param height The height of the revealed portion of the game map.
583 static void getRandomMap(int *x, int *y, int *width, int *height);
589 SightMap *d_sightmap;