Google Code-in Micro AI Tasks

This page contains detailed information on the Google Code-in 2012 Micro AI Tasks.

Getting Help

This page provides information on the Google Code-in Wesnoth Lua AI tasks. If you need additional help, the preferred way of contacting us is on the Wesnoth IRC channels, specifically #wesnoth-dev. Ask for mattsc or Alarantalara. If we're not online, ask your questions anyway. Somebody else might be able to help, or we will read the logs later and get back to you as soon as possible.

Another way of contacting us is via the Wesnoth forums, either by posting a question there (go to the 'Coders Corner' forum, we have a GCI thread there) or by sending us a personal message (PM).

Getting Started

Programming languages: For working on the GCI Lua AI tasks, you need to have a basic familiarity with the Wesnoth Markup Language (WML) and with the Lua programming language. If you do not know WML or Lua yet, but are familiar with coding in other languages, you can probably acquire the basic skills needed in a few hours. This project does not require any in-depth knowledge of the complexities of either language.

The game: While not absolutely necessary, it would also be helpful to be familiar with Wesnoth gameplay itself.

Add-on: Finally, you need to download the Wesnoth AI-Demos add-on, as this contains the AIs that you will be working with.

If you are already know all of this, you can skip the rest of this section.

Wesnoth

Note that all the GCI work needs to be done with Wesnoth's development version 1.11. It is not necessary that you compile the latest trunk version, downloading the last release of 1.11 (currently 1.11.0) is sufficient.

If you are not familiar with Wesnoth, start by playing a couple scenarios. Yes, part of the assignment is to play a computer game! Some things to try:

• Check out the 'Play' link at the top of this page
• Start one of the four novice level campaigns and play a couple scenarios
• Start a multiplayer game (if this is your first time, you might want to start with a local game against the AI, but there is nothing wrong with playing a networked game against another human and get some advice as you go along)

AI-Demos Add-on

Download the AI-Demos add-on (called 'AI Modification Demos' in the add-ons dialog) and check out the scenarios, in particular those for which GCI tasks exist (see below). Note how the AI behavior differs from the normal Wesnoth AI.

You can download the add-on simply by clicking on 'Add-ons' in the main screen of the game. However, if you want to work on the GCI tasks, you will later need to download it from the AI-Demos github repository anyway, so you might as well do that right now:

• Download the repository to a local directory of your choice
• Set up a link to that directory from directory 'data/add-ons' in the Wesnoth user data directory

Either way, you should now see AI Demos in the campaign list in the game and can start it from there.

Wesnoth Markup Language

Wesnoth uses an event-driven markup language, WML, to create scenarios and campaigns. The language manuals can be accessed through the 'Create' link at the top of this page.

You do not require a detailed knowledge of WML for the GCI tasks. You will, however, need to work with existing WML files, so you should at least understand their structure. Have a look at some of the files in the AI-Demos github repository scenarios/ folder. dragon.cfg is an example of a basic scenario that still uses the old AI syntax, while healer_support.cfg is an example of a scenario that uses a Micro AI and the [micro_ai] tag.

Lua

The AIs you will be working with are written in Lua. You do not need a detailed knowledge of Lua for the GCI tasks (there are templates available for all parts of the work), but some basic familiarity is required, in particular with the general language structure and with Lua tables. Check out the Lua documentation, in particular the first few sections of the reference manual.

The use of Lua in Wesnoth is explained on the LuaWML wiki page. Again, it is not necessary that you work through this page in detail, but have a quick look at it and keep it in mind as a reference for the code in the Lua files you will be working with.

Micro AIs Overview

Setting up new AI functionality in Wesnoth from scratch is non-trivial and something most scenario and campaign authors don't want to deal with or don't have the time for. Even including some of the existing AI-Demos in a scenario requires quite a few lines of code (see, for example, prune_cart.cfg), and adapting them to the given scenario can be rather difficult. To facilitate the process, we have recently started to convert the existing AIs in AI-Demos to so-called Micro_AIs. Micro AIs can be included in and configured to any suitable scenario with a few simple lines of WML code. Thus, the goal of the GCI Lua AI tasks is to:

1. Convert existing AIs to Micro AIs as they are (to enable easy inclusion in scenarios)
2. Remove all scenario-specific content from the AIs and replace it by [micro_ai] tag parameters (to enable configurability of the Micro AI to the needs of different scenarios)

See Micro_AIs for the Micro AI formalism and descriptions of the two already converted AIs. That page is also the one you will be editing for documenting your work.

Note: If you are interested in more background on how AIs in Wesnoth work in general, check out Practical_Guide_to_Modifying_AI_Behavior.

Converting an Existing AI to a Micro AI

Converting one of the existing AIs to a Micro AI without changing its behavior is relatively straightforward. The following is a step-by-step guide. Note, however, that not every step applies literally to every AI. Figuring out when it is necessary to deviate somewhat from this procedure is part of the task (but see below for additional information on specific AIs). As a general rule, if you are stuck, have a look at the corresponding file for one of the already existing Micro AIs.

micro_ais/ais/micro_ais_macros.cfg

1. Create a macro definition for the new Micro AI in this file. Simply copy-and-paste one of the existing macros and modify the few AI specific lines (including the comment).

Lua Engine File

2. Locate the Lua engine file in the lua/ directory and move it to the location specified in the wesnoth.require() function in the macro you just created. Also rename it accordingly.

Important: If the engine file contains functions for files other than the AI you are currently converting, moving it will disable those AIs (and possibly result in a Wesnoth error/crash at startup time). In that case, do not move the file, but copy it instead. Having the functions for the AI you are currently converting defined in both files is not a problem.

micro_ais/ais/micro_ais_wml_tags.lua

This file sets up the keys that can be used in the [micro_ai] tag for the given AI. For the basic AI conversion, we only need the 'side', 'ai_type' and 'action' keys.

3. Duplicate the template section in this file and replace all occurrences of 'template' with the name of the AI you are converting. This adds the the 'add', 'delete' and 'change' action function calls for the given AI. The functions themselves are defined in the next steps.

Micro AI Candidate Action and Scenario Files

4. Duplicate file micro_ais/ais/template_CAs.lua and rename it to match the file name used in the code of the previous step. This file provides the 'add' and 'delete' functionalities that are called by the file in the previous step.

5. Locate the scenario file for the AI being converted and find the [candidate_action] tags in it. Note that a scenario might contain several different AIs. Only locate the candidate actions (CAs) for the AI you are currently converting.

6. In both the 'activate' and 'remove' section of the *_CAs.lua file, create as many copies of the W.modify_ai{} blocks as there are [candidate_action] tags for the AI to be converted. Adjust the keys according to those used in each [candidate_action] tag. (Check the files of one of the existing Micro AIs if unsure how to change things.) Note that there might be a different set of keys used in the [candidate_action] tags than those given in the template file.

At this point, the only remaining steps involve adding the new functionality to the scenario file.

7. Locate the scenario file for the AI and delete the entire [ai] tag in the side definition if this is the only AI for this side. Only delete the parts setting up this AI if other AIs are also defined for this side. Add the macro you defined previously to the side definition. Use the Bottleneck Defense scenario file to check the syntax.

8. Add the [micro_ai] tag to a prestart or start event in the scenario file. This activates the new Micro AI. Again use the Bottleneck Defense scenario file as a template (but delete all keys other than 'side', ai_type' and 'action').

Note: if the AI attaches to a unit (that is, if the 'sticky=' key is set), the unit needs to be on the map before the [micro_ai] tag is applied. Place the tag accordingly in the event.

Testing and Committing

At this point, you should have a working Micro AI.

9. Test the Micro AI by starting the AI-Demos campaign and moving Grnk to the signpost for the AI. Then make sure everything works as expected. (Very important: you need to restart Wesnoth, not just the scenario, after any change you make to the scenario file.)

10. Test removing of the CA by placing a [micro_ai] command in, say, a 'turn 3' event and see whether the AI gets removed successfully at that time.

11. Document the changes you have made on the Micro_AIs wiki page. This is part of the task, which will not be accepted until at least basic documentation has been provided.

12. Once you are satisfied that everything is working correctly, commit the changes to the github repository. (We will give you commit access for this for the duration of you working on the task.) This counts as submitting the task and will start the review process by the mentors.

Parametrizing a Micro AI

The goal of these tasks is to add additional parameters to the [micro_ai] tag and thus to make the Micro AI configurable to work with any (suitable) scenario. The steps involved are much more dependent on the specific AI than the conversion of the existing AI, but can be outlined as follows:

1. Go through the AI code (engine and scenario files) and locate all parts that are scenario-specific, such as specific unit IDs or map locations.

2. Replace these parts by variables, functions or whatever is needed. The code needs to be set up so that the required parameters can be passed to the AI *_eval and *_exec functions.

3. Set up [micro_ai] tag keys for all parameters in the micro_ais_wml_tags.lua file. Check out the already existing Micro AIs for examples.

4. Set up the string(s) through which these parameters are transferred to the AI *_eval and *_exec functions in the *_CAs.lua file. Again, use one of the already existing AIs as guideline.

5. Document and commit, same as for the basic AI conversion tasks.

AIs to be Converted

This section lists which parts of the respective scenarios need to be converted, as well as characteristics of the AIs that might cause deviations from the procedures listed above.

Patrols (1 AI)

The AI to be converted is that controlling goblin handler Jabb on Side 3 of the 'Patrols' scenario. The AIs for Konrad and Urudin are not worth converting to Micro AIs.

Important: This is a Behavior Candidate Actions (BCA), that is, it attaches to a unit, rather than controlling all (relevant) units of a side. This means that:

• The CA is attached to the unit in an event (not in the side definition) and there are additional keys required when setting up the candidate action (see the [modify_ai] tag in the prestart event).
• ai_type in the [micro_ai] tag needs to start with 'bca_'
• The [micro_ai] tag needs to be placed after the creation of the unit it controls in the scenario event. Put it in place of the current [modify_ai] tag.

Lurkers (1 AI)

There are three different lurker AIs in this scenario. The one written in Lua (Side 4) is the AI to be converted to a Micro AI.