Making An AI With Echo (part 1)

Introduction

Echo is the new subsystem for AI's. While Echo does not replace all of the existing AI system, it does provide a new interface to Glob2, and a large set of tools for making AI's. It can save allot of time, you would understand if you've made an AI without Echo.

You should read New AI System to get a general view of how Echo works before proceeding. You can also view nightly generated code documentation (Available from the Developer Center), which includes all of Echo's classes.

Getting Started

First of all, you have to create your AI files. In glob2/src, you can add AI*.h and AI*.cpp, where * is whatever your AI is called. Next, you need to add copyright statements to your files. Find any other source file, and copy&paste the copyright statements from the top of it to the top of your AI*.h and AI*.cpp files, replacing the name on the copyright statements with your name. Next, open up Makefile.am in glob2/src. You'll notice a list of source files, add your AI*.h and AI*.cpp to their correct position alphabetically. Add in header guards to your header file, and you're ready to move on.

Now, we need to copy your AI structure over. Open up AIEcho.h, scroll about 3/4 of the way down. You're looking for a class called "EchoAI". When you find it, copy it over to your AI*.h. Remove all of the virtuals and =0's from the functions, and replace EchoAI with the name of your AI. Publicly derive your class from AIEcho::EchoAI, and add #include "AIEcho.h" to the top of your file. Now, implement all of the functions in your AI in the source file, as simple, empty functions (you won't be adding code yet).

Finally, we need to make your AI recognized by Glob2. You can use ReachToInfinity as an example Echo AI here. Open up AI.h and AI.cpp. At the top of AI.h, you'll find an enum with all of the AI names in uppercase. Add yours after all of the AI's, but before the "SIZE" variable. In AI.cpp, add the #include "AI*.h" at the top for your AI. Now, you're going to change the AI constructor. You'll see a switch statement at the top of the constructor (which should be at the top of the file). Add in a case statement for your AI. Then, set up a your initializer like the following:

 aiImplementation=new AIEcho::Echo(new your_ai_name, player);

Remember to replace your_ai_name with the name of you're actual AI. Now, scroll down the file further until you see another switch statement in AI::load. Add you're AI to this one as well with the following lines

 aiImplementation=new AIEcho::Echo(new your_ai_name, player);
 aiImplementation->load(stream, player, versionMinor);

We have one last thing to do, and that is to add your AI name to the translations. In glob2/data, you will see a bunch of texts.*.txt files for all of the translations. Open up texts.keys.txt, and scroll down to where the AI's are (you can search for [AI] in your text editor to make this faster). Add your AI name as a key in this file, under or arround the others. Now, add it to the English translation (texts.en.txt). To propogate your change throughout all the translation files, execute the check_translations script as so (in the data directory):

 python check_translations.py

In AI.cpp, near the bottom in AI::getAIText, add your translation here as well, using the same key you put in the translation files.

That was a lot of work just to make a new AI. However, you'll find it's well worth your time. You can compile everything, load the game up, and see your now-empty AI do its work. It's time to start implementing your AI! It's recommended you add "using namespace " to the top of your source file for all of the namespaces located in AIEcho.h (they are conveniently prototyped at the top of the file).

Constructing Buildings and Flags

How to

For starters, you need to make a BuildingOrder. This is an order that will be passed to Echo once you have provided all of the information to construct a building. A BuildingOrder takes two things in its constructor, the building type (available from IntBuildingType.h, remember to use IntBuildingType::SWARM_BUILDING, instead of just SWARM_BUILDING, and likewise for other buildings), and the number of workers that will be used to construct the building. After you've created the building order, you now need to add constraints to the order to choose where the building will be located.

Constraints are added via BuildingOrder::add_constraint. There are six constraints to choose from:

• MaximumDistance - can't be to far from a provided object. Takes a GradientInfo and an integer for maximum distance.
• MinimumDistance - can't be to close to a provided object. Takes a GradientInfo and an integer for minimum distance.
• MaximizedDistance - preferably farther than a provided object, but can be close. Takes a GradientInfo and an integer for weight, affecting how much this effect this constraint has on the final result.
• MinimizedDistance - preferably closer to a provided object, but can be far. Takes a GradientInfo and an integer for weight, affecting how much this effect this constraint has on the final result.
• CenteredOfBuilding - A special constraint that only allows the building/flag to be centered on another, provided building. Usefull for flags, to center them on an enemy. Will be discussed later.
• SinglePosition - A special constraint that only allows the building/flag to be centered on the provided x and y cordinates that it takes in its constructor.

To use one of the first four constraints, however, there is something you must do first. You must set the gradient information for that constraint. Gradient information is set with the GradientInfo class. Gradients are Echo's way of computing the distance to various objects. With a GradientInfo class at hand, you add sources and obstacles for the gradient. A source is something that distance will be counted from. An obstacle is an object that may get in the way of the distance computation. For example, you want your building to be placed close to other buildings. However, you don't want direct distance to be counted, because that distance could be going straight through resources. Instead, you want it to compute the distance around the resources, in which case, you would add an obstacle for the resources. Here is a list of entities that can count as sources and obstacles:

• Building - A specific type of building from a particular team. Takes a building type, a team number, and a boolean for whether the building is allowed to be under construction or not.
• AnyTeamBuilding - any building from a particular team. Takes a team number, and a boolean for whether the building is allowed to be under construction or not.
• AnyBuilding - Any building from any team. Takes a boolean for whether the building is allowed to be under construction or not.
• Resource - Any resource of a particular type. Takes a ressource type. Those are listed in Resources.h
• AnyRessource - Any resource. Takes no arguments.
• Water - Water. Takes no arguments.

Be careful, however. If you use an Source that does not exist on the map anywhere (for example, fruits don't exist on some maps), then the Gradient will fail at every point. If you create an Inn that is positioned relative to Fruit tress and there are no fruit trees, the Inn will never be created. In the case of fruit, there is a convenient function, Echo::is_fruit_on_map() that does it for you.

There is another way you can create a GradientInfo, it is somewhat more convenient. Its called make_gradient_info, and make_gradient_info_obstacle. These two convenience functions take Entities as their arguments and return a GradientInfo using them. make_gradient_info can take one or two entities, both refering to sources. make_gradint_info_obstacle can take one or two sources, and one obstacle.

You can obtain your team number from echo.player->team->teamNumber. You can use the functions GradientInfo::add_source and GradientInfo::add_obstacle to add sources and obstacles to your gradient information.

When you're finally ready to add your order to echo, use Echo::add_building_order. This function returns an ID that you can use to add ManagementOrders to the function (described later in Managing Buildings). If, however, Echo can't find a place to put your building, this function will return INVALID_BUILDING.

Annotated Example

Heres an example of ordering the cosntruction of a racetrack, with some very specific requirements on the position.

 //The main order for the race track, to be constructed using 6 workers.
 BuildingOrder bo(IntBuildingType::WALKSPEED_BUILDING, 6);
 

 //Constraints arround the location of wood
 GradientInfo gi_wood;
 //Add wood as a source for the gradient
 gi_wood.add_source(new Entities::Ressource(WOOD));
 //You want to be close to wood, so use a MinimizedDistance.
 bo.add_constraint(new MinimizedDistance(gi_wood, 4));
 

 //Constraints arround the location of stone
 GradientInfo gi_stone;
 //Add stone as a source for the gradient
 gi_stone.add_source(new Entities::Ressource(STONE));
 //You want to be close to stone, so use a MinimizedDistance. However, the above gi_wood has a higher weight, so being close
 //to wood is more important
 bo.add_constraint(new MinimizedDistance(gi_stone, 1));
 //You don't want to be to close, so you have room to upgrade. You use a MinimumDistance for this.
 bo.add_constraint(new MinimumDistance(gi_stone, 2));
 

 //Constraints arround nearby settlement
 GradientInfo gi_building;
 //Add any building on my team as a source for the gradient. I don't want any construction sites counted, only completed buildings
 gi_building.add_source(new Entities::AnyTeamBuilding(echo.player->team->teamNumber, false));
 //You don't want to calculate the distance through ressources, making the AI build on the other side of a big ressource wall. So,
 //Add AnyRessource as an obstacle
 gi_building.add_obstacle(new Entities::AnyRessource);
 //You want to be close to other buildings, but as the weight tells you, wheat is more important
 bo.add_constraint(new MinimizedDistance(gi_building, 2));
 

 //You don't want to be too close to other buildings
 GradientInfo gi_building_construction;
 //This time, unlike the above, similar constraint, we want to allow construction sites to be counted
 gi_building_construction.add_source(new Entities::AnyTeamBuilding(echo.player->team->teamNumber, true));
 //Again, we don't want to compute distance through ressources.
 gi_building_construction.add_obstacle(new Entities::AnyRessource);
 //Don't build the racetrack too close to other buildings or construction sites, a minimum distance of 4 means that there are going
 //to be three blocks in between them. A distance of one would cause the buildings to be right next to eachother.
 bo.add_constraint(new MinimumDistance(gi_building_construction, 4));
 

 //Add the building order to the list of orders
 echo.add_building_order(bo);

Here is the same code, except using make_gradient_info.

 //The main order for the race track, to be constructed using 6 workers.
 BuildingOrder bo(IntBuildingType::WALKSPEED_BUILDING, 6);
 

 //Constraints arround the location of wood
 //You want to be close to wood, so use a MinimizedDistance.
 bo.add_constraint(new MinimizedDistance(make_gradient_info(new Entities::Ressource(WOOD)), 4));
 

 //Constraints arround the location of stone
 //You want to be close to stone, so use a MinimizedDistance. However, the above gi_wood has a higher weight, so being close
 //to wood is more important
 bo.add_constraint(new MinimizedDistance(make_gradient_info(new Entities::Ressource(STONE)), 1));
 //You don't want to be to close, so you have room to upgrade. You use a MinimumDistance for this.
 bo.add_constraint(new MinimumDistance(make_gradient_info(new Entities::Ressource(STONE)), 2));
 

 //Constraints arround nearby settlement
 //You want to be close to other buildings, but as the weight tells you, wheat is more important
 bo.add_constraint(new MinimizedDistance(make_gradient_info_obstacle(
     new Entities::AnyTeamBuilding(echo.player->team->teamNumber, false), new Entities::AnyRessource), 2));
 

 //You don't want to be too close to other buildings
 //Don't build the racetrack too close to other buildings or construction sites, a minimum distance of 4 means that there are going
 //to be three blocks in between them. A distance of one would cause the buildings to be right next to eachother.
 bo.add_constraint(new MinimumDistance(make_gradient_info_obstacle(
     new Entities::AnyTeamBuilding(echo.player->team->teamNumber, true)), new Entities::AnyRessource), 4));
 

 //Add the building order to the list of orders
 echo.add_building_order(bo);

Its shorter, but it can also cause for some fairly long lines. You can use which-ever one you prefer.

Flags

Flags are created in the same manner as other buildings. However, since flags can be placed on top of other buildings, its sometimes usefull have a MaximumDistance constraint set to 0, causing the flag to be put directly on top of another object. This would not be valid for other buildings.

Conditional Construction

There are ways for Buildings to be automatically constructed when certain conditions are passed. This is called the condition system. Conditions are described in further detail in the Managing Buildings section. To use conditions with a BuildingOrder, simply use the function BuildingOrder::add_condition in the same manner as you would for a ManagementOrder.

This can be used, for example, in chained construction, meaning after one building finishes being constructed, the next building is instantly started. This kind of a system could also be done using the Internal Messaging system. How you do things is up to you.

Summary

While constructing a building can be a lengthy amount of code, you will be happy that your building is placed in a very intelligent location, and that its construction is managed for you. There are other things you can do after the code to order the construction of a building, such as add management orders, which will be explained in the next section. This becomes very convienent and usefull.

Managing Buildings

How to

Managing buildings is a somewhat simpler task than constructing them. To manage a building, you first need to create a ManagementOrder. ManagementOrders come in a variety of types, some of them change the number of units assigned to a building, others change the size of a flag. The management orders that operate on a building (all but the last 4) take the buildings id number as their last argument. Here is a list of them:

• AssignWorkers - Takes the number of workers to assign, and it assigns it to the building
• ChangeSwarm - Takes three ratios, and changes the ratios of worker, explorer, and warrior on a swarm
• DestroyBuilding - Destroys a building
• AddRessourceTracker - Attaches a ressource tracker to the building. Ressource trackers are explained later.
• PauseRessourceTracker - Pauses a buildings ressource tracker. Usefull during upgrades.
• UnPauseRessourceTracker - Unpauses a buildings ressource tracker. Usefull after an upgrade.
• ChangeFlagSize - Changes the radius of a flag to the provided radius. Takes an integer for the size.
• ChangeFlagMinimumLevel - Changes the minimum level that a unit must be to come to a flag. Takes an integer for the minimum level.
• UpgradeRepair - Orders your building to be upgraded, or repaired if its damaged (to be discussed later)
• AddArea - Adds restricted area, guard area, or clearing area to the map (to be discussed later)
• RemoveArea - Removes restricted area, guard area, or clearing area from the map (to be discussed later)
• ChangeAlliances - Changes alliances with another player (to be discussed later)
• SendMessage - Sends a message to your AI's internal messaging system (to be discussed later)

What makes ManagementOrders so useful is the fact that they can have **Conditions** attached to them. A condition is attached using ManagementOrder::add_condition. The order will not be executed untill the condition has been satisfied. A prime example of this would be to change the number of units assigned after a building has finished construction. For this, you would attach a NotUnderConstruction condition to the AssignWorkers management order and send it right after you order construction of the building. When the building is done being constructed, the NotUnderConstruction condition will match, and then the AssignWorkers order will follow through.

• ParticularBuilding - This condition basically wraps the building conditions listed below. This will be detailed further below.
• BuildingDestroyed - This condition matches when the provided building is destroyed. It takes the ID of the building.
• EnemyBuildingDestroyed - This condition is matched when the provided enemy building is destroyed. It takes a reference to the Echo System for technical reasons, and the gbid of the enemy building.
• EitherCondition - Takes two conditions, and matches if one or the other matches. This can be used for condition logic.
• AllConditions - Takes 1 to 4 conditions (Conditions that are NULL are ignored) and matches when all of them match.
• Population - Matches when a population condition is reached. It takes 3 booleans designating whether workers, explorers, and warriors respectivly are to be counted, and integer that designates the number that has to be matched, and a PopulationMethod. The two PopulationMethods are Population::Greater and Population::Lesser, which causes the condition to match when the population exceeds or goes below the given amount respectively.

There are numerous conditions that operate on buildings. These conditions are used to both count and find buildings that match these conditions (explained later), or in this case, they can match when the properties of one particular building meet the requirements. To use them like you would the above conditions, you must wrap them in ParticularBuilding and provide the ID of the building that is to be tested. ParticularBuilding takes the BuildingCondition as its first argument, and the ID of the building to be tested as its second. The building ID is an integer ID, you can get it from the return of Echo::add_building_order for example. Other ways of getting an ID are explained in Obtaining Information.

• NotUnderConstruction - Passes buildings that are not under any sort of construction
• UnderConstruction - Passes buildings that *are* under construction
• BeingUpgraded - Passes buildings that are being upgraded.
• BeingUpgradedTo - Passes buildings being upgraded to a particular level. Takes an integer of the level.
• SpecificBuildingType - Passes buildings buildings of a particular type. Takes an integer for the type.
• NotSpecificBuildingType - Passes any buildings *but* the particular type. Takes an integer for the type.
• BuildingLevel - Passes any buildings of the particular level. Takes an integer for the level.
• Upgradable - Passes any buildings that can be upgraded. Eg, swarms can't be upgraded, level three buildings can't be upgraded, damaged buildings can't be upgraded, etc..
• RessourceTrackerAmount - Passes any buildings whos ressource tracker matches the provided amount. It takes an integer providing the amount as its first argument, and a TrackerMethod as its second. The TrackerMethod is one of RessourceTrackerAmount::Greater or RessourcetrackerAmmount::Lesser. Be careful

l not to use this on buildings that aren't guaranteed to have a ressource tracker already, as this will not create a ressource tracker and will result in a crash.

• RessourceTrackerAge - Passes any buildings whose resource tracker's age matches the provided age. It takes an integer for the age as its first argument, and a TrackerMethod as its second. The TrackerMethod is one of RessourceTrackerAge::Greater or RessourceTrackerAge::Lesser. Like the above, be careful not to use this on buildings that have no resource tracker.

Any of these conditions can be attached to an Order, but only certain ones (such as NotUnderConstruction) make any sense to do so, because their values can change. Other ones, like SpecificBuildingType, are more for sorting through buildings as explained later, since a building's type doesn't change during its existence.

Once you have created your management order, and added any conditions that you desire, its finally time to pass it into Echo. You can use the function Echo::add_management_order to do this. add_management_order takes only one argument, the management order.

Some Examples

Here is an example where you want several things to be done after the construction of a swarm:

 BuildingOrder* bo = new BuildingOrder(IntBuildingType::SWARM_BUILDING, 3);
 //.......
 //Add the building order to the list of orders
 unsigned int id=echo.add_building_order(bo);
 

 //Change the number of workers assigned when the building is finished
 ManagementOrder* mo_completion=new AssignWorkers(5, id);
 //This adds the condition that the building must be finished construction before the workers will be reassigned.
 mo_completion->add_condition(new ParticularBuilding(new NotUnderConstruction, id));
 //Add the management order to the queue.
 echo.add_management_order(mo_completion);
 

 //Change the ratio of the swarm when its finished
 ManagementOrder* mo_ratios=new ChangeSwarm(15, 1, 0, id);
 //Again, the building must be completed before its ratios are changes
 mo_ratios->add_condition(new ParticularBuilding(new NotUnderConstruction, id));
 //Add the management order to the queue
 echo.add_management_order(mo_ratios);
 

 //Add a ressource tracker to track the amount of wheat in the swarm/
 ManagementOrder* mo_tracker=new AddRessourceTracker(12, id, CORN);
 //We don't want to track ressource ammounts during construction, only after construction
 mo_tracker->add_condition(new ParticularBuilding(new NotUnderConstruction, id));
 //Add the management order to the queue
 echo.add_management_order(mo_tracker);

Here is an example where we have are creating an exploration flag on an enemy building, and, if that building happens to be destroyed, we want our flag to be destroyed with it.

 unsigned int enemy_building_id=*ebi;
 BuildingOrder* bo = new BuildingOrder(IntBuildingType::EXPLORATION_FLAG, 1);
 bo->add_constraint(new CenterOfBuilding(enemy_building_id));
 unsigned int id=echo.add_building_order(bo);
 

 if(id!=INVALID_BUILDING)
 {
   ManagementOrder* mo_completion=new ChangeFlagSize(12, id);
   echo.add_management_order(mo_completion);
   

   ManagementOrder* mo_destroyed=new DestroyBuilding;
   mo_destroyed->add_condition(new EnemyBuildingDestroyed(echo, enemy_building_id));
   echo.add_management_order(mo_destroyed);
 }

Summary

ManagementOrders are very important for manipulating the Glob2 universe, and the ability to attach a condition to them makes them much more convenient and useful.

Proceed to Making An AI With Echo (part 2)