== Note ==
'''THIS PAGE IS UNDER CONSTRUCTION.'''

== Writing your own AI ==

Wesnoth supports a pluggable AI system that allows programmers to write their own AIs in C++ or Python.
You might like to look this over before starting: [[WhyWritingAWesnothAIIsHard]]

== Python ==

For information on the Python AI API look at [[ReferencePythonAPI]].

== C++ ==

The rest of this page describes the C++ AI API. To write an AI in C++, you need to derive a class from ''ai_interface'' (defined in '''ai.hpp'''), and implement the function ''play_turn()'' which will be called every time your AI is expected to play a turn.

Class ''ai_interface'' contains three important functions
which allow you to execute the three basic types of move available in the game:

* ''attack_enemy()'', which is used to order an attack on an enemy unit,
* ''move_unit()'', which is used to order a unit to move from one location to another, and
* ''recruit()'', which is used to recruit a new unit.

Of course, to decide where units are to move and attack, you must have information about the state of the game - the dimensions and layout of the map, the locations and type of units on the map, the types of units your side can recruit, and information about your allies and enemies.

Firstly, a type ''location'' is defined, which defines any location on the map. It has members ''x'' and ''y''. In '''pathfind.hpp''' there are a number of functions which will tell you useful things about locations -- whether two locations
are adjacent, all the locations adjacent to a certain location,
and the distance between locations.

A type ''move_map'' is defined as a ''std::multimap<location,location>''. Note that ''std::multimap'' is of course a standard C++ container, and cannot be documented here. http://www.sgi.com/tech/stl/ is a good reference on standard C++ containers. The purpose of a ''move_map'' is to show all the possible moves for a side. It can either be a ''source -> destination'' map, which associates the locations of all the units a side has to all the possible places they can move to, or a ''destination -> source'' map, which associates all the locations all the units a side has can get to, to all the places they are now.

The function ''calculate_possible_moves()'' is provided
as a useful utility function. It can give you maps for where all
your units can move, or where all your enemy's movements
can move when it's their turn. This is a very important
function to use to work out all the possible places your units can move to.

''ai_interface'' also defines an ''info'' type. This type contains a number of references to various game objects which you
will need access to in order to make moves. The two most important of these objects are the unit map (unit_map units)
and the game map (gamemap map).

The unit map is of type ''std::map<location,unit>''
and associates locations with units. This object can be used to find the location of, and information about, every unit on the board. See '''unit.hpp''' for a definition of the ''unit'' object.

The game map allows you to inspect the dimensions and layout of the playing board. Given a location, it can tell you the
terrain type at that location. See '''map.hpp''' for a definition of this object. You can combine this class with use of the functions in '''pathfind.hpp''' to find various
information about where units can move to.

The team class (defined in '''team.hpp''') is also very important. Each side is represented by a ''team'' object. The team object can tell you the gold balance of a team, which villages (note that internally, villages are often called 'towers') the team owns, what units the team can recruit,
and which other teams are this teams friends or enemies.

The utility function ''current_team()'' can be used to get a reference to the team that your AI is in control of, but you
can also use the vector ''teams'' inside the info object to get a list of all teams.

If you want to make your AI customizable within the configuration file, you can gain access to any parameters passed to your AI using ''team::ai_parameters()''. This returns an object of type ''config'' (see '''config.hpp'''). These ''config'' objects are representations of WML document fragments. When the user defines your side, if they put an [ai] tag inside it, everything inside the [ai] tag will be returned by ''team::ai_parameters()''.

== Using your AI ==

Finally, when you have your AI ready to go, you can add it to the ''create_ai()'' function in '''ai.cpp'''. Suppose you called your class ''killer_ai'', you could add it like so:

if(name == "killer_ai")
return new killer_ai(info);

Then, you can define a side to use your AI in [[ReferenceWML|WML]]:

ai_algorithm=killer_ai

and when that side is created, it'll use your AI!

== An example ==

Let us conclude with a small sample AI, called ''sample_ai''. How should this AI behave?

* First it should detect if there are any enemies in range,
and if there are it should attack them by moving onto the
best defensive terrain next to them. Attacks should be made with the weapon for which damage*strikes*chance to hit is
the highest.
* If there are no enemies in range, it should move units onto villages that don't already belong to it.
* If there are no enemies or villages in range, it should move toward the enemy leader along the shortest possible route.
* At the end of its turn, it should recruit random units until it runs out of money or doesn't have any space.

In the following example, I will place all functions in-line
rather than in the cpp file. To do this properly, of course you should put them in the cpp file. The entire definition of this AI can be found in '''ai.cpp''' and '''ai.hpp''' in the source distribution.

We start the definition,

class sample_ai : public ai_interface {
public:
sample_ai(info& i) : ai_interface(i) {}

We have defined the constructor which takes an ''info'' object
and passes it straight onto ai_interface. We don't need to
store anything ourselves in this simple AI. (Although it would be fine to have data members if we wanted them.)

Next we define the main function, ''play_turn()'':

void play_turn() {
do_attacks();
get_villages();
do_moves();
do_recruitment();
}

Just a series of calls to functions we are about to write which do the actual work. Firstly, ''do_attacks()''. We start by
calculating all the moves our units can make:

private:
void do_attacks() {
std::map<location,paths> possible_moves;
move_map srcdst, dstsrc;
calculate_possible_moves(possible_moves,srcdst,dstsrc,false);

Note that the ''possible_moves'' thing is of little direct interest. It contains details of exactly which tiles the unit
moves along to get from one tile to another. This is useful for the display to know about when it draws the unit moving, but as an AI programmer, it's not likely you'll ever care about
what it contains. Just pass it along to the ''move_unit()'' function so it can draw the unit moving along the correct path.

The things we're interested in are ''srcdst'', and especially ''dstsrc'', which will tell us all the hexes our units can reach.
We want to check if any of these hexes are next to an enemy unit. Let's walk over the units and see if we can reach any of them:

for(unit_map::const_iterator i = get_info().units.begin(); i != get_info().units.end(); ++i) {
if(current_team().is_enemy(i->second.side()) {

We're iterating over all units, but we're only interested in units that are enemies of our side. So, we access our team object, and ask if the side the unit is on is an enemy. If it is, then we're interested in seeing if any of our units can move to a hex that's adjacent to the enemy unit. We do this by getting the six locations around the enemy unit:

location adjacent_tiles[6];
get_adjacent_tiles(i->first,adjacent_tiles);

This kind of call is very common in the game's code -- make an array of 6 locations, and fill them up with the locations adjacent to a certain location. We actually want to find the position to attack from which gives our unit the best possible defense. So, we initialize some variables to find the best possible defense:

int best_defense = -1;
std::pair<location,location> best_movement;

The value of ''best_defense'' will of course be between 1 and 100, but we give it a value of -1 to mean 'not initialized', since we haven't found any possible attacks at all yet. Variable ''best_movement'' will contain the destination/source pair that gives the best possible defense for our attacking unit.

for(size_t n = 0; n != 6; ++n) {
typedef move_map::const_iterator Itor;
std::pair<Itor,Itor> range = dstsrc.equal_range(adjacent_tiles[n]);

If you don't understand how ''equal_range'' works, then look up documentation on how the standard container multimap works. ''range'' now refers to all the possible movements that can end
with our unit being at ''adjacent_tiles[n]''. Let's iterate over all those movements, and find if any of them give a better defensive rating than our current best defense. We'll start our iteration by creating some aliases that ensure we don't go crazy ;)

while(range.first != range.second) {
const location& dst = range.first->first;
const location& src = range.first->second;

Now let's find out about the unit that we're planning to send to this destination:

const unit_map::const_iterator un = get_info().units.find(src);
assert(un != get_info().units.end());

We can assume that the unit is in that location (hence the assert), because ''calculate_possible_moves()'' said that it's the possible source of a move. Let's find out the type of terrain we're planning to move to:

const gamemap::TERRAIN terrain = get_info().map.get_terrain(dst);

Okay, so we have the unit, and we have the terrain, now we should be able to find out the unit's defensive rating on this terrain.
The ''unit'' class has a convenient ''defense_modifier()'' function which will tell us the chance of hitting that unit on a certain terrain.

const int chance_to_hit = un->second.defense_modifier(get_info().map,terrain);

So, now we have all that, if it's the best chance to hit we've seen so far, or we haven't seen any other chances to hit at all, then we add it as our best option seen.

if(best_defense == -1 || chance_to_hit < best_defense) {
best_defense = chance_to_hit;
best_movement = *range.first;
}

That's it for these two loops. Iterate and close:

++range.first;
}
}

Now if we found a possible move, best_defense will not be -1,
and the movement will be stored in ''best_movement''. So, if ''best_defense'' is not -1, we want to move from ''best_movement.second'' to ''best_movement.first''.

if(best_defense != -1) {
move_unit(best_movement.second,best_movement.first,possible_moves);

Remember that ''possible_moves'' thing? That comes in useful here, where we have to give it to the display object so it can know the path to move the unit along. This is the only time we need to touch it.

Immediately after moving, we want to attack. First we need to know which weapon to use. We'll write a ''choose_weapon()''
function later which will choose our weapon. It'll have to take the location of the attacker and the location of the defender, and it'll return an int referring to our weapon of choice. For now we'll just make use of this function:

const int weapon = choose_weapon(best_movement.first,i->first);
attack_enemy(best_movement.first,i->first,weapon);

This will implement our attack. What now? We've attacked once, but we want to attack with as many units as we can attack with, right? We can't use the same move_maps again, because they'll be invalid now that we've moved and attacked. What we'll do is we'll call ''do_attacks()'' all over again, recursively, and return immediately. This way all our maps will be recalculated.

do_attacks();
return;
}
}
}
}

That's the entire function done. It'll keep attacking while it finds attacks, and when it finally runs out of attacks to execute, it'll return nicely. Let's write that ''choose_weapon()'' function now:

int choose_weapon(const location& attacker, const location& defender) {
const unit_map::const_iterator att = get_info().units.find(attacker);
assert(att != get_info().units.end());

const std::vector<a ttack_type>& attacks = att->second.attacks();

unit contains a convenient ''attacks()'' function which returns a vector of all a unit's possible attacks. We'll store the
best attack found so far, and iterate over all attacks:

int best_attack_rating = -1;
int best_attack = -1;
for(int n = 0; n != attacks.size(); ++n) {

There is a nice function called ''evaluate_battle_stats()'' in '''actions.hpp''' which will give us all sorts of information about a potential battle. We make use of it here:

const battle_stats stats = evaluate_battle_stats(get_info().map,
attacker, defender, n, get_info().units,
get_info().state, get_info().gameinfo, 0, false);

A rather complicated function call, but most of the parameters can be pulled straight from ''get_info()''. The last two parameters are a little confusing. The first one of these, ''attacker_terrain_override'', is used if we wanted to know what the combat would look like if the attacker was on different terrain to what it is on now. If this is non-0, the function will assume the attacker is on the type of terrain given. This is useful if you want to test the possibility of moving to many different hexes without actually moving there. The last parameter is false, meaning that strings won't be included in the results. Strings are useful for showing to a player in a dialog,
but not useful for an AI, and are expensive to calculate, so this should always be false from within AI algorithms.

Let's use our stats to come up with a rating for this attack:

const int attack_rating = stats.damage_defender_takes*stats.nattacks*stats.chance_to_hit_defender;

Now if this is the best attack, we can use it,

if(best_attack == -1 || attack_rating > best_attack_rating) {
best_attack = n;
best_attack_rating = attack_rating;
}
}

return best_attack;
}

Now we're done with that, we can move onto our ''get_villages()'' function. We start off by calculating possible moves,

void get_villages() {
std::map<location,paths> possible_moves;
move_map srcdst, dstsrc;
calculate_possible_moves(possible_moves,srcdst,dstsrc,false);

Now it's a simple matter of iterating over possible destinations,
and seeing if they are villages not controlled by us:

for(move_map::const_iterator i = dstsrc.begin(); i != dstsrc.end(); ++i) {
if(get_info().map.is_village(i->first) &&
current_team().owns_village(i->first) == false) {

First it checks whether the destination is a village. The right side of the ''&&'' simply sees if our team owns the village at that location or not. If we don't own the village, we've found the movement we want to make, and we recurse and return.

move_unit(i->second,i->first,possible_moves);
get_villages();
return;
}
}
}

Just a couple more functions now. Firstly, ''do_moves()'' is meant to move our units toward the enemy leader. Well, there may be multiple enemies and thus more than one leader, so we'll just go for the first enemy leader we can find. We start off by trying to find the enemy leader:

void move_units() {
unit_map::const_iterator leader;
for(leader = get_info().units.begin(); leader != get_info().units.end(); ++leader) {

A unit is a leader if it can recruit -- so we use the ''can_recruit()'' function to test if it's a leader.

if(leader->second.can_recruit() && current_team().is_enemy(leader->second.side())) {
break;
}
}

We better have found an enemy leader, otherwise we'll just return...

if(leader == get_info().units.end())
return;

Now, let's find all our unit's possible moves:

std::map<location,paths> possible_moves;
move_map srcdst, dstsrc;
calculate_possible_moves(possible_moves,srcdst,dstsrc,false);

We want to find the move that'll take us as close as possible to the enemy leader. Let's make our variables to show us the best move so far,

int closest_distance = -1;
std::pair<location,location> closest_move;

Now iterate and find the destination closest to the enemy leader:

for(move_map::const_iterator i = dstsrc.begin(); i != dstsrc.end(); ++i) {
const int distance = distance_between(i->first,leader->first);
if(closest_distance == -1 || distance < closest_distance) {
closest_distance = distance;
closest_move = *i;
}
}

If ''closest_distance'' is not -1, we've found a valid move that'll take one of our units toward the enemy leader. We can make the move and recurse

if(closest_distance != -1) {
move_unit(closest_move.second,closest_move.first,possible_moves);
do_moves();
}
}

Okay, all our movement functions are done! Now all we've got left is the recruitment function. We start by getting the units that we can recruit.

void do_recruitment() {
const std::set<std::string>& options = current_team().recruits();

We can choose the number of a unit to recruit at random:

const int choice = (rand()%options.size());
std::set<std::string>::const_iterator i = options.begin();
std::advance(i,choice);
const bool res = recruit(*i);

And if the recruitment succeeds, we will try to recruit another unit,

if(res) {
do_recruitment();
}
}
};

That's it! We've made our ''sample_ai''. All we have to do is add it to ''create_ai'' in '''ai.cpp''' and we're done!

== AI - specific parameters ==

wesnoth --multiplayer --controller1=ai --controller2=ai --algorithm1=z_ai --algorithm2=sample_ai

Use the ''--nogui'' switch before ''--multiplayer'' to make the game run without displaying a GUI. The winner will be reported on stdout.

== See Also ==

* [[DeveloperResources]]
* [[PythonTestScript]] - Simple Python AI test script

[[Category:Create]]
[[Category:AI]]