The Battle for Wesnoth Wiki - User contributions [en]

Micro AIs

2012-12-01T19:33:56Z

Ubuntor: /* Patrol specific keys for the [micro_ai] tag: */

More information: '''[[Google Code-in Micro AI Tasks]]'''

The add-on ''AI Modification Demos'' contains a number of so-called Micro AIs (well, currently there are only three, but the goal is to add more). Mirco AIs add specific functionalities to a side's AI that can be added to a scenario easily using only a few lines of WML code. Adding (or deleting) a Micro AI is done via the [micro_ai] tag, which also lets the campaign designer configure the AI behavior to the specific need of the scenario.

Note that the AI-Demos add-on is only supported for Wesnoth 1.11 any more. In time, fewer and fewer of the AIs (and Micro AIs) will function with Wesnoth 1.10.

== Setting up a Micro AI ==

After installing the ''AI Modification Demos'' add-on, there are currently three steps required to set up a Micro AI:

==== 1. Making the Micro AIs and [micro_ai] tag available in your add-on ====

The following line needs to be added to your _main.cfg file, inside the #ifdef for your campaign:
{~add-ons/AI-demos/micro_ais/activate_micro_ais.cfg}
This loads the required AI files and sets up the [micro_ai] tag.

==== 2. Setting up the Lua AI engine ====

Add the following line to the [side] tag of the side that should use the Micro AI. The exact macro name depends on the specific Micro AI - see below for the available Micro AIs and respective macro names:
{MICRO_AI_HEALER_SUPPORT}
This does not yet activate any Micro AIs, but it is currently still necessary to define the Lua AI engine inside the side definition for the Micro AIs to work. This requirement will go away for one of the upcoming Wesnoth 1.11 releases.

==== 3. Activating and configuring the Micro AI ====

Micro AIs are activated, deleted and configured using the [micro_ai] tag. This tag needs to be placed in [[ActionWML]], that is, in an event, a menu option or the like. As an example, the following code activates the healer_support Micro AI in its default configuration for Side 2 from the beginning of the scenario:
[event]
name=prestart

# Configure the healer support micro AI
[micro_ai]
side=2
ai_type=healer_support
action=add
[/micro_ai]
[/event]
For the full syntax of the [micro_ai] tag and the available Micro AIs, see the next sections.

== The [micro_ai] Tag ==

The [micro_ai] tag activates, deletes and configures the Micro AIs for use in a scenario. It needs to be placed in [[ActionWML]] and must contain the following three required keys:
* '''action''' (string): The action to take concerning the Micro AI. The following values are allowed:
** ''add'': Add a Micro AI to a side.
** ''change'': Change the configuration of an existing Micro AI. Note that this does not only change the specific parameters provided in the tag, but it replaces the entire existing Micro AI by a new version with the new (and only the new) configuration. It is therefore equivalent to using first the ''delete'' and then the ''add'' action.
** ''delete'': Delete an existing Micro AI from a side.
* '''side''': The side for which the Micro AI is to be added, changed or deleted
* '''ai_type''': The type of Micro AI to be added, changed or deleted. See the following sections for allowed values. A Micro AI that attaches to a unit, that is, a [[Lua_AI_Howto#Behavior_.28Sticky.29_Candidate_Actions|Behavior Candidate Action]] (BCA), has an ai_type starting with 'bca_'. Consequently, ai_types not starting with 'bca_' apply to all units of a side.

If no other keys are given, the Micro AI is set up in its default configuration when using the ''add'' and ''change'' actions. Additional keys allowed for each Micro AI are listed below. The ''add'' and ''change'' actions ignore all keys that do not apply to the respective Micro AI type. The ''delete'' action ignores all keys other than the three listed above.

== Healer Support Micro AI ==

The Healer Support Micro AI configures the healers of a side to stay behind the battle lines and heal injured and/or threatened units rather than participate in combat under all circumstances. You can set different levels of aggressiveness for the healers, from "never attack" to "only heal if you cannot attack" (not all implemented yet).

For a demonstration, check out scenario "Healer Support" of the AI-Demos campaign.

Enable the Healer Support Micro AI by putting
{MICRO_AI_HEALER_SUPPORT}
into the [side] tag and configure it by using
ai_type=healer_support
in the [micro_ai] tag.

====Healer Support specific keys for the [micro_ai] tag:====
* '''aggression'''=1.0: (float) Sets the aggressiveness of the AI. This parameter is set up as a float to accommodate future functionality, but it currently acts as a boolean: if set to zero, the AI will never let its healers participate in combat, for all other values it allows them to attack after all other units have attacked and if the healers cannot find any more units to support. The former behavior might be appropriate in scenarios with only one or few valuable healers, while the latter might work better in scenarios with many healers.
* '''injured_units_only'''=no/false: (boolean) If set to 'yes' or 'true', the AI will only move healers next to units that are already injured and skip units that currently have full hitpoints, but might get injured during the next enemy turn.
* '''max_threats'''=9999: (integer) The maximum allowable number of enemies that can attack a hex in order for it to be considered for a healer. As an example, setting 'max_threats=0' means that the AI only moves healers to locations that are entirely safe from the enemy (assuming that none of the units currently on the map dies). Note that the value of this key is checked against the number of enemies that can make it to the hex, not the number of adjacent hexes from which the healer could be attacked.

== Bottleneck Defense Micro AI ==

The Bottleneck Defense Micro AI lets you define a location on the map where the AI can take a defensive stance behind a narrow passage (bottleneck). Units on the front line are backed up by healers and/or units with the leadership ability. Injured units are moved to the back and replaced by uninjured (or less injured) units. The units on the front line only attack when it is safe (no retaliation) or when there is a high chance that they will make a kill or level up. Using this Micro AI only makes sense if there is no way for the enemy sides to move around the bottleneck and attack the AI's units from behind.

For a demonstration, check out scenario "Bottleneck Defense" of the AI-Demos campaign.

Enable the Bottleneck Defense Micro AI by putting
{MICRO_AI_BOTTLENECK_DEFENSE}
into the [side] tag and configure it by using
ai_type=bottleneck_defense
in the [micro_ai] tag.

====Bottleneck Defense specific keys for the [micro_ai] tag:====

'''Required keys:'''

The Bottleneck Defense AI requires two sets of coordinates that define where it should be taking up its defensive stance, and from which side the enemy attacks at that location.

* '''x,y''': Comma separated lists of the hexes on the front line, where strong units are placed. All hexes on which the AI makes contact with (be attacked by) the enemy need to be included here. Units are placed on them in the order in which they are listed here.
* '''enemy_x,enemy_y''': Comma separated list of the hexes from which the enemy can attack the AI front line units. This is needed for the AI to know on which side of the front line support units (healers etc.) need to be placed. In many cases, it is sufficient to provide only one of the enemy front line hexes, but there are geometries for which that does not work. It is therefore safer to list all enemy front line hexes here.

'''Optional keys:'''

By default, the AI places healers and units with the leadership ability both on the front line itself (if they are the strongest units available) and on hexes adjacent to and behind the line. If different placement is desired, these locations can be overridden with the following keys.

As an example, in the Bottleneck Defense scenario of the AI-Demos add-on, there are three front line hexes, two of which are on hill terrain, while the third is a road with a lower defense rating. The healer and side leader are supposed to participate in combat because they are strong units, but only from the hill hexes to keep them safer. This is accomplished but using the following keys (see code example below):

* '''healer_x,healer_y''': Comma separated list of hexes where healers are placed. This can be used to keep healers from the front line (or to take up only certain positions on the front line), and/or to override the default healing positions behind the line. Healers are placed on them in the order in which the hexes are listed, with the exception that hexes on the line always take priority over hexes behind the line.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability.
* '''active_side_leader'''=no: (boolean) If set to 'yes', the side leader participates in the bottleneck defense action after the side's gold has been spent. If set to 'no' (default), the leader follows default AI behavior (sitting on the keep and recruiting, for the most part).

Here's an example of the [micro_ai] tag usage from scenario "Bottleneck Defense" of the AI-Demos campaign:
[micro_ai]
# Required keys of [micro_ai] tag
side=1
ai_type=bottleneck_defense
action=add

# Required keys of Bottleneck Defense Micro AI
x=14,14,14
y= 7, 9, 8
enemy_x=13,13
enemy_y= 8, 9

# Optional keys of Bottleneck Defense Micro AI
healer_x=14,14,15,15
healer_y= 7, 9, 8, 9
leadership_x=14,14,15,15
leadership_y= 7, 9, 9 ,8
active_side_leader=yes
[/micro_ai]

== Messenger Escort Micro AI ==

The Messenger Escort Micro AI lets you define a location on the map where the AI will attempt to move to safely. One unit is defined as a messenger, and the other units will escort the messenger.

For a demonstration, check out scenario "Messenger Escort" of the AI-Demos campaign.

Enable the Messenger Escort Micro AI by putting
{MICRO_AI_MESSENGER_ESCORT}
into the [side] tag and configure it by using
ai_type=messenger_escort
in the [micro_ai] tag.

====Messenger Escort specific keys for the [micro_ai] tag:====

'''Required keys:'''

* '''id''': The id of the messenger. All other units with the AI will protect the messenger.
* '''goal_x,goal_y''': The x and y-value of the hex of the destination, where the messenger will attempt to reach.

'''Optional keys:'''

* '''enemy_death_chance''': A number ranging from 0 to 1. When a unit is adjacent to an enemy unit, if the probability of the enemy dying is greater than or equal to this value, then the unit will attack. Default is 0.67.
* '''messenger_death_chance''': A number ranging from 0 to 1. When a unit is adjacent to an enemy unit, if the probability of the unit dying is lesser than or equal to this value, then the unit will attack. Default is 0.

Here's an example of the [micro_ai] tag usage from scenario "Messenger Escort" of the AI-Demos campaign:
[micro_ai]
side=2
ai_type=messenger_escort
action=add

id=messenger
goal_x,goal_y=28,1
[/micro_ai]

== Guardian Micro AI ==
The Guardian Micro AI defines a number of a guardian AIs. Guardians typically protect certain locations on the map. Different guardian AIs behave differently, some moving, some remaining in place. For details, see below.

For a demonstration, check out scenario "Guardians" of the AI-Demos campaign.

Enable the Guardians Micro AI by putting
{MICRO_AI_GUARDIAN}
into the [side] tag. Configure using the [micro_ai] tag with ai_type as "guardian". Different types of guardians are specified below.

====Guardian types and their specific keys for the [micro_ai] tag:====

'''Stationed Guardian:'''

The stationed guardian will remain at its station until an enemy unit enters its radius of defense. It will continuously attack any unit within this radius until there are no more, at which time it returns to its station.

Enemies will only be attacked if they enter within the radius from both the unit's station and guarded hex. Thus ensure that the guarded hex and the station are at most 2*radius hexes apart.

You can configure it using the micro_ai tag as follows (all keys are required):
* '''guardian_type''': Must be "stationed_guardian"
* '''id''': The ID of the unit to which this AI should be applied.
* '''radius''': The maximum distance from its station that this unit will move to attack an enemy unit.
* '''station_x and station_y''': The x and y position of the hex that the unit must take as its station (point to which it returns)
* '''guard_x and guard_y''': The x and y position of the hex this unit is guarding

For example:
[micro_ai]
side=1
ai_type=guardian
action=add

guardian_type=stationed_guardian

id=stationed1
radius=4
station_x,station_y=3,5
guard_x,guard_y=4,5
[/micro_ai]

'''Coward:'''

The coward will remain where it is until an enemy unit enters its radius. It then run to the hex furthest from all enemies (ie with least distance sum to enemies). It also attempts to move towards the "seek" hex and away from the "avoid" hex (if specified).

You can configure it using the micro_ai tag as follows:

'''Required keys:'''
* '''guardian_type''': Must be "coward"
* '''id''': The ID of the unit to which this AI should be applied.
* '''radius''': The distance that an enemy must be to "scare" the unit
'''Optional keys:'''
* '''seek_x and seek_y''': The x and y position of the hex to seek
* '''avoid_x and avoid_y''': The x and y position of the hex to avoid

For example:
[micro_ai]
side=1
ai_type=guardian
action=add

guardian_type=coward

id=coward1
radius=4
seek_x,seek_y=3,5
avoid_x,avoid_y=4,5
[/micro_ai]

'''Return Guardian:'''

The return guardian moves towards the hex passed to it.

You can configure it using the micro_ai tag as follows:

'''Required keys:'''
* '''guardian_type''': Must be "return_guardian"
* '''id''': The ID of the unit to which this AI should be applied.
* '''to_x and to_y''': The x and y position of the hex to move towards

For example:
[micro_ai]
side=1
ai_type=guardian
action=add

guardian_type=return_guardian

id=return1
to_x,to_y=3,5
[/micro_ai]

== Lurkers Micro AI ==
The Lurkers Micro AI defines a lurker battle AI. A lurker can move across most terrains but only stops on swamp.
They always attack the weakest enemy within their reach. If no enemy is in reach, the lurker does a random move instead.

For a demonstration, check out scenario "Swamp Lurkers" of the AI-Demos campaign.

Enable the Lurkers Micro AI by putting
{MICRO_AI_LURKERS}
into the [side] tag and configure it by using
ai_type=lurkers
in the [micro_ai] tag

== Protect Unit Micro AI ==

The Protect Unit Micro AI lets you define a location on the map where a chosen unit will attempt to move to safely. The chosen unit will stay away from enemy units, and stay close to friendly units. Other units with the AI will protect the chosen unit.

For a demonstration, check out scenario "Protect Unit" of the AI-Demos campaign.

Enable the Protect Unit Micro AI by putting
{MICRO_AI_PROTECT_UNIT}
into the [side] tag and configure it by using
ai_type=protect_unit
in the [micro_ai] tag.

====Protect Unit specific keys for the [micro_ai] tag:====

'''Required keys:'''

* '''units''': Information about the protected unit(s). Listed as id,goal_x,goal_y for each unit. All other units with the AI will protect this/these unit(s).

'''Optional keys:'''

* '''disable_move_leader_to_keep''' (boolean): If true, will prevent protected leaders from returning to their keep.

Here's an example of the [micro_ai] tag usage from scenario "HttT: The Elves Besieged" of the AI-Demos campaign:
[micro_ai]
# Required keys of [micro_ai] tag
side=1
ai_type=protect_unit
action=add

units=Delfador,1,2,Konrad,1,1
disable_move_leader_to_keep=true
[/micro_ai]

== Animals Micro AI ==

The Animals Micro AI defines a number of a animal AIs. Different animal AIs behave differently. For details, see below. '''Currently only the hunter, wolves and wolves_multipacks micro AI works.'''

For a demonstration, check out scenario "Dragon" of the AI-Demos campaign.

Enable the Animals Micro AI by putting
{MICRO_AI_ANIMALS}
into the [side] tag and configure it by using
ai_type=animals
in the [micro_ai] tag. The animal_type tag is used to choose from different animal AIs.

An example of the tag's usage:
# Set up the hunter micro AI
[micro_ai]
# Required keys of [micro_ai] tag
side=1
ai_type=animals
animal_type=hunter
action=add
# Required keys of hunter micro AI
id=Rowck
hunt_x,hunt_y="9-38","4-19"
home_x,home_y=4,3
rest_turns=2
[/micro_ai]

'''Animal types:'''

* '''hunter''': hunts in a specific area, then stays home for a specified time/until fully healed.
* '''wolves''': they hunt in a pack of up to three.
* '''wolves_multipacks''': same as above but this AI supports an arbitrary number of units and this can't avoid specific types of enemies.

====Required keys of the hunter AI (all of them are required):====

* '''id''': The ID of the unit to which this AI should be applied.
* '''animal_type''': This has to be "hunter" (without quotation marks) if you want a hunter AI.
* '''hunt_x''': The x range of the area where the AI will wander.
* '''hunt_y''': The y range of the area where the AI will wander.
* '''home_x''': The x coordinate of the place where the AI will return.
* '''home_y''': The y coordinate of the place where the AI will return.
* '''rest_turns''': The number of turns the AI will stay at "home".

====Keys of the wolves and wolves_multipacks AI:====

* '''animal_type''': You have to set this to "wolves" or "wolves_multipacks" (without quotation marks) if you want one of these types of animal AI.
* '''to_avoid''': The wolves will try to avoid creatures with these types. '''Optional. The wolves_multipacks AI doesn't support this.'''

== Patrol Micro AI ==

The Patrol Micro AI lets you define locations on the map where a unit will move in order in a loop. Optionally, attack targets can be specified, which the unit will attack if it ends up next to them.

For a demonstration, check out Goblin Handler Jabb in scenario "Patrols" of the AI-Demos campaign.

Enable the Patrol Micro AI by putting
{MICRO_AI_PATROL}
into the [side] tag and configure it by using
ai_type=bca_patrol
in the [micro_ai] tag.

'''NOTE: The [micro_ai] tag needs to be placed after the creation of the unit it controls in the scenario event.'''

====Patrol specific keys for the [micro_ai] tag:====

'''Required keys:'''

* '''id''': The id of the patrol.
* '''waypoint_x,waypoint_y''': The x and y-value(s) of the hex(es) of the waypoints(s), where the patrol will travel to in order.

'''Optional keys:'''

* '''attack_all''' (boolean): If true, the patrol will attack any adjacent enemy after moving. Default is false. Overrides attack_target if true.
* '''attack_targets''': The id(s) of the attack target(s). The patrol will attack this/these unit(s) when it ends up next to them.

Here's an example of the [micro_ai] tag usage from scenario "Patrols" of the AI-Demos campaign:
[micro_ai]
# Required keys of [micro_ai] tag
side=3
ai_type=bca_patrol
action=add

id=Goblin Handler Jabb
waypoint_x=6,7,11,11
waypoint_y=17,14,14,18
attack_targets=Jacques
[/micro_ai]

== Other Potential Micro AIs ==

The following Micro AIs might be added at some point. Feel free to add to this list, if you have other ideas.

* Leader support
* Targeted enemy poisoning
* Protect unit/location/area
* Annoying AI (grab targets and avoid fights as much as possible)
* Hunter AI (e.g. wolves)
* Orderly retreat

[[Category:AI]]

Micro AIs

2012-12-01T06:58:02Z

Ubuntor: /* Patrol Micro AI */ GCI Patrols Step 2

More information: '''[[Google Code-in Micro AI Tasks]]'''

The add-on ''AI Modification Demos'' contains a number of so-called Micro AIs (well, currently there are only three, but the goal is to add more). Mirco AIs add specific functionalities to a side's AI that can be added to a scenario easily using only a few lines of WML code. Adding (or deleting) a Micro AI is done via the [micro_ai] tag, which also lets the campaign designer configure the AI behavior to the specific need of the scenario.

Note that the AI-Demos add-on is only supported for Wesnoth 1.11 any more. In time, fewer and fewer of the AIs (and Micro AIs) will function with Wesnoth 1.10.

== Setting up a Micro AI ==

After installing the ''AI Modification Demos'' add-on, there are currently three steps required to set up a Micro AI:

==== 1. Making the Micro AIs and [micro_ai] tag available in your add-on ====

The following line needs to be added to your _main.cfg file, inside the #ifdef for your campaign:
{~add-ons/AI-demos/micro_ais/activate_micro_ais.cfg}
This loads the required AI files and sets up the [micro_ai] tag.

==== 2. Setting up the Lua AI engine ====

Add the following line to the [side] tag of the side that should use the Micro AI. The exact macro name depends on the specific Micro AI - see below for the available Micro AIs and respective macro names:
{MICRO_AI_HEALER_SUPPORT}
This does not yet activate any Micro AIs, but it is currently still necessary to define the Lua AI engine inside the side definition for the Micro AIs to work. This requirement will go away for one of the upcoming Wesnoth 1.11 releases.

==== 3. Activating and configuring the Micro AI ====

Micro AIs are activated, deleted and configured using the [micro_ai] tag. This tag needs to be placed in [[ActionWML]], that is, in an event, a menu option or the like. As an example, the following code activates the healer_support Micro AI in its default configuration for Side 2 from the beginning of the scenario:
[event]
name=prestart

# Configure the healer support micro AI
[micro_ai]
side=2
ai_type=healer_support
action=add
[/micro_ai]
[/event]
For the full syntax of the [micro_ai] tag and the available Micro AIs, see the next sections.

== The [micro_ai] Tag ==

The [micro_ai] tag activates, deletes and configures the Micro AIs for use in a scenario. It needs to be placed in [[ActionWML]] and must contain the following three required keys:
* '''action''' (string): The action to take concerning the Micro AI. The following values are allowed:
** ''add'': Add a Micro AI to a side.
** ''change'': Change the configuration of an existing Micro AI. Note that this does not only change the specific parameters provided in the tag, but it replaces the entire existing Micro AI by a new version with the new (and only the new) configuration. It is therefore equivalent to using first the ''delete'' and then the ''add'' action.
** ''delete'': Delete an existing Micro AI from a side.
* '''side''': The side for which the Micro AI is to be added, changed or deleted
* '''ai_type''': The type of Micro AI to be added, changed or deleted. See the following sections for allowed values. A Micro AI that attaches to a unit, that is, a [[Lua_AI_Howto#Behavior_.28Sticky.29_Candidate_Actions|Behavior Candidate Action]] (BCA), has an ai_type starting with 'bca_'. Consequently, ai_types not starting with 'bca_' apply to all units of a side.

If no other keys are given, the Micro AI is set up in its default configuration when using the ''add'' and ''change'' actions. Additional keys allowed for each Micro AI are listed below. The ''add'' and ''change'' actions ignore all keys that do not apply to the respective Micro AI type. The ''delete'' action ignores all keys other than the three listed above.

== Healer Support Micro AI ==

The Healer Support Micro AI configures the healers of a side to stay behind the battle lines and heal injured and/or threatened units rather than participate in combat under all circumstances. You can set different levels of aggressiveness for the healers, from "never attack" to "only heal if you cannot attack" (not all implemented yet).

For a demonstration, check out scenario "Healer Support" of the AI-Demos campaign.

Enable the Healer Support Micro AI by putting
{MICRO_AI_HEALER_SUPPORT}
into the [side] tag and configure it by using
ai_type=healer_support
in the [micro_ai] tag.

====Healer Support specific keys for the [micro_ai] tag:====
* '''aggression'''=1.0: (float) Sets the aggressiveness of the AI. This parameter is set up as a float to accommodate future functionality, but it currently acts as a boolean: if set to zero, the AI will never let its healers participate in combat, for all other values it allows them to attack after all other units have attacked and if the healers cannot find any more units to support. The former behavior might be appropriate in scenarios with only one or few valuable healers, while the latter might work better in scenarios with many healers.
* '''injured_units_only'''=no/false: (boolean) If set to 'yes' or 'true', the AI will only move healers next to units that are already injured and skip units that currently have full hitpoints, but might get injured during the next enemy turn.
* '''max_threats'''=9999: (integer) The maximum allowable number of enemies that can attack a hex in order for it to be considered for a healer. As an example, setting 'max_threats=0' means that the AI only moves healers to locations that are entirely safe from the enemy (assuming that none of the units currently on the map dies). Note that the value of this key is checked against the number of enemies that can make it to the hex, not the number of adjacent hexes from which the healer could be attacked.

== Bottleneck Defense Micro AI ==

The Bottleneck Defense Micro AI lets you define a location on the map where the AI can take a defensive stance behind a narrow passage (bottleneck). Units on the front line are backed up by healers and/or units with the leadership ability. Injured units are moved to the back and replaced by uninjured (or less injured) units. The units on the front line only attack when it is safe (no retaliation) or when there is a high chance that they will make a kill or level up. Using this Micro AI only makes sense if there is no way for the enemy sides to move around the bottleneck and attack the AI's units from behind.

For a demonstration, check out scenario "Bottleneck Defense" of the AI-Demos campaign.

Enable the Bottleneck Defense Micro AI by putting
{MICRO_AI_BOTTLENECK_DEFENSE}
into the [side] tag and configure it by using
ai_type=bottleneck_defense
in the [micro_ai] tag.

====Bottleneck Defense specific keys for the [micro_ai] tag:====

'''Required keys:'''

The Bottleneck Defense AI requires two sets of coordinates that define where it should be taking up its defensive stance, and from which side the enemy attacks at that location.

* '''x,y''': Comma separated lists of the hexes on the front line, where strong units are placed. All hexes on which the AI makes contact with (be attacked by) the enemy need to be included here. Units are placed on them in the order in which they are listed here.
* '''enemy_x,enemy_y''': Comma separated list of the hexes from which the enemy can attack the AI front line units. This is needed for the AI to know on which side of the front line support units (healers etc.) need to be placed. In many cases, it is sufficient to provide only one of the enemy front line hexes, but there are geometries for which that does not work. It is therefore safer to list all enemy front line hexes here.

'''Optional keys:'''

By default, the AI places healers and units with the leadership ability both on the front line itself (if they are the strongest units available) and on hexes adjacent to and behind the line. If different placement is desired, these locations can be overridden with the following keys.

As an example, in the Bottleneck Defense scenario of the AI-Demos add-on, there are three front line hexes, two of which are on hill terrain, while the third is a road with a lower defense rating. The healer and side leader are supposed to participate in combat because they are strong units, but only from the hill hexes to keep them safer. This is accomplished but using the following keys (see code example below):

* '''healer_x,healer_y''': Comma separated list of hexes where healers are placed. This can be used to keep healers from the front line (or to take up only certain positions on the front line), and/or to override the default healing positions behind the line. Healers are placed on them in the order in which the hexes are listed, with the exception that hexes on the line always take priority over hexes behind the line.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability.
* '''active_side_leader'''=no: (boolean) If set to 'yes', the side leader participates in the bottleneck defense action after the side's gold has been spent. If set to 'no' (default), the leader follows default AI behavior (sitting on the keep and recruiting, for the most part).

Here's an example of the [micro_ai] tag usage from scenario "Bottleneck Defense" of the AI-Demos campaign:
[micro_ai]
# Required keys of [micro_ai] tag
side=1
ai_type=bottleneck_defense
action=add

# Required keys of Bottleneck Defense Micro AI
x=14,14,14
y= 7, 9, 8
enemy_x=13,13
enemy_y= 8, 9

# Optional keys of Bottleneck Defense Micro AI
healer_x=14,14,15,15
healer_y= 7, 9, 8, 9
leadership_x=14,14,15,15
leadership_y= 7, 9, 9 ,8
active_side_leader=yes
[/micro_ai]

== Messenger Escort Micro AI ==

The Messenger Escort Micro AI lets you define a location on the map where the AI will attempt to move to safely. One unit is defined as a messenger, and the other units will escort the messenger.

For a demonstration, check out scenario "Messenger Escort" of the AI-Demos campaign.

Enable the Messenger Escort Micro AI by putting
{MICRO_AI_MESSENGER_ESCORT}
into the [side] tag and configure it by using
ai_type=messenger_escort
in the [micro_ai] tag.

====Messenger Escort specific keys for the [micro_ai] tag:====

'''Required keys:'''

* '''id''': The id of the messenger. All other units with the AI will protect the messenger.
* '''goal_x,goal_y''': The x and y-value of the hex of the destination, where the messenger will attempt to reach.

'''Optional keys:'''

* '''enemy_death_chance''': A number ranging from 0 to 1. When a unit is adjacent to an enemy unit, if the probability of the enemy dying is greater than or equal to this value, then the unit will attack. Default is 0.67.
* '''messenger_death_chance''': A number ranging from 0 to 1. When a unit is adjacent to an enemy unit, if the probability of the unit dying is lesser than or equal to this value, then the unit will attack. Default is 0.

Here's an example of the [micro_ai] tag usage from scenario "Messenger Escort" of the AI-Demos campaign:
[micro_ai]
side=2
ai_type=messenger_escort
action=add

id=messenger
goal_x,goal_y=28,1
[/micro_ai]

== Guardian Micro AI ==
The Guardian Micro AI defines a number of a guardian AIs. Guardians typically protect certain locations on the map. Different guardian AIs behave differently, some moving, some remaining in place. For details, see below.

For a demonstration, check out scenario "Guardians" of the AI-Demos campaign.

Enable the Guardians Micro AI by putting
{MICRO_AI_GUARDIAN}
into the [side] tag. Configure using the [micro_ai] tag with ai_type as "guardian". Different types of guardians are specified below.

====Guardian types and their specific keys for the [micro_ai] tag:====

'''Stationed Guardian:'''

The stationed guardian will remain at its station until an enemy unit enters its radius of defense. It will continuously attack any unit within this radius until there are no more, at which time it returns to its station.

Enemies will only be attacked if they enter within the radius from both the unit's station and guarded hex. Thus ensure that the guarded hex and the station are at most 2*radius hexes apart.

You can configure it using the micro_ai tag as follows (all keys are required):
* '''guardian_type''': Must be "stationed_guardian"
* '''id''': The ID of the unit to which this AI should be applied.
* '''radius''': The maximum distance from its station that this unit will move to attack an enemy unit.
* '''station_x and station_y''': The x and y position of the hex that the unit must take as its station (point to which it returns)
* '''guard_x and guard_y''': The x and y position of the hex this unit is guarding

For example:
[micro_ai]
side=1
ai_type=guardian
action=add

guardian_type=stationed_guardian

id=stationed1
radius=4
station_x,station_y=3,5
guard_x,guard_y=4,5
[/micro_ai]

'''Coward:'''

The coward will remain where it is until an enemy unit enters its radius. It then run to the hex furthest from all enemies (ie with least distance sum to enemies). It also attempts to move towards the "seek" hex and away from the "avoid" hex (if specified).

You can configure it using the micro_ai tag as follows:

'''Required keys:'''
* '''guardian_type''': Must be "coward"
* '''id''': The ID of the unit to which this AI should be applied.
* '''radius''': The distance that an enemy must be to "scare" the unit
'''Optional keys:'''
* '''seek_x and seek_y''': The x and y position of the hex to seek
* '''avoid_x and avoid_y''': The x and y position of the hex to avoid

For example:
[micro_ai]
side=1
ai_type=guardian
action=add

guardian_type=coward

id=coward1
radius=4
seek_x,seek_y=3,5
avoid_x,avoid_y=4,5
[/micro_ai]

'''Return Guardian:'''

The return guardian moves towards the hex passed to it.

You can configure it using the micro_ai tag as follows:

'''Required keys:'''
* '''guardian_type''': Must be "return_guardian"
* '''id''': The ID of the unit to which this AI should be applied.
* '''to_x and to_y''': The x and y position of the hex to move towards

For example:
[micro_ai]
side=1
ai_type=guardian
action=add

guardian_type=return_guardian

id=return1
to_x,to_y=3,5
[/micro_ai]

== Lurkers Micro AI ==
The Lurkers Micro AI defines a lurker battle AI. A lurker can move across most terrains but only stops on swamp.
They always attack the weakest enemy within their reach. If no enemy is in reach, the lurker does a random move instead.

For a demonstration, check out scenario "Swamp Lurkers" of the AI-Demos campaign.

Enable the Lurkers Micro AI by putting
{MICRO_AI_LURKERS}
into the [side] tag and configure it by using
ai_type=lurkers
in the [micro_ai] tag

== Protect Unit Micro AI ==

The Protect Unit Micro AI lets you define a location on the map where a chosen unit will attempt to move to safely. The chosen unit will stay away from enemy units, and stay close to friendly units. Other units with the AI will protect the chosen unit.

For a demonstration, check out scenario "Protect Unit" of the AI-Demos campaign.

Enable the Protect Unit Micro AI by putting
{MICRO_AI_PROTECT_UNIT}
into the [side] tag and configure it by using
ai_type=protect_unit
in the [micro_ai] tag.

====Protect Unit specific keys for the [micro_ai] tag:====

'''Required keys:'''

* '''units''': Information about the protected unit(s). Listed as id,goal_x,goal_y for each unit. All other units with the AI will protect this/these unit(s).

'''Optional keys:'''

* '''disable_move_leader_to_keep''' (boolean): If true, will prevent protected leaders from returning to their keep.

Here's an example of the [micro_ai] tag usage from scenario "HttT: The Elves Besieged" of the AI-Demos campaign:
[micro_ai]
# Required keys of [micro_ai] tag
side=1
ai_type=protect_unit
action=add

units=Delfador,1,2,Konrad,1,1
disable_move_leader_to_keep=true
[/micro_ai]

== Animals Micro AI ==

The Animals Micro AI defines a number of a animal AIs. Different animal AIs behave differently. For details, see below. '''Currently only the hunter micro AI works.'''

For a demonstration, check out scenario "Dragon" of the AI-Demos campaign.

Enable the Animals Micro AI by putting
{MICRO_AI_ANIMALS}
into the [side] tag and configure it by using
ai_type=animals
in the [micro_ai] tag.

'''Required keys:'''

* '''id''': The ID of the unit to which this AI should be applied.
* '''hunt_x''': The x range of the area where the AI will wander.
* '''hunt_y''': The y range of the area where the AI will wander.
* '''home_x''': The x coordinate of the place where the AI will return.
* '''home_y''': The y coordinate of the place where the AI will return.
* '''rest_turns''': The number of turns the AI will stay at "home".

An example of the tag's usage:
# Set up the hunter micro AI
[micro_ai]
# Required keys of [micro_ai] tag
side=1
ai_type=animals
action=add
# Required keys of hunter micro AI
id=Rowck
hunt_x,hunt_y="9-38","4-19"
home_x,home_y=4,3
rest_turns=2
[/micro_ai]

== Patrol Micro AI ==

The Patrol Micro AI lets you define locations on the map where a unit will move in order in a loop. Optionally, attack targets can be specified, which the unit will attack if it ends up next to them.

For a demonstration, check out Goblin Handler Jabb in scenario "Patrols" of the AI-Demos campaign.

Enable the Patrol Micro AI by putting
{MICRO_AI_PATROL}
into the [side] tag and configure it by using
ai_type=bca_patrol
in the [micro_ai] tag.

'''NOTE: The [micro_ai] tag needs to be placed after the creation of the unit it controls in the scenario event.'''

====Patrol specific keys for the [micro_ai] tag:====

'''Required keys:'''

* '''id''': The id of the patrol.
* '''waypoint_x,waypoint_y''': The x and y-value(s) of the hex(es) of the waypoints(s), where the patrol will travel to in order.

'''Optional keys:'''

* '''attack_all''' (boolean): If true, the patrol will attack any adjacent enemy after moving. Default is false. Overrides attack_target.
* '''attack_targets''': The id(s) of the attack target(s). The patrol will attack this/these unit(s) when it ends up next to them.

Here's an example of the [micro_ai] tag usage from scenario "Patrols" of the AI-Demos campaign:
[micro_ai]
# Required keys of [micro_ai] tag
side=3
ai_type=bca_patrol
action=add

id=Goblin Handler Jabb
waypoint_x=6,7,11,11
waypoint_y=17,14,14,18
attack_targets=Jacques
[/micro_ai]

== Other Potential Micro AIs ==

The following Micro AIs might be added at some point. Feel free to add to this list, if you have other ideas.

* Leader support
* Targeted enemy poisoning
* Protect unit/location/area
* Annoying AI (grab targets and avoid fights as much as possible)
* Hunter AI (e.g. wolves)
* Orderly retreat

[[Category:AI]]

Google Code-in Micro AI Tasks

2012-12-01T01:26:26Z

Ubuntor: complete strikethrough

This page contains detailed information on the [http://www.google-melange.com/gci/homepage/google/gci2012 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 [[Support#IRC|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 [http://www.wesnoth.org/irclogs/ logs] later and get back to you as soon as possible.

Another way of contacting us is via the [http://forums.wesnoth.org/index.php 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 [https://github.com/mattsc/Wesnoth-AI-Demos 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 [[EditingWesnoth#Where_is_my_user_data_directory.3F|Wesnoth user data directory]]
* You might also want to familiarize yourself with doing [https://help.github.com/articles/using-pull-requests pull requests], as that is how you will be submitting your work.

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 [https://github.com/mattsc/Wesnoth-AI-Demos AI-Demos github repository] [https://github.com/mattsc/Wesnoth-AI-Demos/tree/master/scenarios scenarios/] folder. [https://github.com/mattsc/Wesnoth-AI-Demos/blob/master/scenarios/dragon.cfg dragon.cfg] is an example of a basic scenario that still uses the old AI syntax, while [https://github.com/mattsc/Wesnoth-AI-Demos/blob/master/scenarios/healer_support.cfg 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 [http://www.lua.org/ 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 [http://www.lua.org/docs.html Lua documentation], in particular the first few sections of the [http://www.lua.org/manual/5.1/manual.html 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, [https://github.com/mattsc/Wesnoth-AI-Demos/blob/master/scenarios/prune-cart.cfg 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:

# Convert existing AIs to Micro AIs ''as they are'' (to enable easy inclusion in scenarios)
# 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 requires you to go through a number of steps, but is otherwise 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 tasks (but see [[Google_Code-in_Micro_AI_Tasks#AIs_to_be_Converted|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.

Note: For this initial conversion you can (should) work with hard-coded values for things like unit IDs, unit types, locations etc., exactly as they are currently used in the respective scenario. The generalization of these parameters happens in the [[Google_Code-in_Micro_AI_Tasks#Parametrizing_a_Micro_AI|next step]].

=== 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). This macro will later be included in the [side] tag for the side that is to use this AI. It sets up the AI engine for that side.

=== Lua Engine File ===

The Lua engine file needs to be moved to the Micro AIs directory.

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. If you are unsure whether you should move or copy the file, copy it. You can always remove the original later.

=== 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 '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. In some cases, the CAs are defined in a macro in a separate file. If that is the case, this is noted in the [[Google_Code-in_Micro_AI_Tasks#AIs_to_be_Converted|descriptions of the individual AIs]] below.

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. For some AIs, AI [[AiWML#Aspects_and_Goals_Overview|aspects]] need to be added/deleted also. If so, this is also noted in the [[Google_Code-in_Micro_AI_Tasks#AIs_to_be_Converted|descriptions of the individual AIs]] below.

At this point, you should have a working Micro AI. 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, Documenting and Pushing to the Github Repository ===

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. '''The task will not be accepted until at least basic documentation has been provided.'''

12. Once you are satisfied that everything is working correctly, add yourself to the credits in the _main.cfg file and put in a [https://help.github.com/articles/using-pull-requests pull request] with your changes at the github repository. This counts as submitting the task and will start the review process by the mentors, who will commit it once it is accepted.

== Parametrizing a Micro AI ==

For each Micro AI, there are one or more follow-up tasks that involve adding additional parameters to the [micro_ai] tag. The goal of these tasks is to make the Micro AI configurable to work in 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. Test, document and submit a [https://help.github.com/articles/using-pull-requests pull request] at the github repository, same as for the basic AI conversion tasks.

More information concerning the parametrization of the specific AIs is given in the following.

== 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) ===

'''<s>Step 1</s>: Completed'''

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 [[Lua_AI_Howto#Behavior_.28Sticky.29_Candidate_Actions|Behavior Candidate Action]] (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.

Step 1 is completed when scenario 'Patrols' uses the [micro_ai] tag to control Jabb and the basic Micro AI has been documented.

'''Step 2:'''

Parametrization of this AI involves (at least) making the [micro_ai] tag work for arbitrary units (not just Jabb) and for an arbitrary set of waypoints. The controlled unit should also attack any enemy unit that it ends up next to, not just Jacques.

Step 2 is completed when this parametrization has been achieved, has been included in the scenario and has been documented.

=== Lurkers (1 AI) ===

'''<s>Step 1</s>: Completed'''

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.

Step 1 is completed when scenario 'Lurkers' uses the [micro_ai] tag and the basic Micro AI has been documented.

'''Step 2:'''

Part of the work for Step 2 is figuring out what parameters can be added to the lurker AI to make it more generally useful. Examples could be to make it work for arbitrary unit type and arbitrary terrain.

Step 2 is completed when at least 3 keys/parameters have been added to the Micro AI and have been documented.

=== Protect Unit (1 AI) ===

'''<s>Step 1</s>: Completed'''

This AI is used in 2 scenarios, 'Protect the Wizard' and 'The Elves Besieged'. The first step of this task involves setting up a Micro AI for scenario 'Protect the Wizard' only. Thus, leave the original engine file in place (copy it, rather than moving it), otherwise 'The Elves Besieged' will stop working.

Note that, in order to activate/delete this Micro AI, the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|attack aspect]] needs to be added/removed in the *_CA.lua file in addition to the candidate actions. See the scenario file.

Step 1 is completed when scenario 'Protect the Wizard' uses the [micro_ai] tag and the basic Micro AI has been documented.

'''<s>Step 2</s>: Completed'''

Parametrization for this AI is already done in the engine functions, so Step 2 for the 'Protect Unit' scenario mostly involves just setting up the keys and parameter handlers for the parameters. However, scenario 'The Elves Besieged' requires the removal of one of the default AI candidate actions (see the scenario file). Thus, you also need to set up an additional key/parameter that allows for optional removal of this CA.

Step 2 is completed when both scenarios 'Protect the Wizard' and 'The Elves Besieged' use the [micro_ai] tag and the parametrized Micro AI has been documented.

=== Messenger Escort (1 AI) ===

'''<s>Step 1</s>: Completed'''

Convert the AI in scenario 'Messenger Escort' to a Micro AI following the steps described above.

Step 1 is completed when scenario 'Messenger Escort' uses the [micro_ai] tag and the basic Micro AI has been documented.

'''<s>Step 2</s>: Completed'''

Parametrization for this AI is already done in the engine functions for the messenger ID and the goal coordinates. Additionally, this task requires the definition of at least one more parameter to make the AI more generally useful. An example could be a parameter that configures if/when the messenger attacks adjacent units.

Step 2 is completed when at least 3 keys/parameters have been added to the Micro AI and have been documented.

=== Guardians (3 AIs) ===

Scenario 'Guardians' contains several guardian AIs, three of which should be converted to Micro AIs: return guardian, stationed guardian and coward.

'''Important notes:'''

* The guardian AIs (including a fourth AI that will not be converted to a Micro AI) are all part of Side 2, which means that the [ai] tag in the side definition cannot be deleted.
* All three guardian AI functions are defined in the same engine file. Thus, the file needs to be copied, rather than moved, to the new location until all three guardian AIs have been converted.
* This is a [[Lua_AI_Howto#Behavior_.28Sticky.29_Candidate_Actions|Behavior Candidate Action]] (BCA), that is, it attaches to a unit, rather than controlling all (relevant) units of a side. See the comments about BCAs in the description of the [[Google_Code-in_Micro_AI_Tasks#Patrols_.281_AI.29|Patrols AI]].
* The BCA CA code is included as macros. The macros are defined in file utils/lua_macros.cfg.

'''<s>Step 1</s>: Completed'''

Choose one of the three guardian AIs and convert it to a basic Micro AI. For this step, it is sufficient to make the Micro AI work for a single guardian unit (comment out the other unit(s) of the same guardian type in the scenario file) with hard-coded values for the unit ID and other parameters.

Step 1 is completed when scenario 'Guardians' controls one guardian unit using the [micro_ai] tag and the basic Micro AI has been documented.

'''<s>Step 2</s>: Completed'''

Change the guardian Micro AI code so that the hard-coded values of the previous step are configurable keys/parameters in the [micro_ai] tag.

Step 2 is completed when several units of the same guardian type are controlled by the Micro AI (using one [micro_ai] tag per unit) in the 'Guardians' scenario and this has been documented.

'''<s>Steps 3a and 3b</s>: Completed'''

Pick one of the other guardian AIs and convert it to a Micro AI. This should be done as a parametrization of the AI that was already converted in Steps 1 and 2, and not by defining a new Micro AI type. Thus, 'ai_type=' should be 'guardian' for all guardian Micro AIs, and an additional key 'guardian_type=' should be added.

Note: Steps 3a and 3b can, in principle, be done in parallel. They only require Steps 1 and 2 to be completed first.

Each of these steps is completed when several units of the same guardian type are controlled by the new guardian Micro AI type (using one [micro_ai] tag per unit) in the 'Guardians' scenario and this has been documented.

=== Animals (7 AIs) ===

There are a total of 7 animal AIs in 4 different scenarios: 'Dragon' (1 AI), 'Wolves' (1 AI), 'Swarm' (1 AI) and 'Animals' (big animals, forest animals, sheep and another wolves AIs). All of these need to be converted to Micro AIs with 'ai_type=animal' and different 'animal_type=" values.

'''Important Notes:'''

* The dragon AI should be converted first (Steps 1 and 2). After that, you can choose any order for the remaining AIs.
* The dragon AI is a BCA with the candidate action being set up in a macro. See the notes for the [[Google_Code-in_Micro_AI_Tasks#Guardians_.283_AIs.29|guardian Micro AI]] for how to deal with such an AI. All other AIs control all (suitable) units on their side.
* When converting the AIs, the unit types should be set up as parameters (if different unit types on the same side display different types of behavior), rather than being hardcoded as they are now for some of the animal AIs.
* Side 6 in scenario 'Animals' (wolves AI) contains two aspect definitions in addition to the candidate actions. These aspects need to be made part of the Micro AI as well (and ideally they could be turned on/off with configurable parameters).

'''<s>Step 1</s>: Completed'''

Convert the dragon AI to a basic Micro AI. For this step, it is sufficient to use the hard-coded values for the unit ID and other parameters.

Step 1 is completed when scenario 'Dragon' controls the dragon using the [micro_ai] tag and the basic Micro AI has been documented.

'''<s>Step 2</s>: Completed'''

Change the dragon Micro AI code so that the hard-coded values of the previous step are configurable keys/parameters in the [micro_ai] tag.

Step 2 is completed when the parametrization of the dragon Micro AI is complete and has been documented.

'''Steps 3a-3f:'''

Pick any one of the other animal AIs and convert it to a Micro AI. This should be done as a parametrization of the AI that was already converted in Steps 1 and 2, and not by defining a new Micro AI type. Thus, 'ai_type=' should be 'animal' for all animal Micro AIs, and an additional key 'animal_type=' should be added.

Note: Steps 3a-3f can, in principle, be done in parallel. They only require Steps 1 and 2 to be completed first.

Each of these steps is completed when all sides using the given AI type are controlled by the new animal Micro AI type in the respective scenario and this has been documented.

[[Category:AI]]

Micro AIs

2012-12-01T01:00:50Z

Ubuntor: GCI patrols step 1

More information: '''[[Google Code-in Micro AI Tasks]]'''

The add-on ''AI Modification Demos'' contains a number of so-called Micro AIs (well, currently there are only three, but the goal is to add more). Mirco AIs add specific functionalities to a side's AI that can be added to a scenario easily using only a few lines of WML code. Adding (or deleting) a Micro AI is done via the [micro_ai] tag, which also lets the campaign designer configure the AI behavior to the specific need of the scenario.

Note that the AI-Demos add-on is only supported for Wesnoth 1.11 any more. In time, fewer and fewer of the AIs (and Micro AIs) will function with Wesnoth 1.10.

== Setting up a Micro AI ==

After installing the ''AI Modification Demos'' add-on, there are currently three steps required to set up a Micro AI:

==== 1. Making the Micro AIs and [micro_ai] tag available in your add-on ====

The following line needs to be added to your _main.cfg file, inside the #ifdef for your campaign:
{~add-ons/AI-demos/micro_ais/activate_micro_ais.cfg}
This loads the required AI files and sets up the [micro_ai] tag.

==== 2. Setting up the Lua AI engine ====

Add the following line to the [side] tag of the side that should use the Micro AI. The exact macro name depends on the specific Micro AI - see below for the available Micro AIs and respective macro names:
{MICRO_AI_HEALER_SUPPORT}
This does not yet activate any Micro AIs, but it is currently still necessary to define the Lua AI engine inside the side definition for the Micro AIs to work. This requirement will go away for one of the upcoming Wesnoth 1.11 releases.

==== 3. Activating and configuring the Micro AI ====

Micro AIs are activated, deleted and configured using the [micro_ai] tag. This tag needs to be placed in [[ActionWML]], that is, in an event, a menu option or the like. As an example, the following code activates the healer_support Micro AI in its default configuration for Side 2 from the beginning of the scenario:
[event]
name=prestart

# Configure the healer support micro AI
[micro_ai]
side=2
ai_type=healer_support
action=add
[/micro_ai]
[/event]
For the full syntax of the [micro_ai] tag and the available Micro AIs, see the next sections.

== The [micro_ai] Tag ==

The [micro_ai] tag activates, deletes and configures the Micro AIs for use in a scenario. It needs to be placed in [[ActionWML]] and must contain the following three required keys:
* '''action''' (string): The action to take concerning the Micro AI. The following values are allowed:
** ''add'': Add a Micro AI to a side.
** ''change'': Change the configuration of an existing Micro AI. Note that this does not only change the specific parameters provided in the tag, but it replaces the entire existing Micro AI by a new version with the new (and only the new) configuration. It is therefore equivalent to using first the ''delete'' and then the ''add'' action.
** ''delete'': Delete an existing Micro AI from a side.
* '''side''': The side for which the Micro AI is to be added, changed or deleted
* '''ai_type''': The type of Micro AI to be added, changed or deleted. See the following sections for allowed values. A Micro AI that attaches to a unit, that is, a [[Lua_AI_Howto#Behavior_.28Sticky.29_Candidate_Actions|Behavior Candidate Action]] (BCA), has an ai_type starting with 'bca_'. Consequently, ai_types not starting with 'bca_' apply to all units of a side.

If no other keys are given, the Micro AI is set up in its default configuration when using the ''add'' and ''change'' actions. Additional keys allowed for each Micro AI are listed below. The ''add'' and ''change'' actions ignore all keys that do not apply to the respective Micro AI type. The ''delete'' action ignores all keys other than the three listed above.

== Healer Support Micro AI ==

The Healer Support Micro AI configures the healers of a side to stay behind the battle lines and heal injured and/or threatened units rather than participate in combat under all circumstances. You can set different levels of aggressiveness for the healers, from "never attack" to "only heal if you cannot attack" (not all implemented yet).

For a demonstration, check out scenario "Healer Support" of the AI-Demos campaign.

Enable the Healer Support Micro AI by putting
{MICRO_AI_HEALER_SUPPORT}
into the [side] tag and configure it by using
ai_type=healer_support
in the [micro_ai] tag.

====Healer Support specific keys for the [micro_ai] tag:====
* '''aggression'''=1.0: (float) Sets the aggressiveness of the AI. This parameter is set up as a float to accommodate future functionality, but it currently acts as a boolean: if set to zero, the AI will never let its healers participate in combat, for all other values it allows them to attack after all other units have attacked and if the healers cannot find any more units to support. The former behavior might be appropriate in scenarios with only one or few valuable healers, while the latter might work better in scenarios with many healers.
* '''injured_units_only'''=no/false: (boolean) If set to 'yes' or 'true', the AI will only move healers next to units that are already injured and skip units that currently have full hitpoints, but might get injured during the next enemy turn.
* '''max_threats'''=9999: (integer) The maximum allowable number of enemies that can attack a hex in order for it to be considered for a healer. As an example, setting 'max_threats=0' means that the AI only moves healers to locations that are entirely safe from the enemy (assuming that none of the units currently on the map dies). Note that the value of this key is checked against the number of enemies that can make it to the hex, not the number of adjacent hexes from which the healer could be attacked.

== Bottleneck Defense Micro AI ==

The Bottleneck Defense Micro AI lets you define a location on the map where the AI can take a defensive stance behind a narrow passage (bottleneck). Units on the front line are backed up by healers and/or units with the leadership ability. Injured units are moved to the back and replaced by uninjured (or less injured) units. The units on the front line only attack when it is safe (no retaliation) or when there is a high chance that they will make a kill or level up. Using this Micro AI only makes sense if there is no way for the enemy sides to move around the bottleneck and attack the AI's units from behind.

For a demonstration, check out scenario "Bottleneck Defense" of the AI-Demos campaign.

Enable the Bottleneck Defense Micro AI by putting
{MICRO_AI_BOTTLENECK_DEFENSE}
into the [side] tag and configure it by using
ai_type=bottleneck_defense
in the [micro_ai] tag.

====Bottleneck Defense specific keys for the [micro_ai] tag:====

'''Required keys:'''

The Bottleneck Defense AI requires two sets of coordinates that define where it should be taking up its defensive stance, and from which side the enemy attacks at that location.

* '''x,y''': Comma separated lists of the hexes on the front line, where strong units are placed. All hexes on which the AI makes contact with (be attacked by) the enemy need to be included here. Units are placed on them in the order in which they are listed here.
* '''enemy_x,enemy_y''': Comma separated list of the hexes from which the enemy can attack the AI front line units. This is needed for the AI to know on which side of the front line support units (healers etc.) need to be placed. In many cases, it is sufficient to provide only one of the enemy front line hexes, but there are geometries for which that does not work. It is therefore safer to list all enemy front line hexes here.

'''Optional keys:'''

By default, the AI places healers and units with the leadership ability both on the front line itself (if they are the strongest units available) and on hexes adjacent to and behind the line. If different placement is desired, these locations can be overridden with the following keys.

As an example, in the Bottleneck Defense scenario of the AI-Demos add-on, there are three front line hexes, two of which are on hill terrain, while the third is a road with a lower defense rating. The healer and side leader are supposed to participate in combat because they are strong units, but only from the hill hexes to keep them safer. This is accomplished but using the following keys (see code example below):

* '''healer_x,healer_y''': Comma separated list of hexes where healers are placed. This can be used to keep healers from the front line (or to take up only certain positions on the front line), and/or to override the default healing positions behind the line. Healers are placed on them in the order in which the hexes are listed, with the exception that hexes on the line always take priority over hexes behind the line.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability.
* '''active_side_leader'''=no: (boolean) If set to 'yes', the side leader participates in the bottleneck defense action after the side's gold has been spent. If set to 'no' (default), the leader follows default AI behavior (sitting on the keep and recruiting, for the most part).

Here's an example of the [micro_ai] tag usage from scenario "Bottleneck Defense" of the AI-Demos campaign:
[micro_ai]
# Required keys of [micro_ai] tag
side=1
ai_type=bottleneck_defense
action=add

# Required keys of Bottleneck Defense Micro AI
x=14,14,14
y= 7, 9, 8
enemy_x=13,13
enemy_y= 8, 9

# Optional keys of Bottleneck Defense Micro AI
healer_x=14,14,15,15
healer_y= 7, 9, 8, 9
leadership_x=14,14,15,15
leadership_y= 7, 9, 9 ,8
active_side_leader=yes
[/micro_ai]

== Messenger Escort Micro AI ==

The Messenger Escort Micro AI lets you define a location on the map where the AI will attempt to move to safely. One unit is defined as a messenger, and the other units will escort the messenger.

For a demonstration, check out scenario "Messenger Escort" of the AI-Demos campaign.

Enable the Messenger Escort Micro AI by putting
{MICRO_AI_MESSENGER_ESCORT}
into the [side] tag and configure it by using
ai_type=messenger_escort
in the [micro_ai] tag.

====Messenger Escort specific keys for the [micro_ai] tag:====

'''Required keys:'''

* '''id''': The id of the messenger. All other units with the AI will protect the messenger.
* '''goal_x,goal_y''': The x and y-value of the hex of the destination, where the messenger will attempt to reach.

'''Optional keys:'''

* '''enemy_death_chance''': A number ranging from 0 to 1. When a unit is adjacent to an enemy unit, if the probability of the enemy dying is greater than or equal to this value, then the unit will attack. Default is 0.67.
* '''messenger_death_chance''': A number ranging from 0 to 1. When a unit is adjacent to an enemy unit, if the probability of the unit dying is lesser than or equal to this value, then the unit will attack. Default is 0.

Here's an example of the [micro_ai] tag usage from scenario "Messenger Escort" of the AI-Demos campaign:
[micro_ai]
side=2
ai_type=messenger_escort
action=add

id=messenger
goal_x=28
goal_y=1
[/micro_ai]

== Guardian Micro AI ==
The Guardian Micro AI defines a number of a guardian AIs. Guardians typically protect certain locations on the map. Different guardian AIs behave differently, some moving, some remaining in place. For details, see below.

For a demonstration, check out scenario "Guardians" of the AI-Demos campaign.

Enable the Guardians Micro AI by putting
{MICRO_AI_GUARDIAN}
into the [side] tag. Configure using the [micro_ai] tag with ai_type as "guardian". Different types of guardians are specified below.

====Guardian types and their specific keys for the [micro_ai] tag:====

'''Stationed Guardian:'''

The stationed guardian will remain at its station until an enemy unit enters its radius of defense. It will continuously attack any unit within this radius until there are no more, at which time it returns to its station.

Enemies will only be attacked if they enter within the radius from both the unit's station and guarded hex. Thus ensure that the guarded hex and the station are at most 2*radius hexes apart.

You can configure it using the micro_ai tag as follows (all keys are required):
* '''guardian_type''': Must be "stationed_guardian"
* '''id''': The ID of the unit to which this AI should be applied.
* '''radius''': The maximum distance from its station that this unit will move to attack an enemy unit.
* '''station_x and station_y''': The x and y position of the hex that the unit must take as its station (point to which it returns)
* '''guard_x and guard_y''': The x and y position of the hex this unit is guarding

For example:
[micro_ai]
side=1
ai_type=guardian
action=add

guardian_type=stationed_guardian

id=stationed1
radius=4
station_x=3
station_y=5
guard_x=4
guard_y=5
[/micro_ai]

'''Coward:'''

The coward will remain where it is until an enemy unit enters its radius. It then run to the hex furthest from all enemies (ie with least distance sum to enemies). It also attempts to move towards the "seek" hex and away from the "avoid" hex (if specified).

You can configure it using the micro_ai tag as follows:

'''Required keys:'''
* '''guardian_type''': Must be "coward"
* '''id''': The ID of the unit to which this AI should be applied.
* '''radius''': The distance that an enemy must be to "scare" the unit
'''Optional keys:'''
* '''seek_x and seek_y''': The x and y position of the hex to seek
* '''avoid_x and avoid_y''': The x and y position of the hex to avoid

For example:
[micro_ai]
side=1
ai_type=guardian
action=add

guardian_type=coward

id=coward1
radius=4
seek_x=3
seek_y=5
avoid_x=4
avoid_y=5
[/micro_ai]

'''Return Guardian:'''

The return guardian moves towards the hex passed to it.

You can configure it using the micro_ai tag as follows:

'''Required keys:'''
* '''guardian_type''': Must be "return_guardian"
* '''id''': The ID of the unit to which this AI should be applied.
* '''to_x and to_y''': The x and y position of the hex to move towards

For example:
[micro_ai]
side=1
ai_type=guardian
action=add

guardian_type=return_guardian

id=return1
to_x=3
to_y=5
[/micro_ai]

== Lurkers Micro AI ==
The Lurkers Micro AI defines a lurker battle AI. A lurker can move across most terrains but only stops on swamp.
They always attack the weakest enemy within their reach. If no enemy is in reach, the lurker does a random move instead.

For a demonstration, check out scenario "Swamp Lurkers" of the AI-Demos campaign.

Enable the Lurkers Micro AI by putting
{MICRO_AI_LURKERS}
into the [side] tag and configure it by using
ai_type=lurkers
in the [micro_ai] tag

== Protect Unit Micro AI ==

The Protect Unit Micro AI lets you define a location on the map where a chosen unit will attempt to move to safely. The chosen unit will stay away from enemy units, and stay close to friendly units. Other units with the AI will protect the chosen unit.

For a demonstration, check out scenario "Protect Unit" of the AI-Demos campaign.

Enable the Protect Unit Micro AI by putting
{MICRO_AI_PROTECT_UNIT}
into the [side] tag and configure it by using
ai_type=protect_unit
in the [micro_ai] tag.

====Protect Unit specific keys for the [micro_ai] tag:====

'''Required keys:'''

* '''units''': Information about the protected unit(s). Listed as id,goal_x,goal_y for each unit. All other units with the AI will protect this/these unit(s).

'''Optional keys:'''

* '''disable_move_leader_to_keep''' (boolean): If true, will prevent protected leaders from returning to their keep.

Here's an example of the [micro_ai] tag usage from scenario "HttT: The Elves Besieged" of the AI-Demos campaign:
[micro_ai]
# Required keys of [micro_ai] tag
side=1
ai_type=protect_unit
action=add

units=Delfador,1,2,Konrad,1,1
disable_move_leader_to_keep=true
[/micro_ai]

== Animals Micro AI ==

The Animals Micro AI defines a number of a animal AIs. Different animal AIs behave differently. For details, see below. '''Currently only the hunter micro AI works.'''

For a demonstration, check out scenario "Dragon" of the AI-Demos campaign.

Enable the Animals Micro AI by putting
{MICRO_AI_ANIMALS}
into the [side] tag and configure it by using
ai_type=animals
in the [micro_ai] tag.

'''Required keys:'''

* '''id''': The ID of the unit to which this AI should be applied.
* '''hunt_x''': The x range of the area where the AI will wander.
* '''hunt_y''': The y range of the area where the AI will wander.
* '''home_x''': The x coordinate of the place where the AI will return.
* '''home_y''': The y coordinate of the place where the AI will return.
* '''rest_turns''': The number of turns the AI will stay at "home".

An example of the tag's usage:
# Set up the hunter micro AI
[micro_ai]
# Required keys of [micro_ai] tag
side=1
ai_type=animals
action=add
# Required keys of hunter micro AI
id=Rowck
hunt_x="9-38"
hunt_y="4-19"
home_x=4
home_y=3
rest_turns=2
[/micro_ai]

== Patrol Micro AI ==

The Patrol Micro AI lets you define locations on the map where a unit will move in order in a loop. Optionally, attack targets can be specified, which the unit will attack if it ends up next to them.

For a demonstration, check out Goblin Handler Jabb in scenario "Patrols" of the AI-Demos campaign.

Enable the Patrol Micro AI by putting
{MICRO_AI_PATROL}
into the [side] tag and configure it by using
ai_type=bca_patrol
in the [micro_ai] tag.

'''NOTE: The [micro_ai] tag needs to be placed after the creation of the unit it controls in the scenario event.'''

====Patrol specific keys for the [micro_ai] tag:====

'''Required keys:'''

* '''waypoint_x,waypoint_y''': The x and y-value(s) of the hex(es) of the waypoints(s), where the patrol will travel to in order.

'''Optional keys:'''

* '''attack_target''': The id(s) of the attack target(s). The patrol will attack this/these unit(s) when it ends up next to them.

Here's an example of the [micro_ai] tag usage from scenario "Patrols" of the AI-Demos campaign:
[micro_ai]
to be added later
[/micro_ai]

== Other Potential Micro AIs ==

The following Micro AIs might be added at some point. Feel free to add to this list, if you have other ideas.

* Leader support
* Targeted enemy poisoning
* Protect unit/location/area
* Annoying AI (grab targets and avoid fights as much as possible)
* Hunter AI (e.g. wolves)
* Orderly retreat

[[Category:AI]]

Micro AIs

2012-11-29T22:28:32Z

Ubuntor: /* Protect Unit Micro AI */

More information: '''[[Google Code-in Micro AI Tasks]]'''

The add-on ''AI Modification Demos'' contains a number of so-called Micro AIs (well, currently there are only three, but the goal is to add more). Mirco AIs add specific functionalities to a side's AI that can be added to a scenario easily using only a few lines of WML code. Adding (or deleting) a Micro AI is done via the [micro_ai] tag, which also lets the campaign designer configure the AI behavior to the specific need of the scenario.

Note that the AI-Demos add-on is only supported for Wesnoth 1.11 any more. In time, fewer and fewer of the AIs (and Micro AIs) will function with Wesnoth 1.10.

== Setting up a Micro AI ==

After installing the ''AI Modification Demos'' add-on, there are currently three steps required to set up a Micro AI:

==== 1. Making the Micro AIs and [micro_ai] tag available in your add-on ====

The following line needs to be added to your _main.cfg file, inside the #ifdef for your campaign:
{~add-ons/AI-demos/micro_ais/activate_micro_ais.cfg}
This loads the required AI files and sets up the [micro_ai] tag.

==== 2. Setting up the Lua AI engine ====

Add the following line to the [side] tag of the side that should use the Micro AI. The exact macro name depends on the specific Micro AI - see below for the available Micro AIs and respective macro names:
{MICRO_AI_HEALER_SUPPORT}
This does not yet activate any Micro AIs, but it is currently still necessary to define the Lua AI engine inside the side definition for the Micro AIs to work. This requirement will go away for one of the upcoming Wesnoth 1.11 releases.

==== 3. Activating and configuring the Micro AI ====

Micro AIs are activated, deleted and configured using the [micro_ai] tag. This tag needs to be placed in [[ActionWML]], that is, in an event, a menu option or the like. As an example, the following code activates the healer_support Micro AI in its default configuration for Side 2 from the beginning of the scenario:
[event]
name=prestart

# Configure the healer support micro AI
[micro_ai]
side=2
ai_type=healer_support
action=add
[/micro_ai]
[/event]
For the full syntax of the [micro_ai] tag and the available Micro AIs, see the next sections.

== The [micro_ai] Tag ==

The [micro_ai] tag activates, deletes and configures the Micro AIs for use in a scenario. It needs to be placed in [[ActionWML]] and must contain the following three required keys:
* '''action''' (string): The action to take concerning the Micro AI. The following values are allowed:
** ''add'': Add a Micro AI to a side.
** ''change'': Change the configuration of an existing Micro AI. Note that this does not only change the specific parameters provided in the tag, but it replaces the entire existing Micro AI by a new version with the new (and only the new) configuration. It is therefore equivalent to using first the ''delete'' and then the ''add'' action.
** ''delete'': Delete an existing Micro AI from a side.
* '''side''': The side for which the Micro AI is to be added, changed or deleted
* '''ai_type''': The type of Micro AI to be added, changed or deleted. See the following sections for allowed values. A Micro AI that attaches to a unit, that is, a [[Lua_AI_Howto#Behavior_.28Sticky.29_Candidate_Actions|Behavior Candidate Action]] (BCA), has an ai_type starting with 'bca_'. Consequently, ai_types not starting with 'bca_' apply to all units of a side.

If no other keys are given, the Micro AI is set up in its default configuration when using the ''add'' and ''change'' actions. Additional keys allowed for each Micro AI are listed below. The ''add'' and ''change'' actions ignore all keys that do not apply to the respective Micro AI type. The ''delete'' action ignores all keys other than the three listed above.

== Healer Support Micro AI ==

The Healer Support Micro AI configures the healers of a side to stay behind the battle lines and heal injured and/or threatened units rather than participate in combat under all circumstances. You can set different levels of aggressiveness for the healers, from "never attack" to "only heal if you cannot attack" (not all implemented yet).

For a demonstration, check out scenario "Healer Support" of the AI-Demos campaign.

Enable the Healer Support Micro AI by putting
{MICRO_AI_HEALER_SUPPORT}
into the [side] tag and configure it by using
ai_type=healer_support
in the [micro_ai] tag.

====Healer Support specific keys for the [micro_ai] tag:====
* '''aggression'''=1.0: (float) Sets the aggressiveness of the AI. This parameter is set up as a float to accommodate future functionality, but it currently acts as a boolean: if set to zero, the AI will never let its healers participate in combat, for all other values it allows them to attack after all other units have attacked and if the healers cannot find any more units to support. The former behavior might be appropriate in scenarios with only one or few valuable healers, while the latter might work better in scenarios with many healers.
* '''injured_units_only'''=no/false: (boolean) If set to 'yes' or 'true', the AI will only move healers next to units that are already injured and skip units that currently have full hitpoints, but might get injured during the next enemy turn.
* '''max_threats'''=9999: (integer) The maximum allowable number of enemies that can attack a hex in order for it to be considered for a healer. As an example, setting 'max_threats=0' means that the AI only moves healers to locations that are entirely safe from the enemy (assuming that none of the units currently on the map dies). Note that the value of this key is checked against the number of enemies that can make it to the hex, not the number of adjacent hexes from which the healer could be attacked.

== Bottleneck Defense Micro AI ==

The Bottleneck Defense Micro AI lets you define a location on the map where the AI can take a defensive stance behind a narrow passage (bottleneck). Units on the front line are backed up by healers and/or units with the leadership ability. Injured units are moved to the back and replaced by uninjured (or less injured) units. The units on the front line only attack when it is safe (no retaliation) or when there is a high chance that they will make a kill or level up. Using this Micro AI only makes sense if there is no way for the enemy sides to move around the bottleneck and attack the AI's units from behind.

For a demonstration, check out scenario "Bottleneck Defense" of the AI-Demos campaign.

Enable the Bottleneck Defense Micro AI by putting
{MICRO_AI_BOTTLENECK_DEFENSE}
into the [side] tag and configure it by using
ai_type=bottleneck_defense
in the [micro_ai] tag.

====Bottleneck Defense specific keys for the [micro_ai] tag:====

'''Required keys:'''

The Bottleneck Defense AI requires two sets of coordinates that define where it should be taking up its defensive stance, and from which side the enemy attacks at that location.

* '''x,y''': Comma separated lists of the hexes on the front line, where strong units are placed. All hexes on which the AI makes contact with (be attacked by) the enemy need to be included here. Units are placed on them in the order in which they are listed here.
* '''enemy_x,enemy_y''': Comma separated list of the hexes from which the enemy can attack the AI front line units. This is needed for the AI to know on which side of the front line support units (healers etc.) need to be placed. In many cases, it is sufficient to provide only one of the enemy front line hexes, but there are geometries for which that does not work. It is therefore safer to list all enemy front line hexes here.

'''Optional keys:'''

By default, the AI places healers and units with the leadership ability both on the front line itself (if they are the strongest units available) and on hexes adjacent to and behind the line. If different placement is desired, these locations can be overridden with the following keys.

As an example, in the Bottleneck Defense scenario of the AI-Demos add-on, there are three front line hexes, two of which are on hill terrain, while the third is a road with a lower defense rating. The healer and side leader are supposed to participate in combat because they are strong units, but only from the hill hexes to keep them safer. This is accomplished but using the following keys (see code example below):

* '''healer_x,healer_y''': Comma separated list of hexes where healers are placed. This can be used to keep healers from the front line (or to take up only certain positions on the front line), and/or to override the default healing positions behind the line. Healers are placed on them in the order in which the hexes are listed, with the exception that hexes on the line always take priority over hexes behind the line.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability.
* '''active_side_leader'''=no: (boolean) If set to 'yes', the side leader participates in the bottleneck defense action after the side's gold has been spent. If set to 'no' (default), the leader follows default AI behavior (sitting on the keep and recruiting, for the most part).

Here's an example of the [micro_ai] tag usage from scenario "Bottleneck Defense" of the AI-Demos campaign:
[micro_ai]
# Required keys of [micro_ai] tag
side=1
ai_type=bottleneck_defense
action=add

# Required keys of Bottleneck Defense Micro AI
x=14,14,14
y= 7, 9, 8
enemy_x=13,13
enemy_y= 8, 9

# Optional keys of Bottleneck Defense Micro AI
healer_x=14,14,15,15
healer_y= 7, 9, 8, 9
leadership_x=14,14,15,15
leadership_y= 7, 9, 9 ,8
active_side_leader=yes
[/micro_ai]

== Messenger Escort Micro AI ==

The Messenger Escort Micro AI lets you define a location on the map where the AI will attempt to move to safely. One unit is defined as a messenger, and the other units will escort the messenger.

For a demonstration, check out scenario "Messenger Escort" of the AI-Demos campaign.

Enable the Messenger Escort Micro AI by putting
{MICRO_AI_MESSENGER_ESCORT}
into the [side] tag and configure it by using
ai_type=messenger_escort
in the [micro_ai] tag.

====Messenger Escort specific keys for the [micro_ai] tag:====

'''Required keys:'''

* '''id''': The id of the messenger. All other units with the AI will protect the messenger.
* '''goal_x,goal_y''': The x and y-value of the hex of the destination, where the messenger will attempt to reach.

'''Optional keys:'''

* '''enemy_death_chance''': A number ranging from 0 to 1. When a unit is adjacent to an enemy unit, if the probability of the enemy dying is greater than or equal to this value, then the unit will attack. Default is 0.67.
* '''messenger_death_chance''': A number ranging from 0 to 1. When a unit is adjacent to an enemy unit, if the probability of the unit dying is lesser than or equal to this value, then the unit will attack. Default is 0.

Here's an example of the [micro_ai] tag usage from scenario "Messenger Escort" of the AI-Demos campaign:
[micro_ai]
side=2
ai_type=messenger_escort
action=add

id=messenger
goal_x=28
goal_y=1
[/micro_ai]

== Guardian Micro AI ==
The Guardian Micro AI defines a number of a guardian AIs. Guardians typically protect certain locations on the map. Different guardian AIs behave differently, some moving, some remaining in place. For details, see below.

For a demonstration, check out scenario "Guardians" of the AI-Demos campaign.

Enable the Guardians Micro AI by putting
{MICRO_AI_GUARDIAN}
into the [side] tag. Configure using the [micro_ai] tag with the following properties (currently only the stationed guardian is implemented).

====Guardian types and their specific keys for the [micro_ai] tag:====

'''Stationed Guardian:'''

The stationed guardian will remain at its station until an enemy unit enters its radius of defense. It will continuously attack any unit within this radius until there are no more, at which time it returns to its station.

You can configure it using the micro_ai tag as follows:
* '''unitID''': The ID of the unit to which this AI should be applied.
* '''radius''': The maximum distance from its station that this unit will move to attack an enemy unit.
* '''station_x and station_y''': The x and y position of the hex that the unit must take as its station (point to which it returns)
* '''guard_x and guard_y''': The x and y position of the hex this unit is guarding

For example:
[micro_ai]
side=1
ai_type=stationed_guardian
action=add

unitID='stationed1'
radius=4
station_x=3
station_y=5
guard_x=4
guard_y=5
[/micro_ai]

== Lurkers Micro AI ==
The Lurkers Micro AI defines a lurker battle AI. A lurker can move across most terrains but only stops on swamp.
They always attack the weakest enemy within their reach. If no enemy is in reach, the lurker does a random move instead.

For a demonstration, check out scenario "Swamp Lurkers" of the AI-Demos campaign.

Enable the Lurkers Micro AI by putting
{MICRO_AI_LURKERS}
into the [side] tag and configure it by using
ai_type=lurkers
in the [micro_ai] tag

== Protect Unit Micro AI ==

The Protect Unit Micro AI lets you define a location on the map where a chosen unit will attempt to move to safely. The chosen unit will stay away from enemy units, and stay close to friendly units. Other units with the AI will protect the chosen unit.

For a demonstration, check out scenario "Protect Unit" of the AI-Demos campaign.

Enable the Protect Unit Micro AI by putting
{MICRO_AI_PROTECT_UNIT}
into the [side] tag and configure it by using
ai_type=protect_unit
in the [micro_ai] tag.

====Protect Unit specific keys for the [micro_ai] tag:====

'''Required keys:'''

* '''units''': Information about the protected unit(s). Listed as id,goal_x,goal_y for each unit. All other units with the AI will protect this/these unit(s).

'''Optional keys:'''

* '''disable_move_leader_to_keep''' (boolean): If true, will prevent protected leaders from returning to their keep.

Here's an example of the [micro_ai] tag usage from scenario "HttT: The Elves Besieged" of the AI-Demos campaign:
[micro_ai]
# Required keys of [micro_ai] tag
side=1
ai_type=protect_unit
action=add

units=Delfador,1,2,Konrad,1,1
disable_move_leader_to_keep=true
[/micro_ai]

== Animals Micro AI ==

The Animals Micro AI defines a number of a animal AIs. Different animal AIs behave differently. For details, see below. Currently only the hunter micro AI works, and only in the example scenario.

For a demonstration, check out scenario "Dragon" of the AI-Demos campaign.

Enable the Animals Micro AI by putting
{MICRO_AI_ANIMALS}
into the [side] tag and configure it by using
ai_type=animals
in the [micro_ai] tag. (This is not implemented yet.)

== Other Potential Micro AIs ==

The following Micro AIs might be added at some point. Feel free to add to this list, if you have other ideas.

* Leader support
* Targeted enemy poisoning
* Protect unit/location/area
* Annoying AI (grab targets and avoid fights as much as possible)
* Hunter AI (e.g. wolves)
* Orderly retreat

[[Category:AI]]

Micro AIs

2012-11-29T22:27:52Z

Ubuntor: /* Protect Unit specific keys for the [micro_ai] tag: */

More information: '''[[Google Code-in Micro AI Tasks]]'''

The add-on ''AI Modification Demos'' contains a number of so-called Micro AIs (well, currently there are only three, but the goal is to add more). Mirco AIs add specific functionalities to a side's AI that can be added to a scenario easily using only a few lines of WML code. Adding (or deleting) a Micro AI is done via the [micro_ai] tag, which also lets the campaign designer configure the AI behavior to the specific need of the scenario.

Note that the AI-Demos add-on is only supported for Wesnoth 1.11 any more. In time, fewer and fewer of the AIs (and Micro AIs) will function with Wesnoth 1.10.

== Setting up a Micro AI ==

After installing the ''AI Modification Demos'' add-on, there are currently three steps required to set up a Micro AI:

==== 1. Making the Micro AIs and [micro_ai] tag available in your add-on ====

The following line needs to be added to your _main.cfg file, inside the #ifdef for your campaign:
{~add-ons/AI-demos/micro_ais/activate_micro_ais.cfg}
This loads the required AI files and sets up the [micro_ai] tag.

==== 2. Setting up the Lua AI engine ====

Add the following line to the [side] tag of the side that should use the Micro AI. The exact macro name depends on the specific Micro AI - see below for the available Micro AIs and respective macro names:
{MICRO_AI_HEALER_SUPPORT}
This does not yet activate any Micro AIs, but it is currently still necessary to define the Lua AI engine inside the side definition for the Micro AIs to work. This requirement will go away for one of the upcoming Wesnoth 1.11 releases.

==== 3. Activating and configuring the Micro AI ====

Micro AIs are activated, deleted and configured using the [micro_ai] tag. This tag needs to be placed in [[ActionWML]], that is, in an event, a menu option or the like. As an example, the following code activates the healer_support Micro AI in its default configuration for Side 2 from the beginning of the scenario:
[event]
name=prestart

# Configure the healer support micro AI
[micro_ai]
side=2
ai_type=healer_support
action=add
[/micro_ai]
[/event]
For the full syntax of the [micro_ai] tag and the available Micro AIs, see the next sections.

== The [micro_ai] Tag ==

The [micro_ai] tag activates, deletes and configures the Micro AIs for use in a scenario. It needs to be placed in [[ActionWML]] and must contain the following three required keys:
* '''action''' (string): The action to take concerning the Micro AI. The following values are allowed:
** ''add'': Add a Micro AI to a side.
** ''change'': Change the configuration of an existing Micro AI. Note that this does not only change the specific parameters provided in the tag, but it replaces the entire existing Micro AI by a new version with the new (and only the new) configuration. It is therefore equivalent to using first the ''delete'' and then the ''add'' action.
** ''delete'': Delete an existing Micro AI from a side.
* '''side''': The side for which the Micro AI is to be added, changed or deleted
* '''ai_type''': The type of Micro AI to be added, changed or deleted. See the following sections for allowed values. A Micro AI that attaches to a unit, that is, a [[Lua_AI_Howto#Behavior_.28Sticky.29_Candidate_Actions|Behavior Candidate Action]] (BCA), has an ai_type starting with 'bca_'. Consequently, ai_types not starting with 'bca_' apply to all units of a side.

If no other keys are given, the Micro AI is set up in its default configuration when using the ''add'' and ''change'' actions. Additional keys allowed for each Micro AI are listed below. The ''add'' and ''change'' actions ignore all keys that do not apply to the respective Micro AI type. The ''delete'' action ignores all keys other than the three listed above.

== Healer Support Micro AI ==

The Healer Support Micro AI configures the healers of a side to stay behind the battle lines and heal injured and/or threatened units rather than participate in combat under all circumstances. You can set different levels of aggressiveness for the healers, from "never attack" to "only heal if you cannot attack" (not all implemented yet).

For a demonstration, check out scenario "Healer Support" of the AI-Demos campaign.

Enable the Healer Support Micro AI by putting
{MICRO_AI_HEALER_SUPPORT}
into the [side] tag and configure it by using
ai_type=healer_support
in the [micro_ai] tag.

====Healer Support specific keys for the [micro_ai] tag:====
* '''aggression'''=1.0: (float) Sets the aggressiveness of the AI. This parameter is set up as a float to accommodate future functionality, but it currently acts as a boolean: if set to zero, the AI will never let its healers participate in combat, for all other values it allows them to attack after all other units have attacked and if the healers cannot find any more units to support. The former behavior might be appropriate in scenarios with only one or few valuable healers, while the latter might work better in scenarios with many healers.
* '''injured_units_only'''=no/false: (boolean) If set to 'yes' or 'true', the AI will only move healers next to units that are already injured and skip units that currently have full hitpoints, but might get injured during the next enemy turn.
* '''max_threats'''=9999: (integer) The maximum allowable number of enemies that can attack a hex in order for it to be considered for a healer. As an example, setting 'max_threats=0' means that the AI only moves healers to locations that are entirely safe from the enemy (assuming that none of the units currently on the map dies). Note that the value of this key is checked against the number of enemies that can make it to the hex, not the number of adjacent hexes from which the healer could be attacked.

== Bottleneck Defense Micro AI ==

The Bottleneck Defense Micro AI lets you define a location on the map where the AI can take a defensive stance behind a narrow passage (bottleneck). Units on the front line are backed up by healers and/or units with the leadership ability. Injured units are moved to the back and replaced by uninjured (or less injured) units. The units on the front line only attack when it is safe (no retaliation) or when there is a high chance that they will make a kill or level up. Using this Micro AI only makes sense if there is no way for the enemy sides to move around the bottleneck and attack the AI's units from behind.

For a demonstration, check out scenario "Bottleneck Defense" of the AI-Demos campaign.

Enable the Bottleneck Defense Micro AI by putting
{MICRO_AI_BOTTLENECK_DEFENSE}
into the [side] tag and configure it by using
ai_type=bottleneck_defense
in the [micro_ai] tag.

====Bottleneck Defense specific keys for the [micro_ai] tag:====

'''Required keys:'''

The Bottleneck Defense AI requires two sets of coordinates that define where it should be taking up its defensive stance, and from which side the enemy attacks at that location.

* '''x,y''': Comma separated lists of the hexes on the front line, where strong units are placed. All hexes on which the AI makes contact with (be attacked by) the enemy need to be included here. Units are placed on them in the order in which they are listed here.
* '''enemy_x,enemy_y''': Comma separated list of the hexes from which the enemy can attack the AI front line units. This is needed for the AI to know on which side of the front line support units (healers etc.) need to be placed. In many cases, it is sufficient to provide only one of the enemy front line hexes, but there are geometries for which that does not work. It is therefore safer to list all enemy front line hexes here.

'''Optional keys:'''

By default, the AI places healers and units with the leadership ability both on the front line itself (if they are the strongest units available) and on hexes adjacent to and behind the line. If different placement is desired, these locations can be overridden with the following keys.

As an example, in the Bottleneck Defense scenario of the AI-Demos add-on, there are three front line hexes, two of which are on hill terrain, while the third is a road with a lower defense rating. The healer and side leader are supposed to participate in combat because they are strong units, but only from the hill hexes to keep them safer. This is accomplished but using the following keys (see code example below):

* '''healer_x,healer_y''': Comma separated list of hexes where healers are placed. This can be used to keep healers from the front line (or to take up only certain positions on the front line), and/or to override the default healing positions behind the line. Healers are placed on them in the order in which the hexes are listed, with the exception that hexes on the line always take priority over hexes behind the line.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability.
* '''active_side_leader'''=no: (boolean) If set to 'yes', the side leader participates in the bottleneck defense action after the side's gold has been spent. If set to 'no' (default), the leader follows default AI behavior (sitting on the keep and recruiting, for the most part).

Here's an example of the [micro_ai] tag usage from scenario "Bottleneck Defense" of the AI-Demos campaign:
[micro_ai]
# Required keys of [micro_ai] tag
side=1
ai_type=bottleneck_defense
action=add

# Required keys of Bottleneck Defense Micro AI
x=14,14,14
y= 7, 9, 8
enemy_x=13,13
enemy_y= 8, 9

# Optional keys of Bottleneck Defense Micro AI
healer_x=14,14,15,15
healer_y= 7, 9, 8, 9
leadership_x=14,14,15,15
leadership_y= 7, 9, 9 ,8
active_side_leader=yes
[/micro_ai]

== Messenger Escort Micro AI ==

The Messenger Escort Micro AI lets you define a location on the map where the AI will attempt to move to safely. One unit is defined as a messenger, and the other units will escort the messenger.

For a demonstration, check out scenario "Messenger Escort" of the AI-Demos campaign.

Enable the Messenger Escort Micro AI by putting
{MICRO_AI_MESSENGER_ESCORT}
into the [side] tag and configure it by using
ai_type=messenger_escort
in the [micro_ai] tag.

====Messenger Escort specific keys for the [micro_ai] tag:====

'''Required keys:'''

* '''id''': The id of the messenger. All other units with the AI will protect the messenger.
* '''goal_x,goal_y''': The x and y-value of the hex of the destination, where the messenger will attempt to reach.

'''Optional keys:'''

* '''enemy_death_chance''': A number ranging from 0 to 1. When a unit is adjacent to an enemy unit, if the probability of the enemy dying is greater than or equal to this value, then the unit will attack. Default is 0.67.
* '''messenger_death_chance''': A number ranging from 0 to 1. When a unit is adjacent to an enemy unit, if the probability of the unit dying is lesser than or equal to this value, then the unit will attack. Default is 0.

Here's an example of the [micro_ai] tag usage from scenario "Messenger Escort" of the AI-Demos campaign:
[micro_ai]
side=2
ai_type=messenger_escort
action=add

id=messenger
goal_x=28
goal_y=1
[/micro_ai]

== Guardian Micro AI ==
The Guardian Micro AI defines a number of a guardian AIs. Guardians typically protect certain locations on the map. Different guardian AIs behave differently, some moving, some remaining in place. For details, see below.

For a demonstration, check out scenario "Guardians" of the AI-Demos campaign.

Enable the Guardians Micro AI by putting
{MICRO_AI_GUARDIAN}
into the [side] tag. Configure using the [micro_ai] tag with the following properties (currently only the stationed guardian is implemented).

====Guardian types and their specific keys for the [micro_ai] tag:====

'''Stationed Guardian:'''

The stationed guardian will remain at its station until an enemy unit enters its radius of defense. It will continuously attack any unit within this radius until there are no more, at which time it returns to its station.

You can configure it using the micro_ai tag as follows:
* '''unitID''': The ID of the unit to which this AI should be applied.
* '''radius''': The maximum distance from its station that this unit will move to attack an enemy unit.
* '''station_x and station_y''': The x and y position of the hex that the unit must take as its station (point to which it returns)
* '''guard_x and guard_y''': The x and y position of the hex this unit is guarding

For example:
[micro_ai]
side=1
ai_type=stationed_guardian
action=add

unitID='stationed1'
radius=4
station_x=3
station_y=5
guard_x=4
guard_y=5
[/micro_ai]

== Lurkers Micro AI ==
The Lurkers Micro AI defines a lurker battle AI. A lurker can move across most terrains but only stops on swamp.
They always attack the weakest enemy within their reach. If no enemy is in reach, the lurker does a random move instead.

For a demonstration, check out scenario "Swamp Lurkers" of the AI-Demos campaign.

Enable the Lurkers Micro AI by putting
{MICRO_AI_LURKERS}
into the [side] tag and configure it by using
ai_type=lurkers
in the [micro_ai] tag

== Protect Unit Micro AI ==

The Protect Unit Micro AI lets you define a location on the map where a chosen unit will attempt to move to safely. The chosen unit will stay away from enemy units, and stay close to friendly units. Other units with the AI will protect the chosen unit.

For a demonstration, check out scenario "Protect Unit" of the AI-Demos campaign.

Enable the Protect Unit Micro AI by putting
{MICRO_AI_PROTECT_UNIT}
into the [side] tag and configure it by using
ai_type=protect_unit
in the [micro_ai] tag.

====Protect Unit specific keys for the [micro_ai] tag:====

'''Required keys:'''

* '''units''': Information about the protected unit(s). Listed as id,goal_x,goal_y for each unit. All other units with the AI will protect this/these unit(s).

'''Optional keys:'''

* '''disable_move_leader_to_keep''' (boolean): If true, will prevent protected leaders from returning to their keep.

Here's an example of the [micro_ai] tag usage from scenario "HttT: The Elves Besieged" of the AI-Demos campaign:
[micro_ai]
# Required keys of [micro_ai] tag
side=1
ai_type=protect_unit
action=add

id=Delfador,1,2,Konrad,1,1
disable_move_leader_to_keep=true
[/micro_ai]

== Animals Micro AI ==

The Animals Micro AI defines a number of a animal AIs. Different animal AIs behave differently. For details, see below. Currently only the hunter micro AI works, and only in the example scenario.

For a demonstration, check out scenario "Dragon" of the AI-Demos campaign.

Enable the Animals Micro AI by putting
{MICRO_AI_ANIMALS}
into the [side] tag and configure it by using
ai_type=animals
in the [micro_ai] tag. (This is not implemented yet.)

== Other Potential Micro AIs ==

The following Micro AIs might be added at some point. Feel free to add to this list, if you have other ideas.

* Leader support
* Targeted enemy poisoning
* Protect unit/location/area
* Annoying AI (grab targets and avoid fights as much as possible)
* Hunter AI (e.g. wolves)
* Orderly retreat

[[Category:AI]]

Micro AIs

2012-11-29T06:41:39Z

Ubuntor: /* Protect Unit specific keys for the [micro_ai] tag: */

Micro AIs

2012-11-29T06:39:26Z

Ubuntor: /* Protect Unit specific keys for the [micro_ai] tag: */

Micro AIs

2012-11-29T01:47:21Z

Ubuntor: /* Protect Unit Micro AI */

Micro AIs

2012-11-29T01:46:45Z

Ubuntor: /* Protect Unit Micro AI */

Micro AIs

2012-11-29T01:46:27Z

Ubuntor: GCI Protect Unit Step 1

Google Code-in Micro AI Tasks

2012-11-29T00:20:18Z

Ubuntor: /* AIs to be Converted */ messenger escort complete

This page contains detailed information on the [http://www.google-melange.com/gci/homepage/google/gci2012 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 [[Support#IRC|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 [http://www.wesnoth.org/irclogs/ logs] later and get back to you as soon as possible.

Another way of contacting us is via the [http://forums.wesnoth.org/index.php 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 [https://github.com/mattsc/Wesnoth-AI-Demos 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 [[EditingWesnoth#Where_is_my_user_data_directory.3F|Wesnoth user data directory]]
* You might also want to familiarize yourself with doing [https://help.github.com/articles/using-pull-requests pull requests], as that is how you will be submitting your work.

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 [https://github.com/mattsc/Wesnoth-AI-Demos AI-Demos github repository] [https://github.com/mattsc/Wesnoth-AI-Demos/tree/master/scenarios scenarios/] folder. [https://github.com/mattsc/Wesnoth-AI-Demos/blob/master/scenarios/dragon.cfg dragon.cfg] is an example of a basic scenario that still uses the old AI syntax, while [https://github.com/mattsc/Wesnoth-AI-Demos/blob/master/scenarios/healer_support.cfg 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 [http://www.lua.org/ 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 [http://www.lua.org/docs.html Lua documentation], in particular the first few sections of the [http://www.lua.org/manual/5.1/manual.html 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, [https://github.com/mattsc/Wesnoth-AI-Demos/blob/master/scenarios/prune-cart.cfg 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:

# Convert existing AIs to Micro AIs ''as they are'' (to enable easy inclusion in scenarios)
# 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 requires you to go through a number of steps, but is otherwise 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 tasks (but see [[Google_Code-in_Micro_AI_Tasks#AIs_to_be_Converted|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.

Note: For this initial conversion you can (should) work with hard-coded values for things like unit IDs, unit types, locations etc., exactly as they are currently used in the respective scenario. The generalization of these parameters happens in the [[Google_Code-in_Micro_AI_Tasks#Parametrizing_a_Micro_AI|next step]].

=== 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). This macro will later be included in the [side] tag for the side that is to use this AI. It sets up the AI engine for that side.

=== Lua Engine File ===

The Lua engine file needs to be moved to the Micro AIs directory.

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. If you are unsure whether you should move or copy the file, copy it. You can always remove the original later.

=== 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 '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. In some cases, the CAs are defined in a macro in a separate file. If that is the case, this is noted in the [[Google_Code-in_Micro_AI_Tasks#AIs_to_be_Converted|descriptions of the individual AIs]] below.

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. For some AIs, AI [[AiWML#Aspects_and_Goals_Overview|aspects]] need to be added/deleted also. If so, this is also noted in the [[Google_Code-in_Micro_AI_Tasks#AIs_to_be_Converted|descriptions of the individual AIs]] below.

At this point, you should have a working Micro AI. 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, Documenting and Pushing to the Github Repository ===

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. '''The task will not be accepted until at least basic documentation has been provided.'''

12. Once you are satisfied that everything is working correctly, add yourself to the credits in the _main.cfg file and put in a [https://help.github.com/articles/using-pull-requests pull request] with your changes at the github repository. This counts as submitting the task and will start the review process by the mentors, who will commit it once it is accepted.

== Parametrizing a Micro AI ==

For each Micro AI, there are one or more follow-up tasks that involve adding additional parameters to the [micro_ai] tag. The goal of these tasks is to make the Micro AI configurable to work in 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. Test, document and submit a [https://help.github.com/articles/using-pull-requests pull request] at the github repository, same as for the basic AI conversion tasks.

More information concerning the parametrization of the specific AIs is given in the following.

== 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) ===

'''Step 1:'''

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 [[Lua_AI_Howto#Behavior_.28Sticky.29_Candidate_Actions|Behavior Candidate Action]] (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.

Step 1 is completed when scenario 'Patrols' uses the [micro_ai] tag to control Jabb and the basic Micro AI has been documented.

'''Step 2:'''

Parametrization of this AI involves (at least) making the [micro_ai] tag work for arbitrary units (not just Jabb) and for an arbitrary set of waypoints. The controlled unit should also attack any enemy unit that it ends up next to, not just Jacques.

Step 2 is completed when this parametrization has been achieved, has been included in the scenario and has been documented.

=== Lurkers (1 AI) ===

'''Step 1:'''

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.

Step 1 is completed when scenario 'Lurkers' uses the [micro_ai] tag and the basic Micro AI has been documented.

'''Step 2:'''

Part of the work for Step 2 is figuring out what parameters can be added to the lurker AI to make it more generally useful. Examples could be to make it work for arbitrary unit type and arbitrary terrain.

Step 2 is completed when at least 3 keys/parameters have been added to the Micro AI and have been documented.

=== Protect Unit (1 AI) ===

'''Step 1:'''

This AI is used in 2 scenarios, 'Protect the Wizard' and 'The Elves Besieged'. The first step of this task involves setting up a Micro AI for scenario 'Protect the Wizard' only. Thus, leave the original engine file in place (copy it, rather than moving it), otherwise 'The Elves Besieged' will stop working.

Note that, in order to activate/delete this Micro AI, the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|attack aspect]] needs to be added/removed in the *_CA.lua file in addition to the candidate actions. See the scenario file.

Step 1 is completed when scenario 'Protect the Wizard' uses the [micro_ai] tag and the basic Micro AI has been documented.

'''Step 2:'''

Parametrization for this AI is already done in the engine functions, so Step 2 for the 'Protect Unit' scenario mostly involves just setting up the keys and parameter handlers for the parameters. However, scenario 'The Elves Besieged' requires the removal of one of the default AI candidate actions (see the scenario file). Thus, you also need to set up an additional key/parameter that allows for optional removal of this CA.

Step 2 is completed when both scenarios 'Protect the Wizard' and 'The Elves Besieged' use the [micro_ai] tag and the parametrized Micro AI has been documented.

=== Guardians (3 AIs) ===

Scenario 'Guardians' contains several guardian AIs, three of which should be converted to Micro AIs: return guardian, stationed guardian and coward.

'''Important notes:'''

* The guardian AIs (including a fourth AI that will not be converted to a Micro AI) are all part of Side 2, which means that the [ai] tag in the side definition cannot be deleted.
* All three guardian AI functions are defined in the same engine file. Thus, the file needs to be copied, rather than moved, to the new location until all three guardian AIs have been converted.
* This is a [[Lua_AI_Howto#Behavior_.28Sticky.29_Candidate_Actions|Behavior Candidate Action]] (BCA), that is, it attaches to a unit, rather than controlling all (relevant) units of a side. See the comments about BCAs in the description of the [[Google_Code-in_Micro_AI_Tasks#Patrols_.281_AI.29|Patrols AI]].
* The BCA CA code is included as macros. The macros are defined in file utils/lua_macros.cfg.

'''Step 1:'''

Choose one of the three guardian AIs and convert it to a basic Micro AI. For this step, it is sufficient to make the Micro AI work for a single guardian unit (comment out the other unit(s) of the same guardian type in the scenario file) with hard-coded values for the unit ID and other parameters.

Step 1 is completed when scenario 'Guardians' controls one guardian unit using the [micro_ai] tag and the basic Micro AI has been documented.

'''Step 2:'''

Change the guardian Micro AI code so that the hard-coded values of the previous step are configurable keys/parameters in the [micro_ai] tag.

Step 2 is completed when several units of the same guardian type are controlled by the Micro AI (using one [micro_ai] tag per unit) in the 'Guardians' scenario and this has been documented.

'''Steps 3a and 3b:'''

Pick one of the other guardian AIs and convert it to a Micro AI. This should be done as a parametrization of the AI that was already converted in Steps 1 and 2, and not by defining a new Micro AI type. Thus, 'ai_type=' should be 'guardian' for all guardian Micro AIs, and an additional key 'guardian_type=' should be added.

Note: Steps 3a and 3b can, in principle, be done in parallel. They only require Steps 1 and 2 to be completed first.

Each of these steps is completed when several units of the same guardian type are controlled by the new guardian Micro AI type (using one [micro_ai] tag per unit) in the 'Guardians' scenario and this has been documented.

=== Animals (7 AIs) ===

There are a total of 7 animal AIs in 4 different scenarios: 'Dragon' (1 AI), 'Wolves' (1 AI), 'Swarm' (1 AI) and 'Animals' (big animals, forest animals, sheep and another wolves AIs). All of these need to be converted to Micro AIs with 'ai_type=animal' and different 'animal_type=" values.

'''Important Notes:'''

* The dragon AI should be converted first (Steps 1 and 2). After that, you can choose any order for the remaining AIs.
* The dragon AI is a BCA with the candidate action being set up in a macro. See the notes for the [[Google_Code-in_Micro_AI_Tasks#Guardians_.283_AIs.29|guardian Micro AI]] for how to deal with such an AI. All other AIs control all (suitable) units on their side.
* When converting the AIs, the unit types should be set up as parameters (if different unit types on the same side display different types of behavior), rather than being hardcoded as they are now for some of the animal AIs.
* Side 6 in scenario 'Animals' (wolves AI) contains two aspect definitions in addition to the candidate actions. These aspects need to be made part of the Micro AI as well (and ideally they could be turned on/off with configurable parameters).

'''Step 1:'''

Convert the dragon AI to a basic Micro AI. For this step, it is sufficient to use the hard-coded values for the unit ID and other parameters.

Step 1 is completed when scenario 'Dragon' controls the dragon using the [micro_ai] tag and the basic Micro AI has been documented.

'''Step 2:'''

Change the dragon Micro AI code so that the hard-coded values of the previous step are configurable keys/parameters in the [micro_ai] tag.

Step 2 is completed when the parametrization of the dragon Micro AI is complete and has been documented.

'''Steps 3a-3f:'''

Pick any one of the other animal AIs and convert it to a Micro AI. This should be done as a parametrization of the AI that was already converted in Steps 1 and 2, and not by defining a new Micro AI type. Thus, 'ai_type=' should be 'animal' for all animal Micro AIs, and an additional key 'animal_type=' should be added.

Note: Steps 3a-3f can, in principle, be done in parallel. They only require Steps 1 and 2 to be completed first.

Each of these steps is completed when all sides using the given AI type are controlled by the new animal Micro AI type in the respective scenario and this has been documented.

[[Category:AI]]

Micro AIs

2012-11-28T23:51:22Z

Ubuntor: Messenger Escort step 2

Micro AIs

2012-11-28T04:02:57Z

Ubuntor: GCI Messenger (step 1)