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