= Introduction =

*Basics

**Write a small introduction to yourself.
My name is Bartek Waresiak and I'm from Poland. I'm 22 years old male interested in programming, computer science and gaming. I have been Battle for Wesnoth player for more than 5 years, and developer for about 4 years (coder since Summer of Code 2008).

**State your preferred email address.
either dragonking_ATTT_o2_D0T_pl or b.waresiak_ATTT_gmail_D0T_com

**If you have chosen a nick for IRC and Wesnoth forums, what is it?
Dragonking

**Why do you want to participate in summer of code?
By participating in Google Summer of Code I want to significantly increase amount of time that I spend working for Battle for Wesnoth, have some fun and earn some money.

**What are you studying, subject, level and school?
I'm studying Information Technology, 3nd year at AGH University of Science and Technology in Cracow, Poland.

**If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for Wesnoth. If you have gained commit access to our SVN (during the evaluation period or earlier) please state so.
I have access to SVN. My recent contributions to Wesnoth:
*** Before 1.6 release 'bugfixing-time':

*** Directly before Summer of Code application period:

*Experience
**What programs/software have you worked on before?
***I've been one of Battle for Wesnoth developers since September 2005 and I have been working on FormulaAI language since Summer of Code 2008. Besides that, I wrote various projects for my university (algorithm-testing, training projects, optimalization tasks, etc...).
**Have you developed software in a team environment before? (As opposed to hacking on something on your own)
***I'm one of Developers in 'Battle for Wesnoth' project and I have experience in group decision making.
**Have you participated to the Google Summer of Code before? As a mentor or a student? In what project? Were you successful? If not, why?
***I had been participatin in Google Summer of Code 2008, workin on Formula AI for Battle for Wesnoth project. My project was successful.

*Open Source
**Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.
***As Developer for Battle for Wesnoth project I've been responsible for developing, improving, testing and documentation of the FormulaAI language. Besides that, I've been supporting people trying to use this language in their scenarios/campaigns. Previously, as a Multiplayer Developer I've been one of people responsible for unit balancing (unit statistics tweaking), multiplayer server moderation and basic administration.

*Gaming experience
**Are you a gamer?
***Yes, I like to play various types of games: strategy games - both real time and turn-based, role-playing games and some of the first person shooters. I'm rather patient and calm player and I enjoy difficult games which require some amount of 'hard thinking'.
**What type of opponents do you prefer?
***I prefer human opponents much more than AI, but they have to be polite, civil and mature. I really enjoy games against experienced player, though I don't mind also tutoring new ones.
**Are you more interested in story or gameplay?
***I value both - IMHO to bring a game to someone's attention, it must have a decent gameplay. If it has a nice storyline as well, then chances that players will keep playing and won't leave increase.
**Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer.
***I have been playing Wesnoth since about 0.7 version, mainly multiplayer because I enjoy Wesnoth players community and recognize it as polite and mature one. Also, like I mentioned, multiplayer games against human opponents are for me much more enjoyable than single-player campaigns.

*Communication skills
**Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.
***I have no problem with understanding written English, and describing my thoughts to the others in this language.
**Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.
***I think I know Wesnoth developers and players community well, and I've always been trying to always be on good terms with everyone. I know whom to talk to about different issues and who can give me needed advice or support. I also have quite a lot experience with interacting with multiplayer community.
**Do you give constructive advice?
***When giving advice, I try to be as detailed as possible, and make sure that people who I direct advice to understand me well. I am aware that during the internet chat you can be misinterpreted and your advice may instead be received as a negative criticism, I'm trying to avoid it by being friendly towards others.
**Do you receive advice well?
***I know that I can be wrong and that around me many people are far more experienced than me, I consider advices from others as a good thing which helps me improve and develop my skills.
**Are you good at sorting useful criticisms from useless ones?
***I have to admit it is hard to receive bad criticism - if someone is telling you that you are plain wrong, but is not providing any arguments to back up his opinion, then usually this kind of criticism is a useless one. If someone can criticize what I am doing providing examples what is wrong and how it can be improved - it is definitely an example of useful and desired criticism.

*Project
Described below.

*Practical considerations
**AAre you familiar with any of the following tools or languages?
***Subversion
****Yes, about 3-year experience.
***C++
****I have more than 2 years of C/C++ experience.
***Python
****No.
**Which tools do you normally use for development? Why do you use them?
***I'm working on Debian Linux.
**What programming languages are you fluent in?
***C/C++ and Java.
**What spoken languages are you fluent in?
***Polish - which is my mother tongue, and English.
**At what hours are you awake (please specify in UTC)
***Usually I'm awake between 8 and 23 UTC, and available on IRC betweeen 17 and 23 UTC.
**Would you mind talking with your mentor on telephone / internet phone? We would like to have a backup way for communications for the case that somehow emails and IRC do fail.
***I wouldn't mind.

= Idea Description =
== Why FormulaAI? ==

I have been working on FormulaAI for a while now - bugfixing, new functions, new features, testing, etc. I know the existing code well. Besides that, I'm experienced wesnoth player, and I know many various strategies/tactics, so I have really strong understanding of different aspects of the game, what is definiately a desired thing if one wants to work on improving the AI. Besides that, formula AI language can be used by other people to write their own simple AI - and I do enjoy helping others who want learn this language.

== Let's start from what is proposed... ==

In the wiki, and after some talking on the IRC I can see 2 proposed ideas: first is Formula AI library, with functions that user could inclue and use. Second, is AI written in FormulaAI language, that improves current C++ and can beat it. After some thinking, I consider first idea to be too general one. I find it hard to define milestones, find reasonable ideas for functions. In my opinion, such thing is not good to choose for SoC, when you have to write something useful in limited amount of time, but should grow slowly, based on what people who actually use formula AI need.

== Then, why not AI ? ==

Second proposal is simmilar to the one form year ago. Because I was one of the people working on this during SoC 2008, I can see some problems with this idea. First problem I encountered year ago, was FormulaAI language itself - it was not developed enough for such a big task at that time, and because of that I was forced to focus on improving language itself rather than working on the AI. I believe that in current state of FormulaAI language, designing AI could be easier, but still would be disturbed by bugfixing. Second problem I can see, is that I don't believe that general wesnoth AI can be written in FormulaAI language alone. It can work perfectly for some scenario where you nee a specific-purpose AI, but not for general case, even with current approach of candidate moves/side formulas because of how complicated AI in wesnoth must be. And third thing: recently DarthFool and Sirp presented some interesting ideas of re-developing AI for wesnoth. Both of them mentioned, that formulas written in formula AI language could be used as plugins to the AI - difference between current implementation and their ideas would be that we could better design the relation between C++ AI and formulas - not make formula AI and then fallback to default "stupid" one like it is only possible now. And this leads to what I would like to do during Summer of Code:

== Straight to the point ==

I would like to focus on improving and extending the formulaAI language during Google Summer of Code 2009. First, because it could be later used to "support" creating better default AI, second, because 1.6 is first stable release in which formula AI is available for campaign designers. I know that it may sound a bit "general" and it may be hard to consider good tasks and milestones, but I believe that with my experience from previous GSoC I can propose reasonable approach. Generally, I would work on my ideas for formula AI language, and in between, I would fix some bugs and help people around using formula AI. It is hard to define now how much time fixing bugs/helping others will take, so I don't want to base my evaluation on that. I just want to note that there may be a need to alter my milestones/timeline (like last year's SoC showed us). But to give you some detail that I do know what I want to do...

== Things to implement to formula engine ==

=== 'on_fail' formulas ===
==== Background ====
Current problem with formula language is: what if there no no room for recruitment but we still send order to recruit? Or we send recruit order, but with unknown/incorrect unit name? ATM, formula treats it as an invalid move, so all loop-type formulas are cancelled. This is not a good approach, because order itself is valid, just it contains incorrect data.
==== Solution ====
I propose "on_fail" formula, available both for side and for unit formulas. Basic example is:

move="recruit('Skeleton Archer')"
on_fail="fallback()"

If we cannot recruit Skeleton Archer, then we just fallaback to default AI. But there's more - to give proper info about what happened, the "error" and "errdsc" side variables would be set to allow trace the problem, thus we could use on_fail formulas like that:

on_fail="if(vars.error = 'recruitment',
if( vars.errdsc = 'no_space', find_nearest_free_keep(), var.errdsc = 'unknown_unit', something_else() ), fallback() )"

There would be different types of errors and errdscs - depending on what caused the problem. on_fail formulas would support recruit, move, move_partial and attack formula orders.

=== Fractions ===
==== Background ====
Currently formula language does not support fractions like 0.25, so formula like "1/2" is evaluated to 0.
==== Solution ====
I would implement simple fractions - by simple I mean that these fraction would have only 2 decimal places. So "1/3" would result in 0.33. Such simplified solution should be enough for formula AI, and still will make writing formulas more intuitive. This change would lead to implementing new variant TYPE_FRACTION and of course various rounding functions like round(), floor(), ceil().

=== Candidate moves ideas ===
==== Generic "three part" formula ( based on what boucman proposed )====
This kind of candidate move would look like that:

name=something
type=three_part
precondition="calculate_units()"
evaluation="eval()"
actions="action()"

precondition would be used to create vector or map with units. Then based on outcome, evaluation would be run, and finally, action. Thanks ot that, we could add some flexibility to candidate moves system. I already can see that probably some new functions that operate on a map will be needed. Example usage:

precondition="[ tomap( my_leader, enemy_units ) ]"

Assuming we extend "tomap" functionality it could return map like

[ my_leader -> unit1, my_leader -> unit2, ... ]

Then we would take keys and values and do pair evaluation:

my_leader <-> unit1
my_leader <-> unit2
....

==== 'support' type candidate move ====
Simple idea, simmilar to "attack" candidate move, just working for 2 units of the same side.

==== Precondition formula ====
===== Background =====
Currently, when we have attack candidate move with eval like:

name=my_candidate_move
evaluation="if( me.hitpoints > 30, evaluate_me_and_target(), -1 )"

It is evaluated for each friendly unit m times - where m is number of enemies. And after one valuation, it can be evaluated again - and that happens j+1 times, where j is number of units for which different evals returned score > 0. This is quite not optimal solution.

===== Solution =====
I want to add precondition formula, which would be evaluated once for every unit, so above example coulbe be replaced with:

precondition="if(me.hitpoints > 30, 1, -1)"
evaluation="evaluate_me_and_target()"

For each my unit precondition will be run once, and only if it returns score > 0, evaluation will be executed m times (for every enemy unit). I think that assuming we can have 10+ candidate moves, and more than 50 units on a map, we should consider implementing it.

=== FormulaAI improved logs ===
This idea is about making formula AI more verbose, and allow it to take advantage of different log levels:

info level would provide information about executed orders

warning level would provide info about possible type errors

error level would provide info about moves that caused formula to run on_fail formula

=== More info for FormulaAI ===
To know where we or anamy can move, we can use now my_moves and enemy_moves. But we lack info about how far we can move if we for example kill one unit. For that I would like to add functions that return info about individual unit range, and AI members that could inform about the same, just for all units - my_range, enemy_range.

=== Add option to choose FormulaAI as alternative AI ===
That idea requires taking care of two things:

First, add option to choose formula AI, which would be at the beggining defaul AI with my recruting algorithm. Second - allow user data to overwrite default ai settings while creating multiplayer scenarios with custom formula - that is not yet possible.

=== Other ideas ===

I had few different ideas, regarding writing formulas and making that and testing easier, but currently other students (well, mainly Crab :) ) are working on some patches to do exactly that, so I'll focus on what I've written above, to not duplicate their work.

== Things to write with FormulaAI language ==

I believe, that to spot bugs and be able to think about new features and functions, usage of formula AI is needed. Besides that ,we need testing, that's why I would like to organize from time to time (starting from around midterm evaluation) regular developer games to test formula AI.

=== Recruitment formula and leader move ===

Based on my last year proposal: [[FormulaAIBaseAI#AI_recruitment]]

Recent testing of this formula, showed that it is quite useful and generally recruits better than defaul AI. Generally, this time I'd like to extend this formula to make it more loke a "leader control formula". There is still number of things to take into account while recruting for example:

'''size of the map''', units '''max movement'''
To calculate how many scouts we need, we have to remember that on small maps often we don't need any scouts.

And besides that, some more testing is needed, to tweak bonuses that units get for weapon specials and abilities.

A leader part would be responsible for keeping leader in keep/getting some nearby villages at the beggining. Further improvements may include using some special abilities like healing/poison/leadership - and these need to have higher priority than any used candidate moves.

=== Candidate moves formulas ===

I'd like to add some candidate moves for poisoners (I know velory wrote one already, but I have my own idea for that) and scouting evaluation (we already have one now, but also I'd do it a bit in a different way). But this task can wait for now.

= My contributions =

== Up to one month before releasing 1.6 ==

=== More important and significant changes ===
* Implemented pathfinding especially for formula AI to make functions move and move_partial work properly and be intuitive [http://svn.gna.org/viewcvs/wesnoth?rev=33009&view=rev][http://svn.gna.org/viewcvs/wesnoth?rev=33223&view=rev][http://svn.gna.org/viewcvs/wesnoth?rev=33361&view=rev][http://svn.gna.org/viewcvs/wesnoth?rev=33362&view=rev]
* Fixed candidate moves crash wesnoth every time there was an error in the formula [http://svn.gna.org/viewcvs/wesnoth?rev=32804&view=rev]
* Made unit loop formulas work even when no unit formula is specified [http://svn.gna.org/viewcvs/wesnoth?rev=33370&view=rev]
* Candidate moves and general side formula now work besides each other, not instead [http://svn.gna.org/viewcvs/wesnoth?rev=33618&view=rev]
* Added support for prorities for unit formulas, fixed candidate moves bug that made it execute first moves with *lowest* score, initial unit modification to prepare it for on_fail formula support.[http://svn.gna.org/viewcvs/wesnoth?rev=33636&view=rev]
* Added [ai] tag to single unit WML, renamed [ai_vars] to [vars], renamed 'faifile' keyword to 'fai', added new keyword: end. Fixed bug that caused some unit variables be saved to file incorrectly. Removed obsolete formula test case. [http://svn.gna.org/viewcvs/wesnoth?rev=33677&view=rev]
* Added new formula function castle_locs [http://svn.gna.org/viewcvs/wesnoth?rev=33712&view=rev]

=== Various fixes and improvements ===

* Disable formula AI in multiplayer [http://svn.gna.org/viewcvs/wesnoth?rev=33169&view=rev]
* Fixed candidate moves into infinite loop bug [http://svn.gna.org/viewcvs/wesnoth?rev=33192&view=rev]
* Fix for attack function and some overall improvements [http://svn.gna.org/viewcvs/wesnoth?rev=33190&view=rev][http://svn.gna.org/viewcvs/wesnoth?rev=33346&view=rev]
* Made formula AI unit members correspond to these in SingleUnitWML [http://svn.gna.org/viewcvs/wesnoth?rev=33368&view=rev]
* Fixed formula parser bug [http://svn.gna.org/viewcvs/wesnoth?rev=33373&view=rev]
* Fixed formula operator '.' bug [http://svn.gna.org/viewcvs/wesnoth?rev=33566&view=rev]
* Made [function] WML tag for formula work [http://svn.gna.org/viewcvs/wesnoth?rev=33612&view=rev]
* Improved formula test scenario [http://svn.gna.org/viewcvs/wesnoth?rev=33648&view=rev]
* Moved adjacent_locs form location object to separate function and fixed it. Fixed attack() function. [http://svn.gna.org/viewcvs/wesnoth?rev=33639&view=rev]
* Fixed buggy 'special' attack object member [http://svn.gna.org/viewcvs/wesnoth?rev=33653&view=rev]
* Formula AI parser bug causing where keyword crash wesnoth when 'self' was used in the formula [http://svn.gna.org/viewcvs/wesnoth?rev=33793&view=rev]
* Fixed defense_on function [http://svn.gna.org/viewcvs/wesnoth?rev=33860&view=rev]

== During Summer of Code application period ==

[[Category:Summer of Code]]

2009-03-29T20:21:20Z

Dragonking: /* Idea Description */

== Introduction ==

*Basics

**Write a small introduction to yourself.
My name is Bartek Waresiak and I'm from Poland. I'm 22 years old male interested in programming, computer science and gaming. I have been Battle for Wesnoth player for more than 5 years, and developer for about 4 years (coder since Summer of Code 2008).

**State your preferred email address.
either dragonking_ATTT_o2_D0T_pl or b.waresiak_ATTT_gmail_D0T_com

**If you have chosen a nick for IRC and Wesnoth forums, what is it?
Dragonking

**Why do you want to participate in summer of code?
By participating in Google Summer of Code I want to significantly increase amount of time that I spend working for Battle for Wesnoth, have some fun and earn some money.

**What are you studying, subject, level and school?
I'm studying Information Technology, 3nd year at AGH University of Science and Technology in Cracow, Poland.

**If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for Wesnoth. If you have gained commit access to our SVN (during the evaluation period or earlier) please state so.
I have access to SVN. My recent contributions to Wesnoth:
*** Before 1.6 release 'bugfixing-time':

*** Directly before Summer of Code application period:

*Experience
**What programs/software have you worked on before?
***I've been one of Battle for Wesnoth developers since September 2005 and I have been working on FormulaAI language since Summer of Code 2008. Besides that, I wrote various projects for my university (algorithm-testing, training projects, optimalization tasks, etc...).
**Have you developed software in a team environment before? (As opposed to hacking on something on your own)
***I'm one of Developers in 'Battle for Wesnoth' project and I have experience in group decision making.
**Have you participated to the Google Summer of Code before? As a mentor or a student? In what project? Were you successful? If not, why?
***I had been participatin in Google Summer of Code 2008, workin on Formula AI for Battle for Wesnoth project. My project was successful.

*Open Source
**Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.
***As Developer for Battle for Wesnoth project I've been responsible for developing, improving, testing and documentation of the FormulaAI language. Besides that, I've been supporting people trying to use this language in their scenarios/campaigns. Previously, as a Multiplayer Developer I've been one of people responsible for unit balancing (unit statistics tweaking), multiplayer server moderation and basic administration.

*Gaming experience
**Are you a gamer?
***Yes, I like to play various types of games: strategy games - both real time and turn-based, role-playing games and some of the first person shooters. I'm rather patient and calm player and I enjoy difficult games which require some amount of 'hard thinking'.
**What type of opponents do you prefer?
***I prefer human opponents much more than AI, but they have to be polite, civil and mature. I really enjoy games against experienced player, though I don't mind also tutoring new ones.
**Are you more interested in story or gameplay?
***I value both - IMHO to bring a game to someone's attention, it must have a decent gameplay. If it has a nice storyline as well, then chances that players will keep playing and won't leave increase.
**Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer.
***I have been playing Wesnoth since about 0.7 version, mainly multiplayer because I enjoy Wesnoth players community and recognize it as polite and mature one. Also, like I mentioned, multiplayer games against human opponents are for me much more enjoyable than single-player campaigns.

*Communication skills
**Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.
***I have no problem with understanding written English, and describing my thoughts to the others in this language.
**Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.
***I think I know Wesnoth developers and players community well, and I've always been trying to always be on good terms with everyone. I know whom to talk to about different issues and who can give me needed advice or support. I also have quite a lot experience with interacting with multiplayer community.
**Do you give constructive advice?
***When giving advice, I try to be as detailed as possible, and make sure that people who I direct advice to understand me well. I am aware that during the internet chat you can be misinterpreted and your advice may instead be received as a negative criticism, I'm trying to avoid it by being friendly towards others.
**Do you receive advice well?
***I know that I can be wrong and that around me many people are far more experienced than me, I consider advices from others as a good thing which helps me improve and develop my skills.
**Are you good at sorting useful criticisms from useless ones?
***I have to admit it is hard to receive bad criticism - if someone is telling you that you are plain wrong, but is not providing any arguments to back up his opinion, then usually this kind of criticism is a useless one. If someone can criticize what I am doing providing examples what is wrong and how it can be improved - it is definitely an example of useful and desired criticism.

*Project
Described below.

*Practical considerations
**AAre you familiar with any of the following tools or languages?
***Subversion
****Yes, about 3-year experience.
***C++
****I have more than 2 years of C/C++ experience.
***Python
****No.
**Which tools do you normally use for development? Why do you use them?
***I'm working on Debian Linux.
**What programming languages are you fluent in?
***C/C++ and Java.
**What spoken languages are you fluent in?
***Polish - which is my mother tongue, and English.
**At what hours are you awake (please specify in UTC)
***Usually I'm awake between 8 and 23 UTC, and available on IRC betweeen 17 and 23 UTC.
**Would you mind talking with your mentor on telephone / internet phone? We would like to have a backup way for communications for the case that somehow emails and IRC do fail.
***I wouldn't mind.

== Idea Description ==
=== Why FormulaAI? ===

I have been working on FormulaAI for a while now - bugfixing, new function, new features, testing, etc. I know the existing code well. Besides that, I'm experienced wesnoth player, and I know many verious strategies/tactics, so I have really strong understanding of different aspects of the game, what is definiately a desired thing if one wants to work on improving the AI. Besides that, forula AI language can be used by other people to write their own simple AI - and I do enjoy helping others gain knowledge about how to use this language.

=== Let's start from what is proposed... ===

On the wiki, and after some talking on the IRC I can see 2 ideas: first is Formula AI library, with functions that user could inclue and use. Second, is AI written in FormulaAI language, that improves current C++ and can beat it. After some thinking, I consider first idea to be too general one. I find it hard to define milestones, find reasonable ideas for functions. In my opinion, such thing is not good to choose for SoC, when you have to write something useful in limited amount of time, but should grow slowly, based on what people who actually use formula AI need.

=== Then, why not AI ? ===

Second proposal is simmilar to the one form year ago. Because I was one of the people working on this during SoC 2008, I can see some problems with this idea. First problem I encountered year ago, was FormulaAI language itself - it was not developed enough for such a big task at that time, and because of that I was forced to focus on improving language itself rather than working on the AI. I believe that in current state of FormulaAI language, designing AI could be easier, but still would be disturbed by bugfixing. Second problem I can see, is that I don't believe that general wesnoth AI can be written in FormulaAI language alone. It can work perfectly for some scenario where you nee a specific-purpose AI, but not for general case, even with current approach of candidate moves/side formulas because of how complicated AI in wesnoth must be. And third thing: recently DarthFool and Sirp presented some interesting ideas of re-developing AI for wesnoth. Both of them mentioned, that formulas written in formula AI language could be used as plugins to the AI - difference between current implementation and their ideas would be that we could better design the relation between C++ AI and formulas - not make formula AI and then fallback to default "stupid" one like it is only possible now. And this leads to what I would like to do during Summer of Code:

=== Straight to the point ===

I would like to focus on improving and extending the formulaAI language during Google Summer of Code 2009. First, because it could be later used to "support" creating better default AI, second, because 1.6 is first stable release in which formula AI is available for campaign designers. I know that it may sound a bit "general" and it may be hard to consider good tasks and milestones, but I believe that with my experience from previous GSoC I can propose reasonable approach. Generally, I would work on my ideas for formula AI language, and in between, I would fix some bugs and help people around using formula AI. It is hard to define now how much time fixing bugs/helping others will take, so I don't want to base my evaluation on that. I just want to note that there may be a need to alter my milestones/timeline (like last year's SoC showed us). But to give you some detail that I do know what I want to do...

=== Things to implement to formula engine ===

==== 'on_fail' formulas ====
===== Background =====
Current problem with formula language is: what if there no no room for recruitment but we still send order to recruit? Or we send recruit order, but with unknown/incorrect unit name? ATM, formula treats it as an invalid move, so all loop-type formulas are cancelled. This is not a good approach, because order itself is valid, just it contains incorrect data.
===== Solution =====
I propose "on_fail" formula, available both for side and for unit formulas. Basic example is:

move="recruit('Skeleton Archer')"
on_fail="fallback()"

If we cannot recruit Skeleton Archer, then we just fallaback to default AI. But there's more - to give proper info about what happened, the "error" and "errdsc" side variables would be set to allow trace the problem, thus we could use on_fail formulas like that:

on_fail="if(vars.error = 'recruitment',
if( vars.errdsc = 'no_space', find_nearest_free_keep(), var.errdsc = 'unknown_unit', something_else() ), fallback() )"

There would be different types of errors and errdscs - depending on what caused the problem. on_fail formulas would support recruit, move, move_partial and attack formula orders.

==== Fractions ====
===== Background =====
Currently formula language does not support fractions like 0.25, so formula like "1/2" is evaluated to 0.
===== Solution =====
I would implement simple fractions - by simple I mean that these fraction would have only 2 decimal places. So "1/3" would result in 0.33. Such simplified solution should be enough for formula AI, and still will make writing formulas more intuitive. This change would lead to implementing new variant TYPE_FRACTION and of course various rounding functions like round(), floor(), ceil().

==== Candidate moves ideas ====
===== Generic "three part" formula ( based on what boucman proposed )=====
This kind of candidate move would look like that:

name=something
type=three_part
precondition="calculate_units()"
evaluation="eval()"
actions="action()"

precondition would be used to create vector or map with units. Then based on outcome, evaluation would be run, and finally, action. Thanks ot that, we could add some flexibility to candidate moves system. I already can see that probably some new functions that operate on a map will be needed. Example usage:

precondition="[ tomap( my_leader, enemy_units ) ]"

Assuming we extend "tomap" functionality it could return map like

[ my_leader -> unit1, my_leader -> unit2, ... ]

Then we would take keys and values and do pair evaluation:

my_leader <-> unit1
my_leader <-> unit2
....

===== 'support' type candidate move =====
Simple idea, simmilar to "attack" candidate move, just working for 2 units of the same side.

===== Precondition formula =====
====== Background ======
Currently, when we have attack candidate move with eval like:

evaluation="if( me.hitpoints > 30, evaluate_me_and_target(), -1 )"

It is evaluated for each friendly unit m times - where m is number of enemies. And after one valuation, it can be evaluated again - and that happens j+1 times, where j is number of units for which this eval returned score > 0. This is quite not optimal solution.

====== Solution ======
I want to add precondition formula, which would be evaluated once for every unit, so above example coulbe be replaced with:

precondition="if(me.hitpoints > 30, 1, -1)"
evaluation="evaluate_me_and_target()"

For each my unit precondition will be run once, and only if it returns score > 0, evaluation will be executed m times (for every enemy unit). I think that assuming we can have 10+ candidate moves, and more than 50 units on a map, we should consider implementing it.

==== FormulaAI improved logs ====
This idea is about making formula AI more verbose, and allow it to take advantage of different log levels:

info level would provide information about executed orders

warning level would provide info about possible type errors

error level would provide info about moves that caused formula to run on_fail formula

==== More info for FormulaAI ====
To know where we or anamy can move, we can use now my_moves and enemy_moves. But we lack info about how far we can move if we for example kill one unit. For that I would like to add functions that return info about individual unit range, and AI members that could inform about the same, just for all units - my_range, enemy_range.

==== Add option to choose FormulaAI as alternative AI ====
That idea requires taking care of two things:

First, add option to choose formula AI, which would be at the beggining defaul AI with my recruting algorithm. Second - allow user data to overwrite default ai settings while creating multiplayer scenarios with custom formula - that is not yet possible.

=== Things to write with FormulaAI language ===
WIP

[[Category:Summer of Code]]

2008-08-30T10:25:26Z

Dragonking: /* Files and formulas */

== Overview ==

The Wesnoth Formula AI is an attempt to develop an AI framework for Wesnoth that allows easy and fun development and modification of AIs for Wesnoth.

Wesnoth already has support for AIs written in Python, but writing AIs in Python has a couple of problems:

* it's still rather difficult, especially for a non-programmer, to develop an AI, even in Python
* Python is insecure; a malicious trojan horse Python script masquerading as an AI could do untold damage

The Wesnoth Formula AI aims to create a fairly simple, pure functional language which allows one to implement an AI. It also aims to allow AIs to be tweaked and modified by people with relatively little technical skill; anyone who can use WML should also be able to use the Formula AI to tweak an AI to make the AI in a scenario behave how they want.

The Wesnoth Formula AI is currently in an experimental stage of development. One can play with it and develop a rudimentary AI. Feedback is appreciated.

To develop an AI using the Formula AI, set ai_algorithm=formula_ai in [side].

== Approach ==

To use the Formula AI, one should put an [ai] tag inside the [side] tag. Inside this [ai] tag, one should specify the 'move' attribute to be a formula which specifies what movement the AI will make. Each time it's the AI's move, this formula will be run, and the move it results in will be executed. Then the formula will be run again; it'll continue to be run until it stops producing a valid move, at which point the AI will end its turn. Alternatively there is a command that the formula may return which will make it end its turn immediately.

A sample AI which does nothing but recruit Wolf Riders is as follows:

[side]
...
ai_algorithm=formula_ai
[ai]
move="recruit('Wolf Rider')"
[/ai]
[/side]

== Formula Command Line ==

To attempt to make it convenient to debug formulas, one can run formulas from within Wesnoth, and see the results. To run a formula, just start game and type 'f'. A command textbox will appear, where you can type a formula, and the results will be printed. For instance, typing

8 + 4

will result in "12" appearing on the screen. You can now use Wesnoth like a calculator. :-)

== Formula Basics ==

* The Formula language supports basic arithmetic operations, such as: +, -, *, /, % and ^. It supports integers but does NOT support decimal or floating point numbers. For example:

4 + 8*7 #evaluates to 60
(4 + 8)*7 #evaluates to 84
8 % 6 #evaluates to 2
5 / 2 #evaluates to 2
3 ^ 2 #evaluates to 9

* It also supports equality, = and !=, and comparison operators, <, >, <=, and >=. 'false' values are 0 (integer) and null. Other values are true. It also supports common operators such as and, or, and not:

2 = 4 #evaluates to 0
2 <= 3 #evaluates to 1
0 != 1 #evaluates to 1
not 4 #evaluates to 0
not 0 #evaluates to 1
(2 < 4) and (3 > 6) #evaluates to 1 and 0 which evaluates to 0
(2 < 4) or (3 > 6) #evaluates to 1 or 0 which evaluates to 1

* Formula language supports also 'dice' operator 'd'. Example usage is:

3d5

Which will give you one of results of rolling three five-sided dice (so random number between 3 and 15).

== Data Types ==

Formula System supports different types of data, which can be stored as a variables and are used in evaluations:

* Numbers: like 0, 1, 2 etc. Floating-point numbers are not supported. 0 is equal to logical 'false', any other number is 'true'.

* Text strings:

'this is a text string'

* Lists: A list is a sequence of values. For example, ai.my_units is a list of unit objects. A list is represented as square brackets, [], surrounding a comma-seperated list. For instance:

[4, 8, 7]

is a list of three numbers, and

[]

is a empty list. Various functions can operate on lists.

To acces one particular element of a list we can use operator [], for example:

my_list[0]

Returns first element from the my_list, so:

[ 10, 20, 30, 40][2]

Returns

30

* Maps: A map is a sequence of pairs, each pair is a key and assigned to it value. For example:

[ 'Elvish Fighter' -> 50, 'Elvish Archer' -> 60 ]

Is a map which consist of two pairs, first one assigns to the text string 'Elvish Fighter' the value 50, second one assigns 60 to the 'Elvish Archer' string.

To access value assigned to the key, we can use operator []:

[ 'Elvish Fighter' -> 50, 'Elvish Archer' -> 60 ][ 'Elvish Fighter' ]

Above example returns

50

== AI Formula Language ==

=== Overview ===

The formula language must be able to access information about the scenario being played to make intelligent decisions. Thus there are various 'inputs' that one may access. A simple example of an input is the turn number one is on, given by the input, 'turn'. Try bringing up the formula command line using 'f' and then type in

turn

The AI will print out the current turn number the game is on.

The 'turn' input is a simple integer. However, some inputs are complex types which contain other inputs, or which may be lists of inputs. For instance, the input 'my_units' contains a list of all the AI's units.

A complex input such as a unit will contain a variety of inputs inside it. If one has a unit input, called 'u' for instance, one can access the 'x' co-ordinate of that unit by using u.loc.x -- u.loc accesses the 'location' object inside the 'unit' object, and the 'location' object contains 'x' and 'y' inputs inside it, which are the x and y co-ordinate of the unit.
=== Available variables ===
these are variables that you can call in an AI formula or from the command line.

* ''turn'' the current turn number
* ''units'' the complete list of all units
* ''my_units'' the complete list of all units owned by the current player
* ''ennemy_units'' all units that are ennemy to the current player
* ''villages'' all the villages on the map
* ''my_villages'' all the villages owned by the current player
* ''ennemy_and_unowned_villages'' all villages that you don't own
* ''map'' all the data about the map
* ''teams'' all the data about all the teams

=== Built-in functions ===
The formula language contains a large number of built-in functions which allow you to carry out all kinds of complex tasks. List of these functions, usage and simple examples can be found [http://www.wesnoth.org/wiki/FormulaAI_Functions here].

=== Custom Functions ===

* You can define your own functions. A function is a formula which takes some inputs as parameters. Suppose we wanted to define a function that puts some value on a unit, we might add the following to the [ai] tag:

[function]
name=value_unit
inputs="unit"
formula="unit.hitpoints + unit.level*4"
[/function]

This has defined a new function which takes a 'unit' as an input, and runs the given calculation over it.

* We can have multiple inputs in our functions, to define them, just create comma-separated inputs list:

inputs="attacker,defender"

This has defined a new function which takes both 'attacker' and 'defender' as an inputs.

* Sometimes, we use one of our inputs really often in our function - to make our life easier we can make its members (inputs) directly accessible from within the formula. This is improved version of function from above:

[function]
name=value_unit
inputs="unit*"
formula="hitpoints + level*4"
[/function]

As you can see, if we define input with a * char at the end, we make it a 'default input' for a formula. Note, that you can define only one default input per function.

* It is important to know difference between formulas defined in custom functions, and formula defined by a 'move=' in a [ai] tag. For example, if we want to get info about leader, we write in formula 'my_leader' - which acces member of the AI. To be able to use 'my_leader' in custom functions we have to add 'ai' as an input for our function:

inputs="ai"

allows us to access leader info by writing 'ai.my_leader', or:

inputs="ai*"

allows us to access leader info by simply writing 'my_leader'

* You can also use 'def' [[#Keywords|keyword]] to define custom functions

=== Comments ===

Comments in Formula AI scripts are enclosed by # #:

#Define opening move#
def opening(*ai)
if(turn = 1,
move(loc(11,23), loc(14,22)),
[])

Comments may also be included at the end of a line:

def opening(*ai)
if(turn = 1,
move(loc(11,23), loc(14,22)), #capture village#
[]) #do nothing#

and they may also be used inline:

def opening(*ai)
if(turn = 1,
move(loc(11,23) #my_leader#, loc(14,24) #closest village#),
[] #do nothing# )

== Keywords ==

The formula language has some reserved keywords to provide primitive functionality. Currently the following keywords are defined:

* where: This keyword is used to defining statements in formulas. You can define multiple comma-separated statements. Syntax:

<formula> where <comma-separated list of statements>

For example formula:

a + b where a = 2, b = 4

will give as result 6.

* functions: Returns a list of all built-in and custom functions available to the AI

* def: This keyword creates functions using the syntax:

def function_name(arg1, arg2, ....) function_body

For example,

def sum(x,y) x + y

creates a function sum taking two arguments and returns their sum.

== Unit Formulas ==

You san specify a formula for any kind of unit. This is a simple way of doing it:

[unit]
...
formula="move(me.loc, loc(me.loc.x, me.loc.y - 1))"
[/unit]

Custom unit formulas are executed first at the begining of side's turn. Above formula will simply move unit one hex to the north every turn. Note how "me" keyword allows access to unit itself.

You can also define AI unit-specific variables and use them in you formulas:

[unit]
...
formula="if(attack, attack, move(me.loc, choose(unit_moves(me.loc), -distance_between(self, me.vars.guard_loc))))
where attack = choose(filter(attacks, units = [me.loc] and distance_between(me.vars.guard_loc, target) <= me.vars.guard_radius), avg_damage_inflicted)"
[ai_vars]
guard_radius=3
guard_loc="loc(8,5)"
[/ai_vars]
[/unit]

This formula will get location position from variable guard_loc and make sure that unit attacks opponent which is 3 hexes (value specified by guard_radius variable) or less from guard_loc.

Types of variables that are supported:
*number:
variable=3
*text (important: note the ' ' within " "):
name="'I am variable'"
*list:
number_list=[ 1, 2, 3]
* map:
map=[ 'Elvish Archer' -> 70, 'Elvish Shaman' -> 60 ]
*location:
place="loc(X,Y)"

== Files and formulas ==

You can easily split your formulas between different files and include them when necessary. For example:

[unit]
...
formula={my_unit_formula.fai}
[/unit]

Will look for unit formula in the my_unit_formula.fai file.

Although it is not mandatory, we advocate to use following syntax in your fai files:

faifile '<filename>'
...
faiend

This makes formula system know which file it is working with now, and gives you improved error reporting, which is often really helpful. Valid syntax for my_unit_formula.fai would be:

faifile 'my_unit_formula.fai'
...
faiend

== Tool Support ==

=== ctags ===

For some rudimentary support for exuberant ctags, add the following to .ctags (or create the file if it doesn't exist):

--langdef=formulaai
--langmap=formulaai:.fai
--regex-formulaai=/^def[ \t]*([a-zA-Z0-9_]+)/\1/d,definition/

This is especially nice when used with an editor or plugin with ctags support, such as Taglist for Vim.

=== Vim ===

====Syntax Highlighting====

Follow these steps to enjoy vim syntax highlighting support for Formula AI.

# Grab the Formula AI vim syntax file, [http://svn.gna.org/viewcvs/*checkout*/wesnoth/trunk/data/tools/vim/formulaai.vim formulaai.vim].
# Copy formulaai.vim to .vim/syntax
# Add the following to .vimrc :
autocmd! BufRead,BufNewFile *.fai setfiletype formulaai

====Taglist Support====

First you will need the very nice [http://www.vim.org/scripts/script.php?script_id=273 taglist plugin]. Follow the link for downloads and install directions if you don't already have it installed.

Next, you'll need Formula AI support for exuberant ctags, follow the instructions in the [[#ctags|ctags]] section.

Once you have all that, simply add the following line to your .vimrc:

let tlist_formulaai_settings = 'formulaai;d:definition'

To test it all out, open a Formula AI script file and enter the command
:Tlist

You should now have some nice highlighting and be able to easily navigate through formula, enjoy!

[[Category:Development]]

[[Category:Development]]

FormulaAI

2008-08-30T10:18:11Z

Dragonking:

FormulaAI

2008-08-30T10:13:19Z

Dragonking: /* Unit Formulas */