WritingYourOwnAI

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 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 -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.

WritingYourOwnAI

Contents