The Battle for Wesnoth Wiki - User contributions [en]

LuaWML/Pathfinder

2013-10-09T13:38:14Z

Flixx: insert find_cost_map

This page describes the [[LuaWML]] functions and helpers for finding paths.

==== wesnoth.find_path ====

Returns the shortest path from one location to another. The source location is given either by coordinates as two arguments x and y; there must be a unit at the source location when using the standard path calculator. The source location can also be given by a unit as a single argument (as returned by the functions from [[LuaWML:Units]]). The second location is given by its coordinates. The last argument is an optional table that can be used to parametrize the pathfinder. Its options are:
* '''max_cost''': if set, the pathfinder will ignore paths longer than its value
* '''ignore_units''': if set, the path will go through units and ignore zones of control
* '''ignore_teleport''': if set, the teleport ability of the unit is ignored
* '''viewing_side''': if set to a valid side number, fog and shroud for this side will be taken into account; if set to an invalid number (e.g. 0), fog and shroud will be ignored; if left unset, the viewing side will be the unit side

The path is returned as a table of coordinate pairs. It contains both the source and destination tile if a path was found. The total cost of the path is also available as a second return value, if needed.

-- Display some items along the path from (x1,y1) to (x2,y2).
local u = wesnoth.get_units({ x = x1, y = y1 })[1]
local path, cost = wesnoth.find_path(u, x2, y2, { ignore_units = true, viewing_side = 0 })
if cost > u.moves then
wesnoth.message("That's too far!")
else
for i, loc in ipairs(path) do
wesnoth.fire("item", { x = loc[1], y = loc[2], image = "items/buckler.png" })
end
end

Instead of a parameter table, a cost function can be passed to the pathfinder. It will be called for all the tiles the computed path may possibly go through. It receives three arguments. The first two are the coordinates of the tile, the last one is the current cost for reaching that tile. The function should return a floating-point value that is the cost for entering the given tile. This cost should be greater or equal to one.

-- Count how many turns it would take, assuming the worst case (3 movement points per tile)
local max_moves = wesnoth.get_units({ x = x1, y = y1 })[1].max_moves
local path, cost = wesnoth.find_path(x1, y2, x2, y2,
function(x, y, current_cost)
local remaining_moves = max_moves - (current_cost % max_moves)
if remaining_moves < 3 then current_cost = current_cost + remaining_moves end
return current_cost + 3
end)
wesnoth.message(string.format("It would take %d turns.", math.ceil(cost / 3)))

==== wesnoth.find_vacant_tile ====

Returns the two coordinates of an empty tile the closest to the tile passed by coordinates. An optional unit (either a WML table or a proxy object) can be passed as a third argument; if so, the returned tile has terrain which is passable for the passed unit.

function teleport(src_x, src_y, dst_x, dst_y)
local u = wesnoth.get_units({x = src_x, y = src_y })[1]
local ut = u.__cfg
dst_x, dst_y = wesnoth.find_vacant_tile(dst_x, dst_y, u)
wesnoth.put_unit(src_x, src_y)
wesnoth.put_unit(dst_x, dst_y, ut)
end

==== wesnoth.find_reach ====

Returns all the locations reachable by a unit. The unit is given either by its two coordinates or by a proxy object. The last argument is an optional table that can be used to parametrize the pathfinder. Its options are:
* '''additional_turns''': if set to an integer n, the pathfinder will consider tiles that can be reached in n+1 turns
* '''ignore_units''': if set, the paths will go through units and ignore zones of control
* '''ignore_teleport''': if set, the teleport ability of the unit is ignored
* '''viewing_side''': if set to a valid side number, fog and shroud for this side will be taken into account; if set to an invalid number (e.g. 0), fog and shroud will be ignored; if left unset, the viewing side will be the unit side
The locations are stored as triples in an array. The first two elements of a triple are the coordinates of a reachable tile, the third one is the number of movement points left when reaching the tile.

-- overlay the number of turns needed to reach each tile
local t = wesnoth.find_reach(u, { additional_turns = 8 })
local m = u.max_moves
for i,l in ipairs(t) do
wesnoth.fire("label", { x = l[1], y = l[2], text = math.ceil(9 - l[3]/m) })
end

==== wesnoth.find_cost_map ====

Builds a cost map for one, multiple units or unit types.
In a cost map each hex is mapped to two values:
a) The summed cost to reach this hex for all input units
b) A value which indicates how many units can reach this hex
The caller can divide a) with b) to get a average cost to reach this hex for the input units.
The costs will consider movement lost during turn changes. (So with simple calculus it is possible to get the turns to reach a hex)

Input arguments:
* 1 + 2. A units location
* '''OR''' 1. A unit
* '''OR''' 1. A unit filter
* 2. (optional) A array of triples (coordinates + unit type as string)
* 3. (optional) A table with options: ignore_units, ignore_teleport, viewing_side, debug, use_max_moves
* 4. (optional) A [[StandardLocationFilter|Standard Location Filter]].

If the array of unit types is given the units will be added to the first parameter. Use a empty filter or a invalid location to only add unit types.

Return value:
A array of quadruples (coordinates + a summed cost + reach count)

A location set can be build by calling location.set.of_pairs(retval).

==== helper.distance_between ====

Returns the distance between two tiles given by their coordinates.

local d = distance_between(x1, y1, x2, y2)

==== helper.adjacent_tiles ====

Returns an iterator on the (at most six) tiles around a given location that are on the map. If the third argument is ''true'', tiles on the map border are also visited.

-- remove all the units next to the (a,b) tile
for x, y in helper.adjacent_tiles(a, b) do
wesnoth.put_unit(x, y)
end

[[Category: Lua Reference]]

AI Recruitment

2013-10-06T23:10:14Z

Flixx: /* Example */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode ''and'' the game is started with the parameter <code>--log-info=ai/recruitment</code> the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.
The minimum depends on the aspect <code>recruitment_diversity</code>

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (recruitment_diversity * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment_instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it can be a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. When the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (5 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.5: (double)''' See explanation above.
* '''end=1.1: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the AI will never switch to the state SPEND_ALL_GOLD.
* '''save_on_negative_income=no: (boolean)''' If this is set to yes, the AI will switch to the state SAVE_GOLD even if the income is negative. (estimation over 5 turns, village gain and unit loss estimation included).

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.5
end=1.1
spend_all_gold=-1
save_on_negative_income=no
[/value]
[/facet]
[/aspect]
[/ai]

A macro can be used to deactivate recruitment_save_gold:

{AI_ASPECT recruitment_save_gold {AI_DEACTIVATE_SAVE_GOLD} }

=Other aspects=
*'''recruitment_diversity'''=2.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. When the value is 0.0, the AI will only recruit the best unit.(see [[AI_Recruitment#Implementation_details_for_interested_readers| above]] for implementation details).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0.8''' Let the AI recruit the best units only.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-10-06T23:10:01Z

Flixx: /* The Aspect */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode ''and'' the game is started with the parameter <code>--log-info=ai/recruitment</code> the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.
The minimum depends on the aspect <code>recruitment_diversity</code>

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (recruitment_diversity * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment_instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it can be a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. When the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (5 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.5: (double)''' See explanation above.
* '''end=1.1: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the AI will never switch to the state SPEND_ALL_GOLD.
* '''save_on_negative_income=no: (boolean)''' If this is set to yes, the AI will switch to the state SAVE_GOLD even if the income is negative. (estimation over 5 turns, village gain and unit loss estimation included).

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.1
end=0.9
spend_all_gold=-1
save_on_negative_income=no
[/value]
[/facet]
[/aspect]
[/ai]

A macro can be used to deactivate recruitment_save_gold:

{AI_ASPECT recruitment_save_gold {AI_DEACTIVATE_SAVE_GOLD} }

=Other aspects=
*'''recruitment_diversity'''=2.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. When the value is 0.0, the AI will only recruit the best unit.(see [[AI_Recruitment#Implementation_details_for_interested_readers| above]] for implementation details).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0.8''' Let the AI recruit the best units only.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-10-06T23:00:14Z

Flixx: /* Example */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode ''and'' the game is started with the parameter <code>--log-info=ai/recruitment</code> the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.
The minimum depends on the aspect <code>recruitment_diversity</code>

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (recruitment_diversity * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment_instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it can be a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. When the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (5 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.1: (double)''' See explanation above.
* '''end=0.9: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the AI will never switch to the state SPEND_ALL_GOLD.
* '''save_on_negative_income=no: (boolean)''' If this is set to yes, the AI will switch to the state SAVE_GOLD even if the income is negative. (estimation over 5 turns, village gain and unit loss estimation included).

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.1
end=0.9
spend_all_gold=-1
save_on_negative_income=no
[/value]
[/facet]
[/aspect]
[/ai]

A macro can be used to deactivate recruitment_save_gold:

{AI_ASPECT recruitment_save_gold {AI_DEACTIVATE_SAVE_GOLD} }

=Other aspects=
*'''recruitment_diversity'''=2.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. When the value is 0.0, the AI will only recruit the best unit.(see [[AI_Recruitment#Implementation_details_for_interested_readers| above]] for implementation details).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0.8''' Let the AI recruit the best units only.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-10-06T22:57:01Z

Flixx: /* The Aspect */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode ''and'' the game is started with the parameter <code>--log-info=ai/recruitment</code> the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.
The minimum depends on the aspect <code>recruitment_diversity</code>

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (recruitment_diversity * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment_instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it can be a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. When the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (5 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.1: (double)''' See explanation above.
* '''end=0.9: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the AI will never switch to the state SPEND_ALL_GOLD.
* '''save_on_negative_income=no: (boolean)''' If this is set to yes, the AI will switch to the state SAVE_GOLD even if the income is negative. (estimation over 5 turns, village gain and unit loss estimation included).

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.1
end=0.9
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

A macro can be used to deactivate recruitment_save_gold:

{AI_ASPECT recruitment_save_gold {AI_DEACTIVATE_SAVE_GOLD} }

=Other aspects=
*'''recruitment_diversity'''=2.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. When the value is 0.0, the AI will only recruit the best unit.(see [[AI_Recruitment#Implementation_details_for_interested_readers| above]] for implementation details).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0.8''' Let the AI recruit the best units only.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

EasyCoding

2013-10-04T15:18:15Z

Flixx: /* Improvements to AI */

== Foreword ==

'''We are currently in the process of updating this page. Parts marked by <s>strikeout</s> will likely be deleted shortly.

This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature I'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

--[[User:Boucman|Boucman]] 20:48, 3 October 2006 (CEST)

== MP related features ==
=== Add possibility to give reason for "ignore" ===
As per FR #16001 [https://gna.org/bugs/?16001]

* See https://github.com/wesnoth/wesnoth-old/pull/1

=== Add possibility to switch off dependency checking ===
MP add-ons can define dependencies. Currently there's no way to force a "broken" configuration, although overzealous use of the system by UMC authors could make this feature useful. Add an option to the MP game creation screen to switch on/off dependency checking. Ask lipk (forum)/lipkab (IRC).

== WML related features ==

=== Side-specific results ===
Giving result=defeat or result=victory for specific sides. ([http://gna.org/bugs/index.php?4960 FR #4960]) -- [[User:dlr365|dlr365]] -- patch submitted [https://gna.org/bugs/index.php?4960]

--[[User:Boucman|Boucman]] 08:58, 28 February 2010 (UTC) Patch seems abandonned, but can be used for further work feel free to take over the FR

=== Support for leaderless multiplayergames ===
Add support for the WML key victory_when_enemies_defeated= in the scenario tag during multiplayergames. ([https://gna.org/bugs/index.php?8106 FR #8106])

=== Support variable recall cost in wml ===
see https://gna.org/bugs/?16538

the syntax needs to be discussed and refined, but the overall idea is good

make sure to update whiteboard to handle this correctly

Ask Boucman

=== Other Ideas ===
See [[FutureWML]]; some ideas there are easier than others.

== Improvements to AI ==

Note: not all of these are simple tasks. Talk to Crab or mattsc.

* Make external CAs fully usable. This requires adding a persistent data variable that is accessible across the CAs and being able to pass parameters to the CA eval and exec functions.

* Add option to take avoided hexes into account in wesnoth.find_path()

* Make the (old) simple aspect syntax work when the Lua engine is defined for a side. Setting aspects in the [side] tag like this:
[ai]
aggression=0.123
[/ai]
does not work if the Lua engine is defined. You either need to use the [aspect] tag in the [side] tag with 'engine=lua', or use the code above in a [modify_side] tag in an event. Making the above syntax available (as it is with the c++ engine) would be nice. The same also applies to the FAI engine and to aspects set for AI sides in MP games.

* Add more replay-safe actions to the Lua AI actions. A first step could be to add an AI action (and add lua function to do that) to use a right-click menu item.

* Add a Lua function ai.get_individual_attacks() that returns all the single attacks the side can do (as opposed to attack combinations). This needs to include an option to recalculate and take the current situation on the map into account (making the function believe that the game state has changed).

* Set up an option the allows us to exclude units from the move-to-targets phase similar to [filter_own] for the combat phase (other than setting ai_special=guardian, which has a number of other side effects). Actually, having this option for all CA's would be nice. (This is not a simple task. Some first attempts to do it have been made, but work seems abandoned at the moment.)

* Change the aspects "passive_leader", "passive_leader_shares_keep", "leader_ignores_keep" to work with multiple leaders. The idea is to change the type of those aspects from yes/no to string so both "passive_leader=yes" and "passive_leader=leader_id_1,leader_id_2" is possible.

== GUI related features ==
-------------------

Note at the moment Mordante is working on a new GUI system, these
changes will probably affect the way these items need to be implemented.
Contact Mordante on IRC before starting to work on these.

--[[User:SkeletonCrew|SkeletonCrew]] 14:04, 9 March 2008 (EDT)

=== Theme Changes ===

* hide the hourglass item from the statusbar when there is no timer

=== Widget Changes ===
* make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* input history (chat, commands, ..)

== GUI2 related features ==
GUI2 is the new gui engine Mordante/SkeletonCrew is working on.
* Information on the wiki can be found here http://www.wesnoth.org/wiki/GUIToolkit
* The source code is under src/gui/
* The configuration config files are under data/gui/default

Some tasks need the --new-widgets since the code is only shown in the experimental mode. Tasks which need this switch have the * in the title.

=== Port the random map generator dialog to GUI2 ===
The map generator currently doesn't use the GUI2 framework, but there's no reason why it couldn't. Ask lipk (forum)/lipkab (IRC).

== Miscellaneous ==

=== More powerful village naming ===
'''Adding mountain names and other features to village names, having a second random name in village names'''

Currently the village naming engine has a very good structure that could allow
more powerfull names to be generated.
Understanding how it works should be quite easy, and a few usefull improvements could be added.

* Currently villages can use lake names and river names, this should be extended to other features like bridges, swamps, mountains etc...
* It would be nice to have a separate list of "first sylabus" and "last sylabus" for naming. That's not really needed in english, but some translations could use it
* Again, it is common to have villages with more than one "random" word in them. having a $name2 variable would be nice

=== Debug Mode ===
* New debug command functionality (setting additional status.variables, possibly terrain)
* Add a right-click option in debug mode to kill the unit under the cursor ([[User:PL_kolek|PL_kolek]], Patch submitted [https://gna.org/patch/index.php?3905])

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]

AI Recruitment

2013-10-04T13:12:52Z

Flixx: /* How it works */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode ''and'' the game is started with the parameter <code>--log-info=ai/recruitment</code> the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.
The minimum depends on the aspect <code>recruitment_diversity</code>

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (recruitment_diversity * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment_instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it can be a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. When the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (5 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.1: (double)''' See explanation above.
* '''end=0.9: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the AI will never switch to the state SPEND_ALL_GOLD.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.1
end=0.9
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

A macro can be used to deactivate recruitment_save_gold:

{AI_ASPECT recruitment_save_gold {AI_DEACTIVATE_SAVE_GOLD} }

=Other aspects=
*'''recruitment_diversity'''=2.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. When the value is 0.0, the AI will only recruit the best unit.(see [[AI_Recruitment#Implementation_details_for_interested_readers| above]] for implementation details).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0.8''' Let the AI recruit the best units only.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-10-04T13:12:01Z

Flixx: /* The Aspect */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode ''and'' the game is started with the parameter <code>--log-info=ai/recruitment</code> the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.
The minimum depends on the aspect <code>recruitment_diversity</code>

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (recruitment_diversity * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment_instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it can be a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (5 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.1: (double)''' See explanation above.
* '''end=0.9: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the AI will never switch to the state SPEND_ALL_GOLD.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.1
end=0.9
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

A macro can be used to deactivate recruitment_save_gold:

{AI_ASPECT recruitment_save_gold {AI_DEACTIVATE_SAVE_GOLD} }

=Other aspects=
*'''recruitment_diversity'''=2.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. When the value is 0.0, the AI will only recruit the best unit.(see [[AI_Recruitment#Implementation_details_for_interested_readers| above]] for implementation details).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0.8''' Let the AI recruit the best units only.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-10-04T13:10:28Z

Flixx: /* Map analyis */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode ''and'' the game is started with the parameter <code>--log-info=ai/recruitment</code> the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.
The minimum depends on the aspect <code>recruitment_diversity</code>

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (recruitment_diversity * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment_instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it can be a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (5 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.1: (double)''' See explanation above.
* '''end=0.9: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.1
end=0.9
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

A macro can be used to deactivate recruitment_save_gold:

{AI_ASPECT recruitment_save_gold {AI_DEACTIVATE_SAVE_GOLD} }

=Other aspects=
*'''recruitment_diversity'''=2.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. When the value is 0.0, the AI will only recruit the best unit.(see [[AI_Recruitment#Implementation_details_for_interested_readers| above]] for implementation details).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0.8''' Let the AI recruit the best units only.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-10-04T13:10:05Z

Flixx: /* Map analyis */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode ''and'' the game is started with the parameter "--log-info=ai/recruitment" the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.
The minimum depends on the aspect <code>recruitment_diversity</code>

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (recruitment_diversity * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment_instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it can be a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (5 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.1: (double)''' See explanation above.
* '''end=0.9: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.1
end=0.9
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

A macro can be used to deactivate recruitment_save_gold:

{AI_ASPECT recruitment_save_gold {AI_DEACTIVATE_SAVE_GOLD} }

=Other aspects=
*'''recruitment_diversity'''=2.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. When the value is 0.0, the AI will only recruit the best unit.(see [[AI_Recruitment#Implementation_details_for_interested_readers| above]] for implementation details).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0.8''' Let the AI recruit the best units only.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-10-03T18:52:11Z

Flixx: /* How it works */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.
The minimum depends on the aspect <code>recruitment_diversity</code>

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (recruitment_diversity * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment_instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it can be a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (5 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.1: (double)''' See explanation above.
* '''end=0.9: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.1
end=0.9
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

A macro can be used to deactivate recruitment_save_gold:

{AI_ASPECT recruitment_save_gold {AI_DEACTIVATE_SAVE_GOLD} }

=Other aspects=
*'''recruitment_diversity'''=2.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. When the value is 0.0, the AI will only recruit the best unit.(see [[AI_Recruitment#Implementation_details_for_interested_readers| above]] for implementation details).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0.8''' Let the AI recruit the best units only.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-26T15:40:03Z

Flixx: /* Aspect recruitment_instruction */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.
The minimum depends on the aspect <code>recruitment_diversity</code>

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (recruitment_diversity * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment_instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it can be a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.1: (double)''' See explanation above.
* '''end=0.9: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.1
end=0.9
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

A macro can be used to deactivate recruitment_save_gold:

{AI_ASPECT recruitment_save_gold {AI_DEACTIVATE_SAVE_GOLD} }

=Other aspects=
*'''recruitment_diversity'''=2.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. When the value is 0.0, the AI will only recruit the best unit.(see [[AI_Recruitment#Implementation_details_for_interested_readers| above]] for implementation details).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0.8''' Let the AI recruit the best units only.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-26T13:56:17Z

Flixx: /* How it works */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.
The minimum depends on the aspect <code>recruitment_diversity</code>

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (recruitment_diversity * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it can be a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.1: (double)''' See explanation above.
* '''end=0.9: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.1
end=0.9
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

A macro can be used to deactivate recruitment_save_gold:

{AI_ASPECT recruitment_save_gold {AI_DEACTIVATE_SAVE_GOLD} }

=Other aspects=
*'''recruitment_diversity'''=2.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. When the value is 0.0, the AI will only recruit the best unit.(see [[AI_Recruitment#Implementation_details_for_interested_readers| above]] for implementation details).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0.8''' Let the AI recruit the best units only.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-26T13:52:31Z

Flixx: /* Example */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.
The minimum depends on the aspect <code>recruitment_diversity</code>

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (recruitment_diversity * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.1: (double)''' See explanation above.
* '''end=0.9: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.1
end=0.9
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

A macro can be used to deactivate recruitment_save_gold:

{AI_ASPECT recruitment_save_gold {AI_DEACTIVATE_SAVE_GOLD} }

=Other aspects=
*'''recruitment_diversity'''=2.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. When the value is 0.0, the AI will only recruit the best unit.(see [[AI_Recruitment#Implementation_details_for_interested_readers| above]] for implementation details).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0.8''' Let the AI recruit the best units only.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-26T13:50:42Z

Flixx: /* Making recruitment strong */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.
The minimum depends on the aspect <code>recruitment_diversity</code>

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (recruitment_diversity * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.1: (double)''' See explanation above.
* '''end=0.9: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.1
end=0.9
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=2.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. When the value is 0.0, the AI will only recruit the best unit.(see [[AI_Recruitment#Implementation_details_for_interested_readers| above]] for implementation details).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0.8''' Let the AI recruit the best units only.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-26T13:49:22Z

Flixx: /* Implementation details for interested readers */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.
The minimum depends on the aspect <code>recruitment_diversity</code>

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (recruitment_diversity * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.1: (double)''' See explanation above.
* '''end=0.9: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.1
end=0.9
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=2.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. When the value is 0.0, the AI will only recruit the best unit.(see [[AI_Recruitment#Implementation_details_for_interested_readers| above]] for implementation details).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0''' Let the AI recruit the best units.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-26T13:47:35Z

Flixx: /* Other aspects */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.1: (double)''' See explanation above.
* '''end=0.9: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.1
end=0.9
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=2.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. When the value is 0.0, the AI will only recruit the best unit.(see [[AI_Recruitment#Implementation_details_for_interested_readers| above]] for implementation details).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0''' Let the AI recruit the best units.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-26T02:29:35Z

Flixx: /* Other aspects */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.1: (double)''' See explanation above.
* '''end=0.9: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.1
end=0.9
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0''' Let the AI recruit the best units.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-26T01:09:21Z

Flixx: /* Example */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.1: (double)''' See explanation above.
* '''end=0.9: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.1
end=0.9
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0''' Let the AI recruit the best units.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-26T01:08:47Z

Flixx: /* The Aspect */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.1: (double)''' See explanation above.
* '''end=0.9: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0''' Let the AI recruit the best units.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-25T14:35:17Z

Flixx: /* Making recruitment strong */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0''' Let the AI recruit the best units.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-25T14:32:49Z

Flixx:

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0''' Let the AI recruit the best units.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-25T13:54:40Z

Flixx: /* Map analyis */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-25T13:54:28Z

Flixx: /* Map analyis */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white "X".

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-23T21:37:25Z

Flixx: /* Example */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-23T21:34:16Z

Flixx: /* The Aspect */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-23T21:33:56Z

Flixx: /* The Aspect */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active (So the AI will always spend all gold until the defined turn). <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-23T21:31:47Z

Flixx: /* The Aspect */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

User:Flixx/GSoC 2013/AI: AI: Refactor recruitment algorithm

2013-09-14T17:26:37Z

Flixx: /* Goals / Milestones */

{{SoC2013Student}}
[[Category:SoC_Ideas_AI_Recruitment_2013]]

=Description=
<h4>flix: Refactor recruitment algorithm</h4>
An AI opponent have to decide in a separate phase which units to recruit. Right now the default recruitment algorithm is very simple and can be improved in many ways. I want to make the AI recruiting better, more fun to play against and more configurable by a scenario editor.

= Make it better =
(In terms of harder to play against)

== Map Analysis==

Previous attempts have been made to this:
* analyze_potential_recruit_movements() analyzes nearby targets and how to reach them.
* the "Formula AI dev"-Recruitment uses the terrain near to villages ("important locations") and recruits units which defend good in those areas. According to Crab_ the algorithm easily beats the RCA AI (default-AI). The algorithm is written in Formula-AI and hard to understand (and probably therefore not in use). Additionally Formula-AI is not longer supported in future developments.

In my project I want to refactor the "Formula AI dev"-Recruitment in C++, test it, improve it and make it easy to configure.

== Combat Analysis ==

The current RCA AI make much use of a combat analysis. This works actually pretty well.
Although there are still some improvements possible.
In context of my Game Theory Algorithm, I already tried to weight the attacks in a different way. Tests have shown that this was a good thing to do.

A lot of things that have a minor effects in combat analysis are not considered yet. Examples for this are traits, movement-costs, daytime, abilities like leadership or healing.

I will give the combat analysis a refactoring and try to include all those specialties.

== Counter Recruitment Strategies ==
In order to recruit the best units for a set of enemy units and make the best use of a combat analysis, it is sometimes useful to wait for the enemy to recruit. (Not spend all money in the first round). The RCA AI will always recruit when it has enough gold available. This can be improved. The hardest part when implementing this is to decide when such a strategy is appropriate.

I want first to introduce a state "Counter Recruitment". When the AI is in this state it will first wait (and discover) enemy units before spending all the money. Then I will test (via benchmarking) in which cases it is useful for the AI to enter or leave this state.

== Counter-Counter Recruitment Strategies ==
Note: I need a better name for this ;)

We don't want the enemy to counter easy our own units. This could happen when all of our recruited units can be easily countered by one unit type of the enemy. So when we recruit we need to recruit in a way our units will look diverse from a combat point of view.

As a part of the proposal I already implemented a Proof of Concept for such a strategy. For this I've used tools from Game Theory. (Finding a mixed strategy Nash Equilibrium).
See [[User:Flixx/Game Theory for Recruiting]] for more.

= Make it more Fun =

In terms of recruitment ''more fun'' is achieved when the AI is recruiting not only one type but a good mix of all available units. This can easily be achieved by just favor rare units. The hard part here is again, how to weight it against other options.

= Implementation Details: Score Map =

So far I spoke about several analyze algorithms: map-analyze, combat-analyze, counter- and counter-counter strategies, and some possibility to boost diversity.
Here I want to say something how this algorithms could work together.

At the beginning of the recruitment phase (but after filtering units according to configurations) a '''score map''' is created with all possible units which can be recruited. In the analysis phases (map analysis, combat analysis, ...) it will be filled with scores. More specifically:
Let i denote a analysis algorithm and j a unit.
Score_j = sum_over_all_i (score_ij * weight_i)

After the score-map is completed the recruitments will be executed according to it. One Example:

'''Unit''' '''Score''' '''percentage'''
A 50 1 %
B 2000 40 %
C 450 9 %
D 1000 20 %
E 500 10 %
F 1000 20 %

If 5 Hexes are available for recruiting the Leader will recruit 2 B's , 1 D, 1 F and 1 E.

Notes:
# To make the recruitment-analysis efficient, all analyses algorithms should only run once per CA Execution.
# The score map will most likely also have a score for 'recruit no unit' for making Counter-Recruiting-Strategies work.
# To make this work with multiple leaders: The score-map can be expanded so there are scores for each leader. The separate analyse-algorithms can then set for a unit a different score for leader 1 then for leader 2. To start easy on this we can first assume that for all leaders the scores will be the same. Later one could extend the analyse-algorithms so they can set different scores for leaders. (This could be useful for example if the Combat-Analysis can figure out that one specific unit can fight better against the units around leader 1). After the score-map is completed each leader will recruit according to their score-map (They could swap after each recruitment if money is rare so the units will be split equally)
# One could also think about negative scores. For example when the combat-analyzes wants to make sure that we not recruit Woses when there are fire-units around, although Woses seemed best for Map-analysis.
# The Cost could influence the score too. Without cost the AI would only recruit good and expensive units.
# Even when ''diversity'' is weighted to zero, the current units on the map should influence the scores too. Otherwise if the leader can only recruit one unit per turn he would always recruit the same unit.
# One could also think about giving scouts in the first rounds a higher score.

= Make it more configurable =

For a better *development flow* I want first specify the configurations (in the wiki) before implementing them. Before it comes to implementation I will also use the forum to discuss my suggestions.

See [[User:Flixx/Configuration Specifications]]

= Purposes Idea =
For the Idea see this page: [[User:Flixx/GSoC 2013/Idea AI Recruitment: Purposes]]

In the scope of this project I want to take some time to implement a Proof of Concept of this idea for further evaluation. I think it is a good idea but I don't want to define the implementation of this as a project goal. Probably Purpose-Driven-Recruitment will get too complex, and I don't want to fail the goals. Though I want to plan some time at the end of the summer for this idea to see if it's worth something.

= Multiple Leader =

Although the AI could have multiple recruiters available it will currently only recruit with one leader. I want to change this. All necessary configurations for this are already in place (a scenario-editor can specify multiple leaders and leader specific recruitment lists).

I already wrote some thoughts how to make the recruitment work. I will repeat it here:

''To make this work with multiple leaders: The score-map can be expanded so there are scores for each leader. The separate analyse-algorithms can then set for a unit a different score for leader 1 then for leader 2. To start easy on this we can first assume that for all leaders the scores will be the same. Later one could extend the analyse-algorithms so they can set different scores for leaders. (This could be useful for example if the Combat-Analysis can figure out that one specific unit can fight better against the units around leader 1). After the score-map is completed each leader will recruit according to their score-map (They could swap after each recruitment if money is rare so the units will be split equally)''

Additionally I need to extend the Move_Leader_To_Keep CA so that both leaders will advised to return to a keep. I want to implement this early so I can test everything with multiple leaders from the beginning on.

When I have time I want to make the Move_Leader_To_Keep CA actually ''intelligent'' so it can be decided if it is really necessary to move all recruiters back to a keep (and if not decide which recruiter). I marked this as 'optional'.

= Set of Goals - Brief overwiew =

* Refactor the "Formula AI dev"-Recruitment in C++, test it, improve it and make it easy to configure.
* Refactor Combat analysis
* Implement a Counter-Recruitment-Strategy and find good conditions when to use it
* Implementing a system to favor rare units
* Find good default-weights for all sub-algorithms
* Make those weights configurable
* Introduce easy understandalbe configurations
* Support recruitment with Multiple Leaders
* (optional) Implementing a Proof of Concept for the Purpose Idea and test it

= Timeline =

{| border="1"
| style="width: 125px;" | May 27 || ''Accepted student proposals announced by Google''
|-
| May 28 - Jun 17 || ''Before the official Coding Phase:'' Do Step 1 to Step 5 (Goals). Start Coding already. Maybe provide some patches with have not necessarily something to do with recruitment to familiarize more with the Code.
|-
| Jun 18 - Jul 01 || Time off. See [http://wiki.wesnoth.org/index.php?title=User:Flixx/GSoC_2013/AI:_AI:_Refactor_recruitment_algorithm#time 1.7) in the Questionnaire]
|-
| Jul 02 - Jul 28 || Do everything (mandatory) up to Milestone 1.
|-
| Jul 29 - Aug 02 || ''Mid term evaluation''
|-
| Aug 03 - Aug 25 || Do everything (mandatory) up to Milestone 2.
|-
| Aug 26 - Sep 15 || Do most steps up to Milestone 3.
|-
| Sep 16 || ''Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.''
|-
| Sep 16 - Sep 23 || Do documentary steps up to Milestone 3 and finish at least mandatory steps of Milestone 3
|-
| Sep 23 - Oct 01 || ''Final Evaluation, submitting required code samples to Google''
|-
| Afterwards || If Purpose-Driven-Recruitment works -> improve it. Otherwise I'm sure I'll find something to work on ;) 
|}

= Goals / Milestones =
(Note: I added a column "complexity" and filled it with values between 1 (easy) and 3 (complex). This is a rough guess but it helped me to balance the steps between the Milestones.)

{| border="1"
! ID !! PRIORITY !! DESCRIPTION !! COMPLEXITY !! PROGRESS
|-
| 1 || style="width: 110px;" | MANDATORY || Specify configurations and [http://forums.wesnoth.org/viewtopic.php?f=8&t=38885 discuss them in the Forums]. Write the results in [http://wiki.wesnoth.org/User:Flixx/Configuration_Specifications this wikipage]. || 2 || done without feedback
|-
| 2 || MANDATORY || Completely understand the Map Analyses of "Formula AI dev" and write a explanation in [http://wiki.wesnoth.org/User:Flixx/Recruitment_Algorithm_Collection this wikipage]. || 1 || done
|-
| 3 || MANDATORY || Set up a own CA for recruitment, implement a score table. Let units recruit according to some mock values in the score table. || 1 || [https://github.com/flixx/wesnoth-old/commit/fa859891f40203e6aaa61d183eda62e09b83f06e done]
|-
| 4 || OPTIONAL || Collect experimental recruitment algorithms which were written over the last years. Evaluate them and think if they could be of some use. Write results down. || 2 || 80 %
|-
| 5 || OPTIONAL || Think about what to pay attention so all following steps will be implemented to work with multiple leaders. Maybe implement Multiple Leader Support in the current Recruitment Algorithms. || 2 || done

|-
| - || MILESTONE 0|| Have at least all mandatory steps above done when the coding period starts (Jun 16) || 4 + 4 ||

|-
| 6 || MANDATORY || Add Multiple Leader support for the Move_Leader_To_Keep CA. || 2 || [https://github.com/flixx/wesnoth-old/commit/d866480d1a44cb6d02ade98d3fce6f48946ad50d done]
|-
| 7 || OPTIONAL || Make this implementation (Multiple Leader in MLTK CA) 'intelligent', so that it can be decided which leader shall go to a keep. || 3 ||
|-
| 8 || MANDATORY || Refactor the Map Analyses of "Formula AI dev" in C++. || 3 || done
|-
| 9 || MANDATORY || Test implementation of Map Analyses. || 1 || done
|-
| 10 || OPTIONAL || Extract parameters which could later be configured by aspects. || 1 || done
|-
| 11 || OPTIONAL || Batch test Map Analyses (with parameter variations) || 2 ||
|-
| 12 || MANDATORY || Integrate current Combat-Analysis to work with the score map. When weighting the Map-Analysis with 0 the AI should now exactly recruit the same as it did before the refactoring. || 2 || skipped

|-
| - || MILESTONE 1|| Have at least all mandatory steps above done until July 28. || 8 + 6 ||

|-
| 13 || MANDATORY || Refactor current Combat Analysis. || 3 || done
|-
| 14 || OPTIONAL || Extract parameters of Combat Analysis which could later be configured by aspects. Batch Test parameter variations || 2 || done
|-
| 15 || MANDATORY || Implement Counter-Recruitment-Strategies. || 2 || done
|-
| 16 || MANDATORY || Extract parameters of Counter-Recruitment-Strategies which could later be configured by aspects. || 1 || done
|-
| 17 || OPTIONAL || Implement 'Counter-Counter-Recruitment-Strategies' and test it. || 3 || done
|-
| 18 || OPTIONAL || Batch-test and improve Counter- and Counter-Counter Recruitment Strategies. || 2 ||
|-
| 19 || MANDATORY || Implement 'Diversity'. When weighting all other phases with 0 the AI should only recruit units, which are currently rare on the map. || 1 || done
|-
| 20 || MANDATORY || Set up a parameterizable weight-system. || 1 || done
|-
| 21 || MANDATORY || Batch-test with different weights. Document results in this wiki page, define default weights (they will be normalized to 1 for easy configuration then) || 3 || done / not necessary

|-
| - || MILESTONE 2|| Have at least all mandatory steps above done until Aug 25. || 11 + 7 ||

|-
| 22 || MANDATORY || Review Configuration Specifications from Step 1 and adjust them if necessary. || 1 || done
|-
| 23 || MANDATORY || Define Aspects for the Configurations and implement missing aspects (like 'recruit-more=') and make them work with the score map. || 3 || done
|-
| 24 || MANDATORY || Test those new aspects. || 2 || done
|-
| 25 || MANDATORY || Write a separate wikipage for scenario-editors about those aspects and provide some examples and describe use-cases. || 2 || [[AI_Recruitment|done]]
|-
| 26 || MANDATORY || Test recruitment with multiple leaders (I should implement and test every step with multiple leaders so there is hopefully not much to do here) || 1 || done
|-
| 27 || OPTIONAL || Introduce a purpose memory for the AI-Units || 2 ||
|-
| 28 || OPTIONAL || Implement a Proof of Concept for my Purpose-Driven-Recruitment Idea || 3 ||
|-
| 29 || OPTIONAL || Test this Implementation. || 2 ||
|-
| 30 || OPTIONAL || If successful write further steps for Purpose-Driven-Recruitment in a wikipage (e.g. how the purposes could be work in other phases) || 2 ||
|-
| 31 || || Clean everything up and document || n/a ||

|-
| - || MILESTONE 3|| Have at least all mandatory steps above done until Sep 23. || 9 + 9 ||
|}

=IRC=
flix
=Questionnaire=

'''1) Basics'''

'''1.1) Write a small introduction to yourself.'''

Hi! I'm Felix, 22 and from Germany/Berlin. I'm currently as a exchange student in Amman/Jordan (until June) studying Computer Science at Princess Sumaya University for Technology.

'''1.2) State your preferred email address.'''

I will add my address in the google application.

'''1.3) If you have chosen a nick for IRC and Wesnoth forums, what is it?'''

flix

'''1.4) Why do you want to participate in summer of code?'''

I've played with the thought to join a Open Source Community for some time now. And GSoC seems like a great way to to this. I admire the idea of Open Source and the way how international communities can assemble such great software!

'''1.5) What are you studying, subject, level and school?'''

When I'm not in Jordan I study something fancy called "Science in the Information Society" at Technical University in Berlin. I'm currently in my 3rd year. This courses are great because we have over 50% optional courses and we could study nearly anything (Physics, Math, Chemistry, ...) I chose to focus on Computer Science very early (in my first year). So I had a lot courses with the Computer Scientists and consider myself at the same level as a Computer Scientist in his/her 3rd year.

Here in Jordan I learnt to love [http://en.wikipedia.org/wiki/Massive_open_online_course MOOCs]. I mention this because I also finished the course [https://www.edx.org/courses/BerkeleyX/CS188.1x/2012_Fall/about Artificial Intelligence (BerkeleyX)] It was the best course I ever had (online and offline).

'''1.6) What country are you from, at what time are you most likely to be able to join IRC?'''

Germany (UTC+01:00) My favorite time to work is between 4 pm and 2 am. Although I'm quite flexible with times and can try to be online when my mentor is.

<div id="time"></div>
'''1.7) Do you have other commitments for the summer period ? Do you plan to take any vacations ? If yes, when.'''

Yes! I'm currently in Amman/Jordan as a exchange student. I will go back to Germany on the 24th of June. And around this date I need some time off. More specific: I'm only partly available from 18th of June to the 1st of July.

Apart from that I have no other commitments and would consider SoC as a full-time job. Also I can start early (before 18th of June) to work on my project.

'''2) Experience'''

'''2.1) What programs/software have you worked on before?'''
*In High-school I started to tweak phpBB for my purposes (don't work on this anymore)
*In my first year in university I developed for a project a AI for the Game [http://en.wikipedia.org/wiki/Hive_(game) Hive] (Java).
*I'm currently developing a mobile-tagging software for images in Java (Tomcat Server) and Android.

'''2.2) Have you developed software in a team environment before? (As opposed to hacking on something on your own)'''

Yes, for the AI I mentioned for example (team of 8). I strongly prefer to develop in teams.

'''2.3) Have you participated to the Google Summer of Code before? As a mentor or a student? In what project? Were you successful? If not, why?'''

No.

'''2.4) Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.'''

No, I'm not :(

'''2.5) Gaming experience - Are you a gamer?'''

I wouldn't consider myself as a gamer...

'''2.5.1) What type of gamer are you?'''

...although I love to play once in while. Especially multi-player games with friends.
In a month I maybe play 6 nights long ;)

'''2.5.2) What type of games?'''

*Turnbased Stategy games like Wesnoth, Civilisations,
*Old-school realtime strategy games like Empire Earth, WarcraftIII

'''2.5.3) What type of opponents do you prefer?'''

I prefer AI opponents.

'''2.5.4) Are you more interested in story or gameplay?'''

Definitely gameplay. I'm a story-skipper ;).

'''2.5.5) Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer.'''

I started to play Wesnoth half a year ago and have played it with a friend once in a while since. I play the mainline campaigns too. I like both.

'''2.6) If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our repository (during the evaluation period or earlier) please state so.'''

Yes, I enjoyed it to dig into the code and trying to do some things from the EasyCoding Page.

*[https://gna.org/patch/?3875 Added new aspect 'advancements']
*[https://gna.org/patch/?3849 Improved ai behavior when using goto_x / goto_x in WML]
*[https://gna.org/patch/?3888 Command 'lua wesnoth.debug_ai(side).ai]

*Additionally: Some work on the ai-testing suite and my Game-Theory-Algorithm can be found [https://github.com/flixx/wesnoth-old/tree/game_theory/src/ai/flix here].

'''3) Communication skills'''

'''3.1) Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.'''

Should be more then enough to communicate with the community.

'''3.2) What spoken languages are you fluent in?'''

German, English (Arabic is way too hard ;) )

'''3.3) Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.'''

Yes, I think so.

'''3.4) Do you give constructive advice?'''

When I can, sure!

'''3.5) Do you receive advice well?'''

Depends on who want to advice me. But in general of course!

'''3.6) Are you good at sorting useful criticisms from useless ones?'''

I think so, yes.

'''3.7) How autonomous are you when developing ? Would you rather discuss intensively changes and not start coding until you know what you want to do or would you rather code a proof of concept to "see how it turn out", taking the risk of having it thrown away if it doesn't match what the project want'''

I think I am the autonomous developer who would code a proof of concept.
Although since i'm new to this community I would definitively ask questions and discuss the project goals so the risk of failing them is minimized.

I always try to figure out problems of technical nature myself.

'''4) Project'''

'''4.1) Did you select a project from our list? If that is the case, what project did you select? What do you want to especially concentrate on?'''

The Project "AI Refactor recruitment algorithm".

'''4.2) If you have invented your own project, please describe the project and the scope.'''

-

'''4.3) Why did you choose this project?'''

Basically because Crab_ said so ;). When I first read the project page I wanted to do the "defensive AI" project. But after some advice I concentrated on the Recruitment Idea. And meanwhile I really like this Idea and prefer it over the others. I would love to improve the AIs recruitment.

'''4.4) Include an estimated timeline for your work on the project. Don't forget to mention special things like "I booked holidays between A and B" and "I got an exam at ABC and won't be doing much then".'''

See above.

'''4.5) Include as much technical detail about your implementation as you can'''

See above.

'''4.6) What do you expect to gain from this project?'''

I would finally be part of a Open Source Community. Furthermore I expect to gain experience in C++ (and Lua). I'm quite new to C++ and I think Wesnoth is great for improving C++-skills.

'''4.7) What would make you stay in the Wesnoth community after the conclusion of SOC? '''

A failed project would be demotivating, but otherwise I would love to stay in the community if I find some time when university starts again.

'''5) Practical considerations'''

'''5.1) Are you familiar with any of the following tools or languages?'''

*'''Git (used for all commits)'''
**Yes
*'''C++ (language used for all the normal source code)'''
**I'm new to C++. But since I worked on some patches I've already learned a lot and feel capable to work with Wesnoth's code.
*'''STL, Boost, Sdl (C++ libraries used by Wesnoth)'''
**I've heard of it and made use of it in the patches, but without big background knowledge.
*'''Python (optional, mainly used for tools)'''
**Yes
*'''build environments (eg cmake/scons)'''
**I know how to build. That's it.
*'''WML (the wesnoth specific scenario language)'''
**Yes
*'''Lua (used in combination with WML to create scenarios)'''
**Not really, but ironically I know how C++ and Lua are communicating through the Lua Stack since I worked on two patches dealing with this. Lua seems easy enough though.

'''5.2) Which tools do you normally use for development? Why do you use them?'''

I use Eclipse on ubuntu. I am used to it from Java development.

'''5.3) What programming languages are you fluent in?'''

I list them from most fluent to *I have coded once with it*

Java, Python, PHP, C++, JavaScript, Ruby, Scala, Pearl, Lua.

'''5.4) Would you mind talking with your mentor on telephone / internet phone? We would like to have a backup way for communications for the case that somehow emails and IRC do fail. If you are willing to do so, please do list a phone number (including international code) so that we are able to contact you. You should probably *only* add this number in the application for you submit to google since the info in the wiki is available in public. We will *not* make any use of your number unless some case of "there is no way to contact you" does arise!'''

I will add my number in the google application.

AI Recruitment

2013-09-14T17:02:19Z

Flixx: /* Aspect recruitment_instruction */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-14T16:56:40Z

Flixx: /* Examples */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-14T13:07:47Z

Flixx: /* Examples */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-13T16:06:40Z

Flixx: /* Other aspects */

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-13T16:01:24Z

Flixx:

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-13T15:58:38Z

Flixx: /* Some notes on multiple leaders */

'''This page is work in progress'''

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

AI Recruitment

2013-09-13T15:54:11Z

Flixx: /* Other aspects */

'''This page is work in progress'''

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units then fulfilling the ratios given in the <code>recruitment_pattern</code>.

AI Recruitment

2013-09-13T15:51:59Z

Flixx: /* Other aspects */

'''This page is work in progress'''

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also UnitTypeWML).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units then fulfilling the ratios given in the <code>recruitment_pattern</code>.

AI Recruitment

2013-09-13T15:50:40Z

Flixx: /* Other aspects */

'''This page is work in progress'''

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> is possible to add 50.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also UnitTypeWML).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units then fulfilling the ratios given in the <code>recruitment_pattern</code>.

AI Recruitment

2013-09-13T15:49:48Z

Flixx: /* Other aspects */

'''This page is work in progress'''

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-types score.) <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> is possible to add 50.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also UnitTypeWML).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units then fulfilling the ratios given in the <code>recruitment_pattern</code>.

AI Recruitment

2013-09-13T15:47:38Z

Flixx: /* Example */

'''This page is work in progress'''

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make a easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-types score). <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> is possible to add 50.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also UnitTypeWML).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units then fulfilling the ratios given in the <code>recruitment_pattern</code>.

AI Recruitment

2013-09-13T15:45:54Z

Flixx: /* The Aspect */

'''This page is work in progress'''

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the team's start gold + 1.

==Example==
This example is filled with all default values and there for quick coping.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make a easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-types score). <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> is possible to add 50.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also UnitTypeWML).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units then fulfilling the ratios given in the <code>recruitment_pattern</code>.

AI Recruitment

2013-09-13T15:44:05Z

Flixx: /* How it works */

'''This page is work in progress'''

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code> ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the teams start gold + 1.

==Example==
This example is filled with all default values and there for quick coping.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make a easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-types score). <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> is possible to add 50.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also UnitTypeWML).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units then fulfilling the ratios given in the <code>recruitment_pattern</code>.

AI Recruitment

2013-09-13T15:38:52Z

Flixx: /* How it works */

'''This page is work in progress'''

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it is a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI doesn't recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

One can imagine that the AI can save quite a lot of gold with this behavior. But saving gold forever is senseless. So when the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start a offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. That happens when a enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code> ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the teams start gold + 1.

==Example==
This example is filled with all default values and there for quick coping.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make a easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-types score). <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> is possible to add 50.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also UnitTypeWML).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units then fulfilling the ratios given in the <code>recruitment_pattern</code>.

AI Recruitment

2013-09-13T15:33:05Z

Flixx: /* Examples */

'''This page is work in progress'''

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
Sometimes it's a good idea not to spend all gold immediately for several reasons:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save money for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in "waves" (in contrary to recruit one unit each turn).

For this we have the aspect "recruitment_save_gold".

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a "unit_ratio". This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ("begin") '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI doesn't recruit units anymore until the unit_ratio falls below another predefined threshold ("end"). Then the AI will switch to the NORMAL state and recruit again.

One can imagine that the AI can save quite a lot of gold with this behavior. But saving gold forever is senseless. So when the AI has more gold then a predefined value ("spend_all_gold"), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start a offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. That happens when a enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code> ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the teams start gold + 1.

==Example==
This example is filled with all default values and there for quick coping.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make a easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-types score). <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> is possible to add 50.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also UnitTypeWML).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units then fulfilling the ratios given in the <code>recruitment_pattern</code>.

AI Recruitment

2013-09-13T15:25:26Z

Flixx: /* Examples */

'''This page is work in progress'''

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader 2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit always random units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work. Only one facet can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one have to create a facet for turn 1-2, a facet for turn 3 and another facet for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
Sometimes it's a good idea not to spend all gold immediately for several reasons:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save money for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in "waves" (in contrary to recruit one unit each turn).

For this we have the aspect "recruitment_save_gold".

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a "unit_ratio". This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ("begin") '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI doesn't recruit units anymore until the unit_ratio falls below another predefined threshold ("end"). Then the AI will switch to the NORMAL state and recruit again.

One can imagine that the AI can save quite a lot of gold with this behavior. But saving gold forever is senseless. So when the AI has more gold then a predefined value ("spend_all_gold"), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start a offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. That happens when a enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code> ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the teams start gold + 1.

==Example==
This example is filled with all default values and there for quick coping.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make a easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-types score). <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> is possible to add 50.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also UnitTypeWML).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units then fulfilling the ratios given in the <code>recruitment_pattern</code>.

AI Recruitment

2013-09-13T15:15:31Z

Flixx: /* Aspect recruitment_instruction */

'''This page is work in progress'''

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit so, that there are at least 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader 2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit always random units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work. Only one facet can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one have to create a facet for turn 1-2, a facet for turn 3 and another facet for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
Sometimes it's a good idea not to spend all gold immediately for several reasons:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save money for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in "waves" (in contrary to recruit one unit each turn).

For this we have the aspect "recruitment_save_gold".

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a "unit_ratio". This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ("begin") '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI doesn't recruit units anymore until the unit_ratio falls below another predefined threshold ("end"). Then the AI will switch to the NORMAL state and recruit again.

One can imagine that the AI can save quite a lot of gold with this behavior. But saving gold forever is senseless. So when the AI has more gold then a predefined value ("spend_all_gold"), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start a offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. That happens when a enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code> ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the teams start gold + 1.

==Example==
This example is filled with all default values and there for quick coping.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make a easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-types score). <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> is possible to add 50.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also UnitTypeWML).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units then fulfilling the ratios given in the <code>recruitment_pattern</code>.

AI Recruitment

2013-09-13T15:13:21Z

Flixx: /* Aspect recruitment_instruction */

'''This page is work in progress'''

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* By default when recruitment is specified for a turn, the AI will '''not recruit any other unit'''. (So if we say recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit so, that there are at least 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader 2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit always random units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work. Only one facet can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one have to create a facet for turn 1-2, a facet for turn 3 and another facet for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
Sometimes it's a good idea not to spend all gold immediately for several reasons:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save money for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in "waves" (in contrary to recruit one unit each turn).

For this we have the aspect "recruitment_save_gold".

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a "unit_ratio". This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ("begin") '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI doesn't recruit units anymore until the unit_ratio falls below another predefined threshold ("end"). Then the AI will switch to the NORMAL state and recruit again.

One can imagine that the AI can save quite a lot of gold with this behavior. But saving gold forever is senseless. So when the AI has more gold then a predefined value ("spend_all_gold"), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start a offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. That happens when a enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code> ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the teams start gold + 1.

==Example==
This example is filled with all default values and there for quick coping.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make a easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-types score). <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> is possible to add 50.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also UnitTypeWML).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units then fulfilling the ratios given in the <code>recruitment_pattern</code>.

AI Recruitment

2013-09-13T15:11:07Z

Flixx: /* Aspect recruitment_instruction */

'''This page is work in progress'''

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'', the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes, the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing the unit-type, usage or level. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* By default when recruitment is specified for a turn, the AI will '''not recruit any other unit'''. (So if we say recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit so, that there are at least 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader 2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit always random units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work. Only one facet can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one have to create a facet for turn 1-2, a facet for turn 3 and another facet for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
Sometimes it's a good idea not to spend all gold immediately for several reasons:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save money for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in "waves" (in contrary to recruit one unit each turn).

For this we have the aspect "recruitment_save_gold".

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a "unit_ratio". This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ("begin") '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI doesn't recruit units anymore until the unit_ratio falls below another predefined threshold ("end"). Then the AI will switch to the NORMAL state and recruit again.

One can imagine that the AI can save quite a lot of gold with this behavior. But saving gold forever is senseless. So when the AI has more gold then a predefined value ("spend_all_gold"), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start a offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. That happens when a enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code> ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the teams start gold + 1.

==Example==
This example is filled with all default values and there for quick coping.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make a easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-types score). <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> is possible to add 50.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also UnitTypeWML).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units then fulfilling the ratios given in the <code>recruitment_pattern</code>.

AI Recruitment

2013-09-13T15:08:09Z

Flixx: /* Aspect recruitment_instruction */

'''This page is work in progress'''

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified has no free hexes)
* '''total=no: (boolean)''' When total is set to ''yes'' the AI will count the own units on the map which matches at least one of the given types and will then recruit the difference between ''number'' and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'', the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes, the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing the unit-type, usage or level. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* By default when recruitment is specified for a turn, the AI will '''not recruit any other unit'''. (So if we say recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit so, that there are at least 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader 2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit always random units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work. Only one facet can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one have to create a facet for turn 1-2, a facet for turn 3 and another facet for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
Sometimes it's a good idea not to spend all gold immediately for several reasons:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save money for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in "waves" (in contrary to recruit one unit each turn).

For this we have the aspect "recruitment_save_gold".

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a "unit_ratio". This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ("begin") '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI doesn't recruit units anymore until the unit_ratio falls below another predefined threshold ("end"). Then the AI will switch to the NORMAL state and recruit again.

One can imagine that the AI can save quite a lot of gold with this behavior. But saving gold forever is senseless. So when the AI has more gold then a predefined value ("spend_all_gold"), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start a offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. That happens when a enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code> ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the teams start gold + 1.

==Example==
This example is filled with all default values and there for quick coping.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make a easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-types score). <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> is possible to add 50.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also UnitTypeWML).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units then fulfilling the ratios given in the <code>recruitment_pattern</code>.

AI Recruitment

2013-09-13T15:01:34Z

Flixx: /* Aspect recruitment_instruction */

'''This page is work in progress'''

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode the important hexes are marked with a white dot.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (1.5 * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment-instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing the unit-type, usage or level. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. A empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader which shall execute this job. Empty sting means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function check_recruit_action() in contexts.hpp will automatically choose another leader if the specified hasn't any free hexes)
* '''total=no: (boolean)''' When total is set to ''yes'' the AI will count the own units on the map which matches at least one of the given types and will then recruit the difference between ''number'' and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'', the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes, the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing the unit-type, usage or level. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* By default when recruitment is specified for a turn, the AI will '''not recruit any other unit'''. (So if we say recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit so, that there are at least 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader 2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit always random units.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment-instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]

This will not work. Only one facet can be active.
[ai]
[aspect]
id=recruitment-instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one have to create a facet for turn 1-2, a facet for turn 3 and another facet for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
Sometimes it's a good idea not to spend all gold immediately for several reasons:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save money for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in "waves" (in contrary to recruit one unit each turn).

For this we have the aspect "recruitment_save_gold".

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a "unit_ratio". This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ("begin") '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI doesn't recruit units anymore until the unit_ratio falls below another predefined threshold ("end"). Then the AI will switch to the NORMAL state and recruit again.

One can imagine that the AI can save quite a lot of gold with this behavior. But saving gold forever is senseless. So when the AI has more gold then a predefined value ("spend_all_gold"), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start a offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. That happens when a enemy is near the leader (3 hexes).

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code> ''(with default values)''
* '''active=yes: (boolean)''' If <code>active=no</code> the AI will always recruit if gold is available.
* '''begin=1.0: (double)''' See explanation above.
* '''end=0.7: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the value will automatically set to the teams start gold + 1.

==Example==
This example is filled with all default values and there for quick coping.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=yes
begin=1.0
end=0.7
spend_all_gold=-1
[/value]
[/facet]
[/aspect]
[/ai]

=Other aspects=
*'''recruitment_diversity'''=1.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. (recruitment_diversity * 25 will be added to each score).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make a easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-types score). <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> is possible to add 50.
*'''recruitment_randomness'''=15 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also UnitTypeWML).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''villages_per_scout'''=4 (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

==Some notes on multiple leaders==
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units then fulfilling the ratios given in the <code>recruitment_pattern</code>.