GCI/Port AI WML configuration to new style syntax

Use wesnoth 1.9.2 or work on trunk version

You can download 1.9.2 from here: http://wiki.wesnoth.org/Download#Development_.281.9_branch.29

Wesnoth uses a custom markup language called WML, which can be edited by hand (it's similar to xml)

AI configuration can be written using WML.

In 2009, a new style syntax for writing AI configurations in Wesnoth was created.

New syntax is described on Customizing_AI_in_Wesnoth_1.8

Old syntax is described on AiWML

We need to convert existing AI syntax to new style.

The preferred way to do it is to teach wesnoth's custom WML conversion tool, wmllint, (written in python) to do it, or to write a helper script to do it. Or it can be done by hand. In any case, human review is required, to see that everything is ok.

As an example of the conversion process, you can use the first scenario of Legend of Wesmere campaign:

before, it contained:

[ai]
   village_value=0
   leader_value=0
   protect_leader=0
   [avoid]
       x=1-30,1-30,1-3,7-30
       y=1-13,17-30,1-30,1-30
   [/avoid]
[/ai]

after:

{ai/aliases/stable_singleplayer.cfg}
[ai]
   {AI_SIMPLE_ALWAYS_ASPECT village_value 0}
   {AI_SIMPLE_ALWAYS_ASPECT leader_value 0}
   {AI_SIMPLE_ALWAYS_ASPECT_VALUE avoid (
       x=1-30,1-30,1-3,7-30
       y=1-13,17-30,1-30,1-30
   )}
[/ai]

Or, if we had separate config for 'night' time of day ( time_of_day=dusk,first_watch,second_watch)

before:

       [ai]
           recruitment_pattern=scout,fighter,fighter,archer,mixed fighter
       [/ai]
       [ai]
           time_of_day=dusk,first_watch,second_watch
           aggression=0.75
           caution=0.0
           grouping=offensive
       [/ai]

after:

 {ai/aliases/stable_singleplayer.cfg}
 [ai]
    {AI_SIMPLE_NIGHT_ASPECT aggression 0.75}
    {AI_SIMPLE_NIGHT_ASPECT caution 0}
    {AI_SIMPLE_NIGHT_ASPECT grouping offensive}
    {AI_SIMPLE_ALWAYS_ASPECT recruitment_pattern "scout,fighter,fighter,archer,mixed fighter"}
  [/ai]

you might need to ask questions about how a particular tag should be converted, ask Crab_ on #wesnoth-dev on libera.chat.

Conversion procedure

In general, we need to add {ai/aliases/stable_singleplayer.cfg} outside the ai tag. then, for each ai tag, we need to look if it's 'for all times or day' or for particular time of day. then, if it's an aspect, just use the appropriate form of

{AI_SIMPLE_NIGHT_ASPECT aspect_name aspect_value}
{AI_SIMPLE_DAY_ASPECT aspect_name aspect_value}
{AI_SIMPLE_ALWAYS_ASPECT aspect_name aspect_value}

list of aspects which are converted that way

aggression

attack_depth

[avoid]

caution

grouping

leader_aggression

leader_goal

leader_value

number_of_possible_recruits_to_force_recruit

passive_leader

passive_leader_shares_keep

recruitment_ignore_bad_combat

recruitment_ignore_bad_movement

recruitment_pattern

scout_village_targeting

simple_targeting

support_villages

village_value

villages_per_scout

[target]\[protect_..] tags are converted to [goal] tags, see the new-style docs for details.

for other AI parameters, figure it out or ask Crab_ on #wesnoth-dev on IRC at libera.chat

Notes (23rd November)

everything should be converted. if it's unclear how to convert something, ask.

for attack_depth, you can convert it in the same way as aggression or, in the specific case '3 for easy, 4 for medium, 5 for hard', use {AI_SCALE_ATTACK_DEPTH_BY_DIFFICULTY} macro

ai goal syntax is at http://wiki.wesnoth.org/Customizing_AI_in_Wesnoth_1.8#AI_goals_.28_via_.5Bgoal.5D_tags_.29

to test the changes, you don't have to recompile - hitting F5 from main menu or restarting should be enough to refresh the cache and pick up new changes to WML code.

you can use :inspect - it allows you to see the ai configuration and you can compare the results of your changes vs the results of the 'upgrade' procedure written in c++ - by using :inspect two times, with and without your changes

Also, you're welcome to show incomplete results for review (link to these in google's task tracker)

If something varies by difficulty, or uses QUANTITY macro, e.g. {QUANTITY aggression 0.55 0.75 0.85} convert it using the ON_DIFFICULTY macro {AI_SIMPLE_ALWAYS_ASPECT aggression {ON_DIFFICULTY 0.55 0.75 0.85} }

Notes (24th November)

convert {NO_SCOUTS} to {AI_NO_SCOUTS}

Notes (25th November)

{ai/aliases/stable_singleplayer.cfg} should be given inside [side] tag, inside each [side] tag where there's at least one [ai] tag.

please test your changes by loading every and each scenario from wesnoth to see if it loads without errors (use debug mode ':n' command to switch levels)

protect_leader and protect_leader_radius

are converted differently (see Customizing_AI_in_Wesnoth_1.8#protect_my_unit_.5Bgoal.5D)

if the block includes turns=, then this block is active only during the specific turns.

To deal with them:

1) write a wml event to change the AI on the turn where it changes.

2) use more low-level macros (deal with [facet] tags ) to specify the active turns for each of the time periods.

Notes (29th November)

To convert [ai] blocks which have turns=, you can the [aspect] tag directly without the macros:

[aspect]
  id=aggression
  [facet]
       value = 0.4
       time_of_day="dawn, morning, afternoon"
       turns=1-12
  [/facet]
  [facet]
       value = 0.7
       time_of_day="dusk,first_watch,second_watch"
       turns=1-12
  [/facet]
  [facet]
       value = 0.9
       turns=13-FOREVER
   [/facet]
[/aspect]

To handle adjacent '[avoid]' sections, combine them using the [or] filter

converting:

[avoid]
x,y=1,11
[/avoid]
[avoid]
x,y=21,31
[/avoid]
[avoid]
x,y=41,51
[/avoid]

to

{AI_SIMPLE_ALWAYS_ASPECT_VALUE avoid
(
x,y=1,11
[or]
x,y=21,31
[/or]
[or]
x,y=41,51
[/or]
)}