The Battle for Wesnoth  1.13.10+dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
create.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2003 - 2017 by David White <dave@whitevine.net>
3  Part of the Battle for Wesnoth Project http://www.wesnoth.org/
4 
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 2 of the License, or
8  (at your option) any later version.
9  This program is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY.
11 
12  See the COPYING file for more details.
13 */
14 
15 /**
16  * @file
17  * Various functions related to the creation of units (recruits, recalls,
18  * and placed units).
19  */
20 
21 #pragma once
22 
23 class config;
24 class team;
25 class unit_type;
26 class vconfig;
27 
28 #include "unit_creator.hpp"
29 
30 #include "map/location.hpp"
31 #include "units/ptr.hpp"
32 
33 #include <tuple>
34 
35 namespace actions {
36 
37 /// The possible results of finding a location for recruiting (or recalling).
39  RECRUIT_NO_LEADER, /// No leaders exist
40  RECRUIT_NO_ABLE_LEADER, /// No leaders able to recall/recruit the given unit/type.
41  RECRUIT_NO_KEEP_LEADER, /// No able leaders are on a keep.
42  RECRUIT_NO_VACANCY, /// No vacant castle tiles around a leader on a keep.
43  RECRUIT_ALTERNATE_LOCATION, /// Recruitment OK, but not at the specified location.
44  RECRUIT_OK /// Recruitment OK.
45 };
46 
47 /**
48  * Checks if there is a location on which to place a recruited unit.
49  * A leader of the @a side must be on a keep connected by castle to a
50  * legal recruiting location to get an "OK" or "ALTERNATE_LOCATION" result.
51  *
52  * If "OK" is returned, then the location provided in @a recruit_location
53  * is legal. If "ALTERNATE_LOCATION" is returned, the provided location was
54  * illegal, so its value was replaced by a location where recruitment can
55  * occur.
56  *
57  * The location of the recruiting leader is stored in @a recruited_from.
58  * The incoming value of this parameter is used as a hint for finding a
59  * legal recruiter, but this hint is given lower priority than finding a
60  * leader who can recruit at recruit_location.
61  *
62  * The @a unit_type is needed in case this is a leader-specific recruit.
63  */
64 RECRUIT_CHECK check_recruit_location(const int side, map_location &recruit_location,
65  map_location& recruited_from,
66  const std::string& unit_type);
67 
68 /**
69  * Finds a location on which to place a unit.
70  * A leader of the @a side must be on a keep
71  * connected by castle to a legal recruiting location. Otherwise, an error
72  * message explaining this is returned.
73  *
74  * If no errors are encountered, the location where a unit can be recruited
75  * is stored in @a recruit_location. Its value is considered first, if it is a
76  * legal option.
77  * Also, the location of the recruiting leader is stored in @a recruited_from.
78  * The incoming value of recruited_from is used as a hint for finding a
79  * legal recruiter, but this hint is given lower priority than finding a
80  * leader who can recruit at recruit_location.
81  *
82  * The @a unit_type is needed in case this is a leader-specific recruit.
83  *
84  * @return an empty string on success. Otherwise a human-readable message
85  * describing the failure is returned.
86  */
87 std::string find_recruit_location(const int side, map_location &recruit_location, map_location& recruited_from, const std::string& unit_type);
88 
89 /**
90  * Checks if there is a location on which to recall @a unit_recall.
91  * A leader of the @a side must be on a keep connected by castle to a legal
92  * recalling location to get an "OK" or "ALTERNATE_LOCATION" result.
93  *
94  * If "OK" is returned, then the location provided in @a recall_location
95  * is legal. If "ALTERNATE_LOCATION" is returned, the provided location was
96  * illegal, so its value was replaced by a location where recalling can
97  * occur.
98  *
99  * The location of the recalling leader is stored in @a recall_from.
100  * The incoming value of this parameter is used as a hint for finding a
101  * legal recaller, but this hint is given lower priority than finding a
102  * leader who can recall at recall_location.
103  */
104 RECRUIT_CHECK check_recall_location(const int side, map_location& recall_location,
105  map_location& recall_from,
106  const unit &unit_recall);
107 
108 /**
109  * Finds a location on which to recall @a unit_recall.
110  * A leader of the @a side must be on a keep
111  * connected by castle to a legal recalling location. Otherwise, an error
112  * message explaining this is returned.
113  *
114  * If no errors are encountered, the location where a unit can be recalled
115  * is stored in @a recall_location. Its value is considered first, if it is a
116  * legal option.
117  * Also, the location of the recalling leader is stored in @a recall_from.
118  * The incoming value of this parameter is used as a hint for finding a
119  * legal recaller, but this hint is given lower priority than finding a
120  * leader who can recall at recall_location.
121  *
122  * @return an empty string on success. Otherwise a human-readable message
123  * describing the failure is returned.
124  */
125 std::string find_recall_location(const int side, map_location& recall_location, map_location& recall_from, const unit &unit_recall);
126 
127 /**
128  * Gets the recruitable units from a side's leaders' personal recruit lists who can recruit on or from a specific hex field.
129  * @param side of the leaders to search for their personal recruit lists.
130  * @param recruit_location the hex field being part of the castle the player wants to recruit on or from.
131  * @return a set of units that can be recruited either by the leader on @a recruit_location or by leaders on keeps connected by castle tiles to @a recruit_location.
132  */
133 const std::set<std::string> get_recruits(int side, const map_location &recruit_location);
134 
135 /**
136  * Gets the recallable units for a side, restricted by that side's leaders' personal abilities to recall on or from a specific hex field.
137  * If no leader is able to recall on or from the given location, the full recall list of the side is returned.
138  * @param side of the leaders to search for their personal recall filters.
139  * @param recall_loc the hex field being part of the castle the player wants to recruit on or from.
140  * @return a set of units that can be recalled by @a side on (or from) @a recall_loc or the full recall list of @a side.
141  */
142 std::vector<unit_const_ptr > get_recalls(int side, const map_location &recall_loc);
143 
144 typedef std::tuple<bool /*event modified*/, int /*previous village owner side*/, bool /*capture bonus time*/> place_recruit_result;
145 
146 /**
147  * Place a unit into the game.
148  * The unit will be placed on @a recruit_location, which should be retrieved
149  * through a call to recruit_location().
150  * @param facing the desired facing for the unit, map_location::NDIRECTIONS to determine facing automatically.
151  * @returns true if an event (or fog clearing) has mutated the game state.
152  */
153 place_recruit_result place_recruit(unit_ptr u, const map_location &recruit_location, const map_location& recruited_from,
154  int cost, bool is_recall, map_location::DIRECTION facing = map_location::NDIRECTIONS, bool show = false, bool fire_event = true, bool full_movement = false, bool wml_triggered = false);
155 
156 /**
157  * Recruits a unit of the given type for the given side.
158  * This is the point at which the code merges for recruits originating from players,
159  * the AI, and replays. It starts just after the recruit location is successfully
160  * found, and it handles creating the unit, paying gold, firing events, tracking
161  * statistics, and (unless @a is_ai) updating the undo stack.
162  */
163 void recruit_unit(const unit_type & u_type, int side_num, const map_location & loc,
164  const map_location & from, bool show=true, bool use_undo=true);
165 
166 /**
167  * Recalls the unit with the indicated ID for the provided team.
168  * The ID can be a reference to data in the recall list.
169  * This is the point at which the code merges for recalls originating from players,
170  * the AI, and replays. It starts just after the recall location is successfully
171  * found, and it handles moving the unit to the board, paying gold, firing events,
172  * tracking statistics, updating the undo stack (unless @a use_undo is false), and
173  * recording the recall (unless @a use_recorder is false).
174  * @param facing the desired facing for the unit, map_location::NDIRECTIONS to determine facing automatically.
175  * @returns false if the recall could not be found in the team's recall list.
176  */
177 bool recall_unit(const std::string & id, team & current_team,
178  const map_location & loc, const map_location & from,
180  bool show=true, bool use_undo=true);
181 }//namespace actions
bool recall_unit(const std::string &id, team &current_team, const map_location &loc, const map_location &from, map_location::DIRECTION facing, bool show, bool use_undo)
Recalls the unit with the indicated ID for the provided team.
Definition: create.cpp:735
bool fire_event(const ui_event event, std::vector< std::pair< widget *, ui_event >> &event_chain, widget *dispatcher, widget *w, F &&...params)
Helper function for fire_event.
std::vector< char_t > string
This class represents a single unit of a specific type.
Definition: unit.hpp:101
No leaders exist.
Definition: create.hpp:40
void show(CVideo &video, const std::string &window_id, const t_string &message, const point &mouse, const SDL_Rect &source_rect)
Shows a tip.
Definition: tooltip.cpp:153
std::tuple< bool, int, bool > place_recruit_result
Definition: create.hpp:144
Recruitment OK, but not at the specified location.
Definition: create.hpp:44
RECRUIT_CHECK
The possible results of finding a location for recruiting (or recalling).
Definition: create.hpp:38
std::vector< unit_const_ptr > get_recalls(int side, const map_location &recall_loc)
Gets the recallable units for a side, restricted by that side's leaders' personal abilities to recall...
Definition: create.cpp:158
A single unit type that the player may recruit.
Definition: types.hpp:43
This class stores all the data for a single 'side' (in game nomenclature).
Definition: team.hpp:44
void recruit_unit(const unit_type &u_type, int side_num, const map_location &loc, const map_location &from, bool show, bool use_undo)
Recruits a unit of the given type for the given side.
Definition: create.cpp:703
const std::set< std::string > get_recruits(int side, const map_location &recruit_loc)
Gets the recruitable units from a side's leaders' personal recruit lists who can recruit on or from a...
Definition: create.cpp:58
No vacant castle tiles around a leader on a keep.
Definition: create.hpp:43
Encapsulates the map of the game.
Definition: location.hpp:40
RECRUIT_CHECK check_recall_location(const int side, map_location &recall_location, map_location &recall_from, const unit &unit_recall)
Checks if there is a location on which to recall unit_recall.
Definition: create.cpp:276
No able leaders are on a keep.
Definition: create.hpp:42
Various functions related to the creation of units (recruits, recalls, and placed units)...
std::string find_recall_location(const int side, map_location &recall_location, map_location &recall_from, const unit &unit_recall)
Finds a location on which to recall unit_recall.
Definition: create.cpp:328
RECRUIT_CHECK check_recruit_location(const int side, map_location &recruit_location, map_location &recruited_from, const std::string &unit_type)
Checks if there is a location on which to place a recruited unit.
Definition: create.cpp:406
DIRECTION
Valid directions which can be moved in our hexagonal world.
Definition: location.hpp:42
boost::intrusive_ptr< unit > unit_ptr
Definition: ptr.hpp:29
A variable-expanding proxy for the config class.
Definition: variable.hpp:42
std::string find_recruit_location(const int side, map_location &recruit_location, map_location &recruited_from, const std::string &unit_type)
Finds a location on which to place a unit.
Definition: create.cpp:464
place_recruit_result place_recruit(unit_ptr u, const map_location &recruit_location, const map_location &recruited_from, int cost, bool is_recall, map_location::DIRECTION facing, bool show, bool fire_event, bool full_movement, bool wml_triggered)
Place a unit into the game.
Definition: create.cpp:610
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:93
No leaders able to recall/recruit the given unit/type.
Definition: create.hpp:41