The Battle for Wesnoth Wiki - User contributions [en]

FormulaAI

2008-03-18T22:30:44Z

PedroFonini: /* Approach */

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

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 type 'f'. A command textbox will appear, where you can type a formula, and the results will be printed. For instance, try pressing 'f' and then type "8 + 4" and the result, "12" will appear. You can now use Wesnoth like a calculator. :-)

== Formula Basics ==

The Formula language supports basic arithmetic operations, such as +, -, *, /, etc. It also supports equality, = and !=, and comparison operators, <, >, <=, and >=. 'false' values are 0 (integer) and null. Other values are true. It supports integers but does NOT support decimal or floating point numbers.

It also supports common operators such as and, or, and not. These are examples of valid formulas

4 + 8*7 (evaluates to 60)
(4 + 8)*7 (evaluates to 84)
5 and 0 (evaluates to 0)

== AI Formula Language ==

Of course, 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 textbox 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.

== Functions ==

The formula language contains a large number of built-in functions which allow you to carry out all kinds of complex tasks. A simple example of a function is the 'if' function. The 'if' function takes three parameters; if the first parameter is true, the function will evaluate to being equal to its second input, otherwise it will evaluate to being equal to its third input.

For instance, an AI that recruits Wolf Riders on the first turn, and Orcish Grunts thereafter might look like this:

move="if(turn = 1, recruit('Wolf Rider'), recruit('Orcish Grunt'))"

There are a wide variety of functions which can be used to accomplish many different tasks. You can also define your own functions (see below).

== Lists ==

The formula language has support for lists. A list is a sequence of values. For instance, '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.

There are various functions which operate on lists:

size(list): number of items in the list EXAMPLE: size(my_units) -- number of units the AI controls

head(list): the first item in the list EXAMPLE: head(my_units) -- the first unit in the list of units.

map(list, formula): will run 'formula' on each item in the list, and evaluate to a new list which contains the same number of items as in 'list', with the formulas run on each item. EXAMPLE: map(my_units, unit.hitpoints) -- will give a list back with the number of hitpoints each unit has. This is more useful in conjunction with other functions.

filter(list, formula): will run 'formula' on each item in the list. Will evaluate to a list which only contains items the formula was true for. EXAMPLE: filter(my_units, hitpoints < max_hitpoints) -- will return all of your units which have less than maximum hitpoints. For instance this could be used if looking for candidates for healing.

sum(list): evaluates to the sum of the items in the list (which all must be numbers) EXAMPLE: sum(map(my_units, max_hitpoints - hitpoints)) -- finds the total damage your units have taken.

max(list) and min(list): evaluates to the maximum or minimum item in the list (which all must be numbers) EXAMPLE: max(my_units, level) -- finds the maximum level of the units you have.

choose(list, formula): evaluates 'formula' for each item in the list. Will evaluate to the item which 'formula' gave the highest value. EXAMPLE: to give back the unit with the highest level, choose(my_units, level).

sort(list, formula): evaluates to a list sorted according to the comparison 'formula' for each item 'a' and its successor 'b'. For instance, sorting units according to hitpoints would be done by sort(my_units, a.hitpoints > b.hitpoints).

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

[[Category:Committers]]

EditingWesnoth

2008-03-03T09:41:36Z

PedroFonini: /* Linux */ other distributions

== Game and User Directories ==

Wherever you install the game, there will be a game data directory that contains, of course, the game's data. This directory should have the following subdirectories: data, music, sounds, and images. There are several others, but these are the important ones. In this wiki, the terms "game data", wesnoth/data, or ./data refers to the wesnoth/data directory. You normally do not need to modify these files, but you can if you want to modify a unit or something.

The user data directory allows you to add custom content without modifying the game's own files. Each OS puts its user data directory in a different place. In this wiki, "user data", ''userdata''/''subdirectory'', or (occasionally) ~wesnoth/ refer to this directory.

=== Where is my '''game''' data directory? ===

====Windows====
Usually C:\Program Files\Wesnoth\data but it will be different if you installed the game in a different location: look for the data folder in the folder where you installed the game.

====Mac OS X====
Downloaded from sourceforge: command-click on the application icon. Select "Show Package Contents." Select "Contents" then "Resources.
If you did not download from sourceforge what do you do?
Command line build: /usr/local/share/wesnoth

====Linux====
/usr/local/share/wesnoth 
From apt-get (Debian and Ubuntu) or emerge (Gentoo): /usr/share/games/wesnoth 
SUSE 10.0 (pre-installed): /usr/share/wesnoth 
Fedora 5 (Installed from yum repository RPM): /usr/share/wesnoth 
Mandriva 2006.0: /usr/share/games/wesnoth 
Slackware 12 (Installed from .tgz package at LinuxPackages.net): /usr/local/share/wesnoth 
If you don't find it, or if you use another distribution, try <code>find / -iname '*wesnoth*'</code>. (as yourself, not as superuser)

=== Where is my '''user''' data directory? ===

====Windows====
c:\Program Files\Wesnoth\userdata

====Mac OS X====
Downloaded from sourceforge: ~/Library/Preferences/Wesnoth 
Command line build: ~/.wesnoth

====Linux====
~/.wesnoth

== Game data ==

The major directories you need to know about are wesnoth/data, wesnoth/data/units, wesnoth/data/campaigns, wesnoth/data/maps, wesnoth/data/scenarios, wesnoth/images

Become familiar with what is in ./data/campaigns, ./data/scenarios, and ./data/maps. These have the officially distributed campaigns and multiplayer maps. If you ever want to examine or edit one of the scenario configuration files, this is where you would go. For example, a common question is how a new player can give himself more turns or gold in scenario X. This is where you would go to do that.

Two very important directories are ./data/units and ./images. You have the ability to drop new units or images in these directories and have the game recognize them. When specifying an image for something, you do so relative to ./images.

=== Game Configuration ===

Some information is stored in files in the ./data directory itself:
* amla.cfg - global definition for After Max-Level Advancement (currently 3 hp per 100 XP)
* fonts.cfg - defines which fonts the game can use
* game.cfg
* help.cfg - the entire help system document
* items.cfg - macros for common objects and items used in the game, also available for campaign writer use
* multiplayer.cfg - defines the multiplayer eras and factions
* names.cfg - lists of name fragments that are randomly put together to create random-sounding names. Segregated by race and gender
* scenario-test.cfg - a simple test scenario. Run it with the command wesnoth -t
* schedules.cfg - defines the global day-night cycle
* terrain.cfg - defines the terrain types
* terrain-graphics.cfg - defines terrain layering and usage of random terrain
* tips.cfg - the contents of the Tome of Wesnoth
* traits.cfg - defines all traits used globally in the game
* utils.cfg - some common macros used in the game, also available for campaign writer use
* units.cfg - defines the races, which traits each race has, and the movement types (which set defenses, resistances, and movement costs)

For more information about game configuration:
* themes/: [[ThemeSystem]]
* maps/: [[BuildingMaps]]
* scenarios/: [[BuildingScenarios]]
* translations/: [[WesnothTranslations]]
* units/: [[BuildingUnits]]
* game.cfg: [[WesnothGameConfigure]]

== User Data ==
The user data directory can do a lot of things. The game looks here for several things:
* ''userdata''/data/campaigns - campaign configuration files and subdirectories
* ''userdata''/data/editor/maps - multiplayer standalone maps (map data only)
* ''userdata''/data/units - drop your custom units here, and they will be visible to the game
* ''userdata''/data/images - drop your custom images here, and they will be visible to the game

The ''userdata''/data/campaigns directory is particularly useful. A single configuration file here can selectively point to an entire subdirectory tree of units, images, sounds, scenarios, and macros. This allows you to wall off parts. Content included in the userdata units or images directories will be available globally whether you want it or not. Content included in the campaigns directory won't be loaded unless the game is told to do it.

For example, assume you have a campaign called MyCampaign. This is what the ''userdata''/data/campaigns directory looks like:
* ''userdata''/data/campaigns/MyCampaign.cfg - a text file
* ''userdata''/data/campaigns/MyCampaign/ - a subdirectory
** ''userdata''/data/campaigns/MyCampaign/scenarios
** ''userdata''/data/campaigns/MyCampaign/units
** ''userdata''/data/campaigns/MyCampaign/images
** ''userdata''/data/campaigns/MyCampaign/music
** ''userdata''/data/campaigns/MyCampaign/sounds
** ''userdata''/data/campaigns/MyCampaign/utils

MyCampaign.cfg will have something called the "campaign ifdef", which is a syntax structure that instructs the game to search ''userdata''/data/campaigns/MyCampaign/ for data. More about this is found in [[BuildingCampaigns]]. However, it is important to understand the different capabilites of the user data directory.

== See Also ==

* [[Create]]

[[Category:Create]]