AiWML

[edit]WML Tags

A: abilities, about, achievement, achievement_group, add_ai_behavior, advanced_preference, advancefrom, advancement, advances, affect_adjacent, ai, allied_with, allow_end_turn, allow_extra_recruit, allow_recruit, allow_undo, and, animate, animate_unit, animation, aspect, attack (replay, weapon), attack_anim, attacks (special, stats), avoid;

B: base_unit, background_layer, berserk, binary_path, break, brush;

C: campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, checkbox, choice, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_palette, color_range, command (action, replay), continue, core, credits_group, criteria;

D: damage, damage_type, death, deaths, default, defend, defends, defense, delay, deprecated_message, destination, difficulty, disable, disallow_end_turn, disallow_extra_recruit, disallow_recruit, do, do_command, drains, draw_weapon_anim;

E: editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry (credits, options), era, event, experimental_filter_ability, experimental_filter_ability_active, experimental_filter_specials, extra_anim;

F: facet, facing, fake_unit, false, feedback, female, filter (concept, event), filter_adjacent, filter_adjacent_location, filter_attack, filter_attacker, filter_base_value, filter_condition, filter_defender, filter_enemy, filter_location, filter_opponent, filter_own, filter_owner, filter_radius, filter_recall, filter_second, filter_second_attack, filter_self, filter_side, filter_student, filter_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, fonts, for, foreach, found_item, frame;

G: game_config, get_global_variable, goal, gold, gold_carryover;

H: harm_unit, has_ally, has_attack, has_unit, has_achievement, have_location, have_unit, heal_on_hit, heal_unit, healed_anim, healing_anim, heals, hide_help, hide_unit, hides;

I: idle_anim, if (action, animation, intro), illuminates, image (intro, terrain), init_side, insert_tag, inspect, item, item_group;

J: jamming_costs, join;

K: kill, killed;

L: label, language, leader, leader_goal, leadership, leading_anim, levelin_anim, levelout_anim, lift_fog, limit, literal, load_resource, locale, lock_view, lua;

M: male, menu_item, message, micro_ai, missile_frame, modification, modifications, modify_ai, modify_side, modify_turns, modify_unit, modify_unit_type, move, move_unit, move_unit_fake, move_units_fake, movement_anim, movement costs, movetype, multiplayer, multiplayer_side, music;

N: not, note;

O: object, objective, objectives, on_undo, open_help, option, options, or;

P: part, petrifies, petrify, place_shroud, plague, poison, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, progress_achievement, put_to_recall_list;

R: race, random_placement, recall (action, replay), recalls, recruit, recruit_anim, recruiting_anim, recruits, redraw, regenerate, remove_event, remove_item, remove_object, remove_shroud, remove_sound_source, remove_time_area, remove_trait, remove_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resolution, resource, return, role, rule;

S: save, scenario, screen_fade, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_achievement, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, objective, set_menu_item), show_objectives, side, skirmisher, slider, slow, snapshot, sound, sound_source, source (replay, teleport), special_note, specials, split, stage, standing_anim, statistics, status, store_gold, store_items, store_locations, store_map_dimensions, store_reachable_locations, store_relative_direction, store_side, store_starting_location, store_time_of_day, store_turns, store_unit, store_unit_defense, store_unit_defense_on, store_unit_type, store_unit_type_ids, store_villages, story, swarm, sub_achievement, switch, sync_variable;

T: target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, test_do_attack_by_id, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel;

U: unhide_unit, unit (action, scenario), unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;

V: value, variable, variables, variant, variation, victory_anim, village, vision_costs, volume;

W: while, wml_message, wml_schema;

Z: zoom;

As of BfW 1.9, the only AI available by default is the RCA AI (Register Candidate Action AI). During the AI turn, a number of potential actions (called candidate actions) are evaluated for each move. The candidate action with the highest evaluation score is executed. Then the next move is evaluated, until no more valid moves are found, which ends the AI turn.

The RCA AI is highly configurable in three different ways (sorted by increasing complexity):

• Changing the parameters/weights by which the AI moves (candidate actions) are evaluated. This can be done easily in the WML code by setting aspects and goals and is the content of this page.

• Changing the order in which candidate actions are executed (changing their evaluation scores) or deleting candidate actions. See Practical Guide to Modifying AI Behavior for details.

• Writing your own candidate actions using FormulaAI or LuaAI. See Practical Guide to Modifying AI Behavior for details.

Historical note: the default AI used through BfW 1.8 was named 'Default AI' (note the capital D). This might cause confusion, as the current default (RCA AI) is not the Default AI.

Evaluating AI Moves -- Candidate Actions (CAs)

When the AI does its turn, a number of potential actions (called candidate actions, CAs) are evaluated for each move. The CA with the highest evaluation score is executed. Then the next move is evaluated, until no more valid moves are found, which ends the AI turn. The following candidate actions are evaluated for each move:

• Goto CA: Move units toward the coordinates set by goto_x and goto_y in their unit WML.

• Recruitment CA: Recruit or recall units.

• Move leader to goals CA: Move the leader to goals set by [leader_goal].

• Move leader to keep CA: Move the leader to the closest available keep.

• Combat CA: Attack enemy units that are in range. Note that this CA includes the move next to the enemy unit as well as the attack itself.

• Healing CA: Move units onto healing locations (generally villages).

• Villages CA: Move units onto villages that are unoccupied or owned by an enemy.

• Retreat CA: Evaluate if any units are in grave danger/hopelessly outnumbered, and if so, retreat them.

• Move to targets CA: Evaluate potential targets and move units toward those targets. The evaluation takes into account how valuable the targets are (this is configurable by setting goals) and how easily the AI's units can get there. Targets are enemy units, villages as well as anything set as a goal. It is important to understand that targets only apply to locations that cannot be reached during the current turn. If the AI's unit(s) can get there, other CAs, such as Combat, Healing and Villages take over instead. Thus, a target is specifically not an attack target, but only a move target.

• Passive leader shares keep CA: Move the leader off the keep to let an allied leader recruit.

If several candidate actions are possible for a given move, they are evaluated in the order given above. For example, the Goto CA is always the first thing that is done. If a valid attack is found in the Combat CA, it is always executed before any healing, village grabbing or move-to-target moves. One of the effects this has is that attacks always override any goals/targets of the move-to-target phase.

Aspects and Goals

'Aspects' are configurable parameters used in the candidate action score evaluation. Most commonly, aspects are set using the [ai] tag as described below. There are simple aspects which take on an individual value, and composite aspects that might contain several keys or sub-tags. The sub-tags of aspects are called 'facets'.

'Goals', also called 'targets', are composite aspects that influence the behavior of the AI in the move-to-targets candidate action. As there a several different goals available, they are given their own subsection below (to be added).

the [ai] tag

The [ai] tag is used inside a [side] tag, and it's contents define how the AI controlling that side acts. You can use multiple [ai] tags and have them apply during different turns or times of day, for example to set an undead side's caution higher and aggression lower during the day, or to boost the aggressiveness of a side when they receive reinforcements on a specific turn.

The following key/tags can be used in an [ai] tag:

• time_of_day: (string) the time(s) of day when the AI should use the parameters given in this [ai] tag. Possible values are listed in data/core/macros/schedules.cfg (See TimeWML).

• turns: (string) during which turns the AI should use the parameters given in this [ai] tag. This takes the same syntax of dashes(-) and commas(,) as is described under Filtering Locations in FilterWML, except of course they apply to turns not locations.

• ai_algorithm: (string) allows an alternate AI algorithm (cannot be created with WML) to be used. Besides the default, the game comes with only idle_ai, which makes the AI do nothing and can be used to create a passive, unmoving side. Cannot be applied only to a set of turns or a given time of day using the keys turns and time_of_day, but must be given either in an [ai] tag without the aforementioned keys or outside [ai] tags inside the [side] tag.

• aggression=0.5: (double) (value ranged from -infinity to 1.0 ) This key affects how an AI player will fight.
  • In the following formulas of type X - Y = Z, X is always 1 and Z is the value that aggression should be set to: aggression=Z.
  • It determines how an AI considers the difference between its units and its opponents by taking the value 1 - AI unit value in proportion to opponent unit value. ('Unit value' here means that the AI weights its decision on the chance to kill a unit or be killed, using a combination of its own units.) So, to make an AI which considers its units worthless, i.e. only cares about how much damage attacks inflict, set aggression at 1 - 0 = 1.0. This is the highest meaningful value for aggression; although it is insane, it is used on many HttT levels. If an AI set on this value can inflict 1 damage and take 0, or inflict 2 damage and take 20 himself, he'll take the latter option. To make an AI which considers its units equally as valuable as its opponent's, i.e. only attacks if he feels he can inflict more damage than he receives, set aggression at 1 - 1 = 0.0.
  • Although an AI which considers its opponent's units worthless is impossible under this scheme, an AI which, for example, considers its units twice as valuable as its opponent's can be represented by aggression 1 - 2 = -1.0.
  • The default is 1 - 1/2 = 0.5, which means the AI is content with dealing only half the damage to his opponent of that which he himself takes.
  • Or to put this whole thing into context, agression=1.0. means it will deal the maximum possible damage, agression=-10000000000000000.0. means it will never attack unless it will recieve no damage in exchange.

• attack_depth=5: (int) a number from 1 to 6. This is how many units will be thought about to attack a single unit. If the attack is completed, the AI on another round of thinking may still decide to attack that unit again with other units. Note that in battles, a unit usually can't be attacked from all six sides anyway, so any high attack_depth will be about the same. If attack_depth is low, the AI won't want to attack unwounded units very much, because it doesn't think it can kill them in the attack.

• [avoid]="": Makes the AI avoid a specific location or unit.
  • x, y standard coordinates- A location for the AI to avoid moving to. The AI will never move a unit to this location except for trying to move its leader to a keep. Either coordinate may be a range; ranges are interpreted in the usual way as areas, in this case to be avoided.
  • StandardLocationFilter A set of locations for the AI to avoid moving to.

• caution=0.25: (double) A number 0.0 or higher that affects how cautious the AI is in various ways. If it is higher, the AI will want to retreat more (especially to a better defensive terrain), it will dislike moving out of a defensive terrain to attack more, and, if grouping is enabled, it forms bigger groups to protect from enemies when going to a target.
  • Considering a retreat will be skipped (during the retreat phase) if caution is set to 0 or lower. If caution is greater than 0, there will be an evaluation of forces for the map location a unit stands on. This is basically the sum of damage that can be done to that location, reduced by terrain defense and relative hitpoints if attackers don't have full health. A retreat will take place, if
    caution * their_power > our_power
    There is also a terrain factor involved if the attacker is not on optimal terrain, but i'll skip this here for simplicity.
    So let's say the AI has its default caution of 0.25. Then the enemy forces have to be 4 times as strong at least before the unit will retreat. For a caution of 1, as soon as the enemy is considered to be stronger, the unit will retreat.
  • Caution is also considered within the attack analysis to evaluate the rating of attacks. The mathematics for that is rather complicated, so let's just state that the caution value directly and proportionally influences a value for reducing the rating of an attack. A caution of 0 will have no influence (the rating won't be reduced at all).
  • If grouping for the AI is enabled and the path to move the group along is considered to be dangerous, caution will have an influence, too. "Dangerous" mainly means there is a possibility for the best attacker of a primary target to be severely harmed, for example if he can be killed by enemies if not protected. In that case, the AI will compare our group with the enemy and based on the result move forward or not. "Group", from what i understood, means every unit of that side, including the leader. So it's not really a coherent group necessarily. Our side is rated which is mainly the sum of maximum damage * defense modifiers for every unit. Then this is compared to the enemy strength by determining a relation of both. A value of 1 means both sides have equal strength. Higher values indicate our side is stronger, lower values likewise. The formula for deciding if a group moves on is:
    our_strength / their_strength > 0.5 + caution
    So if caution is 0.5, our side needs to be at least as strong as the enemy. If it is 0, we go on, even if the enemy is up to twice as strong as we are. Setting caution to 1.5 means we need to be at least twice as strong to have the group keep moving.
  • Caution also influences putting units onto villages. However, i haven't understood the code well enough yet to make backed up statements about it. Probably it's an estimation about how exposed a unit will be on that village, based on how many damage the enemy can do to it.
  • Caution often won't influence the AI if the leader is involved, because for many actions it is hardcoded with a value of 2.0.

• grouping="offensive": (string) how the AI should try to group units
  • offensive: Makes the AI try to group units together before attacking.
  • defensive: Makes the AI group units together very conservatively, and only advances much beyond its castle if it has overwhelming force.
  • no: Makes the AI not use grouping behaviour. This is what it used to be like.

• leader_aggression="-4.0": exactly as aggression, but for units which can recruit.

• [leader_goal]="": Makes the AI try to move its leader to a specific location (as in the goal of The Elves Besieged).
  • x, y: the location for the AI to move its leader to

• leader_value=3: (double) A number 0 or higher which determines how much the AI moves towards enemy leaders (after the turn's combats have been conducted).

• number_of_possible_recruits_to_force_recruit=3.1: (double) a number higher than 0.0. Tells AI to force the leader to move to a keep if it has enough gold to recruit the given number of units. If set to 0.0, moving to recruit is disabled.

• passive_leader=no: (bool) if 'yes' the AI leader will never move or attack, except to obey [leader_goal]s.

• passive_leader_shares_keep=no: (bool) if 'yes', sets passive_leader=yes, but the AI leader will move 1 hex from the keep to share keep with allied players (if they can reach keep next turn), and will return to keep to recruit.

• protect_leader=2.0 and protect_leader_radius=10: the way these parameters work, is to target any enemy units that come within 'protect_leader_radius' of the AI leader with a value of 'protect_leader' on the units.

• [protect_location]="": gives the AI a location to protect. Note that the AI will NOT station any units around the location, it will only send units to attack any enemy units that come within the guarding radius of the target.
  • x, y standard coordinates. These indicate the location the AI is protecting,
  • radius: indicates the radius around it to protect (0 indicates a single hex)
  • value: indicates the importance of protecting this location

• [protect_unit]="": gives the AI a set of units to protect. Note once again that the AI will not place units around the unit if there are no enemies nearby.
  • StandardUnitFilter: The unit(s) to protect. Do not use a [filter] tag.
  • radius: indicates the radius around it to protect (0 indicates a single hex)
  • value: indicates the importance of protecting this unit

• recruitment_ignore_bad_movement=no: (bool) if 'yes', the AI will not analyse the terrain to see if the unit is suitable for it.

• recruitment_ignore_bad_combat=no: (bool) if 'yes', the AI will not analyse the units the enemy has fielded to see if the unit is suitable for fighting them.

• recruitment_pattern="": (string) This key takes a comma separated list containing the usages defined in the recruitable units. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The AI considers all units with the specified usage(s) so make sure the units you want recruited are really covered by the pattern or use an empty pattern to have all available units considered regardless of usage. The usage is listed in the unit type config files. (See data/core/units/ for mainline units; See also UnitTypeWML)
  • For example, "recruitment_pattern=fighter,fighter,archer" means, the AI will recruit twice as many fighters as archers, and not recruit scouts (other than scouts for capturing villages, who are recruited independently), healers or mixed fighters.

• scout_village_targeting=3: (double) The AI multiplies the value of village targets for scouts by this value.

• simple_targeting=no: (bool) When the AI decides what targets to move towards with which units, it considers all its units that can move, sequentially. For each unit, it decides what the best target for it to go towards is. If not 'yes', it will check if any other units would be better to go towards that target than the unit it is currently considering.

• support_villages=no: (bool) Trigger a code path that will try to protect those villages which are threatened by the enemy. This seems to cause the AI to just 'sit around' a lot, so it's only turned on if it's explicitly enabled.

• [target]="": Any number of [target] tags can be used to set a target for the AI. For anything related to 'values', set them relative to other targets. An AI is willing to dedicate twice as many resources and travel twice as far to get a target worth '2.0' as it is a target worth '1.0'.
  • StandardUnitFilter Do not use a [filter] tag.
  • value: A number greater than 0 (default=1) which determines how much the AI tries to kill all units which pass the filter.

• village_value=1: (double) A number 0 or higher which determines how much the AI tries to capture villages.

• villages_per_scout=4: (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages.

See Also

• AI_Module
• ReferenceWML
• Customizing_AI_in_Wesnoth_1.8