The Battle for Wesnoth Wiki - User contributions [en]

AI Recruitment

2014-01-29T05:01:51Z

Alarantalara: Add AI category

The new Recruitment Candidate Action is highly configurable and supports multiple leader recruiting.

=How it works=
==Map analyis==
In a first step the CA will analyse the map and try to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense for the combatants.

When the game is running in debug mode ''and'' the game is started with the parameter <code>--log-info=ai/recruitment</code> the important hexes are marked with a white 'X'.

==Score Map==
A score map will be created for all leaders who are able to recruit. All unit-types from the recruit- and recall lists are mapped to a score.

In the end the scores represent the desired unit-ratios on the map. (This means the AI will ''not'' just recruit the unit with the highest score, but in such a way that the mix of units on the map comes as close as possible to the mix represented by the scores.)
The scores are filled with values coming from combat analysis (see below).

After that the AI modifies the scores in several ways:
* Similar units get a penalty for being similar. Similar units are units in one advancement tree.
Example (Archer can advance to Ranger):
before after
Elvish Fighter: 50 50
Elvish Archer: 50 25
Elvish Ranger: 50 25
* The aspects <code>recruitment_more</code>, <code>recruitment_diversity</code> and <code>recruitment_randomness</code> are handled ([[#Other_aspects|see below]]).

==Combat Analysis==
For each unit-type the AI's leaders can recruit, the CA will simulate a fight against all enemy units on the map. If there are less then 5 enemy units, the enemies recruitment list(s) will be taken into account.

After Combat Analysis the score map may look like this:

Goblin Spearman score: 16.1252
Naga Fighter score: 0
Orcish Archer score: 61.6442
Orcish Assassin score: 88.0737
Orcish Grunt score: 100
Troll Whelp score: 26.7646
Wolf Rider score: 0

===Implementation details for interested readers===

Combat Analysis will use the function <code>compare_unit_types(A, B)</code>. It takes two unit-types and simulates a fight using a cache because simulation is expensive. The function returns a positive value if unit-type <code>A</code> is better then <code>B</code> and a negative value if unit-type <code>B</code> is better then <code>A</code>. If the return value is 2.0 it means that unit-type A is twice as good as unit-type B.

Here is a important code-snipped of <code>compare_unit_types()</code>:

<code>damage_to_b</code> comes from simulations and is the average damage dealt by <code>A</code> when <code>A</code> attacks (<code>A</code> chooses weapon) plus the average damage dealt by <code>A</code> when <code>B</code> attacks (<code>B</code> chooses weapon). <code>damage_to_a</code> is equivalent.
double value_of_a = damage_to_b / (b_max_hp * a_cost);
double value_of_b = damage_to_a / (a_max_hp * b_cost);

if (value_of_a > value_of_b) {
return value_of_a / value_of_b;
} else if (value_of_a < value_of_b) {
return -value_of_b / value_of_a;
} else {
return 0.;
}

The return-value of <code>compare_unit_types()</code> will be multiplied by the enemies current hp and added to the score map.

Included in the damage calculations are average defense (coming from "important hexes"), resistance, resistance abilities, average time of day, drain, poison, berserk, swarm and slows.

At this point the scores can be quite unhandy. They could all be negative, very high or too similar. So the scores will be transformed linearly. The resulting scores are numbers between 0.0 and 100.0.
The minimum depends on the aspect <code>recruitment_diversity</code>

Simplified code-snipped:
double new_100 = max_score;
double new_0 = max_score - (recruitment_diversity * (max_score - average_score));

BOOST_FOREACH(double& score, scores) {
score = 100 * ((score - new_0) / (new_100 - new_0)); // linear transformation
if (score < 0.) {
score = 0.;
}
}

=Aspect recruitment_instruction=
This is a powerful aspect to completely control recruitment via WML. After the score maps are created the CA will start to execute 'jobs' (or <code>[recruit]</code>-tags). If there is no job, the AI will do nothing at all.

This aspect is quite complex and requires the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form of an aspect]].
[ai]
[aspect]
id=recruitment_instruction
[facet]
turns=
[value]
#(here multiple [recruit] and/or [limit]-tags)
[recruit]
#(attributes)
[/recruit]
[limit]
#(attributes)
[/limit]
[value]
[/facet]
[/aspect]
[/ai]

Attributes inside <code>[facet]</code>:
* '''turns="": (string)''' This key takes a comma separated list containing numbers specifying the turns. '-' can be used between two values to define a range. An empty String means ''all turns''.
* See [[AiWML#A Bit More on_Simple vs. Composite Aspects|here]] for more information. But note, that <code>invalidate_on_gamestate_change</code> and <code>invalidate_on_minor_gamestate_change</code> will have no effect on <code>[recruit]</code>-tags. They will be read at the beginning of the turn and then be immutable.

Attributes inside <code>[recruit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. Common usages are: 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means ''all units''. If more then one unit is specified the AI will decide according to the score map what to recruit.
* '''number=-1: (integer)''' A number greater than 0 will tell the AI to recruit n units. -1 means ''as much as possible''. 0 means ''do not recruit''.
* '''importance=1: (integer)''' The importance of a recruitment tells the AI first to recruit units with the highest importance. If gold is lacking or the castle is full, only the most important units will be recruited, the other <code>[recruit]</code>-jobs will be dropped then.
* '''leader_id="": (string)''' ID of the leader who shall execute this job. Empty string means ''all leaders''. (Note: This is only a recommendation for the AI. If the specified leader has no free hexes the AI will use other leaders to do the job. This is because the function <code>check_recruit_action()</code> in contexts.hpp will automatically choose another leader if the specified does has no free hexes)
* '''total=no: (boolean)''' If total is set to ''yes'' the AI will count the own units on the map which match at least one of the given types and will then recruit the difference between <code>number</code> and the counted amount.
* '''blocker=yes: (boolean)''' If set to ''yes'' the AI will stop recruiting when this job cannot be done (because of lacking gold or a <code>[limit]</code> for example). If set to ''no'' the AI will drop this job and try to continue with less important ones.
* '''pattern=no: (boolean)''' If set to yes the unit to recruit will not be chosen by the AI but randomly according to the frequency in the type attribute. For example when "type=Orcish Grunt, Orcish Grunt, scout" and "number=6", the AI will recruit 6 units whereas the probability that one unit is a Grunt is twice as big as the probability that the AI will recruit a scout. If the type-attribute is empty the AI will recruit randomly. (See also [[#Other_aspects|recruitment_pattern]])

Attributes inside <code>[limit]</code>: ''(with default values)''
* '''type="": (string)''' This key takes a comma separated list containing unit-types, usages or levels. A empty string means ''all units''.
* '''max=0: (int)''' The maximum of units of the given type.

Notes:
* <code>[limit]</code> has higher priority than <code>[recruit]</code>.
* The aspect <code>recruitment_save_gold</code> has higher priority then <code>[recruit]</code>. So if exact recruiting is wished, deactivate <code>recruitment_save_gold</code> ([[#Aspect_recruitment_save_gold|see below]])
* If recruitment is specified for a turn, the AI will '''not recruit any other unit''' by default. (So if the AI is told to recruit 1 scout in turn 1 then the AI will only recruit 1 scout and not more). To prevent this behavior one can add this <code>[recruit]</code>-tag:
[recruit]
importance=0
[/recruit]
According to all the default values above (all types, as much as possible, ...) the AI will now ''fall back'' when all other recruitment jobs are done. This is also the content of the <code>[default]</code>-facet for the aspect.
* Even if only a <code>[limit]</code>-tag is used, the <code>[default]</code>-facet will get overwritten. Include the <code>[recruit]</code> mentioned in the previous point to let the AI recruit something.
* Only one facet at a time can be active. When there are more <code>[facet]</code>s defined in a turn the behavior is undefined. In one <code>[facet]</code> can be many <code>[recruit]</code> or <code>[limit]</code>-tags.
* Do not define more than one <code>[recruit]</code>-tags with the same importance. Note that the aspect <code>recruitment_pattern</code> will expand into a <code>[recruit]</code>-tag with importance=1.

==Examples==
Recruit 3 Grunts (and nothing more) in turn 3-5.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=3-5'''
[value]
[recruit]
'''type=Orcish Grunt'''
'''number=3'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit as many scouts as necessary until there are 4 scouts in total and then recruit other units.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=4
'''total=yes'''
importance=1
[/recruit]
'''[recruit]'''
'''importance=0'''
'''[/recruit]'''
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 6 Grunts or level 2 units (whatever seems better for the AI) and nothing more.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type=Orcish Grunt, 2'''
number=6
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit 5 scouts with leader1 and 5 Grunts with leader2. Do even try to recruit the Grunts if leader1 can not recruit all of the scouts.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
type=scout
number=5
'''importance=2'''
'''leader_id=leader1'''
'''blocker=no'''
[/recruit]
[recruit]
type=Orcish Grunt
number=5
'''importance=1'''
'''leader_id=leader2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Recruit random units always.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[recruit]
'''type='''
'''pattern=yes'''
importance=1
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
Do not recruit in turn 4.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=4'''
[value]
[recruit]
importance=1
'''number=0'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]

Do not have more than 6 units on the map.
[ai]
[aspect]
id=recruitment_instructions
[facet]
[value]
[limit]
type= #empty type means all units
max=6
[/limit]
[recruit] #Do not forget to include the default
importance=0 #[recruit]-tag. Otherwise the AI won't
[/recruit] #recruit anything.
[/value]
[/facet]
[/aspect]
[/ai]

This will not work because only one <code>[facet]</code> can be active.
[ai]
[aspect]
id=recruitment_instructions
[facet]
'''turns=1-10'''
[value]
[recruit]
type=scout
number=5
'''importance=1'''
[/recruit]
[/value]
[/facet]
[facet]
'''turns=3'''
[value]
[recruit]
type=Orcish Grunt
number=3
'''importance=2'''
[/recruit]
[/value]
[/facet]
[/aspect]
[/ai]
To achieve this behavior one has to create a <code>[facet]</code> for turn 1-2, a <code>[facet]</code> for turn 3 and another <code>[facet]</code> for turn 4-10.

=Aspect recruitment_save_gold=
==How it works==
For several reasons it can be a good idea not to spend all gold at once:
* To save the upkeep,
* To wait for the enemy to recruit first to counter easily,
* To save gold for the next scenario when the enemy is almost defeated.

At the same time it is a good idea (especially for the AI) to recruit in 'waves' (not to recruit one unit each turn).

For this there is the aspect <code>recruitment_save_gold</code>.

The Recruitment CA is always in one of the following states:
* NORMAL,
* SAVE_GOLD,
* SPEND_ALL_GOLD,
* LEADER_IN_DANGER.
Except the state LEADER_IN_DANGER, the states are persistent over turns.

The AI keeps track of a 'unit_ratio'. This is <code>our_total_unit_costs / enemy_total_unit_costs</code> whereas the costs are the sum of the cost of all units on the map weighted by their HP.
Also the AI tries to estimate the total income over the next 5 turns. (This is a quite rough estimation, but that's fine.)

When the AI is in state NORMAL '''and''' the unit_ratio exceeds a predefined threshold ('begin') '''and''' the estimated income is positive, the AI will switch to the state SAVE_GOLD. Now the AI does not recruit units anymore until the unit_ratio falls below another predefined threshold ('end'). Then the AI will switch to the NORMAL state and recruit again.

With this behavior the AI can save quite a lot of gold. When the AI has more gold then a predefined value ('spend_all_gold'), it will switch into the state SPEND_ALL_GOLD and recruit a big army to start an offensive wave.

The AI will ignore all those gold saving strategies when there is a LEADER_IN_DANGER. This happens when an enemy is near the leader (5 hexes).

'''Important note:''' Although the intuition says that the AI will play better when it tries to save some gold, it doesn't. Tests shown that it is always good for the AI to have as many units as possible. (Probably it will do better in village-capturing then). The aspect is activated by default because playing against wave-like recruiting is fun.

==The Aspect==
This aspect requires also the [[AiWML#A Bit More on_Simple vs. Composite Aspects|composite form]].
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
#(attributes)
[/value]
[/facet]
[/aspect]
[/ai]
Attributes inside <code>[value]</code>: ''(with default values)''
* '''active=2: (int)''' From this turn on the aspect will be active. So the AI will always spend all gold until the defined turn. <code>active=0</code> can be used to always deactivate gold saving. (The default value is 2 so nobody will get confused if the AI doesn't recruit in the first turn)
* '''begin=1.5: (double)''' See explanation above.
* '''end=1.1: (double)''' See explanation above.
* '''spend_all_gold=-1: (int)''' See explanation above. If set to -1 the AI will never switch to the state SPEND_ALL_GOLD.
* '''save_on_negative_income=no: (boolean)''' If this is set to yes, the AI will switch to the state SAVE_GOLD even if the income is negative. (estimation over 5 turns, village gain and unit loss estimation included).

==Example==
This example is filled with all default values and can be used for quick copying.
[ai]
[aspect]
id=recruitment_save_gold
[facet]
[value]
active=2
begin=1.5
end=1.1
spend_all_gold=-1
save_on_negative_income=no
[/value]
[/facet]
[/aspect]
[/ai]

A macro can be used to deactivate recruitment_save_gold:

{AI_ASPECT recruitment_save_gold {AI_DEACTIVATE_SAVE_GOLD} }

=Other aspects=
*'''recruitment_diversity'''=2.0 (double) When this value is high, the AI will recruit more units which are currently rare on the map. When the value is 0.0, the AI will only recruit the best unit.(see [[AI_Recruitment#Implementation_details_for_interested_readers| above]] for implementation details).
*'''recruitment_more'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. This is meant to let a scenario editor make an easy hack when he/she wants the AI to recruit more units of a specific type. (25 will be added to the unit-type's score.) With <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add 50 to the Grunt's score.
*'''recruitment_randomness'''=50 (int) To each score a random value between 0 and <code>recruitment_randomness</code> will be added. Don't hesitate to use a high value (like 200) to increase randomness.
*'''recruitment_pattern'''="" (string) This key takes a comma separated list containing unit-types, usages or levels. 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 usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
**For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
**Internally <code>recruitment_pattern</code> will expand into a <code>recruitment_instruction</code> with <code>pattern=yes</code> and <code>importance=1</code>. (So <code>recruitment_pattern</code> is a shortcut for a special <code>recruitment_instruction</code>). Make sure that there is no <code>recruitment_instruction</code> with <code>importance=1</code> when using <code>recruitment_pattern</code>.
*'''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.

=Making recruitment strong=

The default aspects are chosen so it is fun to play against the AI.
To let the AI recruit stronger this settings are recommended:
* '''recruitment_diversity=0.8''' Let the AI recruit the best units only.
* '''recruitment_randomness=0''' Let the recruitment not be random.
* '''villages_per_scout=0''' Test shown that the AI plays slightly better with less or no scouts at all.
* '''deactivate recruitment_save_gold''' (see above). Test shown that the AI plays better when it spends all money immediately.

In Multiplayer games the AI 'Strong AI (RCA)' can be chosen where the settings are as described here.

=Some notes on multiple leaders=
The CA ''can'' recruit with multiple leaders - even with different recruitment lists. Also the CA 'Move_Leader_To_Keep' will try to move all units with <code>canrecruit=yes</code> to the next keep.

However there are some drawbacks:
* In the current version the leaders will recruit by default almost the same amount of units. This can partly configured with the aspect <code>recruitment_instruction</code> and it's attribute <code>leader_id</code>. A leader will recruit more units when he/she is in danger (enemies are near).
* As mentioned above <code>leader_id</code> in <code>recruitment_instruction</code> is only a recommendation.
* Multiple leaders with different recruitment lists in combination with a <code>recruitment_pattern</code> may be confusing. (For the AI it's more important that the leaders recruit the same amount of units than fulfilling the ratios given in the <code>recruitment_pattern</code>.)

[[Category:AI]]

LuaAI

2014-01-18T19:51:12Z

Alarantalara: Add Lua category

This is a page containing information on configuring the AI using Lua. In addition to the technical information on this page, a tutorial-style guide is also available at [[Lua AI Howto]].

NB: previous contents of the page moved to http://wiki.wesnoth.org/LuaAI(old)

== Aspects ==
Patch r49721 enabled users to write aspects using Lua. This simplifies the definition of aspects that are meant to change depending on the game state. A good example could be aggression, which changes depending on the time of the day(since ToD affects the actual battle performance of your forces). 
Static aggression:
[aspect]
id="aggression"
engine="lua"
value="0.3"
[/aspect]
Dynamic aggression:
[aspect]
id=aggression
engine=lua

code=<<
wesnoth.fire("store_time_of_day")
local value = 0
tod = tostring(wesnoth.get_variable('time_of_day').name)
if (tod == 'Morning') then
value = 0.2
else
value = 1
end

wesnoth.fire("clear_variable", {name = "time_of_day"})
return value
>>
[/aspect]

Note: the way of getting the ToD is hacky here, but I will create a more elegant method soon(Nephro). 
Also note the difference between 'code' and 'value' attributes, this is important. 
At the moment, it is possible to create the following aspects using Lua(the list will be constantly updated):
advancements // string[] or function (see below)
aggression // double
attack_depth // int
avoid // exposed as map_location[], where map_location is a table of form {x, y}
caution // double
grouping // string
leader_aggression // double
leader_goal // exposed as a config
leader_value // double
number_of_possible_recruits_to_force_recruit // double
passive_leader // bool
passive_leader_shares_keep // bool
recruitment_ignore_bad_combat // bool
recruitment_ignore_bad_movement // bool
recruitment_pattern // string[]
scout_village_targeting // double
simple_targeting // bool
support_villages // bool
village_value // double
villages_per_scout // int

Note: simple numeric, bool and string aspect creation can be enabled just by adding a specific factory to registry.cpp, this will also soon be done.

To get the value of a specific aspect in Lua we have to use the
ai.get_<aspect_name>()
function. E.g.
local aggression = ai.get_aggression()

===Aspect: advancements===
This aspect can be used to define to what unit a specific unit on the map should advance.
It can be used in multiple ways:
<ol>
<li> Lua returns a String of the Form "Javelineer, Footpad". When the AI advances a Spearman he will become a Javelineer (because Javelineer is a member of the list).
</li>
<li>Lua returns a function of the Form <code>advance(x, y)</code> which itself returns a string.</li>
[ai]
[aspect]
id=advancements
engine=lua

code=<<
function advance(x, y)
local unit = wesnoth.get_unit(x, y)
if(unit.id == 'bob') then
return 'Swordsman'
else
return 'Javelineer'
end
end
return advance
>>
[/aspect]
[/ai]
When a unit advances <code>advance(x, y)</code> is called with the current location of the unit as parameter. You may use <code>wesnoth.get_unit(x, y)</code> to retrieve the unit object itself.
Note that the return value of <code>advance(x, y)</code> could also be a list (like in 1.).
<li>
Just for completeness: The aspect will work without Lua and can then look like this:
</li>
[ai]
advancements = "Javelineer, Footpad"
[/ai]

</ol>
Note that this aspect only affects attacking units. When a defending unit advances it is still decided randomly. That is because Wesnoths design don't allow the AI to make out of turn decisions.

== Preload event ==

It is a good idea to have such a preload event in your scenario if you are intending to use Lua for AI programming or customizing. The code of this event will most probably be moved out to a macro(except for the line that requires patrol.lua, since it is not necessary).

[event]
name=preload
first_time_only=no
[lua]
code = <<
H = wesnoth.require "lua/helper.lua"
W = H.set_wml_action_metatable {}
_ = wesnoth.textdomain "my-campaign"
ai = {}
ca_counter = 0

H.set_wml_var_metatable(_G)

wesnoth.require("ai/lua/patrol.lua")

>>
[/lua]
[/event]

The code attribute can be further expanded by any Lua code needed. For example, we can set up some global variables there or include additional code libraries("wesnoth.require("ai/lua/patrol.lua")" - includes code that handles patrolling of units).

== Engine code ==

In the engine tag you should define functions that will handle evaluation and execution of your custom candidate actions and stages. You can also run some code that is intended to be run once in the beginning. 
The definition of the [engine] tag should be place inside the [ai] tag.

[engine]
name="lua"
code= <<
-- your engine code here
>>
[/engine]

== Stages ==
Once the engine has been set up, we can start adding stages to the configuration of our AI. 
To add a stage we just use the [stage] tag.
[stage]
engine=lua
code=<<
-- Code for stage execution here
-- It is better to call predefined functions for the [engine] code,
-- than to define the functions here, to keep the structure of the stages clear
>>
[/stage]

== Candidate actions ==
This is an example from the current version of the lua_ai arena. The stage with an id "ca_loop" is the RCA AI loop stage, as we can see from its name. Currently it has two candidate actions, both Lua backed.

[stage]
name=testing_ai_default::candidate_action_evaluation_loop
id=ca_loop
[candidate_action]
engine=lua
name=first
id=firstca
evaluation="return (...):candidate_action_evaluation_hello()"
execution="local ai, cfg = ...; ai:candidate_action_execution_hello(cfg)"
[/candidate_action]
[candidate_action]
engine=lua
name=second
evaluation="return (...):candidate_action_evaluation_hello2()"
execution="(...):candidate_action_execution_hello2()"
[/candidate_action]
[/stage]
Basically, we need to have an engine attribute, an evaluation and execution functions. The syntax (...):foo() means "call eng.foo(eng) where eng is whatever the engine code returns". We can also add, remove, modify candidate actions on the fly, using wesnoth.wml_actions.modify_ai() functionality. Behavior(sticky) candidate actions use this approach.

== Behavior(sticky) candidate actions ==
Sometimes we need a specific unit to do a specific action in our scenario, e.g. we want a scout unit to patrol between 3 places on the map, to provide us with visibility needed. In this case we can create a sticky candidate action that will tie itself to the unit, and remove itself when the unit has died. The syntax for defining a sticky candidate action is the following:
[event]
name=side 2 turn 1
first_time_only=yes
[add_ai_behavior]
side=2
[filter]
name="Rark"
[/filter]
sticky=yes
loop_id=ca_loop
evaluation="return patrol_eval_rark()"
execution="patrol_rark()"
[/add_ai_behavior]
[/event]
Here the behavior CA is added to the configuration of the AI when the event triggers. Obviously this will happen when side 2 gets its first turn, but the event can be whatever needed. The definition is very similar to a simple candidate action, but here we also filter out a unit and state that we want the behavior to be sticky. If we don't, the action will not try to remove itself, when the unit gets killed, and this could cause errors. 
Such CAs can also be added from inside other CA or stage code using wesnoth.wml_actions.add_ai_behavior(cfg) function.

Sticky candidate actions never execute more than once per turn. Therefore, if the action consists of a series of goals, the CA must evaluate and execute each goal as it is achieved within itself and not rely on being called multiple times.

== Behavior function library ==
Behaviors are defined using generators. A behavior generator receives arguments(unit info, configuration, etc) and returns a pair of functions: evaluator and executor. These functions are to be passed to the add_ai_behavior tag, or directly to the function.
=== Patrolling ===
The only behavior defined at the moment is the patrol behavior. After calling patrol_gen(name, locations), we receive a pair of functions to use for creation of candidate actions 
Inclusion of the patrolling code:
wesnoth.require("ai/lua/patrol.lua")
Usage:
local patrol_rark = patrol_gen("Rark", {{x=14, y=7}, {x=15, y=7}, {x=15, y=8}, {x=14, y=8}})
-- patrol_rark.exec -- execution function
-- patrol_rark.eval -- evaluation function
As you can see, the first argument is the name of the unit, the second is a table of coordinates of arbitrary length.

==Goals and targets==

When deciding what move to do next, the AI uses targets(markers on the map, pointing to villages, units, locations, etc). Targets are produced by goal objects. There are multiple predefined goal objects of different types in the C++ implementation, but now it is possible to define goal objects in Lua.

[goal]
name=lua_goal
value=6
engine=lua
code = <<
local t = {
t[1] = {value=2.3, type=3, loc={x=5, y=6} }
t[2] = {value=2.4, type=4, loc={x=4, y=16} }
}
return t
>>
[/goal]

As you can see, the return value must be a table containing 0 or more targets. Each target must contain the three fields: "loc", "type", "value". This code will then be parsed by the Lua engine and the targets will be available to use to any engine desired. To get the targets inside Lua, a simple
local tg = ai.get_targets()
must be called. tg will contain a table of the same format, as one described in the goal definition code upper.

== Persistence ==

If you need to store some data between save/load routines, you probably need a place to store the data. For this purpose, a field named "data" is automatically added to the return value of your engine code. The save routine will find this field, convert it to a config and store its content in readable format. When the scenario gets loaded back, the engine code will inject the data back in the AI context. All other data will be lost. Note that all content of "data" needs to be in WML table format, otherwise it will not be saved.

== Debug access to the AI tree ==

wesnoth.debug_ai(side)
-- has been added. The function only works in debug mode and returns a table containing the component tree of the active AI for a side, the engine functions and the accessor to the ai.* table of the LuaAI Also allows the user to execute stages and evaluate/execute candidate actions(eval and exec can be run independently).

Structure of the table(example):

{
stage_hello = function: 0x6dc24c0,
ai = #the ai table,
data = {
},
do_moves = function: 0x6dc2590,
candidate_action_evaluation_hello = function: 0x6dc2560,
candidate_action_evaluation_hello2 = function: 0x6dc2640,
components = {
id = "",
stage = {
another_stage = {
name = "another_stage",
id = "",
exec = function: 0x17cd3bb,
engine = "lua",
stg_ptr = "userdata: 0x7c5a8d0"
},
testing_ai_default::candidate_action_evaluation_loop = {
name = "testing_ai_default::candidate_action_evaluation_loop",
candidate_action = {
external = {
name = "external",
id = "",
exec = function: 0x17cd2f3,
engine = "lua",
ca_ptr = "userdata: 0x6fb3600"
},
second = {
name = "second",
id = "",
exec = function: 0x17cd2f3,
engine = "lua",
ca_ptr = "userdata: 0x6fb2f50"
}
},
id = "ca_loop",
exec = function: 0x17cd3bb,
engine = "",
stg_ptr = "userdata: 0x6fb2728"
}
},
engine = "",
name = ""
},
candidate_action_execution_hello2 = function: 0x6dc2670,
candidate_action_execution_hello = function: 0x6dc2530
}

The fields described as " name = function: 0xXXXXXXXX" are functions and can be called to using the usual function call syntax of Lua.
wesnoth.debug_ai(2).ai -- will return the AI table of the Lua AI context.

wesnoth.debug_ai(2).stage[another_stage].exec() -- will execute the stage.

wesnoth.debug_ai(2).ai.get_aggression() -- will the return the current value of the aggression aspect of the AI

Therefore, we have up-to-date access to the whole AI, including the data segment.

NB!: the back-end of this function will be refactored quite drastically and that may involve usage syntax changes. This shouldn't be a big problem, since this function is only used for debugging and won't work in non-debug mode. If something suddenly stops working for you, come back to this page and watch the updates.

[[Category:AI]]
[[Category: Lua Reference|*]]

Download

2013-11-16T16:20:55Z

Alarantalara: /* Mac OS X (10.5+) */ partial revert: Previous -> Current

{{Download/Translations}}
Welcome to the Battle for Wesnoth downloads page. The BFW project team only officially releases the source code. Binary packages are only provided by community volunteers and hosted here. Torrents are also unofficial.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS.2C_etc..5D.3F|FAQ]].

__NOTOC__
Jump to: [[Download#Stable_.281.10_branch.29|Stable Branch]] | [[Download#Stable_.28older_versions.29|Stable Branch (older versions)]] | [[Download#Development_.281.11_branch.29|Development Branch]]

== Stable (1.10 branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.10 branch is compatible to each other.

Version 1.10.7 is the latest stable version. This version is recommended for most players since the 1.10 online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/wesnoth-1.10.7.tar.bz2/download Current Version] (1.10.7, 347.4 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6.tar.bz2/download Previous Version] (1.10.6, 346.1 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/wesnoth-1.10.7-win32.exe/download Current Version] (1.10.7, 319.1 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6-win32.exe/download Previous Version] (1.10.6, 317.4 MB)

==== Mac OS X (10.5+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/Wesnoth_1.10.7.dmg/download Current Version] (1.10.7, 349.6 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/Wesnoth_1.10.6.dmg/download Previous Version] (1.10.6, 348.1 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/wesnoth-1.10.7-1.pnd/download Current Version] (1.10.7-1, 340.8 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6-1.pnd/download Previous Version] (1.10.6-1, 338.9 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/wesnoth-1.10.7.tar.bz2.md5/download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Stable_Version_1.10.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== Stable (older versions) ==
Several operating systems do not offer a binary of the latest stable release. Here is a list of the latest known (stable version) binaries for various systems. For those older versions there often is no (official) multiplayer or addon server available anymore.

==== AmigaOS4 ====
* [http://www.amigasoft.net/pages/games/download/Wesnoth186.lha.lzh Older Version] (1.8.6, 300MB)

==== (Open)Solaris ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.4/wesnoth-1.4.5/wesnoth-solaris-i386-1.4.5.pkg.bz2/download Older Version] (1.4.5, 145.6 MB), not compatible with 1.6.x

==== OS/2 & eComStation ====
* [http://download.smedley.info/wesnoth-1.4.5-os2-20080828.zip Older Version] (1.4.5, 160 MB), not compatible with 1.6.x

==== RISC OS ====
*[http://www.riscos.info/packages/arm/Games/wesnoth_1.4.5-1.zip Older version] (1.4.5-1, 140MB), not compatible with 1.6.x

==== Syllable ====
* [http://downloads.syllable.org/Syllable/i586/applications/contributed/Battle-for-Wesnoth/Battle-for-Wesnoth-1.2.6.application Older Version] (1.2.6, 60.8 MB), not compatible with 1.6.x

== Development (1.11 branch) ==
Version 1.11.x is the latest development version, boasting updated graphics and new exciting features. However, there may be occasional bugs or performance problems in the development versions since heavy changes are taking place all the time. For balanced and stable gaming, it is recommended you use the latest version of the 1.10.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth. People familiar with version control systems and compiling can follow the latest development by checking [[WesnothRepository]].

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.7/wesnoth-1.11.7.tar.bz2/download Current Version] (1.11.7, 386.0 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.6/wesnoth-1.11.6.tar.bz2/download Previous Version] (1.11.6, 380.8 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.7/wesnoth-1.11.7-win32.exe/download Current Version] (1.11.7, 351.1 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.6/wesnoth-1.11.6-win32.exe/download Previous Version] (1.11.6, 348.3 MB)

==== Mac OS X (10.5+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.7/Wesnoth_1.11.7.dmg/download Current version] (1.11.7, 386.1MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.6/Wesnoth_1.11.6.dmg/download Previous version] (1.11.6, 379.2MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* The current version (1.11.7) is not available yet.
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.4/wesnoth-1.11.4-1.pnd/download Older Version] (1.11.4-1, 360.7 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.7/wesnoth-1.11.7.tar.bz2.md5/download md5sum for current source code]
* [http://wiki.wesnoth.org/Download_Xdeltas#Development_Version_1.11.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]
* [http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/wesnoth_compile_mac_1.9.zip/download MacCompileStuff for 1.9]

== License ==
''Main article: [[Wesnoth:Copyrights]]

This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org Free Software Foundation].
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== UMC Editor ==
This is available with Wesnoth 1.9.x and greater (including Wesnoth 1.10.x).
Details and installation steps can be found at: http://eclipse.wesnoth.org

== See also ==
* [http://changelog.wesnoth.org Changelog]
* [[WesnothBinaries| More binaries]]
* [[WesnothRepository]] - bleeding edge version from the repository

[[Category:Building and Installing]]

Download

2013-11-16T16:07:20Z

Alarantalara: /* Mac OS X (10.5+) */ Add 1.11.7 for OS X link

{{Download/Translations}}
Welcome to the Battle for Wesnoth downloads page. The BFW project team only officially releases the source code. Binary packages are only provided by community volunteers and hosted here. Torrents are also unofficial.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS.2C_etc..5D.3F|FAQ]].

__NOTOC__
Jump to: [[Download#Stable_.281.10_branch.29|Stable Branch]] | [[Download#Stable_.28older_versions.29|Stable Branch (older versions)]] | [[Download#Development_.281.11_branch.29|Development Branch]]

== Stable (1.10 branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.10 branch is compatible to each other.

Version 1.10.7 is the latest stable version. This version is recommended for most players since the 1.10 online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/wesnoth-1.10.7.tar.bz2/download Current Version] (1.10.7, 347.4 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6.tar.bz2/download Previous Version] (1.10.6, 346.1 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/wesnoth-1.10.7-win32.exe/download Current Version] (1.10.7, 319.1 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6-win32.exe/download Previous Version] (1.10.6, 317.4 MB)

==== Mac OS X (10.5+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/Wesnoth_1.10.7.dmg/download Current Version] (1.10.7, 349.6 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/Wesnoth_1.10.6.dmg/download Previous Version] (1.10.6, 348.1 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/wesnoth-1.10.7-1.pnd/download Current Version] (1.10.7-1, 340.8 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6-1.pnd/download Previous Version] (1.10.6-1, 338.9 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/wesnoth-1.10.7.tar.bz2.md5/download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Stable_Version_1.10.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== Stable (older versions) ==
Several operating systems do not offer a binary of the latest stable release. Here is a list of the latest known (stable version) binaries for various systems. For those older versions there often is no (official) multiplayer or addon server available anymore.

==== AmigaOS4 ====
* [http://www.amigasoft.net/pages/games/download/Wesnoth186.lha.lzh Older Version] (1.8.6, 300MB)

==== (Open)Solaris ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.4/wesnoth-1.4.5/wesnoth-solaris-i386-1.4.5.pkg.bz2/download Older Version] (1.4.5, 145.6 MB), not compatible with 1.6.x

==== OS/2 & eComStation ====
* [http://download.smedley.info/wesnoth-1.4.5-os2-20080828.zip Older Version] (1.4.5, 160 MB), not compatible with 1.6.x

==== RISC OS ====
*[http://www.riscos.info/packages/arm/Games/wesnoth_1.4.5-1.zip Older version] (1.4.5-1, 140MB), not compatible with 1.6.x

==== Syllable ====
* [http://downloads.syllable.org/Syllable/i586/applications/contributed/Battle-for-Wesnoth/Battle-for-Wesnoth-1.2.6.application Older Version] (1.2.6, 60.8 MB), not compatible with 1.6.x

== Development (1.11 branch) ==
Version 1.11.x is the latest development version, boasting updated graphics and new exciting features. However, there may be occasional bugs or performance problems in the development versions since heavy changes are taking place all the time. For balanced and stable gaming, it is recommended you use the latest version of the 1.10.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth. People familiar with version control systems and compiling can follow the latest development by checking [[WesnothRepository]].

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.6/wesnoth-1.11.6.tar.bz2/download Current Version] (1.11.6, 380.8 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.5/wesnoth-1.11.5.tar.bz2/download Previous Version] (1.11.5, 373.2 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.6/wesnoth-1.11.6-win32.exe/download Current Version] (1.11.6, 348.3 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.5/wesnoth-1.11.5-win32.exe/download Previous Version] (1.11.5, 340.3 MB)

==== Mac OS X (10.5+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.7/Wesnoth_1.11.7.dmg/download Current version] (1.11.7, 381.1MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.6/Wesnoth_1.11.6.dmg/download Previous version] (1.11.6, 379.2MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* The current version (1.11.6) is not available yet.
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.4/wesnoth-1.11.4-1.pnd/download Older Version] (1.11.4-1, 360.7 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.6/wesnoth-1.11.6.tar.bz2.md5/download md5sum for current source code]
* [http://wiki.wesnoth.org/Download_Xdeltas#Development_Version_1.11.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]
* [http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/wesnoth_compile_mac_1.9.zip/download MacCompileStuff for 1.9]

== License ==
''Main article: [[Wesnoth:Copyrights]]

This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org Free Software Foundation].
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== UMC Editor ==
This is available with Wesnoth 1.9.x and greater (including Wesnoth 1.10.x).
Details and installation steps can be found at: http://eclipse.wesnoth.org

== See also ==
* [http://changelog.wesnoth.org Changelog]
* [[WesnothBinaries| More binaries]]
* [[WesnothRepository]] - bleeding edge version from the repository

[[Category:Building and Installing]]

Download

2013-09-02T22:07:37Z

Alarantalara: /* Mac OS X (10.5+) */

{{Download/Translations}}
Welcome to the Battle for Wesnoth downloads page. The BFW project team only officially releases the source code. Binary packages are only provided by community volunteers and hosted here. Torrents are also unofficial.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS.2C_etc..5D.3F|FAQ]].

__NOTOC__
Jump to: [[Download#Stable_.281.10_branch.29|Stable Branch]] | [[Download#Stable_.28older_versions.29|Stable Branch (older versions)]] | [[Download#Development_.281.11_branch.29|Development Branch]]

== Stable (1.10 branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.10 branch is compatible to each other.

Version 1.10.7 is the latest stable version. This version is recommended for most players since the 1.10 online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/wesnoth-1.10.7.tar.bz2/download Current Version] (1.10.7, 347.4 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6.tar.bz2/download Previous Version] (1.10.6, 346.1 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/wesnoth-1.10.7-win32.exe/download Current Version] (1.10.7, 319.1 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6-win32.exe/download Previous Version] (1.10.6, 317.4 MB)

==== Mac OS X (10.5+) ====
* The current version (1.10.7) is not available yet.
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/Wesnoth_1.10.6.dmg/download Previous Version] (1.10.6 348.1 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/wesnoth-1.10.7-1.pnd/download Current Version] (1.10.7-1, 340.8 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6-1.pnd/download Previous Version] (1.10.6-1, 338.9 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/wesnoth-1.10.7.tar.bz2.md5/download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Stable_Version_1.10.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== Stable (older versions) ==
Several operating systems do not offer a binary of the latest stable release. Here is a list of the latest known (stable version) binaries for various systems. For those older versions there often is no (official) multiplayer or addon server available anymore.

==== AmigaOS4 ====
* [http://www.amigasoft.net/pages/games/download/Wesnoth186.lha.lzh Older Version] (1.8.6, 300MB)

==== (Open)Solaris ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.4/wesnoth-1.4.5/wesnoth-solaris-i386-1.4.5.pkg.bz2/download Older Version] (1.4.5, 145.6 MB), not compatible with 1.6.x

==== OS/2 & eComStation ====
* [http://download.smedley.info/wesnoth-1.4.5-os2-20080828.zip Older Version] (1.4.5, 160 MB), not compatible with 1.6.x

==== RISC OS ====
*[http://www.riscos.info/packages/arm/Games/wesnoth_1.4.5-1.zip Older version] (1.4.5-1, 140MB), not compatible with 1.6.x

==== Syllable ====
* [http://downloads.syllable.org/Syllable/i586/applications/contributed/Battle-for-Wesnoth/Battle-for-Wesnoth-1.2.6.application Older Version] (1.2.6, 60.8 MB), not compatible with 1.6.x

== Development (1.11 branch) ==
Version 1.11.x is the latest development version, boasting updated graphics and new exciting features. However, there may be occasional bugs or performance problems in the development versions since heavy changes are taking place all the time. For balanced and stable gaming, it is recommended you use the latest version of the 1.10.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth. People familiar with version control systems and compiling can follow the latest development by checking [[WesnothRepository]].

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.6/wesnoth-1.11.6.tar.bz2/download Current Version] (1.11.6, 380.8 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.5/wesnoth-1.11.5.tar.bz2/download Previous Version] (1.11.5, 373.2 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.6/wesnoth-1.11.6-win32.exe/download Current Version] (1.11.6, 348.3 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.5/wesnoth-1.11.5-win32.exe/download Previous Version] (1.11.5, 340.3 MB)

==== Mac OS X (10.5+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.6/Wesnoth_1.11.6.dmg/download Current version] (1.11.6, 379.2MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.5/Wesnoth_1.11.5.dmg/download Previous version] (1.11.5, 371.8MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* The current version (1.11.6) is not available yet.
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.4/wesnoth-1.11.4-1.pnd/download Older Version] (1.11.4-1, 360.7 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.6/wesnoth-1.11.6.tar.bz2.md5/download md5sum for current source code]
* [http://wiki.wesnoth.org/Download_Xdeltas#Development_Version_1.11.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]
* [http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/wesnoth_compile_mac_1.9.zip/download MacCompileStuff for 1.9]

== License ==
''Main article: [[Wesnoth:Copyrights]]

This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org Free Software Foundation].
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== UMC Editor ==
This is available with Wesnoth 1.9.x and greater (including Wesnoth 1.10.x).
Details and installation steps can be found at: http://eclipse.wesnoth.org

== See also ==
* [http://changelog.wesnoth.org Changelog]
* [[WesnothBinaries| More binaries]]
* [[WesnothRepository]] - bleeding edge version from the repository

[[Category:Building and Installing]]

Download

2013-09-02T22:07:03Z

Alarantalara: /* Mac OS X (10.6+) */ Add link to OS X 1.11.6 package

{{Download/Translations}}
Welcome to the Battle for Wesnoth downloads page. The BFW project team only officially releases the source code. Binary packages are only provided by community volunteers and hosted here. Torrents are also unofficial.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS.2C_etc..5D.3F|FAQ]].

__NOTOC__
Jump to: [[Download#Stable_.281.10_branch.29|Stable Branch]] | [[Download#Stable_.28older_versions.29|Stable Branch (older versions)]] | [[Download#Development_.281.11_branch.29|Development Branch]]

== Stable (1.10 branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.10 branch is compatible to each other.

Version 1.10.7 is the latest stable version. This version is recommended for most players since the 1.10 online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/wesnoth-1.10.7.tar.bz2/download Current Version] (1.10.7, 347.4 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6.tar.bz2/download Previous Version] (1.10.6, 346.1 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/wesnoth-1.10.7-win32.exe/download Current Version] (1.10.7, 319.1 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6-win32.exe/download Previous Version] (1.10.6, 317.4 MB)

==== Mac OS X (10.5+) ====
* The current version (1.10.7) is not available yet.
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/Wesnoth_1.10.6.dmg/download Previous Version] (1.10.6 348.1 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/wesnoth-1.10.7-1.pnd/download Current Version] (1.10.7-1, 340.8 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6-1.pnd/download Previous Version] (1.10.6-1, 338.9 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.7/wesnoth-1.10.7.tar.bz2.md5/download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Stable_Version_1.10.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== Stable (older versions) ==
Several operating systems do not offer a binary of the latest stable release. Here is a list of the latest known (stable version) binaries for various systems. For those older versions there often is no (official) multiplayer or addon server available anymore.

==== AmigaOS4 ====
* [http://www.amigasoft.net/pages/games/download/Wesnoth186.lha.lzh Older Version] (1.8.6, 300MB)

==== (Open)Solaris ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.4/wesnoth-1.4.5/wesnoth-solaris-i386-1.4.5.pkg.bz2/download Older Version] (1.4.5, 145.6 MB), not compatible with 1.6.x

==== OS/2 & eComStation ====
* [http://download.smedley.info/wesnoth-1.4.5-os2-20080828.zip Older Version] (1.4.5, 160 MB), not compatible with 1.6.x

==== RISC OS ====
*[http://www.riscos.info/packages/arm/Games/wesnoth_1.4.5-1.zip Older version] (1.4.5-1, 140MB), not compatible with 1.6.x

==== Syllable ====
* [http://downloads.syllable.org/Syllable/i586/applications/contributed/Battle-for-Wesnoth/Battle-for-Wesnoth-1.2.6.application Older Version] (1.2.6, 60.8 MB), not compatible with 1.6.x

== Development (1.11 branch) ==
Version 1.11.x is the latest development version, boasting updated graphics and new exciting features. However, there may be occasional bugs or performance problems in the development versions since heavy changes are taking place all the time. For balanced and stable gaming, it is recommended you use the latest version of the 1.10.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth. People familiar with version control systems and compiling can follow the latest development by checking [[WesnothRepository]].

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.6/wesnoth-1.11.6.tar.bz2/download Current Version] (1.11.6, 380.8 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.5/wesnoth-1.11.5.tar.bz2/download Previous Version] (1.11.5, 373.2 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.6/wesnoth-1.11.6-win32.exe/download Current Version] (1.11.6, 348.3 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.5/wesnoth-1.11.5-win32.exe/download Previous Version] (1.11.5, 340.3 MB)

==== Mac OS X (10.5+) ====
* [

http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.6/Wesnoth_1.11.6.dmg/download Current version] (1.11.6, 379.2MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.5/Wesnoth_1.11.5.dmg/download Previous version] (1.11.5, 371.8MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* The current version (1.11.6) is not available yet.
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.4/wesnoth-1.11.4-1.pnd/download Older Version] (1.11.4-1, 360.7 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.6/wesnoth-1.11.6.tar.bz2.md5/download md5sum for current source code]
* [http://wiki.wesnoth.org/Download_Xdeltas#Development_Version_1.11.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]
* [http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/wesnoth_compile_mac_1.9.zip/download MacCompileStuff for 1.9]

== License ==
''Main article: [[Wesnoth:Copyrights]]

This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org Free Software Foundation].
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== UMC Editor ==
This is available with Wesnoth 1.9.x and greater (including Wesnoth 1.10.x).
Details and installation steps can be found at: http://eclipse.wesnoth.org

== See also ==
* [http://changelog.wesnoth.org Changelog]
* [[WesnothBinaries| More binaries]]
* [[WesnothRepository]] - bleeding edge version from the repository

[[Category:Building and Installing]]

Download

2013-06-26T02:49:18Z

Alarantalara: /* Mac OS X (10.5+) */ Added link to 1.11.5

{{Download/Translations}}
Welcome to the Battle for Wesnoth downloads page. The BFW project team only officially releases the source code. Binary packages are only provided by community volunteers and hosted here. Torrents are also unofficial.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS.2C_etc..5D.3F|FAQ]].

__NOTOC__
Jump to: [[Download#Stable_.281.10_branch.29|Stable Branch]] | [[Download#Stable_.28older_versions.29|Stable Branch (older versions)]] | [[Download#Development_.281.11_branch.29|Development Branch]]

== Stable (1.10 branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.10 branch is compatible to each other.

Version 1.10.6 is the latest stable version. This version is recommended for most players since the 1.10 online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6.tar.bz2/download Current Version] (1.10.6, 330.1 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.5/wesnoth-1.10.5.tar.bz2/download Previous Version] (1.10.5, 327.7 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6-win32.exe/download Current Version] (1.10.6, 302.7 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.5/wesnoth-1.10.5-win32.exe/download Previous Version] (1.10.5, 301.2 MB)

==== Mac OS X (10.5+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/Wesnoth_1.10.6.dmg/download Current Version] (1.10.6 332.0 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.5/Wesnoth_1.10.5.dmg/download Previous Version] (1.10.5 328.8 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6-1.pnd/download Current Version] (1.10.6-1, 323.2 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.5/wesnoth-1.10.5-1.pnd/download Previous Version] (1.10.5-1, 320.5 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6.tar.bz2.md5/download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Stable_Version_1.10.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== Stable (older versions) ==
Several operating systems do not offer a binary of the latest stable release. Here is a list of the latest known (stable version) binaries for various systems. For those older versions there often is no (official) multiplayer or addon server available anymore.

==== AmigaOS4 ====
* [http://www.amigasoft.net/pages/games/download/Wesnoth186.lha.lzh Older Version] (1.8.6, 300MB)

==== (Open)Solaris ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.4/wesnoth-1.4.5/wesnoth-solaris-i386-1.4.5.pkg.bz2/download Older Version] (1.4.5, 145.6 MB), not compatible with 1.6.x

==== OS/2 & eComStation ====
* [http://download.smedley.info/wesnoth-1.4.5-os2-20080828.zip Older Version] (1.4.5, 160 MB), not compatible with 1.6.x

==== RISC OS ====
*[http://www.riscos.info/packages/arm/Games/wesnoth_1.4.5-1.zip Older version] (1.4.5-1, 140MB), not compatible with 1.6.x

==== Syllable ====
* [http://downloads.syllable.org/Syllable/i586/applications/contributed/Battle-for-Wesnoth/Battle-for-Wesnoth-1.2.6.application Older Version] (1.2.6, 60.8 MB), not compatible with 1.6.x

== Development (1.11 branch) ==
Version 1.11.x is the latest development version, boasting updated graphics and new exciting features. However, there may be occasional bugs or performance problems in the development versions since heavy changes are taking place all the time. For balanced and stable gaming, it is recommended you use the latest version of the 1.10.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth. People familiar with version control systems and compiling can follow the latest development by checking [[WesnothRepository]].

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.5/wesnoth-1.11.5.tar.bz2/download Current Version] (1.11.5, 373.2 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.4/wesnoth-1.11.4.tar.bz2/download Previous Version] (1.11.4, 372.9 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.5/wesnoth-1.11.5-win32.exe/download Current Version] (1.11.5, 340.3 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.4/wesnoth-1.11.4-win32.exe/download Previous Version] (1.11.4, 340.4 MB)

==== Mac OS X (10.5+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.5/Wesnoth_1.11.5.dmg/download Previous version] (1.11.5, 371.8MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.4/Wesnoth_1.11.4.dmg/download Previous version] (1.11.4, 373.0MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* The current version (1.11.5) is not available yet.
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.4/wesnoth-1.11.4-1.pnd/download Previous Version] (1.11.4-1, 360.7 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.4/wesnoth-1.11.4.tar.bz2.md5/download md5sum for current source code]
* [http://wiki.wesnoth.org/Download_Xdeltas#Development_Version_1.11.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]
* [http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/wesnoth_compile_mac_1.9.zip/download MacCompileStuff for 1.9]

== License ==
''Main article: [[Wesnoth:Copyrights]]

This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org Free Software Foundation].
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== UMC Editor ==
This is available with Wesnoth 1.9.x and greater (including Wesnoth 1.10.x).
Details and installation steps can be found at: http://eclipse.wesnoth.org

== See also ==
* [http://changelog.wesnoth.org Changelog]
* [[WesnothBinaries| More binaries]]
* [[WesnothRepository]] - bleeding edge version from the repository

[[Category:Building and Installing]]

Download

2013-06-09T14:31:39Z

Alarantalara: /* Mac OS X (10.5+) */ Added 1.11.4 OS X link

{{Download/Translations}}
Welcome to the Battle for Wesnoth downloads page. The BFW project team only officially releases the source code. Binary packages are only provided by community volunteers and hosted here. Torrents are also unofficial.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS.2C_etc..5D.3F|FAQ]].

__NOTOC__
Jump to: [[Download#Stable_.281.10_branch.29|Stable Branch]] | [[Download#Stable_.28older_versions.29|Stable Branch (older versions)]] | [[Download#Development_.281.11_branch.29|Development Branch]]

== Stable (1.10 branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.10 branch is compatible to each other.

Version 1.10.6 is the latest stable version. This version is recommended for most players since the 1.10 online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6.tar.bz2/download Current Version] (1.10.6, 330.1 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.5/wesnoth-1.10.5.tar.bz2/download Previous Version] (1.10.5, 327.7 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6-win32.exe/download Current Version] (1.10.6, 302.7 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.5/wesnoth-1.10.5-win32.exe/download Previous Version] (1.10.5, 301.2 MB)

==== Mac OS X (10.5+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/Wesnoth_1.10.6.dmg/download Current Version] (1.10.6 332.0 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.5/Wesnoth_1.10.5.dmg/download Previous Version] (1.10.5 328.8 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6-1.pnd/download Current Version] (1.10.6-1, 323.2 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.5/wesnoth-1.10.5-1.pnd/download Previous Version] (1.10.5-1, 320.5 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.6/wesnoth-1.10.6.tar.bz2.md5/download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Stable_Version_1.10.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== Stable (older versions) ==
Several operating systems do not offer a binary of the latest stable release. Here is a list of the latest known (stable version) binaries for various systems. For those older versions there often is no (official) multiplayer or addon server available anymore.

==== AmigaOS4 ====
* [http://www.amigasoft.net/pages/games/download/Wesnoth186.lha.lzh Older Version] (1.8.6, 300MB)

==== (Open)Solaris ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.4/wesnoth-1.4.5/wesnoth-solaris-i386-1.4.5.pkg.bz2/download Older Version] (1.4.5, 145.6 MB), not compatible with 1.6.x

==== OS/2 & eComStation ====
* [http://download.smedley.info/wesnoth-1.4.5-os2-20080828.zip Older Version] (1.4.5, 160 MB), not compatible with 1.6.x

==== RISC OS ====
*[http://www.riscos.info/packages/arm/Games/wesnoth_1.4.5-1.zip Older version] (1.4.5-1, 140MB), not compatible with 1.6.x

==== Syllable ====
* [http://downloads.syllable.org/Syllable/i586/applications/contributed/Battle-for-Wesnoth/Battle-for-Wesnoth-1.2.6.application Older Version] (1.2.6, 60.8 MB), not compatible with 1.6.x

== Development (1.11 branch) ==
Version 1.11.x is the latest development version, boasting updated graphics and new exciting features. However, there may be occasional bugs or performance problems in the development versions since heavy changes are taking place all the time. For balanced and stable gaming, it is recommended you use the latest version of the 1.10.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth. People familiar with version control systems and compiling can follow the latest development by checking [[WesnothRepository]].

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.4/wesnoth-1.11.4.tar.bz2/download Current Version] (1.11.4, 372.9 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.2/wesnoth-1.11.2.tar.bz2/download Previous Version] (1.11.2, 369.5 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.4/wesnoth-1.11.4-win32.exe/download Current Version] (1.11.4, 340.4 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.2/wesnoth-1.11.2-win32.exe/download Previous Version] (1.11.2, 337.4 MB)

==== Mac OS X (10.5+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.4/Wesnoth_1.11.4.dmg/download Current version] (1.11.4, 373.0MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.2/Wesnoth_1.11.2.dmg/download Previous version] (1.11.2, 369.5 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.4/wesnoth-1.11.4-1.pnd/download Current Version] (1.11.4-1, 360.7 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.2/wesnoth-1.11.2-1.pnd/download Previous Version] (1.11.2-1, 357.4 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.4/wesnoth-1.11.4.tar.bz2.md5/download md5sum for current source code]
* [http://wiki.wesnoth.org/Download_Xdeltas#Development_Version_1.11.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]
* [http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/wesnoth_compile_mac_1.9.zip/download MacCompileStuff for 1.9]

== License ==
''Main article: [[Wesnoth:Copyrights]]

This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org Free Software Foundation].
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== UMC Editor ==
This is available with Wesnoth 1.9.x and greater (including Wesnoth 1.10.x).
Details and installation steps can be found at: http://eclipse.wesnoth.org

== See also ==
* [http://changelog.wesnoth.org Changelog]
* [[WesnothBinaries| More binaries]]
* [[WesnothRepository]] - bleeding edge version from the repository

[[Category:Building and Installing]]

EditingWesnoth

2013-02-14T13:01:27Z

Alarantalara: /* Mac OS X */

{{EditingWesnoth/Translations}}


== 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 should not modify these files, but you can if you want to modify a unit or something.

The user data directory holds your preferences file, custom maps, saved games, the WML cache and data files corresponding to user-created content. In this wiki, "user data" and ''userdata''/ refer to this directory.

The paths to the game data and user data directories vary according to the operating system and packager.

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

====Windows====

* ''X:\Program Files\Battle for Wesnoth <version>\data'', where X: corresponds to the drive where Windows is installed (normally C:).
* On 64-bit computers, it will be in ''X:\Program Files (x86)\Battle for Wesnoth <version>\data''.
* The path may be different if you originally chose to install the game in a different location. In such case, look for the data folder in the folder where you installed the game.

====Mac OS X====

* SourceForge.net bundle: Control+click on the application icon. Select "Show Package Contents." Select "Contents", then "Resources".
* Custom builds: ''/usr/local/share/wesnoth''

====Linux====

* Custom builds: ''/usr/local/share/wesnoth''
* Debian/Ubuntu packages, or emerge (Gentoo): ''/usr/share/games/wesnoth''
* Red Hat Linux-based distributions in general (openSUSE, Fedora): ''/usr/share/wesnoth''
* Mandriva: ''/usr/share/games/wesnoth''
* Slackware Linux: ''/usr/local/share/wesnoth''

In a terminal, the command <code>wesnoth --path</code> shows the game data directory.

====BSD====

* OpenBSD package: ''/usr/local/share/wesnoth''

The command <code>wesnoth --path</code> also works.

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

====Windows====

* Windows 2000/XP (1.8 and later): ''My Documents\My Games\Wesnoth1.8''
* Windows Vista/7 (1.8 and later): ''Documents\My Games\Wesnoth1.8''
* General (before 1.8): ''X:\Program Files\Battle for Wesnoth <version>\userdata'', where X: corresponds to the drive where Windows is installed (normally C:).

''Note: If you don't remember where you installed the game, right click on the game's shortcut, open properties, and click on the "Find target" button, then search for the "data" folder.''

''Note: If you chose "Store userdata in the install location" during installation you will find your userdata as mentioned above under "General". This will also apply if you launch wesnoth.exe directly instead of using the start menu shortcut.''

''Note: If your userdata folder is located in the install location (for the reasons mentioned above) and you are not an administrator on this machine Windows Vista/7 will silently redirect any write access to the so called Virtual Store. You can find your userdata folder in e.g. C:\Users\<yourname>\AppData\Local\VirtualStore\Program Files\Battle for Wesnoth <version>''

====Mac OS X====

* SourceForge.net bundle: ''~/Library/Application Support/Wesnoth_1.x/'' (1.8 and later), or ''~/Library/Preferences/Wesnoth'' (older versions). As of OS X 10.7, this location is hidden by default.
* Custom builds: same as Linux - see below for details.

====Linux====
* Wesnoth 1.10: ''~/.local/share/wesnoth/1.10''
* Wesnoth 1.9: ''~/.local/share/wesnoth/1.9''
* Wesnoth 1.8: ''~/.wesnoth1.8''
* Older versions: ''~/.wesnoth''

In a terminal, the command <code>wesnoth --config-path</code> shows the user data directory.

====BSD====
* Same place as Linux.

== Game Data ==

The major directories you need to know about are wesnoth/data, wesnoth/data/core/units, wesnoth/data/campaigns, wesnoth/data/multiplayer, wesnoth/images and wesnoth/data/core/images

Become familiar with what is in ./data/campaigns and ./data/multiplayer/scenarios. 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/core/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.

== User Data ==

The user data directory can do a lot of things. The game looks here for several things:
* ''userdata''/data/add-ons - campaign configuration files and subdirectories
* ''userdata''/editor/maps - multiplayer standalone maps (map data only)

The ''userdata''/data/add-ons 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.

For example, assume you have a campaign called MyCampaign. This is what the ''userdata''/data/add-ons directory might look like:
* ''userdata''/data/add-ons/MyCampaign/ - your campaign's directory
* ''userdata''/data/add-ons/MyCampaign/_main.cfg - a text file containing your instructions for the game about how to load the campaign
** ''userdata''/data/add-ons/MyCampaign/scenarios
** ''userdata''/data/add-ons/MyCampaign/units
** ''userdata''/data/add-ons/MyCampaign/images
** ''userdata''/data/add-ons/MyCampaign/music
** ''userdata''/data/add-ons/MyCampaign/sounds
** ''userdata''/data/add-ons/MyCampaign/utils

== See Also ==

* [[Create]]

[[Category:Create]]

EditingWesnoth

2013-02-14T04:58:22Z

Alarantalara: /* Mac OS X */

{{EditingWesnoth/Translations}}


== 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 should not modify these files, but you can if you want to modify a unit or something.

The user data directory holds your preferences file, custom maps, saved games, the WML cache and data files corresponding to user-created content. In this wiki, "user data" and ''userdata''/ refer to this directory.

The paths to the game data and user data directories vary according to the operating system and packager.

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

====Windows====

* ''X:\Program Files\Battle for Wesnoth <version>\data'', where X: corresponds to the drive where Windows is installed (normally C:).
* On 64-bit computers, it will be in ''X:\Program Files (x86)\Battle for Wesnoth <version>\data''.
* The path may be different if you originally chose to install the game in a different location. In such case, look for the data folder in the folder where you installed the game.

====Mac OS X====

* SourceForge.net bundle: Control+click on the application icon. Select "Show Package Contents." Select "Contents", then "Resources".
* Custom builds: ''/usr/local/share/wesnoth''

====Linux====

* Custom builds: ''/usr/local/share/wesnoth''
* Debian/Ubuntu packages, or emerge (Gentoo): ''/usr/share/games/wesnoth''
* Red Hat Linux-based distributions in general (openSUSE, Fedora): ''/usr/share/wesnoth''
* Mandriva: ''/usr/share/games/wesnoth''
* Slackware Linux: ''/usr/local/share/wesnoth''

In a terminal, the command <code>wesnoth --path</code> shows the game data directory.

====BSD====

* OpenBSD package: ''/usr/local/share/wesnoth''

The command <code>wesnoth --path</code> also works.

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

====Windows====

* Windows 2000/XP (1.8 and later): ''My Documents\My Games\Wesnoth1.8''
* Windows Vista/7 (1.8 and later): ''Documents\My Games\Wesnoth1.8''
* General (before 1.8): ''X:\Program Files\Battle for Wesnoth <version>\userdata'', where X: corresponds to the drive where Windows is installed (normally C:).

''Note: If you don't remember where you installed the game, right click on the game's shortcut, open properties, and click on the "Find target" button, then search for the "data" folder.''

''Note: If you chose "Store userdata in the install location" during installation you will find your userdata as mentioned above under "General". This will also apply if you launch wesnoth.exe directly instead of using the start menu shortcut.''

''Note: If your userdata folder is located in the install location (for the reasons mentioned above) and you are not an administrator on this machine Windows Vista/7 will silently redirect any write access to the so called Virtual Store. You can find your userdata folder in e.g. C:\Users\<yourname>\AppData\Local\VirtualStore\Program Files\Battle for Wesnoth <version>''

====Mac OS X====

* SourceForge.net bundle: ''~/Library/Application Support/Wesnoth_1.x/'' (1.8 and later), or ''~/Library/Preferences/Wesnoth'' (older versions). As of OS X 1.10.7, this location is hidden by default.
* Custom builds: same as Linux - see below for details.

====Linux====
* Wesnoth 1.10: ''~/.local/share/wesnoth/1.10''
* Wesnoth 1.9: ''~/.local/share/wesnoth/1.9''
* Wesnoth 1.8: ''~/.wesnoth1.8''
* Older versions: ''~/.wesnoth''

In a terminal, the command <code>wesnoth --config-path</code> shows the user data directory.

====BSD====
* Same place as Linux.

== Game Data ==

The major directories you need to know about are wesnoth/data, wesnoth/data/core/units, wesnoth/data/campaigns, wesnoth/data/multiplayer, wesnoth/images and wesnoth/data/core/images

Become familiar with what is in ./data/campaigns and ./data/multiplayer/scenarios. 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/core/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.

== User Data ==

The user data directory can do a lot of things. The game looks here for several things:
* ''userdata''/data/add-ons - campaign configuration files and subdirectories
* ''userdata''/editor/maps - multiplayer standalone maps (map data only)

The ''userdata''/data/add-ons 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.

For example, assume you have a campaign called MyCampaign. This is what the ''userdata''/data/add-ons directory might look like:
* ''userdata''/data/add-ons/MyCampaign/ - your campaign's directory
* ''userdata''/data/add-ons/MyCampaign/_main.cfg - a text file containing your instructions for the game about how to load the campaign
** ''userdata''/data/add-ons/MyCampaign/scenarios
** ''userdata''/data/add-ons/MyCampaign/units
** ''userdata''/data/add-ons/MyCampaign/images
** ''userdata''/data/add-ons/MyCampaign/music
** ''userdata''/data/add-ons/MyCampaign/sounds
** ''userdata''/data/add-ons/MyCampaign/utils

== See Also ==

* [[Create]]

[[Category:Create]]

Micro AIs

2012-12-27T04:09:04Z

Alarantalara: /* Recruiting Micro AI (ai_type=recruiting) */ Describe randomness parameter

Mirco AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. A Micro AI is activated and configured (or deleted) via the [micro_ai] tag, requiring only a few lines of WML code. Note that this is a new functionality and theat '''we are very much looking for feedback''' on bugs, new feature requests for the existing AIs or ideas for new Micro AIs.

Micro AIs are available in mainline Wesnoth '''starting from Version 1.11.2'''. Additional AIs that are still in an experimental stage are available in the ''AI Modification Demos'' add-on, which also might contain more advanced (development) versions of the mainline Micro AIs.

== A Few General Words about Micro AIs ==

* Micro AIs are meant to bring new specialized behavior to Wesnoth that cannot be achieved, at least not easily, by adjusting default AI parameters (such as those described at [[AiWML]]) or with WML code.

* Most Micro AIs in their default setting apply to all units of a side, although many of them provide parameters for filtering the units that should be affected by the new behavior. If the Micro AI is applied only to part of the units of a side, the other units follow the default Wesnoth AI behavior.

* By contrast, a few Micro AIs attach directly to a unit and only affect that unit's behavior. These are so-called [[Lua_AI_Howto#Behavior_.28Sticky.29_Candidate_Actions|Behavior Candidate Actions]] (BCAs). This type of Micro AI has an [[Micro_AIs#2._Activating_and_configuring_.28or_deleting.29_a_Micro_AI|ai_type=]] value ending in ''_unit'', in order to distinguish it from the side-wide Micro AIs.

=== Micro AI Test and Demo Scenarios ===

All Micro AIs described here can be checked out in a number of test and demo scenarios. Test scenarios can be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
This starts up a "switchboard scenario" in which you can select the Micro AI demonstration scenario you want to check out. Here, ''path/wesnoth-executable'' needs to be replaced by whatever the path and filename of the Wesnoth executable is on your system.

Another way to test the Micro AIs (as well as some other AIs still under development) is to download the ''AI Modification Demos'' add-on. All the test/demo scenarios are also available there.

== Setting up a Micro AI ==

Setting up a Micro AI is done in two simple steps:

==== 1. Enabling the Micro AI functionality in the [side] tag ====

The desired AI functionality needs to be enabled for a side before it can be used. This is done by including a single macro line inside the [side] tag, such as:
{MICRO_AI_HEALER_SUPPORT}
The exact macro name depends on the specific Micro AI and is given below for each AI. This macro must be put '''directly into the [side] tag''', it does not go inside an [ai] tag. This step does not yet activate the Micro AI, it simply sets up the desired functionality.

==== 2. Activating and configuring (or deleting) a 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]
All [micro_ai] tags must contain the following three (or four) required keys:
* '''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.
* '''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.
* '''id''': If the Micro AI attaches directly to a unit, rather than being side-wide, the id of the unit is also a required parameter.

Other keys may also be required depending on the Micro AI. In additional, a number of optional keys may be available to configure the AI behavior. See the following sections on the individual Micro AIs for details.

'''Notes:'''
* 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 (or four) required keys listed here.

* Some of the Micro AIs use and/or modify default AI components (candidate actions or aspects) when they are added, or reset these components to their default values when they are deleted. Thus, if you have modified the AI yourself using the default CAs or aspects, some of these modifications might be affected, or might be interfering with the Micro AI. The sections below indicate whether a Micro AI modifies any default AI components.

* It is currently not possible to combine different Micro AI types (AIs using different values of ai_type=) on the same side. In other words, you can use several guardians (and even different guardian types) on the same side (as they are all handled by the Guardian Micro AI), but it is not possible to put, for example, guardians and patrollers on the same side. This restriction will be lifted in an upcoming release. In the meantime, you will have to use different (allied) sides to accomplish this.

== Animals Micro AI (ai_type=animals) ==

The Animals Micro AIs are meant to simulate the behaviors of certain types of animals. They are, however, set up so that they can be used with arbitrary unit types and might be applicable in quite diverse situations. The AIs nevertheless remain named after the animals for which they were written originally, so that they are (to some extent) descriptive of their behavior.

Brief descriptions of the AI behaviors are given in the following subsections. To get a better feeling for their behavior, check out the "Animals", "Swarm", "Wolves" and "Dragon" scenarios from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]] or in the ''AI Modification Demos'' add-on. Note that some of the animal AIs are designed for animal types that do not exist in mainline. In the test scenario, other animal types are therefore substituted for them. If you want to see them with the animal types for which they were written, check out the ''AI Demos'' add-on.

Enable an 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 then used to select the desired animal AI.

=== Animals AI: Wolves (animal_type=wolves) ===

The Wolves Micro AI organizes all "wolf" units (predators) of the side to hunt in a single pack. They actively chase after the closest prey and try to corner it (not always super successfully), but are easily distracted by other prey coming into range, to the point where the pack splits up. The wolves can also be told to try to avoid other types of units (such as larger predators), except when they are going in for an attack. When no prey is left, the wolves wander randomly.

For a demonstration of the Wolves AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]] or in the ''AI Modification Demos'' add-on.

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28animal_type.3Dwolves_multipacks.29|Multipack Wolves]], which distributes the wolves of a side into several packs, rather than all of them into one single pack as it is done here.

You can configure the Wolves Micro AI by using the following keys in the [micro_ai] tag:

'''Required keys:'''

* '''animal_type''': Must be "wolves".
* '''[predators]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units
* '''[prey]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units

'''Optional keys:'''

* '''avoid_type''': Comma-separated list of unit types which the wolves try to avoid

'''Note:''' The Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|attacks aspect]].

Here's an example of a wolves [micro_ai] tag usage from the "Animals" test scenario:
[micro_ai]
side=6
ai_type=animals
action=add

animal_type=wolves
[predators]
type=Wolf
[/predators]
[prey]
type=Deer
[/prey]
avoid_type=Yeti,Giant Spider,Tarantula,Bear,Dog
[/micro_ai]

=== Animals AI: Multi-pack Wolves (animal_type=wolves_multipacks) ===

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28animal_type.3Dwolves.29|Wolves Micro AI]] in that there can be an arbitrary number of wolf packs, with the pack size being a free parameter. At the beginning of the scenario, close wolves are grouped into packs in a semi-methodical way. If the wolves are put on the map in distinct groups of close wolves of the correct number, they will be joined into packs matching these groups. If, on the other hand, they are spread out all over the map, the method of assigning them to packs is semi-random.

Wolves of the same pack begin by joining each other on the map. After that, they stay together until only one wolf is left, which then tries to join up with an incomplete pack or with other single wolves. Individual wolves entering the map during the scenario behave in that way as well.

A second difference to the other Wolves AI is that wolves do not actively hunt here. For the most part they just wander (often long distance). However, the pack ferociously (and without regard for its own health) attacks any enemy units that come into range, as long as that does not mean separating the pack by more than a few hexes. Staying together, or joining with a new wolf assigned to the pack, is the only thing that takes priority over satisfying the wolves' thirst for blood.

For a demonstration of the Multi-pack Wolves AI behavior, check out the "Wolves" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]] or in the ''AI Modification Demos'' add-on.

You can configure the Multi-pack Wolves Micro AI by using the following keys in the [micro_ai] tag:

'''Required keys:'''

* '''animal_type''': Must be "wolves_multipacks".

'''Optional keys:'''

* '''type'''=Wolf: Comma-separated list of the unit types which the AI controls. The default value is "Wolf".
* '''pack_size'''=3: (integer) The size of the packs.
* '''show_pack_number'''=no: If set to "yes", the wolves' pack numbers will be shown below them.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" test scenario:
[micro_ai]
side=2
ai_type=animals
action=add

animal_type=wolves_multipacks
show_pack_number=yes
pack_size=4
[/micro_ai]

=== Animals AI: Big Animals (animal_type=big_animals) ===

The Big Animals Micro AI is a simulation of large predators that wander and hunt alone, such as Bears, Giant Spiders or Yetis. For the most part, these just wander on the terrain that's been defined for them, but they attack enemy units if those happen to come into range. The AI can be set up so that the Big Animals stay out of the way of other units (such as other large predators), in which case they only attack those if cornered.

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]] or in the ''AI Modification Demos'' add-on.

You can configure the Big Animals Micro AI by using the following keys in the [micro_ai] tag:

'''Required keys:'''

* '''animal_type''': Must be "big_animals"
* '''[big_animals]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied.

'''Optional keys:'''

* '''[goal_terrain]''': The big animals often go for long distance (multi-turn) wanders. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next wander goal is chosen. The default is all terrain on the map.
* '''[wander_terrain]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. Note that the condition that this must be enemy units is added by the AI automatically and does not need to be included in the filter.

Here's an example of a Big Animals [micro_ai] tag usage from the "Animals" test scenario:
[micro_ai]
side=3
ai_type=animals
action=add

animal_type=big_animals
[big_animals]
type=Bear
[/big_animals]
[avoid_unit]
type=Yeti,Giant Spider,Tarantula,Bear,Dog
[/avoid_unit]
[goal_terrain]
x=1-40
y=1-18
[not]
terrain=*^X*,Wo
[/not]
[/goal_terrain]
[wander_terrain]
terrain=*
[/wander_terrain]
[/micro_ai]

=== Animals AI: Forest Animals (animal_type=forest_animals) ===

* '''forest_animals''': This AI controls a set of animals: tuskers, tusklets, rabbits.

* '''rabbits_number''': The number of rabbits to be on the map.
* '''radius''': Rabbits won't spawn in holes that aren't more than radius hexes away from enemies.
* '''rabbit_hole''': The image/halo of the rabbit hole item.
* '''[move_filter]''': The terrain the animals prefer to move on. This is a [[StandardLocationFilter|Standard Location Filter]].
* '''rabbit_type''': The unit types that should behave as rabbits.
* '''tusker_type''': The unit types that should behave as tuskers.
* '''tusklet_type''': The unit types that should behave as tusklets.
* '''other_types''': The unit types that should behave as deers.

=== Animals AI: Herd and Herders (animal_type=herding) ===

* '''herding''': this AI controls both the sheep and the dogs of a side. The dogs keep the sheep in a herd. This AI only requires the animal_type key in addition to the needed [micro_ai] keys.

* '''[herd]''': The units that are being herded. This is a [[StandardUnitFilter|Standard Unit Filter]].
* '''[herders]''': The units that are herding. This is a [[StandardLocationFilter|Standard Location Filter]].
* '''herd_x,herd_y''': The coordinate of the (approximate) herding area center.
* '''[herder_area]''': The terrain of which the herders prefer. This is a [[StandardLocationFilter|Standard Location Filter]].

'''Optional keys:'''
* '''attention_distance'''=8: (integer) The radius within which enemies must be to attract the attention of the herders.
* '''attack_distance'''=4: (integer) The radius within which enemies must be to be attacked by the herders.

=== Animals AI: Hunter (animal_type=hunter_unit) ===

* '''hunter_unit''': hunts in a specific area, then stays home for a specified time/until fully healed. This AI attaches to a unit, rather than controlling all units of a side.

Required keys:
* '''id''': The ID of the unit to which this AI should be applied.
* '''animal_type''': This has to be "hunter_unit" (without quotation marks) if you want a hunter_unit 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".

Optional keys:
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase

=== Animals AI: Swarm (animal_type=swarm) ===

The Swarm Micro AI uses some very simply algorithms to simulate animal swarm behavior. Without adjacent enemies, they simply do a random move, trying to stay together and at a certain distance from enemies. However, if an enemy unit is close to any bat, the swarm scatters. This is particular fun to watch when one places an enemy unit in the middle of the swarm. After being scattered, the swarm members slowly rejoin, but not in a very organized way. Sub-swarms or individual bats might roam around for quite some time before they find their way back. It is also possible that individual bats (or small groups) split off from the larger swarm at times.

For a demonstration of the Swarm AI behavior, check out the "Swarm" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]] or in the ''AI Modification Demos'' add-on.

You can configure the Swarm Micro AI by using the following keys in the [micro_ai] tag:

'''Required keys:'''

* '''animal_type''': Must be 'swarm'.

'''Optional keys:'''

* '''scatter_distance'''=3: (int) Enemies within "scatter_distance" hexes of any swarm unit cause the swarm to scatter, by each unit trying to maximize its individual distance from the enemy.
* '''enemy_distance'''=5: (int) The minimum distance kept between units of the swarm and enemies when the swarm moves as a whole.
* '''vision_distance'''=12: (int) Only units within this distance follow the overall swarm motion (either away from an enemy or of the swarm as a whole). The smaller this value is set, the less likely the swarm is to stay together or rejoin. This parameter is meant to simulate how far an individual member of the swarm can see, meaning that the swarm is "out of sight" (and the unit will not be able to follow it) if it is more than this distance away.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" test scenario:
[micro_ai]
side=2
ai_type=animals
action=add

animal_type=swarm
[/micro_ai]

== Bottleneck Defense Micro AI (ai_type=bottleneck_defense) ==

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 the "Bottleneck" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]] or in the ''AI Modification Demos'' add-on.

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 (can 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.

* '''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).

As an example, in the "Bottleneck" scenario of the test scenario, 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 by using the following keys settings (check out the scenario to see which hex is which):
[micro_ai]
side=1
ai_type=bottleneck_defense
action=add

x=14,14,14
y= 7, 9, 8
enemy_x=13,13
enemy_y= 8, 9

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]

== Guardian Micro AI (ai_type=guardian_unit) ==
The Guardian Micro AI attaches to an individual unit and can be used to set up different kind of guardian behaviors. Three different types of guardians are available and are described below.

Multiple guardian units can be used on the same side, by setting up a separate [micro_ai] tag for each unit.

For a demonstration of several different guardian behaviors, check out the "Guardians" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]] or in the ''AI Modification Demos'' add-on.

Enable the Guardians Micro AI by putting
{MICRO_AI_GUARDIAN}
into the [side] tag and configure it by using
ai_type=guardian_unit
in the [micro_ai] tag. The ''guardian_type='' key also needs to be set, as shown in the following.

=== Return Guardian (guardian_type=return_guardian) ===

A 'return guardian' is a variation of the standard Wesnoth guardian. It has an assigned guard position (GP) to which it returns after attacks on approaching enemies:
* If at GP with no enemy in reach, do nothing.
* If at GP with an enemy in reach, attack (note that the attack is done by default AI, which might result in the guardian not attacking if the enemy is deemed too strong).
* If not at GP, return there, no matter whether an enemy is in reach or not.
* If enemies are blocking the way back to GP, do your best to move around them.
* If the guardian ends up next to an enemy on the way back, attack that enemy after the move.

You can configure each return guardian using the following keys in the [micro_ai] tag:

'''Required keys:'''

* '''guardian_type''': Must be set to "return_guardian"
* '''id''': The ID of the unit to which this AI should be attached
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack

'''Optional keys:'''

There are no optional keys.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" test scenario:
[micro_ai]
side=2
ai_type=guardian_unit
action=add

guardian_type=return_guardian
id=return1
return_x,return_y=20,2
[/micro_ai]

===Stationed Guardian (guardian_type=stationed_guardian) ===

A 'stationed guardian' is another variation of the standard Wesnoth guardian with a somewhat more complex behavior than that of the 'return guardian'. Two positions are defined for it, a 'station' and a 'guarded location', as well as a distance. The behavior is as follows:
* If no enemy is within 'distance' of the guard's current position, do nothing. This is independent of the guardian being at its station or not.
* Otherwise: If an enemy is within 'distance' of the guard, but not also within the same distance of the guarded location and the station (all of this simultaneously), move the guard in the direction of the station.
* Otherwise:
** Pick the enemy unit that is closest to the guarded location.
** If we can reach it, pick the adjacent hex with the highest defense rating and attack from there.
** If not in reach, move toward this unit.

You can configure each stationed guardian using the following keys in the [micro_ai] tag:

'''Required keys:'''

* '''guardian_type''': Must be "stationed_guardian"
* '''id''': The ID of the unit to which this AI should be attached
* '''distance''': The distance parameter as explained above
* '''station_x,station_y''': The x and y position of the hex that serves as the guardians station.
* '''guard_x, guard_y''': The x and y position of the guarded location.

'''Optional keys:'''

There are no optional keys.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" test scenario:
[micro_ai]
side=2
ai_type=guardian_unit
action=add

guardian_type=stationed_guardian
id=stationed1
distance=4
station_x,station_y=2,14
guard_x,guard_y=3,13
[/micro_ai]

=== Coward (guardian_type=coward) ===

Cowards are units that, like guardians, sit around doing nothing until an enemy comes into range. Unlike guardians, however, they run away once enemies approach. Applications might be wild animals, unarmed civilians getting in the way of a battle, etc. The coward macro can be called with two optional locations, 'seek' and 'avoid':
* If neither is given, the coward retreats to the position farthest away from the approaching enemies.
* If 'seek' is given, it preferentially goes toward that location (but getting away from enemies takes priority).
* If 'avoid' is given, it in addition tries to avoid that location (with both maximizing distance from enemies and going toward 'seek' taking priority).
* Both 'seek' and 'avoid' may consist of only one coordinate ('x' or 'y'), in which case not a single hex, but a line of hexes is sought or avoided.

You can configure each coward using the following keys in the [micro_ai] tag:

'''Required keys:'''

* '''guardian_type''': Must be "coward"
* '''id''': The ID of the unit to which this AI should be attached
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''seek_x, seek_y''': The x and y coordinate of the hex to seek
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid

Here's an example of a coward [micro_ai] tag usage from the "Guardians" test scenario:
[micro_ai]
side=2
ai_type=guardian_unit
action=add

guardian_type=coward
id=coward3
distance=5
seek_x,seek_y=24,5
avoid_x,avoid_y=24,15
[/micro_ai]

== Healer Support Micro AI (ai_type=healer_support) ==

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. Note that it is not always better to use this Micro AI than the default AI, as it takes healers (which can be strong units) away from the pool of units to choose for attacks.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]] or in the ''AI Modification Demos'' add-on.

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

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''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: (boolean) If set to 'yes', 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.

'''Note:''' The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|attacks aspect]].

This is an example of a Healer Support Micro AI configuration:
[micro_ai]
side=2
ai_type=healer_support
action=add

aggression=0
[/micro_ai]

== Lurkers Micro AI (ai_type=lurkers) ==

The Lurker Micro AI controls some or all units of a side in "lurker mode". A lurker is a unit that is capable of moving across most terrains, but that only stops on and attacks from specific terrain. It might also have the ability to hide on this terrain (which is the reason why it is called a lurker).

Lurkers move individually without strategy and always attack the weakest enemy within their reach. If no enemy is in reach, the lurker does a random move instead - or it just sits and waits (lurks).

For a demonstration of different types of lurker behavior, check out the "Lurkers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]] or in the ''AI Modification Demos'' add-on.

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

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

'''Required keys:'''
* '''[lurkers]''': Specifies which units of the side are controlled by the Lurker Micro AI. This is a [[StandardUnitFilter|Standard Unit Filter]].
* '''[attack_terrain]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''Optional keys:'''
* '''[wander_terrain]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [wander_terrain] is not given, it defaults to [attack_terrain].
* '''stationary'''=no: (boolean) If set to yes, a lurker never moves if there is no enemy within attack range.

Here's an example of [micro_ai] tag usage from the "Lurkers" test scenario:
[micro_ai]
side=4
ai_type=lurkers
action=add

[lurkers]
type=Naga Fighter
[/lurkers]
[attack_terrain]
terrain=W*,S*
[/attack_terrain]
[wander_terrain]
terrain=W*
[/wander_terrain]
[/micro_ai]

== Messenger Escort Micro AI (ai_type=messenger_escort) ==

The Messenger Escort Micro AI lets you define a set of waypoints through which it tries to move one of its units, the messenger. The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that the messenger might not strictly hit intermediate waypoints, but that getting close is good enough, especially if a waypoint is occupied by an enemy unit. It does, however, always try to get to the last waypoint.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]] or in the ''AI Modification Demos'' add-on.

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 of the side protect the messenger.
* '''waypoint_x,waypoint_y''': Comma-separated list of waypoint coordinates through which the messenger will go in the given order to reach its goal, given by the last coordinate. If you want the messenger to go directly to the goal, simply enter a single x,y coordinate here. Note that the messenger does not have to hit each waypoint exactly (except for the final one), getting close to them is good enough.

'''Optional keys:'''

* '''enemy_death_chance'''=0.67 and '''messenger_death_chance'''=0.0: (both floats; ranging from 0 to 1) If the messenger is adjacent to an enemy at the end of the move, it will only attack the enemy if the chance of death of the enemy is >= enemy_death_chance and if the messenger's chance of death is <= messenger_death_chance (or if it is an attack at a range for which the enemy does not have a weapon).

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

id=messenger
waypoint_x=31,24,27,28
waypoint_y=20,14,7,1
[/micro_ai]

== Patrol Micro AI (ai_type=patrol_unit) ==

The Patrol Micro AI attaches to an individual unit and defines a number of waypoints for that unit to follow. Options can be set whether the route should be followed in a loop, as an out-and back, only once, whether units encountered along the way should be attacked, etc.

No matter what options are chosen, getting to the next waypoint always takes priority over attacking for a patroller. The AI thus prefers to move the patrol unit around enemies rather than straight for them. Also, if a waypoint is occupied by a unit the AI is not instructed to attack, it will (eventually) abandon that waypoint once it gets close enough and move on to the next one.

Multiple patrol units can be used on the same side, by setting up a separate [micro_ai] tag for each unit.

For a demonstration of several different patrol behaviors, check out the "Patrols" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]] or in the ''AI Modification Demos'' add-on.

Enable the Patrol Micro AI by putting
{MICRO_AI_PATROL}
into the [side] tag and configure it by using
ai_type=patrol_unit
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 unit.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order).

'''Optional keys:'''

* '''out_and_back'''=no: (boolean) By default, a patrol unit returns to the first waypoint after reaching the last, doing the patrol route as a loop. If this parameter is set to 'yes', the unit instead reverses its course and perpetually does out and backs of the route.
* '''one_time_only'''=no: (boolean) If set to 'yes', the unit goes through the patrol route only once and then hangs out at the last waypoint. It also always attacks any enemy unit on the last waypoint, independent of what ''attack='' is set to.
* '''attack''': By default (if this key is not set), the patrol unit attacks any unit it ends up next to after a move. Alternatively, this parameter can be set to a comma-separated list of unit ids. If that is done, the patrol only attacks these units when it ends up next to them and ignores any other unit. This can in turn be used to have the patroller not attack at all, by setting ''attack='' to a non-existing id.

Here's an example of [micro_ai] tag usage from the "Patrols" test scenario:
[micro_ai]
side=2
ai_type=patrol_unit
action=add

id=Konrad
waypoint_x=9,24,25
waypoint_y=21,23,15
one_time_only=yes
attack=Gertburt
[/micro_ai]

== Protect Unit Micro AI (ai_type=protect_unit) ==

The Protect Unit Micro AI tries to move one or several units to a given location while keeping them safe from enem attacks. It does so by keeping the protected units away from enemy units and close to friendly units. Other units on the AI side are controlled by the default Wesnoth AI.

For a demonstration, check out the "Protect Unit" and "The Elves Besieged" scenarios from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]] or in the ''AI Modification Demos'' add-on.

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:'''

* '''[unit]''': A separate [unit] tag is required for each protected unit(s). Each tag has required keys id=, goal_x=, goal_y= for each unit, as shown in the example below.

'''Optional keys:'''

* '''disable_move_leader_to_keep'''=no: (boolean) If set to 'yes', side leaders protected by this AI do not try to return to their keep. This is necessary for this Micro AI to work with units that are side leaders and that are supposed to move to an off-keep location.

'''Note:''' The Protect Unit Micro AI modifies the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[AiWML#Evaluating_AI_Moves_--_Candidate_Actions_.28CAs.29|move leader to keep candidate action]].

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

[unit]
id=Delfador
goal_x,goal_y=1,2
[/unit]
[unit]
id=Konrad
goal_x,goal_y=1,1
[/unit]

disable_move_leader_to_keep=true
[/micro_ai]

== Recruiting Micro AI (ai_type=recruiting) ==

The Recruiting Micro AI replaces the default recruitment AI by alternative recruiting patterns. Currently there are two recruiting algorithms you can choose from, random recruiting and the rush recruiting used in the new (as of Version 1.11.1) Experimental AI (see below).

For a demonstration of a different recruiting pattern, check out the "Recruiting" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]] or in the ''AI Modification Demos'' add-on. You can also explore the unit choices by watching the Experimental AI in a multiplayer game.

Enable the Recruiting Micro AI by putting
{MICRO_AI_RECRUITING}
into the [side] tag and configure it by using
ai_type=recruiting
in the [micro_ai] tag.

=== Random Recruitment AI (recruiting_type=random) ===

This AI randomly selects a unit type from the recruitment list of the side. The probability of choosing each type and the behavior in low-gold situations can be influenced with optional parameters.

'''Required keys:'''

* '''recruiting_type''': Must be "random"

'''Optional keys:'''

* '''[probability]''': This tag sets the probability of selecting the given unit type. It has two required sub-keys:
** '''type''': comma-separated list of unit types to which this probability is to be applied
** '''probability''': (non-negative float) The probability with which these unit types is to be selected. All unit types for which no [probability] tag is defined receive a default probability of 1.0, thus values should be chosen relative to that. As an example, in the code below swordsmen and peasants are given a probability of 8, while no other units have assigned probabilities. Thus, each of these two unit types is 8 times more likely to be selected than any other individual unit type.
* '''skip_low_gold_recruit'''=no: (boolean) By default, the random recruitment AI chooses a unit to recruit only from those types for which it has sufficient gold. If this parameter is set to 'yes', it will instead choose from all available unit types and end recruiting for the turn if there is not enough gold to recruit it this turn (even if other, affordable unit types exist).

Here's an example of a random recruiting [micro_ai] tag usage from the "Recruiting" test scenario:

[micro_ai]
side=1
ai_type=recruiting
action=add

recruiting_type=random
[probability]
type=Swordsman,Peasant
probability=8
[/probability]

skip_low_gold_recruiting=yes
[/micro_ai]

=== Rush Recruitment AI (recruiting_type=rushers) ===

This AI replaces the default recruiting with the rush recruiting used in the new (as of Version 1.11.1) Experimental AI.

'''Required keys:'''

* '''recruiting_type''': Must be "rushers"

'''Optional keys:'''

* '''randomness'''=0.1: (number) A random number is applied to the rusher recruit engine's score to prevent the recruitment pattern from being too predictable. 0 causes no randomness to be applied, while larger numbers increase the random effect. A value of 1-2 generates results in which the random effect is approximately equal to the scored effect. Extremely high values are essentially entirely random.

Rush recruiting is set up like this:
[micro_ai]
side=1
ai_type=recruiting
action=add

recruiting_type=rushers
[/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)
* Orderly retreat

[[Category:AI]]

LuaAI

2012-12-10T17:32:57Z

Alarantalara: /* Behavior(sticky) candidate actions */ Add note on limitation of BCAs

This is a page containing information on configuring the AI using Lua. In addition to the technical information on this page, a tutorial-style guide is also available at [[Lua AI Howto]].

NB: previous contents of the page moved to http://wiki.wesnoth.org/LuaAI(old)

== Aspects ==
Patch r49721 enabled users to write aspects using Lua. This simplifies the definition of aspects that are meant to change depending on the game state. A good example could be aggression, which changes depending on the time of the day(since ToD affects the actual battle performance of your forces). 
Static aggression:
[aspect]
id="aggression"
engine="lua"
value="0.3"
[/aspect]
Dynamic aggression:
[aspect]
id=aggression
engine=lua

code=<<
wesnoth.fire("store_time_of_day")
local value = 0
tod = tostring(wesnoth.get_variable('time_of_day').name)
if (tod == 'Morning') then
value = 0.2
else
value = 1
end

wesnoth.fire("clear_variable", {name = "time_of_day"})
return value
>>
[/aspect]

Note: the way of getting the ToD is hacky here, but I will create a more elegant method soon(Nephro). 
Also note the difference between 'code' and 'value' attributes, this is important. 
At the moment, it is possible to create the following aspects using Lua(the list will be constantly updated):
aggression // double
attack_depth // int
avoid // exposed as map_location[], where map_location is a table of form {x, y}
caution // double
grouping // string
leader_aggression // double
leader_goal // exposed as a config
leader_value // double
number_of_possible_recruits_to_force_recruit // double
passive_leader // bool
passive_leader_shares_keep // bool
recruitment_ignore_bad_combat // bool
recruitment_ignore_bad_movement // bool
recruitment_pattern // string[]
scout_village_targeting // double
simple_targeting // bool
support_villages // bool
village_value // double
villages_per_scout // int

Note: simple numeric, bool and string aspect creation can be enabled just by adding a specific factory to registry.cpp, this will also soon be done.

To get the value of a specific aspect in Lua we have to use the
ai.get_<aspect_name>()
function. E.g.
local aggression = ai.get_aggression()

== Preload event ==

It is a good idea to have such a preload event in your scenario if you are intending to use Lua for AI programming or customizing. The code of this event will most probably be moved out to a macro(except for the line that requires patrol.lua, since it is not necessary).

[event]
name=preload
first_time_only=no
[lua]
code = <<
H = wesnoth.require "lua/helper.lua"
W = H.set_wml_action_metatable {}
_ = wesnoth.textdomain "my-campaign"
ai = {}
ca_counter = 0

H.set_wml_var_metatable(_G)

wesnoth.require("ai/lua/patrol.lua")

>>
[/lua]
[/event]

The code attribute can be further expanded by any Lua code needed. For example, we can set up some global variables there or include additional code libraries("wesnoth.require("ai/lua/patrol.lua")" - includes code that handles patrolling of units).

== Engine code ==

In the engine tag you should define functions that will handle evaluation and execution of your custom candidate actions and stages. You can also run some code that is intended to be run once in the beginning. 
The definition of the [engine] tag should be place inside the [ai] tag.

[engine]
name="lua"
code= <<
-- your engine code here
>>
[/engine]

== Stages ==
Once the engine has been set up, we can start adding stages to the configuration of our AI. 
To add a stage we just use the [stage] tag.
[stage]
engine=lua
code=<<
-- Code for stage execution here
-- It is better to call predefined functions for the [engine] code,
-- than to define the functions here, to keep the structure of the stages clear
>>
[/stage]

== Candidate actions ==
This is an example from the current version of the lua_ai arena. The stage with an id "ca_loop" is the RCA AI loop stage, as we can see from its name. Currently it has two candidate actions, both Lua backed.

[stage]
name=testing_ai_default::candidate_action_evaluation_loop
id=ca_loop
[candidate_action]
engine=lua
name=first
id=firstca
evaluation="return (...):candidate_action_evaluation_hello()"
execution="local ai, cfg = ...; ai:candidate_action_execution_hello(cfg)"
[/candidate_action]
[candidate_action]
engine=lua
name=second
evaluation="return (...):candidate_action_evaluation_hello2()"
execution="(...):candidate_action_execution_hello2()"
[/candidate_action]
[/stage]
Basically, we need to have an engine attribute, an evaluation and execution functions. The syntax (...):foo() means "call eng.foo(eng) where eng is whatever the engine code returns". We can also add, remove, modify candidate actions on the fly, using wesnoth.wml_actions.modify_ai() functionality. Behavior(sticky) candidate actions use this approach.

== Behavior(sticky) candidate actions ==
Sometimes we need a specific unit to do a specific action in our scenario, e.g. we want a scout unit to patrol between 3 places on the map, to provide us with visibility needed. In this case we can create a sticky candidate action that will tie itself to the unit, and remove itself when the unit has died. The syntax for defining a sticky candidate action is the following:
[event]
name=side 2 turn 1
first_time_only=yes
[add_ai_behavior]
side=2
[filter]
name="Rark"
[/filter]
sticky=yes
loop_id=ca_loop
evaluation="return patrol_eval_rark()"
execution="patrol_rark()"
[/add_ai_behavior]
[/event]
Here the behavior CA is added to the configuration of the AI when the event triggers. Obviously this will happen when side 2 gets its first turn, but the event can be whatever needed. The definition is very similar to a simple candidate action, but here we also filter out a unit and state that we want the behavior to be sticky. If we don't, the action will not try to remove itself, when the unit gets killed, and this could cause errors. 
Such CAs can also be added from inside other CA or stage code using wesnoth.wml_actions.add_ai_behavior(cfg) function.

Sticky candidate actions never execute more than once per turn. Therefore, if the action consists of a series of goals, the CA must evaluate and execute each goal as it is achieved within itself and not rely on being called multiple times.

== Behavior function library ==
Behaviors are defined using generators. A behavior generator receives arguments(unit info, configuration, etc) and returns a pair of functions: evaluator and executor. These functions are to be passed to the add_ai_behavior tag, or directly to the function.
=== Patrolling ===
The only behavior defined at the moment is the patrol behavior. After calling patrol_gen(name, locations), we receive a pair of functions to use for creation of candidate actions 
Inclusion of the patrolling code:
wesnoth.require("ai/lua/patrol.lua")
Usage:
local patrol_rark = patrol_gen("Rark", {{x=14, y=7}, {x=15, y=7}, {x=15, y=8}, {x=14, y=8}})
-- patrol_rark.exec -- execution function
-- patrol_rark.eval -- evaluation function
As you can see, the first argument is the name of the unit, the second is a table of coordinates of arbitrary length.

==Goals and targets==

When deciding what move to do next, the AI uses targets(markers on the map, pointing to villages, units, locations, etc). Targets are produced by goal objects. There are multiple predefined goal objects of different types in the C++ implementation, but now it is possible to define goal objects in Lua.

[goal]
name=lua_goal
value=6
engine=lua
code = <<
local t = {
t[1] = {value=2.3, type=3, loc={x=5, y=6} }
t[2] = {value=2.4, type=4, loc={x=4, y=16} }
}
return t
>>
[/goal]

As you can see, the return value must be a table containing 0 or more targets. Each target must contain the three fields: "loc", "type", "value". This code will then be parsed by the Lua engine and the targets will be available to use to any engine desired. To get the targets inside Lua, a simple
local tg = ai.get_targets()
must be called. tg will contain a table of the same format, as one described in the goal definition code upper.

== Persistence ==

If you need to store some data between save/load routines, you probably need a place to store the data. For this purpose, a field named "data" is automatically added to the return value of your engine code. The save routine will find this field, convert it to a config and store its content in readable format. When the scenario gets loaded back, the engine code will inject the data back in the AI context. All other data will be lost. Note that all content of "data" needs to be in WML table format, otherwise it will not be saved.

== Debug access to the AI tree ==

wesnoth.debug_ai(side)
-- has been added. The function only works in debug mode and returns a table containing the component tree of the active AI for a side, the engine functions and the accessor to the ai.* table of the LuaAI Also allows the user to execute stages and evaluate/execute candidate actions(eval and exec can be run independently).

Structure of the table(example):

{
stage_hello = function: 0x6dc24c0,
get_ai = function: 0x6dc25d0,
data = {
},
do_moves = function: 0x6dc2590,
candidate_action_evaluation_hello = function: 0x6dc2560,
candidate_action_evaluation_hello2 = function: 0x6dc2640,
components = {
id = "",
stage = {
another_stage = {
name = "another_stage",
id = "",
exec = function: 0x17cd3bb,
engine = "lua",
stg_ptr = "userdata: 0x7c5a8d0"
},
testing_ai_default::candidate_action_evaluation_loop = {
name = "testing_ai_default::candidate_action_evaluation_loop",
candidate_action = {
external = {
name = "external",
id = "",
exec = function: 0x17cd2f3,
engine = "lua",
ca_ptr = "userdata: 0x6fb3600"
},
second = {
name = "second",
id = "",
exec = function: 0x17cd2f3,
engine = "lua",
ca_ptr = "userdata: 0x6fb2f50"
}
},
id = "ca_loop",
exec = function: 0x17cd3bb,
engine = "",
stg_ptr = "userdata: 0x6fb2728"
}
},
engine = "",
name = ""
},
candidate_action_execution_hello2 = function: 0x6dc2670,
candidate_action_execution_hello = function: 0x6dc2530
}

The fields described as " name = function: 0xXXXXXXXX" are functions and can be called to using the usual function call syntax of Lua.
wesnoth.debug_ai(2).get_ai() -- will return the AI table of the Lua AI context.

wesnoth.debug_ai(2).stage[another_stage].exec() -- will execute the stage.

wesnoth.debug_ai(2).get_ai().get_aggression() -- will the return the current value of the aggression aspect of the AI

Therefore, we have up-to-date access to the whole AI, including the data segment.

NB!: the back-end of this function will be refactored quite drastically and that may involve usage syntax changes. This shouldn't be a big problem, since this function is only used for debugging and won't work in non-debug mode. If something suddenly stops working for you, come back to this page and watch the updates.

[[Category:AI]]

Download

2012-12-09T16:22:16Z

Alarantalara: /* Mac OS X (10.5+) */

{{Download/Translations}}
Welcome to the Battle for Wesnoth downloads page. The BFW project team only officially releases the source code. Binary packages are only provided by community volunteers and hosted here. Torrents are also unofficial.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS.2C_etc..5D.3F|FAQ]].

__NOTOC__
Jump to: [[Download#Stable_.281.10_branch.29|Stable Branch]] | [[Download#Stable_.28older_versions.29|Stable Branch (older versions)]] | [[Download#Development_.281.11_branch.29|Development Branch]]

== Stable (1.10 branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.10 branch is compatible to each other.

Version 1.10.5 is the latest stable version. This version is recommended for most players since the 1.10 online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.5/wesnoth-1.10.5.tar.bz2/download Current Version] (1.10.5, 327.7 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10.4.tar.bz2/download Previous Version] (1.10.4, 326.8 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.5/wesnoth-1.10.5-win32.exe/download Current Version] (1.10.5, 301.2 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10.4-win32.exe/download Previous Version] (1.10.4, 300.6 MB)

==== Mac OS X (10.5+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.5/Wesnoth_1.10.5.dmg/download Current Version] (1.10.5 328.8 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/Wesnoth_1.10.4.dmg/download Previous Version] (1.10.4 328.1 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.5/wesnoth-1.10.5-1.pnd/download Current Version] (1.10.5-1, 320.5 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10.4-1.pnd/download Previous Version] (1.10.4-1, 319.7 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.5/wesnoth-1.10.5.tar.bz2.md5/download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Stable_Version_1.10.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== Stable (older versions) ==
Several operating systems do not offer a binary of the latest stable release. Here is a list of the latest known (stable version) binaries for various systems. For those older versions there often is no (official) multiplayer or addon server available anymore.

==== AmigaOS4 ====
* [http://www.amigasoft.net/pages/games/download/Wesnoth186.lha.lzh Older Version] (1.8.6, 300MB)

==== (Open)Solaris ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.4/wesnoth-1.4.5/wesnoth-solaris-i386-1.4.5.pkg.bz2/download Older Version] (1.4.5, 145.6 MB), not compatible with 1.6.x

==== OS/2 & eComStation ====
* [http://download.smedley.info/wesnoth-1.4.5-os2-20080828.zip Older Version] (1.4.5, 160 MB), not compatible with 1.6.x

==== RISC OS ====
*[http://www.riscos.info/packages/arm/Games/wesnoth_1.4.5-1.zip Older version] (1.4.5-1, 140MB), not compatible with 1.6.x

==== Syllable ====
* [http://downloads.syllable.org/Syllable/i586/applications/contributed/Battle-for-Wesnoth/Battle-for-Wesnoth-1.2.6.application Older Version] (1.2.6, 60.8 MB), not compatible with 1.6.x

== Development (1.11 branch) ==
Version 1.11.x is the latest development version, boasting updated graphics and new exciting features. However, there may be occasional bugs or performance problems in the development versions since heavy changes are taking place all the time. For balanced and stable gaming, it is recommended you use the latest version of the 1.10.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth. People familiar with SVN and compiling can follow the latest development by checking [[WesnothSVN]].

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.1/wesnoth-1.11.1.tar.bz2/download Current Version] (1.11.1, 338.8 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.0/wesnoth-1.11.0.tar.bz2/download Previous Version] (1.11.0, 334.1 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.1/wesnoth-1.11.1-win32.exe/download Current Version] (1.11.1, 312.0 MB))
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.0/wesnoth-1.11.0-win32.exe/download Previous Version] (1.11.0, 307.8 MB))

==== Mac OS X (10.5+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.1/Wesnoth_1.11.1a.dmg/download Current Version] (1.11.1 338.9 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.0/Wesnoth_1.11.0.dmg/download Previous Version] (1.11.0 334.4 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.1/wesnoth-1.11.1-1.pnd/download Current Version] (1.11.1-1, 330.3 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.0/wesnoth-1.11.0-1.pnd/download Previous Version] (1.11.0-1, 326.2 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.1/wesnoth-1.11.1.tar.bz2.md5/download md5sum for current source code]
* [http://wiki.wesnoth.org/Download_Xdeltas#Development_Version_1.11.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]
* [http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/wesnoth_compile_mac_1.9.zip/download MacCompileStuff for 1.9]

== License ==
''Main article: [[Wesnoth:Copyrights]]

This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org Free Software Foundation].
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== UMC Editor ==
This is available with Wesnoth 1.9.x and greater (including Wesnoth 1.10.x).
Details and installation steps can be found at: http://eclipse.wesnoth.org

== See also ==
* [http://changelog.wesnoth.org Changelog]
* [[WesnothBinaries| More binaries]]
* [[WesnothSVN]] - bleeding edge version from SVN

[[Category:Building and Installing]]

Machine Learning Recruiter

2012-12-08T15:19:26Z

Alarantalara: Add AI category

This page documents the new machine learning recruiter submitted as a patch for Wesnoth 1.11.0. We describe how to run it, discuss experiments showing that the ML Recruiter achieves dramatically better performance than the RCA AI recruiter, describe known issues and suggest a development road map.

Note that the ML Recruiter is a work in progress. We welcome feedback on it. Please discuss it on the thread "Machine Learning Recruiter" at http://forums.wesnoth.org/viewtopic.php?f=10&t=36642.

=Why include ML Recruiter in Wesnoth?=

The ML Recruiter makes use of a small subset of the [http://waffles.sourceforge.net/ Waffles] Machine Learning toolkit adding 13 pairs of .cpp/.h files to Wesnoth. In addition, the neural nets used by ML Recruiter are serialized as .json files, which is a format Wesnoth has not yet contained. So why is this patch worthwhile?
==Why the ML Recruiter will be great for Wesnoth==
# Performance is great. ML Recruiter defeats RCA AI 66-73% of the time. We suspect that this would also translate into better performance against human opponents because it also performs better against the "ron" recruiter included in [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976 AI-Demos], which is a more challenging opponent.
# This superior performance is achieved with comparable "fun factor"
#* Variety of units recruited by recommended ML Recruiter is comparable to or better than RCA AI
# Don't need to eliminate RCA AI recruiter. Campaign designers can choose to use one or the other
# ML Recruiter should be easier to customize than RCA AI because
#* All core logic is in Lua, which is easier to modify than existing C++
#* Performance "out of the box" on known units likely to be strong
#* When new recruitable units are introduced by campaign designers, it can be trained by running c. 600 games in two hours. The new model is included as a .json file with the campaign data
#* Plug and play architecture of machine learning "features" easily allows minor modifications to mainline recruiter or to campaign-specific recruiters
# Easy way to adjust campaign difficulty: Adjusting ML AI for more/less randomness makes is easier/harder to defeat
# Inclusion of ML Recruiter could lead to greater publicity and more contributors to Wesnoth
## SeattleDad plans to submit this work as a scientific paper to a conference such as [http://eldar.mathstat.uoguelph.ca/dashlock/CIG2013/ Computational Intelligence in Games]
## Others might later build on this work by, for instance, trying ML algorithms other than neural nets, adding new features, further generalizing the algorithm, etc.
## The machine learning infrastructure is not specific to recruiting and could be repurposed for, for instance, attack planning, weapon selection, and making "retreat and heal" vs. "attack" decisions
## All of the above is potentially publishable research, so Wesnoth could attract contributions from computer science graduate students
### Note that, having established the basic framework with this patch, future work on machine learning will be much easier

=Using ML Recruiter=
==Applying the patch==
* Get the latest version of the patch from https://gna.org/patch/?3479
* Get the Wesnoth 1.11.0 source as per http://wesnoth.org
* Apply the patch as follows:
patch -p1 -i [path to patch file]
* Compile Wesnoth using CMake, SCons, or XCode

==Playing against the ML Recruiter==
# From the main menu, choose "Multiplayer"
# Choose "Local Game"
# Pick a map and adjust settings as desired. ML Recruiter has been trained with the default setting for village gold and support, but it should work fine on other settings
## Hit Okay
# For one side, Choose Player/Type-->Computer Player and then either ML AI (Recommended) or ML AI (Less Variety, probably stronger)
## For the opponent, either play against it yourself (pick your name), watch it play the default AI (Computer Player-->RCA AI), or watch it play itself (pick ML AI again)

==Watching the ML Recruiter play a single game in nogui mode==
The following command is convenient for watching the ML Recruiter play a single game in nogui mode, which allows you to quickly and easily see the ML Recruiter's decision-making process. In this example, we would be running the ML AI (Recommended mode) for the Knalgan Alliance, while the default AI would be playing the Rebels. Note that when run this way (with --log-info=ai/testing,ai/ml), a lot of logging messages will be printed to the console which will describe how the ML Recruiter is analyzing its options.
Wesnoth --log-info=ai/testing,ai/ml --nogui --multiplayer --controller 1:ai --controller 2:ai --parm 1:gold:100 --parm 2:gold:100 --parm 1:village_gold:2 --parm 2:village_gold:2 --scenario multiplayer_Weldyn_Channel --parm 1:gold:100 --parm 2:gold:100 --ai-config 1:ai/ais/ml_ai.cfg --ai-config 2:ai/dev/default_ai_with_recruit_log.cfg --side 1:"Knalgan Alliance" --side 2:Rebels

==Testing the ML Recruiter in batch mode==

Testing in batch mode is easy with the new version of ai_test2.py included in the patch. After applying the ML Recruiter patch, copy utils/ai_test/ai_test2.cfg to the directory in which you want to run the experiment. Then edit the first line of the .cfg file, "path_to_wesnoth_binary" to point to your Wesnoth executable. Then adjust faction1 and faction2 to point to the factions you want to experiment with and point ai_config1 at the ML configuration file you want to try out. Finally, to make everything easier, add the following to your path:
[Wesnoth_Install]/utils/ai_test/
Now you can test Wesnoth in batch as follows:
ai_test2.py ai_test2.cfg

=Experimental Results=

==Win percentages for different AI Pairs==
{| border="1" cellpadding="20" cellspacing="0"
!AI1
!AI2
!Games
!Win % for AI1
!Comment
|-
|ML Recruiter 0.3 (Less Variety)
|RCA AI
|1179
|69.3%
|"Less variety/probably stronger version". Wins 73.4% of the time on the maps version 0.2 was trained on
|-
|ML Recruiter 0.3 (Recommended)
|RCA AI
|2363
|66.6%
|"Recommended version". Same version as above, but has more randomness in its choice of units. See [http://wiki.wesnoth.org/Machine_Learning_Recruiter#The_Weighted_Random_.28Recommended.29_Recruiter documentation on weighted random recruiter]
|-
|ML Recruiter 0.3
|ML Recruiter 0.2
|1937
|58.0%
|We've made a lot of progress since version 0.2
|-
|ML Recruiter 0.3
|Ron Recruiter 0.11.4
|1186
|54.1%
|Ron Recruit is the recruiter build into [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976&start=405 AI Demos]
|-
|ML Recruiter 0.3 (Recommended)
|ML Recruiter 0.3 (Less variety)
|1186
|49.6%
|Difference is not statistically significant, so we pick the variant with more variety as the "Recommended" version. Note, though, that the "Less variety" version does a bit better against the RCA AI as you can see above.
|-
|RCA AI
|RCA AI
|
|50%
|Any AI against itself will win 50% of the time
|-
|RCA AI
|Random
|3,000
|52.7%
|Interesting result. You would expect a completely random choice to get beat by a wider margin
|}

==Faction vs. faction win % for ML Recruiter 0.3 vs. RCA AI==

These results are for the "Recommended" version

<code>
all/data/138 $ analyze_log.py *.log

Overall Stats
AI Wins Win %
default_ai_with_recruit_log 789 33.4%
ml_ai 1574 66.6%
Totals: 2363

Wins Loss Win %
Drakes vs Undead 33 39 45.8%
Drakes vs Northerners 20 39 33.9%
Drakes vs Loyalists 66 11 85.7%
Drakes vs Knalgan Alliance 38 40 48.7%
Drakes vs Drakes 52 19 73.2%
Drakes vs Rebels 46 2 95.8%
Total Drakes 255 150 63.0%

Knalgan Alliance vs Undead 48 19 71.6%
Knalgan Alliance vs Northerners 23 48 32.4%
Knalgan Alliance vs Loyalists 40 14 74.1%
Knalgan Alliance vs Knalgan Alliance 36 23 61.0%
Knalgan Alliance vs Drakes 34 26 56.7%
Knalgan Alliance vs Rebels 46 21 68.7%
Total Knalgan Alliance 227 151 60.1%

Loyalists vs Undead 32 41 43.8%
Loyalists vs Northerners 17 48 26.2%
Loyalists vs Loyalists 58 5 92.1%
Loyalists vs Knalgan Alliance 53 19 73.6%
Loyalists vs Drakes 52 10 83.9%
Loyalists vs Rebels 30 29 50.8%
Total Loyalists 242 152 61.4%

Northerners vs Undead 59 6 90.8%
Northerners vs Northerners 49 21 70.0%
Northerners vs Loyalists 51 9 85.0%
Northerners vs Knalgan Alliance 60 7 89.6%
Northerners vs Drakes 56 14 80.0%
Northerners vs Rebels 55 5 91.7%
Total Northerners 330 62 84.2%

Rebels vs Undead 42 14 75.0%
Rebels vs Rebels 51 15 77.3%
Rebels vs Loyalists 71 8 89.9%
Rebels vs Knalgan Alliance 50 15 76.9%
Rebels vs Drakes 44 22 66.7%
Rebels vs Northerners 21 40 34.4%
Total Rebels 279 114 71.0%

Undead vs Undead 41 37 52.6%
Undead vs Northerners 25 55 31.2%
Undead vs Loyalists 51 18 73.9%
Undead vs Knalgan Alliance 57 6 90.5%
Undead vs Drakes 41 9 82.0%
Undead vs Rebels 26 35 42.6%
Total Undead 241 160 60.1%

</code>

==Units recruited by Recommended ML Recruiter==

Results are for Recommended AI vs. RCA AI for ML Recruiter 0.3

<code>
Grand Totals
Drakes Recruitment Count %
Drake Burner 2925 28.3%
Drake Clasher 909 8.8%
Drake Fighter 2159 20.9%
Drake Glider 1156 11.2%
Saurian Augur 2197 21.3%
Saurian Skirmisher 985 9.5%
Total: 10331

Knalgan Alliance Recruitment Count %
Dwarvish Fighter 1535 14.4%
Dwarvish Guardsman 543 5.1%
Dwarvish Thunderer 4171 39.0%
Dwarvish Ulfserker 767 7.2%
Footpad 1573 14.7%
Gryphon Rider 847 7.9%
Poacher 677 6.3%
Thief 576 5.4%
Total: 10689

Loyalists Recruitment Count %
Bowman 1799 15.6%
Cavalryman 551 4.8%
Fencer 345 3.0%
Heavy Infantryman 1109 9.6%
Horseman 930 8.0%
Mage 934 8.1%
Merman Fighter 852 7.4%
Spearman 5040 43.6%
Total: 11560

Northerners Recruitment Count %
Goblin Spearman 181 1.4%
Naga Fighter 504 3.9%
Orcish Archer 2480 19.1%
Orcish Assassin 1842 14.2%
Orcish Grunt 2524 19.5%
Troll Whelp 4833 37.3%
Wolf Rider 608 4.7%
Total: 12972

Rebels Recruitment Count %
Elvish Archer 1833 17.6%
Elvish Fighter 3213 30.8%
Elvish Scout 1086 10.4%
Elvish Shaman 222 2.1%
Mage 435 4.2%
Merman Hunter 768 7.4%
Wose 2865 27.5%
Total: 10422

Undead Recruitment Count %
Dark Adept 2460 20.7%
Ghost 827 7.0%
Ghoul 1474 12.4%
Skeleton 2386 20.1%
Skeleton Archer 3772 31.7%
Vampire Bat 668 5.6%
Walking Corpse 308 2.6%
Total: 11895
</code>

==Units recruited by Recommended ML Recruiter vs Undead==
As a breakdown of the above, it's interesting to look at the different unit blends that ML Recruiter 0.3 selects vs. the Undead as opposed to the overall totals shown above. MLR's RCA AI opponent recruits a unit blend which consists of just the following four units:

RCA AI Recruitment for Undead:
<code>
Undead Recruitment Count %
Dark Adept 3163 28.4%
Ghost 2451 22.0%
Skeleton 3574 32.1%
Skeleton Archer 1941 17.4%
Total: 11129
</code>
ML Recruiter 0.3 units recruited against the RCA AI Undead. Notice the large increase in the number of units with impact and fire attacks, which would be effective against Skeletons and the decrease in Orcish Assassins and Ghouls, which are ineffective against every Undead unit except Dark Adepts.

<code>
Results for enemy faction:Undead
Drakes Recruitment Count %
Drake Burner 666 37.8%
Drake Clasher 37 2.1%
Drake Fighter 478 27.1%
Drake Glider 339 19.2%
Saurian Augur 91 5.2%
Saurian Skirmisher 152 8.6%
Total: 1763

Knalgan Alliance Recruitment Count %
Dwarvish Fighter 352 17.2%
Dwarvish Guardsman 31 1.5%
Dwarvish Thunderer 259 12.7%
Dwarvish Ulfserker 170 8.3%
Footpad 945 46.2%
Gryphon Rider 153 7.5%
Poacher 66 3.2%
Thief 70 3.4%
Total: 2046

Loyalists Recruitment Count %
Bowman 125 6.7%
Cavalryman 45 2.4%
Fencer 65 3.5%
Heavy Infantryman 533 28.6%
Horseman 20 1.1%
Mage 538 28.8%
Merman Fighter 103 5.5%
Spearman 437 23.4%
Total: 1866

Northerners Recruitment Count %
Goblin Spearman 24 1.1%
Naga Fighter 60 2.8%
Orcish Archer 778 36.9%
Orcish Assassin 43 2.0%
Orcish Grunt 202 9.6%
Troll Whelp 952 45.1%
Wolf Rider 51 2.4%
Total: 2110

Rebels Recruitment Count %
Elvish Archer 92 6.9%
Elvish Fighter 265 19.9%
Elvish Scout 83 6.2%
Elvish Shaman 50 3.8%
Mage 176 13.2%
Merman Hunter 41 3.1%
Wose 625 46.9%
Total: 1332

Undead Recruitment Count %
Dark Adept 548 23.1%
Ghost 56 2.4%
Ghoul 153 6.4%
Skeleton 777 32.7%
Skeleton Archer 669 28.1%
Vampire Bat 80 3.4%
Walking Corpse 94 4.0%
Total: 2377
</code>

=How the ML Recruiter works=

When it's deciding what to recruit, the ML Recruiter works by predicting a "metric" which is a measure of how well a given unit will do in the game in the current situation. A good measure of a unit's usefulness is a tricky question and we will discuss three different metrics below, but let's start with the easiest one, which is the sum of the following quantities for each unit:

# Experience points at the end of the game or when the unit is killed
# Number of villages captured by the unit

Note that this metric is blind to other ways a unit can help you (in particular, it doesn't know about poison, healing, and slowing).

This sum, which we'll call the "metric" is then divided by the unit cost to get metric/cost (think of this as goodness per unit of gold). You can see this in the debugging output that the ML Recruiter prints to stderr when run with the flag --log-info=ai/testing,ai/ml:
unit type metric cost wt cost weighted metric
Elvish Shaman 8.58 15 15.00 0.57
Elvish Fighter 10.42 14 14.00 0.74
Elvish Scout 8.47 18 18.00 0.47
Wose 17.07 20 20.00 0.85
Mage 10.37 20 20.00 0.52
Elvish Archer 8.46 17 17.00 0.50
Merman Hunter 8.55 15 15.00 0.57

This is from the first turn of a game between the Rebels and the Undead. The ML Recruiter is predicting that if it recruits a Wose now, it will end with 17.07 XP + Village Captures. 17.07/20 = 0.85, which is the highest weighted metric at this time, so it picks a Wose as it's top choice.

How does it know to pick a Wose? It looks at the "features" which describe the current situation. Here's another chart from the same game:

unit type metric cost wt cost weighted metric
Elvish Shaman 7.18 15 15.00 0.48
Elvish Fighter 11.82 14 14.00 0.84
Elvish Scout 7.91 18 18.00 0.44
Wose 15.53 20 20.00 0.78
Mage 9.11 20 20.00 0.46
Elvish Archer 9.38 17 17.00 0.55
Merman Hunter 8.36 15 15.00 0.56
Side: 1 Gold: 21 Unit we want: Elvish Fighter
PRERECRUIT:, enemy Dark Adept:1 , enemy Deathblade:1 , enemy Ghost:2 , enemy Skeleton:3 , enemy faction:Undead ,
enemy gold:10 , enemy level3+:0 , enemy total-gold:139 , enemy unit-gold:129 , friendly Elvish Captain:1 ,
friendly Elvish Fighter:1 , friendly Wose:4 , friendly faction:Rebels , friendly gold:21 , friendly level3+:0 ,
friendly total-gold:161 , friendly unit-gold:140 , side:1 , terrain-forest:0.082 , terrain-mountain-hill:0.113 ,
terrain-water-swamp:0.164 , total-gold-ratio:0.537 , turn:4 , village-control-margin:-2 , village-control-ratio:0.417 , village-enemy:7 ,
village-friendly:5 , village-neutral:4 ,

The "features" that it sees are the values following "PRERECRUIT". The ML AI sees that the enemy faction is the Undead and that they have one Deathblade, two ghosts, three Skeletons. The Rebels currently have 4 Wose, 1 Elvish Fighter, and 1 Elvish Captain. It also sees a number of other features like how much gold it and its opponent have, what percentage of each the map is covered by different terrain, and how many friendly, neutral, and enemy villages there are. In this situation, although it still sees that the Wose is likely to score higher on the XP + village capture metric (15.5 vs. 11.8), this isn't enough to overcome the price differential, so it chooses an Elvish Fighter as it's best choice with a weighted metric of 0.84.

Note that these predictions of 15.5 vs. 11.8 are computed by the neural net based on a model built from what the algorithm has seen has happened in similar situations during training.

==Unit Goodness Metrics==
We have experimented with three different unit goodness metrics. All of these metrics are designed to have the property that the higher the value of the metric, the better the unit performed in a a given game. Clearly there is a random element here. In some games when playing against a Skeleton-heavy Undead army, an Elvish Archer, which uses mainly a pierce attack, may get lucky and do better than a Wose, which has an impact attack, but on average the metric should show that the Wose performs better.

The three metrics we've looked at are as follows:

===Experience Point plus Village Capture===
This is the metric used in ML Recruiter 0.2. As noted above, it is the sum of the following quantities:

# Experience points at the end of the game or when the unit is killed
# Number of villages captured by the unit

This metric has the advantage that experience points lead to promotion, which is a very good thing. Also, getting kills should be correlated with how much damage the unit is doing. Adding village captures to experience points is a little flaky, but is intended to give credit to fast units, which are more likely to capture villages.

===Victory===

This metric gives a unit 1.0 if its side wins and 0 if its side loses. The effect is that the neural net's prediction for each unit can be seen as "what is the probability of victory if I recruit this unit in this situation". This is the most natural of all metrics, but experimentally it hasn't performed as well in terms of leading to actual victories as recruiting based on unit-based metrics. Performance has peaked at around a 59% win ratio for a victory metric vs. around 66 - 73% for the XP+VC metric. We think the problem is that the impact of recruiting a single unit of Type A vs. Type B on the victory probability is very small, so the neural net isn't differentiating among the choices enough.

===Gold Yield===

As of ML Recruiter 0.3, this is the new default metric. It is the sum of the following quantities, all of which are intended to quantify a unit's usefulness in terms of how much gold benefit it has yielded for the friendly side plus gold damage done to the enemy side. This metric builds off of a [http://forums.wesnoth.org/viewtopic.php?f=10&t=36642&sid=11062936e4f4c0bab673470b5d211987&start=45#p536132 suggestion] from Sapient.
# Basic Damage Metric: Target unit cost * (Damage inflicted/target max HP). The concept is that you cost your opponent this much gold by destroying this fraction of the unit. Obviously in any given attack, we would calculate this for both the attacker and the defender.
# Village Capture: capturing_unit.variables.ml_gold_yield += wesnoth.game_config.village_income. (Defaults to crediting 2 gold per village capture)
#* The idea, again, is that fast units tend to get more captures than slow units and this gives units credit for being fast.
# Poison: Treated the same as Basic Damage Metric by crediting for the amount of damage done in that turn. On the turn in which the unit is cured, the poisoner is credited with Target Unit Cost * (8/target max HP) to reflect the damage that it would have healed if it hadn't been poisoned (obviously, lessened if it has less than 8 HP of damage)
# Slowing: When a unit is on defense and it slows the attacker, the defender gets no special credit because the attacker just unslows at the end of its turn. When you slow a unit as the attacker, the slowing unit gets credit for the Basic Damage Metric accumulated by the slowed unit until it unslows (the slowed unit would otherwise have done twice as much damage, so you get credit for the damage it didn't do)
# Healing: healing_unit.variables.ml_gold_yield += Healed_unit_cost * (healed amount/healed unit max HP)
#* Directly analogous to the Basic Damage Metric
#* Note that healers also get credit for curing/stopping poison
# Walking Corpse Creation: Credit a unit which gets a kill which creates a unit due to its plague ability with 8 gold (the value of a Walking Corpse). (not implemented)
# Leadership: Credit the leader for the bonus damage inflicted by the unit being led (not implemented)
# Maintenance: Charge units for their share of the maintenance costs, weighted by level. Hence, level 0 units never pay maintenance. Level 2 units pay for twice as much maintenance. (not implemented)

==How MLR makes weighted random choices==
The recommended recruiter is defined in ai/ais/ml_ai.cfg. It is called "Recommended" in the user interface. Although we are currently measuring it as performing roughly the same or slightly worse than the "Less variety/probably stronger" ML AI (ai/ais/ml_ai_less_random.cfg), we recommend it because it allows the player to see a greater variety of opposing units.

The weighted random printout looks like the following:

Turn 13:
unit type metric cost metric/ weighted %
cost m/c of total
Merman Hunter 1.10 15 0.07 0.0000 0.0%
Wose 1.72 20 0.09 0.0000 0.1%
Elvish Shaman 1.66 15 0.11 0.0000 0.4%
Elvish Archer 2.71 17 0.16 0.0000 4.0%
Elvish Fighter 2.54 14 0.18 0.0000 8.5%
Mage 4.18 20 0.21 0.0001 20.1%
Elvish Scout 4.60 18 0.26 0.0003 66.8%
Random Number chosen was 376
Side: 1 Gold: 27 Unit we want: Elvish Scout
PRERECRUIT:, enemy Dark Adept:2 , enemy Revenant:1 , enemy Skeleton:1 , enemy faction:Undead , enemy gold:8 ,
enemy level3+:0 , enemy total-gold:83 , enemy unit-gold:75 , friendly Elder Wose:1 , friendly Elvish Fighter:2 ,
friendly Elvish Ranger:1 , friendly Mage:1 , friendly Wose:3 , friendly faction:Rebels , friendly gold:27 ,
friendly level3+:0 , friendly total-gold:225 , friendly unit-gold:198 , side:1 , terrain-forest:0.082 ,
terrain-mountain-hill:0.113 , terrain-water-swamp:0.164 , total-gold-ratio:0.731 , turn:13 ,
village-control-margin:0 , village-control-ratio:0.5 , village-enemy:8 , village-friendly:8 , village-neutral:0 ,

This situation occurs towards the end of a game that the Rebels are winning. Note that total-gold-ratio (the ratio between the sum of gold + the value of all units on each side) is 0.731, so it's heavily in the Rebels' favor. The ML AI sees an Elvish Scout as being the best choice in this situation with a Mage in second place. The Elvish Scout is probably favored because the game is likely to be won rapidly and only a fast unit will be able to reach the enemy or reach a village fast enough to add to its "experience points + village capture" metric.

The Weighted Random does the following:
# It takes every metric/cost value and raises it to the sixth power. Why? We want to magnify the differences. In this example 0.26/0.21 = 1.23, but (0.26**6)/(0.21**6) = 3.60.
# We then randomly choose a unit with a probability proportional to this weighted value which, in this case, was an Elvish Scout.

The Less Variety/Probably Stronger AI does the same thing, but raises metric/cost to the 24th power instead of the 6th power. This still allows for some randomness, but weights the selection much more strongly towards the more favored units.

=How to train your own ML Recruiter=
utils/ai_test/run_model_and_make_new_model.py is an end-to-end script for running a whole bunch of training games of Wesnoth and then training a new model based on the data output by that run. Documentation on this script can be seen by running
run_model_and_make_new_model.py --help
Note that this script assumes that [http://waffles.sourceforge.net/ the Waffles machine learning toolkit] is installed and that waffles/bin/ is in your path.

=Known issues=
==Bugs==
# Haven't added new Waffles files to Visual C++, so it won't compile under VC++. I need some help with this.
# The default for multiplayer games is that units require only 70% of normal experience to promote, however when a game is run from the command line, it always requires normal 100% of experience to promote. Consequently MLR doesn't see units promote as much as they should in training, which would slightly distort its training data. This is a [https://gna.org/bugs/?19895 limitation of Wesnoth], not MLR.

==Current Limitations==
# Only tested on two-player multiplayer games. Doesn't work when there are more than two leaders on the map.
# Works on all two-player maps except for Hornshark Island, Thousand Stings, Caves of the Basilisk, and Dark Forecast
# As noted above in [http://wiki.wesnoth.org/Machine_Learning_Recruiter#Gold_Yield Gold Yield Metric], we account for all special abilities available in the main-line multiplayer scenarios except for plague, leadership, and unit maintenance costs

=ML Recruiter development roadmap=

* ML Recruiter 0.1: Initial drop
* ML Recruiter 0.1.1: Minor retraining of the model
* ML Recruiter 0.2:
** Logging messages changed from print statements to using lg::log_domain.
** Now have an explicit debug mode by running with --log-debug=ai/ml.
** ML Recruiter can play against itself. Previously could only have ML Recruiter on one side.
** Some work on ML recruiting model (i.e. the core logic). Experimented with different training strategies, but features unchanged from 0.1.
* ML Recruiter 0.3 (10/25/2012) :
** New "gold yield" metric for judging a unit's goodness
** Several new ML features to aid in prediction: alignment, race, time of day, map size, friendly and enemy leader hit point percentage remaining, and nearest enemy unit to friendly leader
** Runs on all 2-player maps except for Hornshark Island, Thousand Stings, Caves of the Basilisk, and Dark Forecast
** Greatly improved ai_test2.py script for running thousands of games to test AI and gather data for the neural net
** New script (run_model_and_make_new_model.py) for running games and building a new neural net based on the data gathered from those games
** Improved performance: Defeats ML Recruiter 0.2 58% of the time
* ML Recruiter 0.4 (11/11/2012):
** Run on all 2-player maps (except Dark Forecast, which has a custom recruiter)
** Refactor code to separate features from predicted values
** Added timeout option to ai_test2.py. Also report time statistics in analyze_log.py
** Improved recruiter for the Ron recruiter. It still underperforms the Ron recruiter on most maps when used with the other Ron CA's, though.
** Move all code into [https://github.com/mattsc/Wesnoth-AI-Demos AI-Demos project on GitHub]. the ML Recruiter 0.4 patch now consists, essentially, of only the C++ code modifications.
* ML Recruiter 0.5 (planned)
** Run on all mainline multiplayer maps
** Experiment with using as the [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976 AI-Demos] recruiter
** Add missing special abilities (plague, leadership, and unit upkeep)
** Add 95% confidence intervals to the win ratios in analyze_log.py and add measures of entropy (randomness) to analyze_recruitment.py. Entropy is a good measure of the variety of units that a recruiter is recruiting--for game play, more is better.

[[Category:AI]]

Micro AIs

2012-12-05T18:44:40Z

Alarantalara: /* Recruiting Micro AI */ more copy/paste fixes

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), generally has an ai_type ending with '_unit' (sometimes the '_unit' is added to another key, if several different AIs can be accessed by the given ai_type).

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.

'''Note:''' Some of the Micro AIs use and/or modify default AI components (candidate actions or aspects) when they are added, or reset these components to their default values when they are deleted. Thus, if you have modified the AI yourself using the default CAs or aspects, some of these modifications might be affected, or might be interfering with the Micro AI. The sections below indicate whether a Micro AI changes any default AI components.

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

'''Note:''' The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|attacks aspect]].

== 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. All Guardian AIs attach to a unit and only affect the moves of that particular unit. 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_unit". 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_unit
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_unit
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_unit
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 stop only on thoes that are explicitly defined.
They always attack the weakest enemy within their reach from only explicitly defined terrains. 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

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

'''Required keys:'''
* '''type''': Specifies which unit types are to be influenced by the Lurker Micro AI.
* '''attack_terrain''': Specifies terrains from which ai can attack.
* '''wander_terrain''': Specifies terrains on which ai can stop if there is no enemy in reach.

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

'''Note:''' The Protect Unit Micro AI modifies the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[AiWML#Evaluating_AI_Moves_--_Candidate_Actions_.28CAs.29|move leader to keep candidate action]].

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.

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_unit micro AI
[micro_ai]
# Required keys of [micro_ai] tag
side=1
ai_type=animals
animal_type=hunter_unit
action=add
# Required keys of hunter_unit 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_unit''': hunts in a specific area, then stays home for a specified time/until fully healed. This AI attaches to a unit, rather than controlling all units of a side.
* '''wolves''': they hunt in a pack of up to three. '''Note:''' The Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|attacks aspect]].
* '''wolves_multipacks''': same as above but this AI supports an arbitrary number of units and this can't avoid specific types of enemies.
* '''big_animals''': these just go to random places, avoid other big animals and stay at their preferred types of terrain.
* '''swarm''': the animals in the side with this AI will try to stay together and avoid enemies. This AI doesn't require any extra keys, except the animal_type.
* '''sheep''': this AI controls both the sheep and the dogs of a side. The dogs keep the sheep in a herd. This AI only requires the animal_type key in addition to the needed [micro_ai] keys.
* '''forest_animals''': This AI controls a set of animals: tuskers, tusklets, rabbits.

====Required keys of the hunter_unit 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_unit" (without quotation marks) if you want a hunter_unit 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.'''

====Required keys of the big_animals AI:====

* '''animal_type''': You have to set this to "big_animals" if you want a big_animals AI.
* '''type''': comma-separated list of unit types of animals in the side to which this AI is applied.

== 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=patrol_unit
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=patrol_unit
action=add

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

== Recruiting Micro AI ==

The Recruiting Micro AI lets you use alternate recruitment strategies.

Only one alternate strategy is available at the moment. It tries to approximate human style recruiting as much as possible and is used by the multiplayer AIs in the add-on.

No demonstration for use exists at this time, but you can explore the unit choices by watching one of the experimental multiplayer AIs in the add-on.

Enable the Recruiting Micro AI by putting
{MICRO_AI_RECRUITING}
into the [side] tag and configure it by using
ai_type=recruiting
in the [micro_ai] tag.

== 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-05T18:44:14Z

Alarantalara: /* Recruiting Micro AI */ remove copy/paste junk

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), generally has an ai_type ending with '_unit' (sometimes the '_unit' is added to another key, if several different AIs can be accessed by the given ai_type).

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.

'''Note:''' Some of the Micro AIs use and/or modify default AI components (candidate actions or aspects) when they are added, or reset these components to their default values when they are deleted. Thus, if you have modified the AI yourself using the default CAs or aspects, some of these modifications might be affected, or might be interfering with the Micro AI. The sections below indicate whether a Micro AI changes any default AI components.

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

'''Note:''' The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|attacks aspect]].

== 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. All Guardian AIs attach to a unit and only affect the moves of that particular unit. 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_unit". 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_unit
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_unit
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_unit
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 stop only on thoes that are explicitly defined.
They always attack the weakest enemy within their reach from only explicitly defined terrains. 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

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

'''Required keys:'''
* '''type''': Specifies which unit types are to be influenced by the Lurker Micro AI.
* '''attack_terrain''': Specifies terrains from which ai can attack.
* '''wander_terrain''': Specifies terrains on which ai can stop if there is no enemy in reach.

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

'''Note:''' The Protect Unit Micro AI modifies the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[AiWML#Evaluating_AI_Moves_--_Candidate_Actions_.28CAs.29|move leader to keep candidate action]].

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.

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_unit micro AI
[micro_ai]
# Required keys of [micro_ai] tag
side=1
ai_type=animals
animal_type=hunter_unit
action=add
# Required keys of hunter_unit 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_unit''': hunts in a specific area, then stays home for a specified time/until fully healed. This AI attaches to a unit, rather than controlling all units of a side.
* '''wolves''': they hunt in a pack of up to three. '''Note:''' The Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|attacks aspect]].
* '''wolves_multipacks''': same as above but this AI supports an arbitrary number of units and this can't avoid specific types of enemies.
* '''big_animals''': these just go to random places, avoid other big animals and stay at their preferred types of terrain.
* '''swarm''': the animals in the side with this AI will try to stay together and avoid enemies. This AI doesn't require any extra keys, except the animal_type.
* '''sheep''': this AI controls both the sheep and the dogs of a side. The dogs keep the sheep in a herd. This AI only requires the animal_type key in addition to the needed [micro_ai] keys.
* '''forest_animals''': This AI controls a set of animals: tuskers, tusklets, rabbits.

====Required keys of the hunter_unit 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_unit" (without quotation marks) if you want a hunter_unit 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.'''

====Required keys of the big_animals AI:====

* '''animal_type''': You have to set this to "big_animals" if you want a big_animals AI.
* '''type''': comma-separated list of unit types of animals in the side to which this AI is applied.

== 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=patrol_unit
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=patrol_unit
action=add

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

== Recruiting Micro AI ==

The Recruiting Micro AI lets you use alternate recruitment strategies.

Only one alternate strategy is available at the moment. It tries to approximate human style recruiting as much as possible and is used by the multiplayer AIs in the add-on.

No demonstration for use exists at this time, but you can explore the unit choices by watching one of the experimental multiplayer AIs in the add-on.

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

== 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-05T18:43:39Z

Alarantalara: Add Recruiting Micro AI description.

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), generally has an ai_type ending with '_unit' (sometimes the '_unit' is added to another key, if several different AIs can be accessed by the given ai_type).

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.

'''Note:''' Some of the Micro AIs use and/or modify default AI components (candidate actions or aspects) when they are added, or reset these components to their default values when they are deleted. Thus, if you have modified the AI yourself using the default CAs or aspects, some of these modifications might be affected, or might be interfering with the Micro AI. The sections below indicate whether a Micro AI changes any default AI components.

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

'''Note:''' The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|attacks aspect]].

== 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. All Guardian AIs attach to a unit and only affect the moves of that particular unit. 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_unit". 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_unit
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_unit
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_unit
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 stop only on thoes that are explicitly defined.
They always attack the weakest enemy within their reach from only explicitly defined terrains. 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

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

'''Required keys:'''
* '''type''': Specifies which unit types are to be influenced by the Lurker Micro AI.
* '''attack_terrain''': Specifies terrains from which ai can attack.
* '''wander_terrain''': Specifies terrains on which ai can stop if there is no enemy in reach.

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

'''Note:''' The Protect Unit Micro AI modifies the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[AiWML#Evaluating_AI_Moves_--_Candidate_Actions_.28CAs.29|move leader to keep candidate action]].

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.

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_unit micro AI
[micro_ai]
# Required keys of [micro_ai] tag
side=1
ai_type=animals
animal_type=hunter_unit
action=add
# Required keys of hunter_unit 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_unit''': hunts in a specific area, then stays home for a specified time/until fully healed. This AI attaches to a unit, rather than controlling all units of a side.
* '''wolves''': they hunt in a pack of up to three. '''Note:''' The Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|attacks aspect]].
* '''wolves_multipacks''': same as above but this AI supports an arbitrary number of units and this can't avoid specific types of enemies.
* '''big_animals''': these just go to random places, avoid other big animals and stay at their preferred types of terrain.
* '''swarm''': the animals in the side with this AI will try to stay together and avoid enemies. This AI doesn't require any extra keys, except the animal_type.
* '''sheep''': this AI controls both the sheep and the dogs of a side. The dogs keep the sheep in a herd. This AI only requires the animal_type key in addition to the needed [micro_ai] keys.
* '''forest_animals''': This AI controls a set of animals: tuskers, tusklets, rabbits.

====Required keys of the hunter_unit 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_unit" (without quotation marks) if you want a hunter_unit 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.'''

====Required keys of the big_animals AI:====

* '''animal_type''': You have to set this to "big_animals" if you want a big_animals AI.
* '''type''': comma-separated list of unit types of animals in the side to which this AI is applied.

== 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=patrol_unit
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=patrol_unit
action=add

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

== Recruiting Micro AI ==

The Recruiting Micro AI lets you use alternate recruitment strategies.

Only one alternate strategy is available at the moment. It tries to approximate human style recruiting as much as possible and is used by the multiplayer AIs in the add-on.

No demonstration for use exists at this time, but you can explore the unit choices by watching one of the experimental multiplayer AIs in the add-on.

Enable the Recruiting Micro AI by putting
{MICRO_AI_PATROL}
into the [side] tag and configure it by using
ai_type=recruiting
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.'''

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

LuaWML/Sides

2012-12-05T15:50:28Z

Alarantalara: /* wesnoth.sides */ Add recruit to list of fields for a side

This page describes the [[LuaWML]] functions and helpers for handling sides and villages.

==== wesnoth.get_side ====

{{DevFeature1.11}}: This function is deprecated, use wesnoth.sides[i] instead of wesnoth.get_side(i).

==== wesnoth.sides ====

This is not a function but a table indexed by side numbers. Its elements are proxy tables with these fields:
* '''side''': the side number
* '''gold''', '''village_gold''', '''base_income''': integers (read/write)
* '''total_income''': integer (read only)
* '''objectives''', '''user_team_name''': translatable strings (read/write)
* '''objectives_changed''': boolean (read/write)
* '''team_name''': string (read/write)
* '''controller''': string (read/write)
''note: In networked multiplayer, the controller attribute is ambiguous. Be very careful or you have OOS errors.''
* '''fog''': boolean (read)
* '''shroud''': boolean (read)
* '''hidden''': boolean (read)
* '''name''': string (read)
* '''color''': string (read) {{DevFeature1.11}}: also write
* '''recruit''': table of strings
* '''__cfg''': WML table (dump)

The metatable of these proxy tables appears as '''"side"'''.

local team = wesnoth.sides[1]
team.gold = team.gold + 50
wesnoth.message(string.format("%d sides", #wesnoth.sides))

==== wesnoth.get_sides ====

Returns a table array containing proxy tables for these sides matching the passed [[StandardSideFilter]].
--set gold to 0 for all sides with a leader
local sides = wesnoth.get_sides({ {"has_unit", { canrecruit = true }} })
for i,v in ipairs(sides) do
v.gold = 0
end

==== wesnoth.get_village_owner ====

Returns the side that owns the village at the given location.

local owned_by_side_1 = wesnoth.get_village_owner(12, 15) == 1

==== wesnoth.set_village_owner ====

Gives ownership of the village at the given location to the given side (or remove ownership if none). Ownership is also removed if nil or 0 is passed for the third parameter, but no capture events are fired in this case.
An optional 4th parameter (boolean true|false, default: false) can be passed determining whether to fire any capture events.

wesnoth.set_village_owner(12, 15, 1)

==== wesnoth.is_enemy ====

Returns true if side A is enemy of side B, false otherwise.

local enemy_flag = wesnoth.is_enemy(1, 3)

==== wesnoth.match_side ====

Matches a side against a given [[StandardSideFilter]].

wesnoth.message(tostring(wesnoth.match_side(1, {{"has_unit", { type = "Troll" }}})))

==== wesnoth.get_starting_location ====

local loc = wesnoth.get_starting_location(1)
wesnoth.message(string.format("side 1 starts at (%u, %u)", loc[1], loc[2]))

==== helper.all_teams ====

Returns an iterator over teams that can be used in a for-in loop.

for team in helper.all_teams() do team.gold = 200 end

[[Category: Lua Reference]]

Google Code-in Micro AI Tasks

2012-11-27T16:54:54Z

Alarantalara: Add AI Category

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

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

'''Step 1:'''

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.

'''Step 2:'''

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.

'''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]]

AI Arena

2012-11-27T16:46:44Z

Alarantalara: Add AI Category

= AI Arena is an interactive AI testing framework =
It is implemented as a test scenario ai_arena_small (available from r34329 (31 Mar 09) )

This documentation is accurate as of r34889 (14 Apr 09)

To launch it, run Wesnoth with a -t parameter (must not come as last parameter). For example:

./wesnoth-debug -t ai_arena_small -d

The scenario is located in data/ai/scenarios/scenario-AI_Arena_small.cfg

It is based on the Den of Onis.

The map includes three sides:

1: Human (AI developer)

2: Challenger AI (Side which which is tested, 'north team')

3: Champion AI (Side which commands the enemy of the AI being tested, 'south team')

All leaders start off-map in pocketed locations.

You can access an interactive menu by right-clicking a map tile.

There are menu options which allows AI developer to pick the challenge (each challenge has a small description and a unique number), and to pick the AI that will try the challenge (AI developer can select from a list a .cfg location which contains the bare *contents* of the SIDE tag with [[SideWML]] and [[AiWML]] configuration - without the SIDE tag itself). The test will be loaded (units will appear inside the Arena) and selected AI will be hot-redeployed).

Then, the AI developer can end his turn and watch the AI's actions.

= Creating new challenges =
Please feel free to add more 'AI challenges' and improve existing ones. Each challenge should be AI-independent.

To create a challenge which will be committed into Wesnoth repository:

# Look at the content ai/scenarios/ai_arena_small directory
# Assign a unique CODE number (4 digits) for your challenge. Pick a NAME (suitable as part of WML event name) for your challenge. Write a small DESCRIPTION for your challenge
# Create a new file in ai/scenarios/ai_arena_small directory.
[event]
name=preload
[lua]
code = << register_test('CODE-NAME','DESCRIPTION'); >>
[/lua]
[/event]
[event]
name=CODE-NAME
first_time_only=no
[/event]

Use the second event to create the situation. If you do not intend to commit that file, you may use any filename and event name you like, just make sure that this is legal WML event name and make sure that it matches in both events.

Note: Add code to clean all your labels to cleanup function. (since there is (so far) no way to delete all labels on the map)

= Creating new AI configurations =

Example of AI configuration file:
ai_algorithm =formula_ai
[ai]
eval_list=yes
[register_candidate_move]
name=poisoner
type=attack
evaluation="{ai/formula/poisoner_eval.fai}"
action="{ai/formula/poisoner_attack.fai}"
[/register_candidate_move]
[/ai]
Then use it by typing a name in the interactive menu, or add a reference to it to the AI Arena scenario

= Where to put new AI configurations =

If it should be available for selection as a multiplayer AI and AI Arena in both non-debug and debug modes, put it in
data/ai/ais/

If it should be available for selection as a multiplayer AI and AI Arena only in debug mode, put it in
data/ai/dev/

= Where to put all formulas which may be used by the AIs=

data/ai/formula/

[[Category:AI]]

Micro AIs

2012-11-27T16:44:08Z

Alarantalara: Add AI Category

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 two, 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]

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

Formula AI Code Library

2012-11-27T16:42:41Z

Alarantalara: Add AI Category

This page lists Formula AI code examples that can be used directly in a scenario or as templates for further development. If you have problems with any of them or would like to see additional examples let us know in [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976 this forum thread]. If you have examples to add, you can also let us know there and we will post them, or feel free to edit these wiki pages yourself.

* Most of the examples shown on these pages can also be tested in action in campaign "AI Modifications Demos", available on the 1.9/1.10 add-ons server
* Check out [[Formula AI Howto]] for a practical guide for setting up and testing these examples in a scenario.
* Additional examples can be found in the Wesnoth data directory under ai/formula/. See [[EditingWesnoth]] for locating the data directory.
* Lua AI code examples can be found in the [[Lua AI Code Library]].

==Swamp Lurker Moves==

This is the Formula AI adaptation of the WML swamp lurker code from [http://forums.wesnoth.org/viewtopic.php?f=8&t=34970 Grnk the Mighty]. Swamp lurkers have the 'swamp_submerge' ability, meaning they are invisible in swamps unless an enemy unit is adjacent to them. They are dumb, impulse-drive creatures which move as follows:

* They can move across most terrain, but only stop on swamp.
* All lurkers move individually, there is no strategy.
* If there are enemies within reach (next to swamp terrain), a lurker will attack the unit with the fewest hitpoints.
* If no unit is in reach, the lurker will move to a random reachable swamp hex.

In Grnk, this behavior is coded in WML (the WML code can be found in '1_unit_macros.cfg' in the Grnk folder or in [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976#p506852 this forum post]). The adaptation to Formula AI follows below. A [[Lua_AI_Code_Library#Swamp_Lurker_Moves|Lua AI version]] exists as well.

<div style="height: 250px; overflow:auto">
fai 'lurker_moves.fai'
# run_file('~add-ons/AItest/ai/lurker_moves.fai') #

def is_swamp(map, xx, yy)
# Tests whether terrain at xx,yy is swamp_water #
map(
filter( map.terrain, (x=xx) and (y=yy)),
self.id
)[0] = 'swamp_water';

def reachable_swamp(unit_loc,map)
# get all reachable swamp locs for unit at unit_loc #
# exclude own location #
filter(
unit_moves( unit_loc ),
(is_swamp( map, x, y )) and (self != unit_loc)
);

def random(array)
# Picks a random elements of 'array' #
array[(1d size(array) - 1)];

def reachable_enemies_next_to_swamp(unit_loc,attacks,map)
# Returns all the attacks for enemies that the unit at 'unit_loc' #
# can reach and that are next to a swamp hex #
filter(
map( attacks.attacks, self),
(move_from = unit_loc) and (is_swamp( map, attack_from.x, attack_from.y))
);

def weakest_defender(attacks)
# Get the enemy with the lowest HP #
choose( attacks, -unit_at(defender).hitpoints
);

# Attack if possible, otherwise random move #
if( size(possible_attacks) != 0,
weakest_defender(possible_attacks),
if( size(swamp_in_reach) != 0,
move(me.loc,random(swamp_in_reach)),
end)
)

where possible_attacks = reachable_enemies_next_to_swamp( me.loc, my_attacks, map)

where swamp_in_reach = reachable_swamp(me.loc, map)

faiend
</div>

This code is meant to be in a file 'lurker_moves.fai. It can be used with the [[Formula_AI_Howto#Setting_up_the_Formula_AI_unit_formulas_Stage|Formula AI ''unit_moves'' stage]] by including

[ai]
formula={lurker_moves.fai}
[/ai]

in the definition of all swamp lurker units. Or it can be set up as a [[Formula_AI_Howto#Setting_up_the_RCA_main_loop_Stage_and_Candidate_Actions|candidate action]] that applies to all swamp lurker units of a given side:

[candidate_action]
engine=fai
name=lurker_moves
type=movement
[filter]
me="filter(input, (input.type = 'Swamp Lurker'))"
[/filter]
evaluation=300000
action={lurker_moves.fai}
[/candidate_action]

Notes:
* This code can, of course, also be used with any non-lurker unit as long as it is able to move through swamp.
* This example currently only works with "pure" swamp, not with quagmire tiles, but the extension to include those should be obvious.

==Specifying simple AI combat targets==

This Formula AI example is from a multiplayer campaign, [http://forums.wesnoth.org/viewtopic.php?f=8&t=33664 The Great Quest], by Coffee.

When the AI has a chance/choice of units to kill, sometimes you might want it to try to kill a certain unit or type of unit in preference of another. The following example makes the AI try to kill a ''loyal'' unit in preference of other units where the chance of a kill from one attack is greater than 50% (it then further prioritizes by chance to kill ''loyal'' units):

*Notes: There is a specific exclusion for the AI leader, so it doesn't get goaded into a bad position. There is also a calculation done to attack from the best terrain spot available for each possible attack pair. Calculate_outcome gives a result in the range of 0 to 10000, with >=5000 meaning a 50% chance of success.

[side]
side={SIDE}
controller=ai
#other params here
[ai]
#others here such as ''grouping'' or ''aggression''
{MODIFY_AI_ADD_CANDIDATE_ACTION {SIDE} main_loop (
[candidate_action]
id=go_for_loyal_units
name=go_for_loyal_units
engine=fai
type=attack
[filter]
me="filter(input, 'me', me.leader=0)"
target="filter(input, 'target', index_of('loyal',target.traits) != -1)"
[/filter]
evaluation="if(max_possible_damage(me,target)>=target.hitpoints, if(ca_prob>=5000, {AI_CA_COMBAT_SCORE}+ca_prob,0), 0)
where ca_prob=calculate_outcome(me.loc, choose(filter(map(filter(my_moves.moves, src=me.loc), dst), distance_between(self, target.loc) = 1), defense_on(me, self)), target.loc)[1].probability[0]"
action="attack(me.loc, choose(filter(map(filter(my_moves.moves, src=me.loc), dst), distance_between(self, target.loc) = 1), defense_on(me, self)), target.loc, -1)"
[/candidate_action]
)}
[/ai]
[/side]

==Recruiting certain types of units on particular hexes==

This side wide Formula AI example is also taken from [http://forums.wesnoth.org/viewtopic.php?f=8&t=33664 The Great Quest] by Coffee.

As it currently stands in Wesnoth 1.9, the AI recruits units based on a ''recruitment_pattern'' AI parameter. This sometimes can lead to non-optimal scout recruiting, etc. The following code attempts to remedy this by suggesting that certain units be recruited on certain hexes to improve village grabbing, etc. (but could also be used to recruit a wider variety of units within each ''recruitment_pattern'' parameter).

This code specifies to recruit an appropriate ''scout'' unit (from default faction units) to grab a village 8 tiles away on (7, 24) by flat for side 4. *Note: undead scouts are excluded as ghost only moves 7 hexes and saurians as they move only 6, with quick scout moving 7.

[event]
name=turn 1

#recruit 8 movement scout unit to get village(7,24) fast
{MODIFY_AI_ADD_CANDIDATE_ACTION 4 main_loop (
[candidate_action]
id=recruit_scout
name=recruit_scout
engine=fai
type=movement
evaluation="if(turn=1 and unit_at(loc(7,24))=null(), {AI_CA_RECRUITMENT_SCORE}+400, 0)"
action="recruit(scout_units[(1 d size(scout_units))-1],loc(7,24))
where scout_units=map(filter(my_recruits,usage='scout' and undead=0 and id!='Saurian Skirmisher'),id)"
[/candidate_action]
)}
[/event]

#delete at turn 2, as we should have the wanted scout recruited by then
[event]
name=turn 2

{MODIFY_AI_TRY_DELETE_CANDIDATE_ACTION 4 main_loop recruit_scout}
[/event]

The evaluation is for turn 1 because this is when we want to recruit this particular unit here. It also checks to see if there is already a unit on this hex as the candidate actions are run more than once. With a score of {AI_CA_RECRUITMENT_SCORE}+400, this formula will be evaluated just before the regular recruitment stage and simply adds to it.

=== Specifying scouts not attack whilst scouting ===

In addition to specifying that scouts should be recruited on certain hexes, an ''aspect'' can be set so that the AI does not choose to attack whilst it could be scouting instead. An example code for this is:

[side]
side={SIDE}
[ai]
{MODIFY_AI_ADD_ASPECT {SIDE} attacks (
[facet]
name=testing_ai_default::aspect_attacks
id=hold_off_initial_scout_attack
invalidate_on_gamestate_change=yes
[filter_own]
[not]
type="Cavalryman,Drake Glider,Elvish Scout,Footpad,Ghost,Gryphon Rider,Vampire Bat,Wolf Rider"
[/not]
[/filter_own]
[/facet]
)}
[/ai]
[/side]
[event]
name=turn 3
{MODIFY_AI_TRY_DELETE_ASPECT {SIDE} attacks hold_off_initial_scout_attack}
[/event]

The above code stops the calculation of combat for the units matching the ''filter_own'' ''Single Unit Filter'' expression. The turn 3 event deletes this changed behavior (presumably after the scouts have collected a village).

This approach might also be useful for when it is desired that a certain unit or type of unit should not attack. Alternatively, it could be useful to specify that a beserker, say, should not attack unless a formula AI candidate action expression evaluates to > 0 (be careful that you don't rely on the built-in calculation functions though, as they are not executed with this aspect set).

== Home guards ==

A "home guard" is a variant on the "guardian" AI special. With this variant, the unit has an assigned "home" location, and the unit will return there if not involved in combat and if not going to a village, whether for healing or to capture it this turn. (The standard guardian AI will cause the unit to stay where it last attacked.) This differs from the [[Lua_AI_Code_Library#Return guardian AI special|Lua return guardian]] in that a home guard will press the attack, possibly getting drawn quite far from "home", rather than returning after each attack.
(It can also be lured away by a string of closely-placed villages, but that is something a map builder can control.)

If a home guard is being created at the location it will guard, the following macro can be used (instead of the usual {UNIT} macro).
<pre>
#define HOME_GUARD_UNIT SIDE TYPE X Y WML
# Creates a unit of TYPE belonging to SIDE at X,Y, which will
# return to its spawn location if it has no one to attack (and
# no need for healing).
{UNIT {SIDE} {TYPE} {X} {Y} (
[ai]
[vars]
home_loc="loc({X},{Y})"
[/vars]
[/ai]
{WML}
)}
#enddef
</pre>
A home guard does not have to be created in the location it will guard though. The following macro can be used after creating a unit to specify a home location independent of where the unit was created (c.f. the core {GUARDIAN} macro).
<pre>
#define HOME_GUARDIAN X Y
# Meant to be used as a suffix to a unit-generating macro call.
# The previously-generated unit will treat (X,Y) as its home.
[+unit]
[ai]
[vars]
home_loc="loc({X},{Y})"
[/vars]
[/ai]
[/unit]
#enddef
</pre>

These macros alone are not enough to get home guardian behavior, though; they merely mark the units. In order to get the behavior, a [[candidate action]] is required. The following macro defines the candidate action. It can be used much the same as the core "AI_CA_*" macros, either as part of an AI definition or added later, perhaps with {MODIFY_AI_ADD_CANDIDATE_ACTION}.
<pre>
#define AI_CA_HOME_GUARDIAN
[candidate_action]
engine=fai
name=go_home
type=movement
evaluation="if( (null != me.vars.home_loc), {AI_CA_MOVE_TO_TARGETS_SCORE}+10, 0)"
action="if( (me.loc != me.vars.home_loc), move(me.loc, next_hop(me.loc, me.vars.home_loc)), move(me.loc, me.loc)#do not move this turn#)"
[/candidate_action]
#enddef
</pre>

(These macros come from a work-in-progress by JaMiT.)

[[Category:AI]]

Formula AI Howto

2012-11-27T16:41:55Z

Alarantalara: Add AI Category

This page is meant as a practical guide for setting up and testing Formula AI functionality in a scenario. It does not give a complete description of the Formula AI language. See [[FormulaAI]] and [[FormulaAI Functions]] for that. In addition, the first post in [http://forums.wesnoth.org/viewtopic.php?f=10&t=27839 this thread] links to a file with (not quite complete but useful) information about Formula AI functions and variables.

Make sure you have read the [[General RCA AI Howto]] as a basic understanding of the purpose of AI engines, stages and candidate actions is assumed here.

Also note that we do not explain all the different ways of setting things up here. Instead, we focus on one specific method that works reasonably well. Using variations thereof will hopefully be straightforward once the principles are understood.

==Formula AI Setup==

Unlike [[Lua AI Howto|Lua AI]], Formula AI does not require an engine to be set up, and (usually) no global variables need to be defined up front either. Thus, only one component needs to be set up, the stage, or stages, controlling Formula AI behavior. Three different stages are available for Formula AI code:
*[[Customizing_AI_in_Wesnoth_1.8#A_stage_to_execute_unit_formulas|Formula AI ''unit_formulas'' stage]]: executes unit-specific Formula AI moves
*[[Customizing_AI_in_Wesnoth_1.8#A_stage_to_execute_side_formulas|Formula AI ''side_formulas'' stage]]: executes side-wide Formula AI moves
*[[Customizing_AI_in_Wesnoth_1.8#Working_with_main_loop_of_the_RCA_AI|RCA AI ''main_loop'' stage]] (''cpp''): the standard AI stage with its candidate actions

The stages are executed in whichever order they are put into the side tag. That is to say, all the moves of the first stage in the [[AiWML|[ai]]] tag are played out first, then all the moves of the second stage, and so on until the last stage. Then the turn ends.

Note: The [[AI Module]] module page mentions another Formula AI stage called ''rca_formulas''. However, that stage does not exist in the current Wesnoth version.

===Setting up the Formula AI ''unit_formulas'' Stage===

This stage executes formulas that are attached directly to specific units. To set it up, simply put the following code into the AI's [[SideWML|[side]]] tag:

[ai]
version=10710
[stage]
engine=fai
name=unit_formulas
[/stage]
[/ai]

The first line is required and ensures that we are using the latest version of the AI. 'name' and 'id' keys can also be assigned to the stage, in case we want to remove it later.

Let's now set up a unit that does nothing but move one hex south each turn by adding an [ai] tag to the unit definition:

[unit]
x,y=10,4
id = Rark
type="Saurian Augur"
name="Rark"
[ai]
formula="move(me.loc, loc(me.loc.x, me.loc.y + 1))"
[/ai]
[/unit]

Here, the variable ''me'' is set automatically and contains all the unit information, with ''loc'' being a table containing its coordinates in ''x'' and ''y'' sub-fields. See the [[Formula_AI_Howto#Testing_Setup|Testing]] section below for information on how to query what fields a unit variable such as ''me'' contains.

This is all that is needed. The unit defined above will move one hex south each turn until it hits an obstacle. It will do nothing else, as 'move()' results in the movement points being set to zero afterward.

Unit formulas can be attached to any unit on the map. If the order in which the units do their moves matters, a priority can be set:

[unit]
...
[ai]
formula="move(me.loc, loc(me.loc.x, me.loc.y + 1))"
priority=10
[/ai]
[/unit]
Units with the highest priority get their moves executed first.

Note: if the above is the only [[AiWML|[ai]]] tag of the [[SideWML|side definition]], the AI will ''only'' do this ''unit_formulas'' move and nothing else at all. In order to also have other behavior, other stages, such as those described in the following sections or additional ''unit_formulas'' stages, can be added to this [ai] tag (or be placed in their own [ai] tags).

===Setting up the Formula AI ''side_formulas'' Stage===

Side-wide formulas are set up very similarly to the unit-specific formulas. Here is an example of a stage that moves all units with movement points left one hex north:

[ai]
version=10710
[stage]
engine=fai
name=side_formulas
move="
if( size(units) != 0,
move(units[0].loc, loc(units[0].loc.x, units[0].loc.y - 1)),
end
)

where units = filter(my_units, movement_left > 0)
"
[/stage]
[/ai]

The 'version' line is again required and the stage can also be given 'name' and 'id' keys, as before. The main difference here is that we now have one move that applies to all the units of the AI side, resulting in the ''me'' variable not being set. Thus, we first need to find all the units of our side (stored in ''my_units'') which have movement left and store them in the ''units'' variable (a table). If the length of the table is not zero, the first unit gets moved one hex north. It now has no movement points left (because 'move()' is used, not 'move_partial()') and is therefore not chosen on the next iteration of the ''side_formulas'' stage. The stage repeats this action until no unit with movement left is found, in which case the 'if' function returns 'end'.

A few notes:
* If the code gets too long, it might make more sense to put it into a file and include it with
move={filename.fai}
instead of including it directly as is done above.
* If this stage is put into the [ai] tags ''in addition'' to the unit-specific stage of the previous section, the outcome depends on the order of the stages:
** If the ''unit_formulas'' stage comes first, Rark is moved south, then all other units are moved north.
** In the opposite order, all units including Rark are first moved north. We then get an error message when the ''unit_formulas'' stage tries to move Rark south because he has no movement points left.

===Setting up the RCA ''main_loop'' Stage and Candidate Actions===

The ''unit_formulas'' and ''side_formulas'' stages are somewhat limited when it comes to complex AI behavior. If a more versatile tool is needed, the candidate actions (CAs) of the RCA AI ''main_loop'' stage provide a powerful framework for setting up variable and adaptable AI behavior. Here is how this stage is set up:

[ai]
version=10710
[stage]
id=main_loop
name=testing_ai_default::candidate_action_evaluation_loop
{AI_CA_GOTO}
{AI_CA_RECRUITMENT}
{AI_CA_MOVE_LEADER_TO_GOALS}
{AI_CA_MOVE_LEADER_TO_KEEP}
{AI_CA_COMBAT}
{AI_CA_HEALING}
#{AI_CA_VILLAGES}
#{AI_CA_RETREAT}
{AI_CA_MOVE_TO_TARGETS}
{AI_CA_PASSIVE_LEADER_SHARES_KEEP}

[candidate_action]
engine=fai
name=go_south
type=movement
evaluation="if((me.hitpoints < me.max_hitpoints), 60010, 0)"
action="move(me.loc, loc(me.loc.x, me.loc.y + 1))"
[/candidate_action]
[/stage]
[/ai]

Note that we have two of the default CAs commented out. If all of them were used unaltered, we could simply use
{ai/aliases/stable_singleplayer.cfg}
inside [[SideWML|[side]]] (but outside [[AiWML|[ai]]]) instead. The advantage of listing them specifically is that individual CAs can then be commented out (as is done here) and/or replaced by custom CAs. [Note that it is important not to add a second stage if 'stable_singleplayer.cfg' is included, even if it has the same name and id as the ''main_loop'' stage, if your new candidate action is to be evaluated against all the default CAs. See the [[Lua_AI_Code_Library#Swamp_Lurker_Moves|swamp lurker moves]] example, and in particular the last note, for an explanation of how this can be done (yes, that's a Lua AI example, but this particular point applies here as well).]

In this example, the default ''villages'' and ''retreat'' CAs are replaced by a custom-built CA. This CA uses the ''fai'' engine and is given user-defined name ''go_south''. It is of type ''movement'', which means that the evaluation code is called once for every unit of the AI's side that has movement points left, and that this unit is passed to the evaluation and action code in variable ''me''.

In this case, as very simple evaluation returns 60,010 if unit ''me'' has less than perfect hitpoints. It returns 0 otherwise. Thus, wounded units that can still move are given an evaluation score below the ''healing'' CA (80,000), but above ''villages'' (60,000). If this is the highest score of any of the CAs with valid moves left, the action code (note that this is 'action', not 'execution' here) is called, which moves the unit(s) one hex south. (Not a particularly useful CA, but easy to understand for demonstration purposes.)

It should be noted that the commenting out of the ''villages'' and ''retreat'' CAs is not actually necessary here. If valid ''go_south'' moves are found, a score of 60,010 is returned, which is higher than those of ''villages'' (60,000) and ''retreat'' (40,000). Thus, ''go_south'', if possible, is always executed before these two. As it uses 'move()', not 'move_partial()', which leaves a unit with no movement points, no other movement actions can take place for this unit afterward. [One difference remains however: if the standard CAs are commented out, then ''no'' unit will retreat or go to villages. If they are included, only units with non-perfect HP will go south, the rest might still do retreat or go-to-villages moves.]

Other notes:
* '''Important''': The evaluation functions '''may not''' change the game state. Doing that can lead to errors and crashes.
* More complicated code should, again, be included from a file, for both evaluation and action.
* The other possible 'type' of candidate action is ''attack'', which is called once for every <''me'', ''target''> pair, where ''me'' is a variable set to a unit on the AI side, and ''target'' is a variable set to an enemy unit that ''me'' can reach
* A [filter] tag can be passed to the Formula AI CA that preselects only units passing the filter for evaluation. Thus, the previous candidate action could also be written as:

[candidate_action]
engine=fai
name=go_south
type=movement
[filter]
me="filter(input, (input.hitpoints < input.max_hitpoints))"
[/filter]
evaluation=60010
action="move(me.loc, loc(me.loc.x, me.loc.y + 1))"
[/candidate_action]

For ''attack'' type CAs, an equivalent 'target=...' line can be included in the filter.

===A Simpler Method for Adding Candidate Actions===

The previous method demonstrates the full setup of the RCA AI ''main_loop'' stage and candidate actions. If we only want to add stages, or delete individual standard stages, a simpler approach is possible. We can simply add (or delete) these candidate actions using the macros in [http://www.wesnoth.org/macro-reference.html#file:ai.cfg core/macros/ai.cfg], without the need for defining the stage and standard CAs. For example, the above stage could be added simply as:

[ai]
{MODIFY_AI_ADD_CANDIDATE_ACTION {SIDE} main_loop (
[candidate_action]
engine=fai
name=go_south
type=movement
[filter]
me="filter(input, (input.hitpoints < input.max_hitpoints))"
[/filter]
evaluation=60010
action="move(me.loc, loc(me.loc.x, me.loc.y + 1))"
[/candidate_action]
)}
[ai]

with no need for a version number or a [stage] tag. Thus, this method is both simpler and does not depend on the number of the most current AI version. See [[Formula_AI_Howto#Adding_.2F_Deleting_Stages_and_Candidate_Actions|Adding / Deleting Stages and Candidate Actions]] below for more on this topic and the [[Formula_AI_Code_Library|Formula AI Code Library]] for examples making use of this method.

==Testing Setup==

Testing Formula AI code is, in principle, very easy. Simply type 'f' in the Wesnoth window (which accesses the Formula AI command line) and then enter the code to be executed. That's a lot of typing, however. It is easier to put the code into a file (say '~add-ons/FAI_tests/fai_manual.fai') and run it by typing
run_file('~add-ons/FAI_tests/fai_manual.fai')

Still easier is to include that line as a comment in the file itself and copy it to the Formula AI command line. Then we can simply type 'f' and 'cmd-v' (or whatever the paste keyboard shortcut is) to execute our test code. As an example, consider this file:

fai 'fai_manual.fai'
# run_file('~add-ons/FAI_tests/fai_manual.fai') #
# ---- Place test code below ----- #

dir(self)

# ---- Place test code above ----- #
faiend

Here, the first and last line are technically unnecessary, but it is good practice to include them in all Formula AI files as they can be useful for debugging purposes. The second line is the 'run_file' command mentioned above, that can now be easily copy-pasted into the Formula AI command line. Note that comments in Formula AI require the '#' symbol both at the beginning and end of the line.

The body of this example is a very simple, but powerful command: 'dir(self)'. It displays all available Formula AI variables. Its output shows that there is a variable ''my_units''. If we want to see the structure and content of this variable, we replace the body of the file above with
my_units
or type that at the command line, since it is so short. In order to get the first of these unit, use
my_units[0]
and for its location (many Formula AI functions use the unit location)
my_units[0].loc
To select the unit with id "Rark", we type
filter(my_units, id='Rark')[0]
and if we wanted to do this using a function
def get_unit(ai*, unit_id)
filter(my_units, id = unit_id)[0];

get_unit(self, 'Rark')

In the function call, ''self'' passes the set of Formula AI variables to the function, the same set that was queried with 'dir(self)' above. It is put into variable ''ai'' in the function, with the '*' denoting ''ai'' as an implicit variable (meaning the variable holding the units can be accessed with ''my_units'' instead of ''ai.my_units).

So much for some very simple examples. For full documentation of the Formula AI language see [[FormulaAI]] and [[FormulaAI Functions]]. We are now ready for testing AI behavior. Let's assume that we have set up a test situation with one of our units (id = "Rark") and an enemy unit (id = "Krar") within reach of Rark. We want to test how to move Rark to the hex south of Krar. The body of '~add-ons/FAI_tests/fai_manual.fai' is now

move(me.loc, loc(target.loc.x, target.loc.y+1))

where me = filter(my_units, id = 'Rark')[0]

where target = filter(enemy_units, id = 'Krar')[0]

The important thing here is that we have now set up a mechanism that creates the ''me'' and ''target'' variables as they are used in some of the stages described above. We can replace the move used here with whatever AI behavior we want to test. Once we are done with testing, we can simply copy the code above the two 'where' lines into the AI stages or candidate actions.

Note that the Formula AI functions and variables do not need to be initialized. They are available at every turn for each side. Thus, we do not need to go through the tricks described for testing [[Lua_AI_Howto#Testing_setup|Lua AI]], but can simply set up Side 1 with 'controller=human' and start with the testing.

== Adding / Deleting Stages and Candidate Actions ==

Stages and candidate actions can be added and removed at any time in the scenario. A large number of macros are available in [http://www.wesnoth.org/macro-reference.html#file:ai.cfg core/macros/ai.cfg] for this purpose.

Here are two code examples of deleting candidate actions from the default RCA AI stage taken from [[Customizing_AI_in_Wesnoth_1.8]]. The first is done right at the beginning during the side definition:

[side]
side=2
{ai/aliases/stable_singleplayer.cfg}
[ai]
{MODIFY_AI_DELETE_CANDIDATE_ACTION 2 main_loop recruitment}
{MODIFY_AI_DELETE_CANDIDATE_ACTION 2 main_loop move_leader_to_keep}
[/ai]
[/side]

The second is done in an event:
[side]
side=2
{ai/aliases/stable_singleplayer.cfg}
[/side]
[event]
name=some_event
{MODIFY_AI_DELETE_CANDIDATE_ACTION 2 main_loop recruitment}
{MODIFY_AI_DELETE_CANDIDATE_ACTION 2 main_loop move_leader_to_keep}
[/side]

== Examples: Formula AI Code Library ==

Many examples of Formula AI code can be found found in the [[Formula AI Code Library]] page and in [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976 this forum thread].

[[Category:AI]]

LuaAI

2012-11-27T16:40:54Z

Alarantalara: Add AI Category

This is a page containing information on configuring the AI using Lua. In addition to the technical information on this page, a tutorial-style guide is also available at [[Lua AI Howto]].

NB: previous contents of the page moved to http://wiki.wesnoth.org/LuaAI(old)

== Aspects ==
Patch r49721 enabled users to write aspects using Lua. This simplifies the definition of aspects that are meant to change depending on the game state. A good example could be aggression, which changes depending on the time of the day(since ToD affects the actual battle performance of your forces). 
Static aggression:
[aspect]
id="aggression"
engine="lua"
value="0.3"
[/aspect]
Dynamic aggression:
[aspect]
id=aggression
engine=lua

code=<<
wesnoth.fire("store_time_of_day")
local value = 0
tod = tostring(wesnoth.get_variable('time_of_day').name)
if (tod == 'Morning') then
value = 0.2
else
value = 1
end

wesnoth.fire("clear_variable", {name = "time_of_day"})
return value
>>
[/aspect]

Note: the way of getting the ToD is hacky here, but I will create a more elegant method soon(Nephro). 
Also note the difference between 'code' and 'value' attributes, this is important. 
At the moment, it is possible to create the following aspects using Lua(the list will be constantly updated):
aggression // double
attack_depth // int
avoid // exposed as map_location[], where map_location is a table of form {x, y}
caution // double
grouping // string
leader_aggression // double
leader_goal // exposed as a config
leader_value // double
number_of_possible_recruits_to_force_recruit // double
passive_leader // bool
passive_leader_shares_keep // bool
recruitment_ignore_bad_combat // bool
recruitment_ignore_bad_movement // bool
recruitment_pattern // string[]
scout_village_targeting // double
simple_targeting // bool
support_villages // bool
village_value // double
villages_per_scout // int

Note: simple numeric, bool and string aspect creation can be enabled just by adding a specific factory to registry.cpp, this will also soon be done.

To get the value of a specific aspect in Lua we have to use the
ai.get_<aspect_name>()
function. E.g.
local aggression = ai.get_aggression()

== Preload event ==

It is a good idea to have such a preload event in your scenario if you are intending to use Lua for AI programming or customizing. The code of this event will most probably be moved out to a macro(except for the line that requires patrol.lua, since it is not necessary).

[event]
name=preload
first_time_only=no
[lua]
code = <<
H = wesnoth.require "lua/helper.lua"
W = H.set_wml_action_metatable {}
_ = wesnoth.textdomain "my-campaign"
ai = {}
ca_counter = 0

H.set_wml_var_metatable(_G)

wesnoth.require("ai/lua/patrol.lua")

>>
[/lua]
[/event]

The code attribute can be further expanded by any Lua code needed. For example, we can set up some global variables there or include additional code libraries("wesnoth.require("ai/lua/patrol.lua")" - includes code that handles patrolling of units).

== Engine code ==

In the engine tag you should define functions that will handle evaluation and execution of your custom candidate actions and stages. You can also run some code that is intended to be run once in the beginning. 
The definition of the [engine] tag should be place inside the [ai] tag.

[engine]
name="lua"
code= <<
-- your engine code here
>>
[/engine]

== Stages ==
Once the engine has been set up, we can start adding stages to the configuration of our AI. 
To add a stage we just use the [stage] tag.
[stage]
engine=lua
code=<<
-- Code for stage execution here
-- It is better to call predefined functions for the [engine] code,
-- than to define the functions here, to keep the structure of the stages clear
>>
[/stage]

== Candidate actions ==
This is an example from the current version of the lua_ai arena. The stage with an id "ca_loop" is the RCA AI loop stage, as we can see from its name. Currently it has two candidate actions, both Lua backed.

[stage]
name=testing_ai_default::candidate_action_evaluation_loop
id=ca_loop
[candidate_action]
engine=lua
name=first
id=firstca
evaluation="return (...):candidate_action_evaluation_hello()"
execution="local ai, cfg = ...; ai:candidate_action_execution_hello(cfg)"
[/candidate_action]
[candidate_action]
engine=lua
name=second
evaluation="return (...):candidate_action_evaluation_hello2()"
execution="(...):candidate_action_execution_hello2()"
[/candidate_action]
[/stage]
Basically, we need to have an engine attribute, an evaluation and execution functions. The syntax (...):foo() means "call eng.foo(eng) where eng is whatever the engine code returns". We can also add, remove, modify candidate actions on the fly, using wesnoth.wml_actions.modify_ai() functionality. Behavior(sticky) candidate actions use this approach.

== Behavior(sticky) candidate actions ==
Sometimes we need a specific unit to do a specific action in our scenario, e.g. we want a scout unit to patrol between 3 places on the map, to provide us with visibility needed. In this case we can create a sticky candidate action that will tie itself to the unit, and remove itself when the unit has died. The syntax for defining a sticky candidate action is the following:
[event]
name=side 2 turn 1
first_time_only=yes
[add_ai_behavior]
side=2
[filter]
name="Rark"
[/filter]
sticky=yes
loop_id=ca_loop
evaluation="return patrol_eval_rark()"
execution="patrol_rark()"
[/add_ai_behavior]
[/event]
Here the behavior CA is added to the configuration of the AI when the event triggers. Obviously this will happen when side 2 gets its first turn, but the event can be whatever needed. The definition is very similar to a simple candidate action, but here we also filter out a unit and state that we want the behavior to be sticky. If we don't, the action will not try to remove itself, when the unit gets killed, and this could cause errors. 
Such CA`s can also be added from inside other CA or stage code using wesnoth.wml_actions.add_ai_behavior(cfg) function.

== Behavior function library ==
Behaviors are defined using generators. A behavior generator receives arguments(unit info, configuration, etc) and returns a pair of functions: evaluator and executor. These functions are to be passed to the add_ai_behavior tag, or directly to the function.
=== Patrolling ===
The only behavior defined at the moment is the patrol behavior. After calling patrol_gen(name, locations), we receive a pair of functions to use for creation of candidate actions 
Inclusion of the patrolling code:
wesnoth.require("ai/lua/patrol.lua")
Usage:
local patrol_rark = patrol_gen("Rark", {{x=14, y=7}, {x=15, y=7}, {x=15, y=8}, {x=14, y=8}})
-- patrol_rark.exec -- execution function
-- patrol_rark.eval -- evaluation function
As you can see, the first argument is the name of the unit, the second is a table of coordinates of arbitrary length.

==Goals and targets==

When deciding what move to do next, the AI uses targets(markers on the map, pointing to villages, units, locations, etc). Targets are produced by goal objects. There are multiple predefined goal objects of different types in the C++ implementation, but now it is possible to define goal objects in Lua.

[goal]
name=lua_goal
value=6
engine=lua
code = <<
local t = {
t[1] = {value=2.3, type=3, loc={x=5, y=6} }
t[2] = {value=2.4, type=4, loc={x=4, y=16} }
}
return t
>>
[/goal]

As you can see, the return value must be a table containing 0 or more targets. Each target must contain the three fields: "loc", "type", "value". This code will then be parsed by the Lua engine and the targets will be available to use to any engine desired. To get the targets inside Lua, a simple
local tg = ai.get_targets()
must be called. tg will contain a table of the same format, as one described in the goal definition code upper.

== Persistence ==

If you need to store some data between save/load routines, you probably need a place to store the data. For this purpose, a field named "data" is automatically added to the return value of your engine code. The save routine will find this field, convert it to a config and store its content in readable format. When the scenario gets loaded back, the engine code will inject the data back in the AI context. All other data will be lost. Note that all content of "data" needs to be in WML table format, otherwise it will not be saved.

== Debug access to the AI tree ==

wesnoth.debug_ai(side)
-- has been added. The function only works in debug mode and returns a table containing the component tree of the active AI for a side, the engine functions and the accessor to the ai.* table of the LuaAI Also allows the user to execute stages and evaluate/execute candidate actions(eval and exec can be run independently).

Structure of the table(example):

{
stage_hello = function: 0x6dc24c0,
get_ai = function: 0x6dc25d0,
data = {
},
do_moves = function: 0x6dc2590,
candidate_action_evaluation_hello = function: 0x6dc2560,
candidate_action_evaluation_hello2 = function: 0x6dc2640,
components = {
id = "",
stage = {
another_stage = {
name = "another_stage",
id = "",
exec = function: 0x17cd3bb,
engine = "lua",
stg_ptr = "userdata: 0x7c5a8d0"
},
testing_ai_default::candidate_action_evaluation_loop = {
name = "testing_ai_default::candidate_action_evaluation_loop",
candidate_action = {
external = {
name = "external",
id = "",
exec = function: 0x17cd2f3,
engine = "lua",
ca_ptr = "userdata: 0x6fb3600"
},
second = {
name = "second",
id = "",
exec = function: 0x17cd2f3,
engine = "lua",
ca_ptr = "userdata: 0x6fb2f50"
}
},
id = "ca_loop",
exec = function: 0x17cd3bb,
engine = "",
stg_ptr = "userdata: 0x6fb2728"
}
},
engine = "",
name = ""
},
candidate_action_execution_hello2 = function: 0x6dc2670,
candidate_action_execution_hello = function: 0x6dc2530
}

The fields described as " name = function: 0xXXXXXXXX" are functions and can be called to using the usual function call syntax of Lua.
wesnoth.debug_ai(2).get_ai() -- will return the AI table of the Lua AI context.

wesnoth.debug_ai(2).stage[another_stage].exec() -- will execute the stage.

wesnoth.debug_ai(2).get_ai().get_aggression() -- will the return the current value of the aggression aspect of the AI

Therefore, we have up-to-date access to the whole AI, including the data segment.

NB!: the back-end of this function will be refactored quite drastically and that may involve usage syntax changes. This shouldn't be a big problem, since this function is only used for debugging and won't work in non-debug mode. If something suddenly stops working for you, come back to this page and watch the updates.

[[Category:AI]]

AiWML

2012-11-27T16:39:23Z

Alarantalara: Add AI Category

{{WML Tags}}

As of Wesnoth 1.9, the default AI is the RCA AI, which stands for Register Candidate Action AI. During the AI turn, the RCA AI evaluates a number of potential actions (called candidate actions) for each move. The candidate action with the highest evaluation score is executed. Then the next move is evaluated in the same way, until no more valid moves are found. This 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 [[AiWML#Aspects_and_Goals_Overview|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.

'''Notes on available AIs:'''
* The default AI used through Wesnoth 1.8 was named 'Default AI' (note the capital D). This might cause confusion, as the current default AI (RCA AI) is not the Default AI.
* Besides the RCA AI, the only other AI available in the core distribution is ''idle_ai'', which does nothing at all (see ''ai_algorithm'' [[AiWML#The_.5Bai.5D_Tag:_Defining_Aspects|below]]).
* The [[General_RCA_AI_Howto#Available_Stages|fallback stage]], which used to fall back to the old Default AI, now falls back to the RCA 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 and the process is repeated, 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 [[SingleUnitWML|goto_x, goto_y]] in their unit WML.

*'''Recruitment''' CA: Recruit or recall units.

*'''Move leader to goals''' CA: Move the leader toward goals set by [[AiWML#The_.5Bai.5D_Tag:_Defining_Aspects|[leader_goal]]].

*'''Move leader to keep''' CA: Move the leader toward the closest available keep.

*'''Combat''' CA: Attack enemy units that are in range. Note that this CA includes the move to a hex adjacent 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 or hopelessly outnumbered, and if so, retreat them.

*'''Move to targets''' CA: Evaluate potential [[AiWML#AI_Targets_and_Goals|targets]] and move units toward them. The evaluation takes into account how valuable the targets are (this is configurable by setting [[AiWML#Aspects_and_Goals_Overview|goals]]), how easily the AI's units can get there, how exposed to attacks they will be, etc. Targets are enemy leaders, enemy units that pose a thread to the AI leader and villages, as well as anything defined as a goal. It is important to understand that targets only apply to the move-to-targets CA. If a target is within range of the AI's unit(s) on the current turn, other CAs, such as combat, healing and villages have a higher evaluation score and are (usually) executed first. Thus, a target is specifically ''not'' an attack target, but 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 the next move, they are prioritized in the order given above. For example, the Goto CA is always the first move that is done (if ''goto_x'' and ''goto_y'' are defined and a move toward them is possible). 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 have priority over any goals/targets of the move-to-target phase.

== Aspects and Goals Overview==

'Aspects' are configurable parameters used in the candidate action score evaluation. Most commonly, aspects are set using the [[AiWML#The_.5Bai.5D_Tag:_Defining_Aspects|[ai] tag]], but there are several other methods as well, as described [[AiWML#A_Bit_More_on_Simple_vs._Composite_Aspects|here]] and [[AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag|here]]. 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', which define AI '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 [[AiWML#AI_Targets_and_Goals|their own subsection]] below.

== The [ai] Tag: Defining Aspects ==

The [ai] tag is used inside a [side] or [modify_side] tag. Its contents are the AI [[AiWML#Aspects_and_Goals_Overview|aspects]] and 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 it receives reinforcements on a specific turn.

[Note: if you use a different AI engine, [[FormulaAI]] or [[LuaAI]], setting aspects in the [side] tag might not work the standard way and you might have to use [modify_side] in an event instead. You can use ':inspect' in debug mode to verify whether an aspect was changed successfully.]

The following keys/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 also [[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 only comes with ''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 in the [side] tag outside all [ai] tags.

* '''aggression'''=0.4: (double: ranging from -infinity to 1.0) This key affects how the AI selects its attack targets. The higher the value, the more likely the AI is to attack even if odds are not in its favor. Applies to combat CA only.
** In the attack evaluation, each attack (this includes attack combinations of several AI units against the same enemy unit) is assigned a score. The attack with the highest score is done first. Then the next attack is evaluated, until no attack with a score greater than 0 is found any more. (Note that this ''attack score'' is different from the ''combat CA score'', which is always 100,000 as long as an individual attack score >0 is found. The combat CA score is zero if the highest attack score is <=0).
** The attack score is a complex combination of many different aspects of the attacks. Positive (additive) contributions to the score are things like the value (cost and XP) of the target, the chance to kill the target, whether it is already wounded, how much damage the attack is likely to inflict, etc. Negative (additive) factors include how much damage the AI's units are likely to take, how valuable they are, how exposed they will be after the attack, etc. There are also multiplicative factors that are used if the attack target is a threat to the AI's leader etc.
** All the negative contributions to the score are multiplied by '(1-aggression)'. This means that:
*** If 'aggression=1', no negative contributions are added to the score. Thus, the AI disregards damage done to its own units and selects attacks based solely on the damage it can do to enemy units. If the AI can inflict 1 damage and take 0, or inflict 2 damage and take 20, it will take the latter option.
*** The smaller the value of ''aggression'', the more weight is put on value of and potential damage to the AI's units as compared to the attack target.
*** Roughly speaking, 'aggression=0' results in the AI valuing its units approximately as much as the enemy units. This is not a one-to-one relation, but can be used as an approximate guideline.
*** Very large negative values of ''aggression'' mean that the value of the AI's units is much more important than that of the enemy units. As a result, the AI never attacks unless it will receive no damage in exchange.
** Note: ''aggression'' is always set to 1.0 for attacks on units that pose a direct threat to the AI's leader. Currently this only means units adjacent to the leader.

*'''[attacks]'''="": Filters the units considered for combat, both on the AI and the enemy sides. Applies to the combat CA only. It cannot be set in the same way as the other aspects and is therefore described in a [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|separate section]] below.

* '''[avoid]'''="": Makes the AI avoid specific locations. The AI never moves a unit to these locations except for trying to move its leader to a keep or toward [leader_goal]s, and thus applies to all CAs except move-leader-to-goals and move-leader-to-keep.
** '''[[StandardLocationFilter]]''': The locations for the AI to avoid. Do not use a [filter_location] tag.

* '''caution'''=0.25: (double) Defines how cautious the AI is in several ways. It determines whether the leader should move toward [leader_goal], if attacks are worth moving onto less favorable terrain, whether units should retreat, and whether the AI should move units toward targets individually, as groups or not at all. Affects several CAs (listed in the order of their [[AiWML#Evaluating_AI_Moves_--_Candidate_Actions_.28CAs.29|evaluation scores]]):
** Move-leader-to-goals CA: If ''max_risk'' is not set in [leader_goal], its default value is '1-caution'. This determines whether the leader takes the next step toward his goal. See description of [leader_goal].
** Combat CA:
*** During the evaluation of attacks, the AI considers whether the attacking units could get onto more favorable terrain if they didn't attack but moved somewhere else instead. The difference between the two terrain ratings, together with a number of other factors, determines the "exposure" rating of the units. This exposure is then subtracted from the 'attack score' as described for ''aggression'' above.
*** The exposure rating also contains a multiplication by ''caution'', meaning that 'caution=0' results in exposure not being taken into account, and that it becomes more and more important for larger values. In other words, the higher the values of ''caution'', the more reluctant is the AI to attack from unfavorable terrain. (Note that exposure is one of the negative contributions to the attack score as described for ''aggression'', and therefore is ignored if 'aggression=1' is set.)
*** If the AI leader is used in an attack, the AI ''always'' uses 'caution=2' for the evaluation of that attack.
** Retreat CA:
*** If caution is greater than 0, there is 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 by either side, reduced by terrain defense and relative hitpoints if attackers don't have full health. A retreat takes place, if caution * their_power > our_power There is also a terrain factor involved if the attacker is not on optimal terrain, similar to the exposure described above for the combat CA.
*** So let's say the AI has its default caution of 0.25. Then the enemy forces have to be at least 4 times as strong before the unit retreats. For a caution of 1, as soon as the enemy is stronger, the unit retreats.
*** The AI never retreats if caution is set to 0 or lower.
** Move-to-targets CA:
*** If grouping for the AI is enabled and the path along which to move toward a target is considered to be dangerous, caution has an influence, too. "Dangerous" mainly means that there is a good chance for a unit to be killed if it's by itself. In that case, the AI compares its units to the enemy units and based on the result moves forward or not. All units that can reach the next location of the move are considered. The formula for deciding whether to move toward the target as a group is our_strength / their_strength > 0.5 + caution If this condition holds true, units are moved toward the goal as a group, otherwise they try to group together in a location favorable for a attack on the enemy during the next turn.
***So if caution is 0.5, the AI side needs to be at least as strong as the enemy. If it is 0, the AI moves toward the target, even if the enemy is up to twice as strong as the AI. Setting caution to 1.5 means the AI needs to be at least twice as strong as the enemy.
*** The AI also considers retreating units during the move-to-target phase based on criteria similar to those for the retreat CA.

* '''[goal]'''="": Defines units or locations as [[AiWML#AI_Targets_and_Goals|targets]] for the AI. See the dedicated section on the [[AiWML#The_.5Bgoal.5D_Tag|[goal] tag]] below for details. Applies to move-to-targets CA only.

* '''grouping'''="offensive": (string) How the AI should try to group units. Applies to move-to-targets CA only. Possible values:
** ''offensive'': Makes the AI try to group units together before attacking.
** ''defensive'': Makes the AI group units together very conservatively, only advancing them much beyond its castle if it has overwhelming force.
** ''no'': Makes the AI use no grouping behavior.

* '''leader_aggression'''="-4.0": Exactly as aggression, but for units which can recruit. Applies to combat CA only. Note that the move-leader-to-keep CA has a higher score than the combat CA. A leader therefore usually only attacks if he is on his keep at the beginning of the turn, otherwise he moves toward the closest keep instead, even with ''leader_aggression=1''.

* '''[leader_goal]'''="": Makes the AI try to move its leader to a specific location. Applies to move-leader-to-goals CA only.
** '''x''', '''y''': The location toward which the AI should move its leader.
** '''auto_remove'''=no: (bool) If 'no' (default), the AI moves the leader to the goal, after which he stays there until [leader_goal] is [[AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag|removed manually]]. If 'yes', the leader_goal is removed upon the leader getting there. Important: this ''only'' works if ''id'' is set correctly (see the next bullet).
** '''id'''="": (string) An internal id key of the [leader_goal] tag. An id is required for ''auto_remove'' to work. However, setting this id does not automatically set the id of the [leader_goal] [[AiWML#A_Bit_More_on_Simple_vs._Composite_Aspects|facet]]. Thus, in principle for this to work, you need to set the id of the facet as described [[AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag|below]] ''and'' set the ''id'' key in [leader_value] to the same value. Since you are probably only going to use one [leader_goal] tag at a time, there is a much simpler way: setting 'id=0' (which refers to the first facet) or 'id=*' (which means all facets) in [leader_goal] allows ''auto_remove'' to work without the extra step of setting the facet id.
**'''max_risk'''=1-caution: (double: meaningful values are >=0) How much risk the leader may be exposed to by moving toward the goal. For evaluating this risk, the AI multiplies the leader's hitpoints by this number. The leader is only moved toward the goal if the resulting value is larger than the expected damage the leader is going to take during the next enemy turn. Thus, 'max_risk=0' means he will only move if no attack on him is possible at the target hex of the move. 'max_risk=1' (or larger) results in him moving even if he's almost certainly going to die.

* '''leader_value'''=3: (double) A number 0 or higher which determines the value of enemy leaders as [[AiWML#AI_Targets_and_Goals|targets]]. Affects move-to-targets CA only (and therefore specifically does not apply to attacks).

* '''passive_leader'''=no: (bool) If 'yes', the AI leader never moves or attacks (not even to move back to the keep or to attack adjacent units), except to obey [leader_goal]s. Affects all CAs except recruitment and move-leader-to-goals.

* '''passive_leader_shares_keep'''=no: (bool) If 'yes', this has most of the effects of ''passive_leader=yes'', but the AI leader moves 1 hex from the keep to share it with allied players (if they can reach it next turn). He also returns to keep to recruit when possible and attacks adjacent enemy units.

*'''recruitment'''="": Limits the number of units of a given type that the AI can have on the map simultaneously. Applies to the recruitment CA only. It cannot be set in the same way as the other aspects and is therefore described in a [[AiWML#Limiting_Recruiting_with_the_.27recruitment.27_Aspect|separate section]] below.

* '''recruitment_ignore_bad_combat'''=no: (bool) If 'yes', the AI does not analyze the enemy units on the map to see if the unit to be recruited is suitable for fighting them. Affects recruitment CA only.

* '''recruitment_pattern'''="": (string) This key takes a comma separated list containing the usages of the units that can be recruited. 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) and ''only'' those, so make sure the units you want recruited are really covered by the pattern, or use an empty pattern (the default) to have it consider all available units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]). Affects recruitment CA only.
** For example, "recruitment_pattern=fighter,fighter,archer" means that the AI recruits on average twice as many fighters as archers, and does not recruit scouts (other than scouts for capturing villages, which are recruited independently), healers or mixed fighters. It does ''not'' mean that it recruits two fighters first, then an archer, then two fighters again, etc.

* '''scout_village_targeting'''=3: (double) The AI multiplies the value of village [[AiWML#AI_Targets_and_Goals|targets]] for scouts by this value. Affects move-to-targets CA only.

* '''simple_targeting'''=no: (bool) If 'yes', the AI moves its units toward [[AiWML#AI_Targets_and_Goals|targets]] one by one (sequentially), without considering whether another unit might be better suited for the current move or target. If 'no' (the default), all units are considered for all targets. This is slower, but might result in better moves. Affects move-to-targets CA only.

* '''support_villages'''=no: (bool) Trigger a code path that tries to protect those villages that are threatened by the enemy. This seems to cause the AI to 'sit around' a lot, so it's only used if it's explicitly enabled. Affects move-to-targets CA only.

* '''village_value'''=1: (double) A number 0 or higher which determines how much the AI tries to go for villages as [[AiWML#AI_Targets_and_Goals|targets]]. Affects move-to-targets CA only.

* '''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. Affects recruitment CA only.

=== Deprecated AI Targeting Aspects ===

The following AI targeting parameters (aspects) currently still work, but have been superseded by the [[AiWML#The_.5Bgoal.5D_Tag|[goal] tag]]. They should not be used any more as they will likely be removed at some point. These tags specify [[AiWML#AI_Targets_and_Goals|targets]] and only apply to the move-to-targets CA.

* '''[target]'''="": '''Deprecated'''. Any number of [target] tags can be used to set targets 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 to a target worth '2.0' as for a target worth '1.0'. Applies to move-to-targets CA only.
** '''[[StandardUnitFilter]]''': Do not use a [filter] tag.
** '''value'''=1: (double) A number greater than 0 (default=1) which determines how much the AI tries to move toward units which pass the filter.

* '''[protect_location]'''="": '''Deprecated'''. Gives the AI a location to protect. Note that the AI does ''not'' station any units around the location, it only sends units to attack any enemy units that come within the guarding radius of the target. Applies to move-to-targets CA only.
** '''x''', '''y''': Standard coordinates. These indicate the location the AI is protecting.
** '''radius''': The radius around it to protect (0 indicates a single hex).
** '''value''': The importance of protecting this location.

* '''[protect_unit]'''="": '''Deprecated'''. Gives the AI a set of units to protect. Note once again that the AI does not place units around the protected units if there are no enemies nearby. Applies to move-to-targets CA only.
** '''[[StandardUnitFilter]]''': The unit(s) to protect. Do not use a [filter] tag.
** '''radius''': The radius around it to protect (0 indicates a single hex).
** '''value''': The importance of protecting this unit.

* '''protect_leader'''=2.0 and '''protect_leader_radius'''=10: '''Deprecated'''. Target any enemy units that come within 'protect_leader_radius' of the AI leader with a value of 'protect_leader'. Applies to move-to-targets CA only.

=== Removed AI Aspects ===

The following AI parameters (aspects) can still be set, their values can be retrieved, and they can be viewed in the gamestate inspector dialog, but they do not seem to have an effect in the RCA AI code any more. Some other parameters will also likely be removed in the future. We will update this list accordingly.

* '''attack_depth'''=5: (int)
* '''number_of_possible_recruits_to_force_recruit'''=3.1: (double)
* '''recruitment_ignore_bad_movement'''=no: (bool)

==AI Targets and Goals==

AI targets are used in the move-to-targets candidate action (CA) to move the AI's units toward selected units or locations. The AI engine automatically selects all enemy leaders, enemy units that pose a thread to the AI leader and unowned or enemy-owned villages as targets and assigns them certain base values. A score is then assigned to each target based on this base value, as well as on the movement cost required to get to the target, whether moving there would put the units involved in danger, etc.

It is possible to define additional targets or influence the relative ratings of the default targets. This is done with the [goal] tag, in which we can set criteria selecting targets and define their base values (which are then evaluated in the same way as the values of the default targets). Values set with the [goal] tag should always be relative to each other. The AI is willing to dedicate twice as many resources and travel twice as far to get to a target worth '2.0' as for a target worth '1.0'.

We stress again that these targets apply to the move-to-targets CA ''only'' and have no influence on other CAs. This is significant since CAs that deal with, for example, combat or village-grabbing have a higher score than the move-to-targets CA and are therefore always executed first. In practice that means that targets set with the [goal] tag only affect the AI behavior for targets that it cannot reach during the current turn, and only after combat, village-grabbing etc. are finished.

Five types of targets can be set using the [goal] tag: ''target'' (the default), ''target_location'', ''protect_unit'', ''protect_my_unit'', and ''protect_location''.

===The [goal] Tag===

The [goal] tag specifies target units or locations toward which the AI should move its units in the move-to-targets CA. The following keys/tags can be used:
* '''name'''="target": (string) The following values are possible and result in different types of targets:
** ''target'': The (default) target goal specifies target units (not necessarily enemy units) toward which the AI should move its units.
** ''target_location'': Specifies target locations toward which the AI should move its units.
** ''protect_location'': Specifies locations that the AI should protect. Enemy units within the specified distance (''protect_radius'') of one of these locations are marked as targets with the provided value. Note that the AI will ''not'' station any units around the protected locations. It will only send units toward enemy units that come within ''protect_radius'' of them.
** ''protect_unit'': Specifies units (of all sides) that the AI should protect. Enemy units within ''protect_radius'' of one of these units are marked as targets with the provided value. Note once again that the AI will not place units around the protected units if there are no enemies nearby.
** ''protect_my_unit'': Specifies units from the AI's own side that the AI should protect. (This is basically the ''protect_unit'' goal with an implied ''side='' in the filter, restricting matching units to the AI's side.) Enemy units within ''protect_radius'' of one of these units are marked as targets with the provided value. Note once again that the AI will not place units around the protected units if there are no enemies nearby.

* '''[criteria]'''="": Contains a [[StandardUnitFilter]] (for ''target'', ''protect_unit'' or ''protect_my_unit'') or [[StandardLocationFilter]] (for ''target_location'' or ''protect_location'') describing the targets.

* '''value'''=0: (int) The value of the goal.

* '''protect_radius'''=20: (int) The protection radius. Applies to ''protect_location'', ''protect_unit'' and ''protect_my_unit''.

===Examples of [goal] Tag Usage===

'''target:'''
[goal]
[criteria] #NOTE: this is a SUF, because we're targeting a unit
side=3
[/criteria]
value=5
[/goal]

'''target_location:'''
[goal]
name=target_location
[criteria] #NOTE: this is a SLF, because we're targeting a location
x,y=42,20
[/criteria]
value=5
[/goal]

'''protect_location:'''
[goal]
name=protect_location
[criteria] #NOTE: this is a SLF, because we're protecting a location
x,y=42,20
[/criteria]
protect_radius=16
value=5
[/goal]

'''protect_unit:'''
[goal]
name=protect_unit
[criteria] #NOTE: this is a SUF, because we're protecting a unit
side=3
[/criteria]
protect_radius=16
value=5
[/goal]

'''protect_my_unit:'''
[goal]
name=protect_my_unit
[criteria] #NOTE: this is a SUF, because we're protecting a unit
canrecruit=yes
[/criteria]
protect_radius=9
value=10
[/goal]

To modify goals from WML events, several helper macros are available in [http://www.wesnoth.org/macro-reference.xhtml#file:ai.cfg data/core/macros/ai.cfg].

== Filtering Combat with the 'attacks' Aspect==

The ''attacks'' aspect lets us filter the units considered during the combat candidate action. Units on the AI side can be selected with the '''[filter_own]''' tag and enemy units are filtered via '''[filter_enemy]''', both of which take a [[StandardUnitFilter]]. Only units defined in these tags are considered as attacker/target pairs. To define, for example, an ''attacks'' aspect in which units from the elvish sorceresses are the only attackers, and undead units are the only targets, use either
[ai]
[aspect]
id=attacks
[facet]
invalidate_on_gamestate_change=yes
[filter_own]
type=Elvish Sorceress,Elvish Enchantress,Elvish Sylph
[/filter_own]
[filter_enemy]
race=undead
[/filter_enemy]
[/facet]
[/aspect]
[/ai]
or
[ai]
[modify_ai]
side=2
action=add
path=aspect[attacks].facet[]
[facet]
invalidate_on_gamestate_change=yes
[filter_own]
type=Elvish Sorceress,Elvish Enchantress,Elvish Sylph
[/filter_own]
[filter_enemy]
race=undead
[/filter_enemy]
[/facet]
[/modify_ai]
[/ai]
Several important notes:
* See [[AiWML#A_Bit_More_on_Simple_vs._Composite_Aspects|A Bit More on Simple vs. Composite Aspects]] and [[AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag|Adding and Deleting Aspects with the [modify_ai] Tag]] below for explanations of the syntax used in these examples.
* This only works if 'invalidate_on_gamestate_change=yes' is set, so that the available attacker/target pairs are recalculated after each move. This is also explained at [[AiWML#A_Bit_More_on_Simple_vs._Composite_Aspects|A Bit More on Simple vs. Composite Aspects]].
* If [filter_own] or [filter_enemy] are omitted, the selection defaults to all units of the respective sides.
* '''Most importantly''': The above examples result in the sorceresses-on-undead attacks being the ''only'' attacks done by the AI. No other attacks are executed, no matter how advantageous their outcomes might be. There is no simple way to get around that. An example of dealing with this (executing all attacks of a certain kind first, then doing whatever possible attacks are left afterward) by setting up an additional Lua candidate action can be found in scenario 'Protect the Wizard' of campaign 'AI modification demos'. This example will also be added to the [[Lua_AI_Code_Library]] at some point.

== Limiting Recruiting with the 'recruitment' Aspect==

The number of units that can be recruited by the AI can be limited using the ''recruitment'' aspect. To define, for example, a ''recruitment'' aspect in which only two bowmen and one swordsman can be recruited, use
[ai]
[aspect]
id=recruitment
[facet]
[value]
name=ai_default::recruitment
[limit]
type=Swordsman
max=1
[/limit]
[limit]
type=Bowman
max=2
[/limit]
[/value]
[/facet]
[/aspect]
[/ai]
Several important notes:
* This aspect may currently result in no recruiting happening at all after the listed units have reached their limit, if those units seem more desirable to the AI than the rest of the recruit list. This is due to a [https://gna.org/bugs/index.php?19662 bug] and will be fixed soon.
* See [[AiWML#A_Bit_More_on_Simple_vs._Composite_Aspects|A Bit More on Simple vs. Composite Aspects]] below for an explanation of the syntax used in this example.
* The [[AiWML#Using_.5Bmodify_ai.5D_to_Change_Goals.2C_Candidate_Actions_and_Stages|[modify_ai] tag]] can also be used, equivalently to what is shown above for the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|''attacks'' aspect]].
* 'name=ai_default::recruitment' needs to be set exactly like this, so that the ''ai_default::recruitment'' stage is used.
* A separate '''[limit]''' tag needs to be used for each unit type.
* The number set by the '''max''' key limits the number of units that the side can have simultaneously. Thus, if one of the bowmen dies in the example above, another can be recruited. This is the same behavior as one gets with the LIMIT_CONTEMPORANEOUS_RECRUITS macro.
* Units for which no [limit] tag is defined can be recruited in arbitrary amounts.

== A Bit More on Simple vs. Composite Aspects ==

We stated [[AiWML#Aspects_and_Goals_Overview|above]] that aspects can be either simple or composite, simple aspects being those that take on an single (scalar) value, while composite aspects have a more complex structure containing subtags called 'facets'. That is only partially true in that, internally, all aspects are set up as composite aspects. For example, if a simple aspect is defined like this in a [side] or [modify_side] tag
[ai]
aggression=0.765
[/ai]
the AI engine turns that into
[aspect]
engine=cpp
id=aggression
name=composite_aspect
[facet]
engine=cpp
name=standard_aspect
value=0.765
[/facet]
[default]
engine=cpp
name=standard_aspect
value=0.4
[/default]
[/aspect]
This can be seen, for example, in savefiles. This shows the aspect id, 'aggression', and the engine for which it is defined, the default 'cpp' engine. It then shows two facets, the one we just defined with the new value of 0.765, and the facet containing the default settings.

Taking this one step further, if we look at 'ai config full' for a given side using the gamestate inspector dialog in debug mode, it shows all keys that can be set for this aspect (with their default values for those that we did not specify):
[aspect]
engine=cpp
id=aggression
invalidate_on_gamestate_change=no
invalidate_on_minor_gamestate_change=no
invalidate_on_tod_change_change=yes
invalidate_on_turn_start=yes
name=composite_aspect
[facet]
engine=cpp
id=
invalidate_on_gamestate_change=no
invalidate_on_minor_gamestate_change=no
invalidate_on_tod_change_change=yes
invalidate_on_turn_start=yes
name=standard_aspect
time_of_day=
turns=
value=0.765
[/facet]
[default]
... (omitted for brevity, same as above)
value=0.4
[/default]
[/aspect]
Thus, we see, that the facet may also contain an id (important if one wants to [[AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag|delete it]] selectively), the time of day and turns for which it is valid, and several invalidate_on_... keys. The AI code stores information derived from the aspects in C++ objects. This information can simply be the aspect value for some aspects (such as ''aggression'') or it can contain a significant amount of additional information. For example, for the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|''attacks'']] aspect, it contains a list of all possible attacks of the filtered attacker/target unit pairs. This list is not valid any more after an attack has been performed and needs to be reset. The AI does this by 'invalidating' the aspect, after which the aspect information is read anew from the [ai] tags and the stored information (such as the attacks list) is reevaluated.

There are 4 levels of invalidation keys:
* '''invalidate_on_turn_start'''="yes": (boolean) If "yes", the value of this aspect is invalidated at the start of each AI turn.
* '''invalidate_on_tod_change'''="yes": (boolean) If "yes", the value of this aspect is invalidated when the time of day changes (not working at the moment). This implies invalidate_on_turn_start.
* '''invalidate_on_gamestate_change'''="no": (boolean) If "yes", the value of this aspect is invalidated on each game state change (on turn start, move, attack, recruit, etc.). This implies invalidate_on_turn_start.
* '''invalidate_on_minor_gamestate_change'''="no": (boolean) If "yes", the value of this aspect is invalidated on each minor game state change (on set unit variable, etc). This implies invalidate_on_gamestate_change.

Thus, information stored about aspects is reevaluated by default at each AI turn and when the time of day changes. It is not reevaluated after the game state changes (such as after an attack), which explains why 'invalidate_on_gamestate_change=yes' needs to be set explicitly for the [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|''attacks'']] aspect.

Long story short, the definition of a simple aspect like
[ai]
aggression=0.765
[/ai]
is a syntactical shortcut for (to be used in [side] or [modify_side] tags)
[ai]
[aspect]
id=aggression
[facet]
value=0.765
[/facet]
[/aspect]
[/ai]
The former syntax is simpler for simple aspects without facet ids, but the latter is needed if a facet id is required, or for the definition of some more complex aspects such as [[AiWML#Filtering_Combat_with_the_.27attacks.27_Aspect|''attacks'']]. Alternatively, composite aspects can also be defined using the [[AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag|[modify_ai] tag]] or with the help of several macros available in [http://www.wesnoth.org/macro-reference.xhtml#file:ai.cfg data/core/macros/ai.cfg].

==Adding and Deleting Aspects with the [modify_ai] Tag==

Aspects (or rather the facets describing their values and the conditions under which they apply) can also be changed, defined or deleted with the [modify_ai] tag, which can be used either in [side][ai] or in an [event]. [modify_ai] has the following keys for modifying aspects:

* '''action''' (string): The action to take concerning the aspect. The following values are allowed:
** ''add'': Add a facet to an aspect.
** ''change'': Change an existing (non-default) facet of an aspect.
** ''delete'': Delete an existing (non-default) facet of an aspect.
** ''try_delete'': Delete a facet if it exists. This does not produce a warning if [modify_ai] fails to change the AI.
* '''path''' (string): Defines the aspect to be modified. Its values are of form 'aspect[id_of_aspect].facet[facet_identifier]'.
*'''[facet]''': Definition of the facet (the details describing the aspect and the conditions under which it applies) in the same format as shown [[AiWML#A_Bit_More_on_Simple_vs._Composite_Aspects|above]].
* '''side''': If used in an [event] tag, the side of the AI to be modified. Not needed if used in [side][ai].
* [[StandardSideFilter]] {{DevFeature1.11}} tags and keys; default for empty side= is all sides, as usual in a SSF.

Here, 'id_of_aspect' is the id/name of the aspect (such as 'aggression'). The 'facet_identifier' is meaningless for adding an aspect. In fact, it can be empty for that. It does ''not'' set the facet id, which needs to be done with the ''id'' key inside the [facet] tag. By contrast, when changing or deleting aspects, 'facet_identifier' needs to be set to one the following values:
* *: Applies to all facets of an aspect, except the [default] facet.
* An integer starting with 0: Identifies the facets in the order in which they were created.
* The facet id as defined in the [facet] subtag.

Let's illustrate all this with a few examples. In order to define ''aggression'' in the same way as [[AiWML#A_Bit_More_on_Simple_vs._Composite_Aspects|above]], we could use
[modify_ai]
side=1
action=add
path=aspect[aggression].facet[]
[facet]
value=0.765
[/facet]
[/modify_ai]
This version of the aggression aspect can then be deleted using
[modify_ai]
side=1
action=delete # or try_delete
path=aspect[aggression].facet[0]
[/modify_ai]
if we know that it is the first non-default facet of the ''aggression'' aspect or with
[modify_ai]
side=1
action=delete # or try_delete
path=aspect[aggression].facet[*]
[/modify_ai]
along with all other user-defined ''aggression'' facets that might have been added. (Note that the aspect itself and its default facet cannot be deleted.) These two methods of deleting the facet also work if the value of aggression was simply set by using 'aggression=0.765' in the [ai] tag.

We can also use 'action=change' to delete an existing facet and overwrite it with a new definition. If '*' is used for ''facet_identifier'', this deletes all existing facets of this aspect and replace them by a single facet with the new definition. [Note that adding a facet with the same ''id'' as an existing facet overwrites the previous occurrence, making that equivalent to changing the facet.]

Sometimes we might want to define several facets of the same aspect, but don't know in advance in which order they will be created. If we then only want to delete some of them selectively, we need to use facets with specific id's, such as
[modify_ai]
side=1
action=add
path=aspect[aggression].facet[]
[facet]
id=aggression_dusk
time_of_day=dusk
value=0.765
[/facet]
[/modify_ai]
This can be deleted by referencing that id
[modify_ai]
side=1
action=delete # or try_delete
path=aspect[aggression].facet[aggression_dusk]
[/modify_ai]

It is, of course, unnecessary to add or delete a simple aspect like ''aggression'' in this way, as it can simply be reset by using another 'aggression=value' statement in an [ai] tag. In fact, this can be done with any aspect. If several facets are set for the same aspect for the same (or overlapping) turns and times of day, the one set up last takes effect. Note, however, that this is not accomplished by modifying the existing facets, but by adding an additional facet to the aspect. Deleting or changing a facet is, in principle, a cleaner method of dealing with this, although that usually won't make much of a difference unless the same aspect is changed many times throughout a scenario.

A large number of helper macros for AI modifications is available in [http://www.wesnoth.org/macro-reference.xhtml#file:ai.cfg data/core/macros/ai.cfg].

===Using [modify_ai] to Change Goals, Candidate Actions and Stages===

For completeness, we mention here that [modify_ai] can also be used to add and delete AI [[AiWML#AI_Targets_and_Goals|goals]], [[General_RCA_AI_Howto#Available_Stages|stages]] and [[General_RCA_AI_Howto#RCA_AI_main_loop_stage_and_Candidate_Actions|candidate actions]] by using the following values for the '''path''' key:
* ''goal[id_of_goal]'': Goal with specified id
* ''goal[0]'': Goal 0 (first)
* ''goal[1]'': Goal 1
* ''goal[*]'': All goals
* ''stage[id_of_stage]'': Stage with specified id
* ''stage[0]'': Stage 0 (first)
* ''stage[1]'': Stage 1
* ''stage[*]'': All stages
* ''stage[id_of_candidate_action_evaluation_loop_stage].candidate_action[id_of_candidate_action]'': Candidate action with specified id of stage with specified id.
* ''stage[id_of_candidate_action_evaluation_loop_stage].candidate_action[*]'': All candidate actions of stage with specified id.

Also see the helper macros in [http://www.wesnoth.org/macro-reference.xhtml#file:ai.cfg data/core/macros/ai.cfg].

Finally note that [modify_ai] in [side][ai] is activated when the AI is first initialized. It is guaranteed to happen before the AI acts for the first time, but otherwise it can happen at any time, for example, when the game is saved. So, for example, you might see the uninitialized version of the config (with unapplied [modify_ai] tags) if using ':inspect' right after the scenario start.

== See Also ==
* [[Practical_Guide_to_Modifying_AI_Behavior]]
* [[ReferenceWML]]
* [[BuildingScenariosIndex]]

[[Category: WML Reference]]
[[Category:AI]]

WhyWritingAWesnothAIIsHard

2012-11-27T16:37:29Z

Alarantalara: Add AI category

= Why Writing a Wesnoth AI is Hard =

== Overview ==

I'm largely writing this in response to the number of people who have historically wanted to write a Wesnoth AI, as well as the number of students who are interested in developing an AI for Wesnoth as part of Summer of Code.

Having an AI for Wesnoth is very useful, but one shouldn't underestimate its difficulty. Most traditional AI methods cannot be applied to Wesnoth, so it is necessary to use highly innovative solutions.

Many people think that a very powerful AI for Wesnoth should be fairly easy. After all, computers can beat the world's best players in chess and backgammon, both of which are turned based games, so why not Wesnoth? This document will give an overview of why techniques used in chess and backgammon will not be near as successful in Wesnoth.

== Wesnoth's flexibility hurts us ==

Wesnoth is very flexible. There are many different maps, of different sizes, and different units. Players can even add their own units. This makes it much more difficult to make a general AI.

Computers are very good at chess because chess is played on a relatively small board, that is always the same, and the pieces always start in the same position. This means there are a relatively limited set of positions that the computer has to deal with, and in particular, the types of positions a computer has to deal with are very limited. Patterns such as three consecutive pawns in front of a castled king are common in chess, and so it is relatively easy for a chess evaluation engine to recognize such patterns and evaluate their strength.

Wesnoth is much different. To even compare Wesnoth with chess, you would have to consider a chess program written for a chess game where the board can be any size and shape. It could have impassable squares in the middle. It could have corners that are inaccessible and so forth. Additionally, players could have various 'fantasy pieces' which are defined according to complex rules. Pieces that move like knights, but with extra steps. Pieces that can move likes knights and like bishops, and so forth.

Such a program would not play near as well against skilled humans. Humans could adapt to the new pieces far more readily than a computer program can.

But that still doesn't begin to approach the complexity of Wesnoth. Wesnoth has uncertain information, and random outcomes. Chess programs rely heavily on chess's deterministic nature. Wesnoth is more like backgammon in this way: you don't know what the outcome will be. But, backgammon has a tiny state space, while Wesnoth has a huge one.

== Wesnoth's computational complexity ==

The computational complexity of Wesnoth is immense compared to board games such as chess, backgammon, shogi, and go.

If one considers a 30x20 map -- a typical size for a Wesnoth map -- and one considers 16 standard terrain types. This can be represented in 2400 bits of data. There are thus 2^2400 possible maps of this size. This is without even considering the many combinations of units that can be on the map, in different locations, in different states of health, and so forth. The number of possible positions is truly immense. The state space of Wesnoth certainly easily exceeds 10^1000, and probably 10^10000.

This dwarfs the complexity of even Go, which has a state space complexity of 'only' around 10^171.

The branching factor of Wesnoth is also huge. In most traditional board games, where much computational analysis has been done, typically a player moves one piece, then the other player moves a piece. In Wesnoth, one moves all their pieces, before the other player moves. Wesnoth also typically has many options as to where one can move a piece. It is not uncommon for a piece to have 20 or more tiles it can move to, and for a player to have a dozen or more pieces. Pieces can also choose to attack, and have a choice of weapon to attack with, and so forth. When an attack does occur, there are many possible results, based on number of strikes that land.

The branching factor of Wesnoth is thus also huge. The game tree complexity of Wesnoth is incalculably large. Thinking ahead many moves is difficult.

== Wesnoth as a fuzzy game ==

Discrete analysis fails badly on Wesnoth because, though technically Wesnoth is a discrete game, there are so many positions that discrete analysis techniques fail.

Fortunately, Wesnoth can be treated much like a continuous game, because many positions tend to be very similar to each other. Additionally, unlike discrete board games, it is not common that a very small wrong move in Wesnoth is disastrous.

[[Category:Development]]
[[Category:AI]]

LuaWML

2012-11-27T16:37:02Z

Alarantalara:

{{WML Tags}}

== The '''[lua]''' tag ==

This tag is a part of [[ActionWML]], thus can be used inside [event] and at other places where [[ActionWML]] can be used. It makes it possible to write actions with the [http://www.lua.org Lua 5.2] language.

The tag supports only the '''code''' key, which is a string containing the Lua scripts. Since Lua makes usage of the quotes and the { and } symbols, it is certainly wise to enclose the script between stronger quotes, as they prevent the preprocessor from performing macro expansion and tokenization.

[lua]
code = << wesnoth.message "Hello World!" >>
[/lua]

The Lua kernel can also be accessed from the [[CommandMode|command mode]]:

:lua local u = wesnoth.get_units({ id = "Konrad" })[1]; u.moves = 5

The '''[args]''' sub-tag can be used to pass a WML object to the script via its variadic local variable "'''...'''".

[lua]
code = << local t = ...; wesnoth.message(tostring(t.text)) >>
[args]
text = _ "Hello world!"
[/args]
[/lua]

== Global environment ==

All the Lua scripts of a scenario share the same global environment (aka Lua state). For instance, a function defined in an event can be used in all the events that happen after it.

[event]
name = preload
first_time_only = no
[lua]
code = <<
function narrator(t)
-- Behave like the [message] tag.
wesnoth.fire("message",
{ speaker = "narrator", message = t.sentence })
end
>>
[/lua]
[/event]

[event]
name = turn 1
[lua]
code = << narrator(...) >>
[args]
sentence = _ "Hello world!"
[/args]
[/lua]
[lua]
code = << narrator(...) >>
[args]
sentence = _ "How are you today?"
[/args]
[/lua]
[/event]

In the example above, the redundant structure could be hidden behind macros. But it may be better to simply define a new WML tag.

[event]
name = preload
first_time_only = no
[lua]
code = <<
-- The function is now local, since its name does not have to be
-- visible outside this Lua scripts.
local function handler(t)
-- Behave like the [message] tag.
wesnoth.fire("message",
{ speaker = "narrator", message = t.sentence })
end
-- Create a new tag named [narrator].
wesnoth.register_wml_action("narrator", handler)
>>
[/lua]
[/event]

[event]
name = turn 1
[narrator]
sentence = _ "Hello world!"
[/narrator]
[narrator]
sentence = _ "How are you today?"
[/narrator]
[/event]

The global environment is not preserved over save/load cycles. Therefore, storing values in the global environment is generally a bad idea (unless it has been redirected to WML variables, see [[LuaWML:Variables#set_wml_var_metatable|helper.set_wml_var_metatable]]). The only time assigning global variables (including function definitions) makes sense is during a [[EventWML#Predefined 'name' Key Values|preload]] event, as this event is always run. Therefore, helper functions defined at that time will be available to all the later scripts.

The global environment initially contains the following modules: [http://www.lua.org/manual/5.1/manual.html#5.1 basic] (no name), [http://www.lua.org/manual/5.1/manual.html#5.4 string], [http://www.lua.org/manual/5.1/manual.html#5.5 table], and [http://www.lua.org/manual/5.1/manual.html#5.6 math]. A '''wesnoth''' module is also available, it provides access to the [[#Interface to the C++ engine|C++ engine]]. Besides, the functions clock, date, time and difftime from the [http://www.lua.org/manual/5.1/manual.html#5.8 os] library (Keep in mind that they aren't multiplayer- and replay-save.) and traceback from the [http://www.lua.org/manual/5.1/manual.html#5.9 debug] library are also available.

At the start of a script, the variadic local variable '''...''' (three dots) is a proxy table representing [[#Encoding WML objects into Lua tables|WML data]]. This table is the content of the '''[args]''' sub-tag of the '''[lua]''' tag, if any.

== Examples ==

The following WML event is taken from Wesnoth' tutorial. It will serve as an example to present how Lua scripts are embedded into Wesnoth. The event is fired whenever a unit from side 1 (that is, the hero controlled by the user) moves to a tile that is not the one set in the WML variable ''target_hex''.

# General catch for them moving to the wrong place.
[event]
name=moveto
first_time_only=no
[allow_undo][/allow_undo]
[filter]
side=1
[/filter]

[if]
[variable]
name=target_hex.is_set
equals=yes
[/variable]
[then]
[if]
[variable]
name=x1
equals=$target_hex.x
[/variable]
[variable]
name=y1
equals=$target_hex.y
[/variable]
[then]
[/then]
[else]
[redraw][/redraw]
[message]
speaker=narrator
message=_ "*Oops!
You moved to the wrong place! After this message, you can press 'u' to undo, then try again." +
_ "
*Left click or press spacebar to continue..."
[/message]
[/else]
[/if]
[/then]
[/if]
[/event]

A Lua script that performs the same action is presented below.

[event]
name=moveto
first_time_only=no
[allow_undo][/allow_undo]
[filter]
side=1
[/filter]

[lua]
code = <<
local event_data = wesnoth.current.event_context
if target_hex.is_set and
(event_data.x1 ~= target_hex.x or event_data.y1 ~= target_hex.y)
then
W.redraw()
narrator_says(_ "*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.")
end
>>
[/lua]
[/event]

Here is a more detailed explanation of the Lua code. Its first line

local event_data = wesnoth.current.event_context

puts the event data into the ''event_data'' local variable. Since it is a ''moveto'' event, the ''event_data'' table contains the destination of the unit in the ''x1'' and ''y1'' fields.

The next two lines then test

if target_hex.is_set and
(event_data.x1 ~= target_hex.x or event_data.y1 ~= target_hex.y)

whether the variable ''target_hex'' matches the event parameters. Since ''target_hex'' is not a local variable, it is taken from the global environment (a table implicitly named ''_G'', so it is actually ''_G.target_hex''). The global environment is not persistent, so it cannot be used to store data. In order to make it useful, it was mapped to the storage of WML variables by the following ''preload'' event.

[event]
name=preload
first_time_only=no
[lua]
code = <<
H = wesnoth.require "lua/helper.lua"
-- skipping some other initializations
-- ...
H.set_wml_var_metatable(_G)
>>
[/lua]
[/event]

Without a prelude redirecting ''_G'', the conditional would have been written

if wesnoth.get_variable("target_hex.is_set") and
(event_data.x1 ~= wesnoth.get_variable("target_hex.x") or event_data.y1 ~= wesnoth.get_variable("target_hex.y")

The body of the conditional then performs the [[InterfaceActionsWML#Other interface tags|[redraw]]] action.

W.redraw()

Again, this short syntax is made possible by a line of the prelude that makes ''W'' a proxy for performing WML actions.

W = H.set_wml_action_metatable {}

Without this shortcut, the first statement would have been written

wesnoth.fire("redraw")

Finally the script displays a message by

narrator_says(_ "*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.")

The ''narrator_says'' function is defined in the prelude too, since the construct behind it occurs several times in the tutorial. In plain WML, macros would have been used instead. The definition of the function is

function narrator_says(m)
W.message { speaker="narrator",
message = m .. _ "\n*Left click or press spacebar to continue..." }
end

The function fires a [[InterfaceActionsWML#.5Bmessage.5D|[message]]] action and passes a WML object containing the usual two fields to it. The second field is initialized by concatenating the function argument with another string. Both strings are prefixed by the ''_'' symbol to mark them as translatable. (Note that ''_'' is just a unary function, not a keyword.) Again, this is made possible by a specific line of the prelude:

_ = wesnoth.textdomain "wesnoth-tutorial"

A longer translation of the tutorial is available at [https://gna.org/patch/download.php?file_id=5483].

== Interface to the engine and helper functions ==

Functionalities of the game engine are available through the functions of the '''wesnoth''' global table. Some of these functions return proxy tables. Writes to fields marked "read-only" are ignored. The '''__cfg''' fields return plain tables; in particular, writes do not modify the original object, and reads return the values from the time the dump was performed.

Some helper functions are provided by the '''lua/helper.lua''' library. They are stored inside a table that is returned when loading the library with [[LuaWML:Files#wesnoth.require|wesnoth.require]].

helper = wesnoth.require "lua/helper.lua"

=== WML variables ===

* [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]]
* [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]]
* [[LuaWML:Variables#helper.set_wml_var_metatable|helper.set_wml_var_metatable]]
* [[LuaWML:Variables#helper.get_child|helper.get_child]]
* [[LuaWML:Variables#helper.child_range|helper.child_range]]
* [[LuaWML:Variables#helper.get_variable_array|helper.get_variable_array]]
* [[LuaWML:Variables#helper.get_variable_proxy_array|helper.get_variable_proxy_array]]
* [[LuaWML:Variables#helper.set_variable_array|helper.set_variable_array]]

=== Events and WML actions ===

* [[LuaWML:Events#wesnoth.fire|wesnoth.fire]]
* [[LuaWML:Events#wesnoth.register_wml_action|wesnoth.register_wml_action]]
* [[LuaWML:Events#wesnoth.wml_actions|wesnoth.wml_actions]]
* [[LuaWML:Events#wesnoth.game_events|wesnoth.game_events]]
* [[LuaWML:Events#wesnoth.fire_event|wesnoth.fire_event]]
* [[LuaWML:Events#wesnoth.eval_conditional|wesnoth.eval_conditional]]
* [[LuaWML:Events#wesnoth.tovconfig|wesnoth.tovconfig]]
* [[LuaWML:Events#helper.set_wml_action_metatable|helper.set_wml_action_metatable]]
* [[LuaWML:Events#helper.wml_error|helper.wml_error]]
* [[LuaWML:Events#helper.literal|helper.literal]]
* [[LuaWML:Events#helper.parsed|helper.parsed]]
* [[LuaWML:Events#helper.shallow_literal|helper.shallow_literal]]
* [[LuaWML:Events#helper.shallow_parsed|helper.shallow_parsed]]

=== User interface ===

* [[LuaWML:Display#wesnoth.message|wesnoth.message]]
* [[LuaWML:Display#wesnoth.clear_messages|wesnoth.clear_messages]]
* [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]
* [[LuaWML:Display#wesnoth.delay|wesnoth.delay]]
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
* [[LuaWML:Display#wesnoth.select_hex|wesnoth.select_hex]]
* [[LuaWML:Display#wesnoth.scroll_to_tile|wesnoth.scroll_to_tile]]
* [[LuaWML:Display#wesnoth.lock_view|wesnoth.lock_view]]
* [[LuaWML:Display#wesnoth.view_locked|wesnoth.view_locked]]
* [[LuaWML:Display#wesnoth.play_sound|wesnoth.play_sound]]
* [[LuaWML:Display#wesnoth.set_music|wesnoth.set_music]]
* [[LuaWML:Display#wesnoth.show_dialog|wesnoth.show_dialog]]
* [[LuaWML:Display#wesnoth.set_dialog_value|wesnoth.set_dialog_value]]
* [[LuaWML:Display#wesnoth.get_dialog_value|wesnoth.get_dialog_value]]
* [[LuaWML:Display#wesnoth.set_dialog_active|wesnoth.set_dialog_active]]
* [[LuaWML:Display#wesnoth.set_dialog_callback|wesnoth.set_dialog_callback]]
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]]
* [[LuaWML:Display#wesnoth.get_displayed_unit|wesnoth.get_displayed_unit]]
* [[LuaWML:Display#wesnoth.theme_items|wesnoth.theme_items]]
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]
* [[LuaWML:Display#wesnoth.get_time_of_day|wesnoth.get_time_of_day]]

=== Map and terrains ===

* [[LuaWML:Tiles#wesnoth.get_map_size|wesnoth.get_map_size]]
* [[LuaWML:Tiles#wesnoth.get_terrain|wesnoth.get_terrain]]
* [[LuaWML:Tiles#wesnoth.set_terrain|wesnoth.set_terrain]]
* [[LuaWML:Tiles#wesnoth.get_terrain_info|wesnoth.get_terrain_info]]
* [[LuaWML:Tiles#wesnoth.get_selected_tile|wesnoth.get_selected_tile]]
* [[LuaWML:Tiles#wesnoth.get_locations|wesnoth.get_locations]]
* {{DevFeature1.11}}[[LuaWML:Tiles#wesnoth.get_villages|wesnoth.get_villages]]
* [[LuaWML:Tiles#wesnoth.match_location|wesnoth.match_location]]
* [[LuaWML:Tiles#wesnoth.add_tile_overlay|wesnoth.add_tile_overlay]]
* [[LuaWML:Tiles#wesnoth.remove_tile_overlay|wesnoth.remove_tile_overlay]]
* [[LuaWML:Tiles#items.place_image|items.place_image]]
* [[LuaWML:Tiles#items.place_halo|items.place_halo]]
* [[LuaWML:Tiles#items.remove|items.remove]]

=== Units ===

* [[LuaWML:Units#wesnoth.get_units|wesnoth.get_units]]
* [[LuaWML:Units#wesnoth.get_unit|wesnoth.get_unit]]
* [[LuaWML:Units#wesnoth.match_unit|wesnoth.match_unit]]
* [[LuaWML:Units#wesnoth.put_unit|wesnoth.put_unit]]
* [[LuaWML:Units#wesnoth.get_recall_units|wesnoth.get_recall_units]]
* [[LuaWML:Units#wesnoth.put_recall_unit|wesnoth.put_recall_unit]]
* [[LuaWML:Units#wesnoth.create_unit|wesnoth.create_unit]]
* [[LuaWML:Units#wesnoth.copy_unit|wesnoth.copy_unit]]
* [[LuaWML:Units#wesnoth.extract_unit|wesnoth.extract_unit]]
* [[LuaWML:Units#wesnoth.add_modification|wesnoth.add_modification]]
* [[LuaWML:Units#wesnoth.unit_resistance|wesnoth.unit_resistance]]
* [[LuaWML:Units#wesnoth.unit_defense|wesnoth.unit_defense]]
* [[LuaWML:Units#wesnoth.unit_movement_cost|wesnoth.unit_movement_cost]]
* [[LuaWML:Units#wesnoth.unit_ability|wesnoth.unit_ability]]
* [[LuaWML:Units#wesnoth.get_unit_type_ids|wesnoth.get_unit_type_ids]]
* [[LuaWML:Units#wesnoth.get_unit_type|wesnoth.get_unit_type]]
* [[LuaWML:Units#wesnoth.unit_types|wesnoth.unit_types]]
* [[LuaWML:Units#wesnoth.races|wesnoth.races]]
* [[LuaWML:Units#wesnoth.get_traits|wesnoth.get_traits]]
* [[LuaWML:Units#wesnoth.simulate_combat|wesnoth.simulate_combat]]
* [[LuaWML:Units#wesnoth.transform_unit|wesnoth.transform_unit]]

=== Sides ===

* [[LuaWML:Sides#wesnoth.get_side|wesnoth.get_side]]
* [[LuaWML:Sides#wesnoth.sides|wesnoth.sides]]
* [[LuaWML:Sides#wesnoth.get_sides|wesnoth.get_sides]]
* [[LuaWML:Sides#wesnoth.get_village_owner|wesnoth.get_village_owner]]
* [[LuaWML:Sides#wesnoth.set_village_owner|wesnoth.set_village_owner]]
* [[LuaWML:Sides#wesnoth.is_enemy|wesnoth.is_enemy]]
* [[LuaWML:Sides#wesnoth.match_side|wesnoth.match_side]]
* [[LuaWML:Sides#wesnoth.get_starting_location|wesnoth.get_starting_location]]
* [[LuaWML:Sides#helper.all_teams|helper.all_teams]]

=== Pathfinder ===

* [[LuaWML:Pathfinder#wesnoth.find_path|wesnoth.find_path]]
* [[LuaWML:Pathfinder#wesnoth.find_vacant_tile|wesnoth.find_vacant_tile]]
* [[LuaWML:Pathfinder#wesnoth.find_reach|wesnoth.find_reach]]
* [[LuaWML:Pathfinder#helper.distance_between|helper.distance_between]]
* [[LuaWML:Pathfinder#helper.adjacent_tiles|helper.adjacent_tiles]]

=== Lua files ===

* [[LuaWML:Files#wesnoth.dofile|wesnoth.dofile]]
* [[LuaWML:Files#wesnoth.require|wesnoth.require]]

=== Location sets ===

* [[LuaWML:Location_set#location_set.create|location_set.create]]
* [[LuaWML:Location_set#location_set.of_pairs|location_set.of_pairs]]
* [[LuaWML:Location_set#location_set.of_wml_var|location_set.of_wml_var]]
* [[LuaWML:Location_set#location_set:empty|location_set:empty]]
* [[LuaWML:Location_set#location_set:size|location_set:size]]
* [[LuaWML:Location_set#location_set:clear|location_set:clear]]
* [[LuaWML:Location_set#location_set:get|location_set:get]]
* [[LuaWML:Location_set#location_set:insert|location_set:insert]]
* [[LuaWML:Location_set#location_set:remove|location_set:remove]]
* [[LuaWML:Location_set#location_set:of_pairs|location_set:of_pairs]]
* [[LuaWML:Location_set#location_set:of_wml_var|location_set:of_wml_var]]
* [[LuaWML:Location_set#location_set:to_pairs|location_set:to_pairs]]
* [[LuaWML:Location_set#location_set:to_stable_pairs|location_set:to_stable_pairs]]
* [[LuaWML:Location_set#location_set:to_wml_var|location_set:to_wml_var]]
* [[LuaWML:Location_set#location_set:union|location_set:union]]
* [[LuaWML:Location_set#location_set:inter|location_set:inter]]
* [[LuaWML:Location_set#location_set:iter|location_set:iter]]
* [[LuaWML:Location_set#location_set:stable_iter|location_set:stable_iter]]
* [[LuaWML:Location_set#location_set:filter|location_set:filter]]
* [[LuaWML:Location_set#location_set:union_merge|location_set:union_merge]]
* [[LuaWML:Location_set#location_set:inter_merge|location_set:inter_merge]]

=== Miscellaneous ===

* [[LuaWML:Misc#wesnoth.game_config|wesnoth.game_config]]
* [[LuaWML:Misc#wesnoth.current|wesnoth.current]]
* [[LuaWML:Misc#wesnoth.synchronize_choice|wesnoth.synchronize_choice]]
* [[LuaWML:Misc#wesnoth.get_image_size|wesnoth.get_image_size]]
* [[LuaWML:Misc#wesnoth.compare_versions|wesnoth.compare_versions]]
* [[LuaWML:Misc#wesnoth.debug|wesnoth.debug]]
* [[LuaWML:Misc#helper.set_wml_tag_metatable|helper.set_wml_tag_metatable]]
* [[LuaWML:Misc#helper.modify_unit|helper.modify_unit]]
* [[LuaWML:Misc#helper.move_unit_fake|helper.move_unit_fake]]
* [[LuaWML:Misc#helper.rand|helper.rand]]
* [[LuaWML:Misc#helper.round|helper.round]]

== Encoding WML objects into Lua tables ==

Function [[LuaWML:Events#wesnoth.fire|wesnoth.fire]] expects a table representing a WML object as its second argument (if needed). Function [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]] allows to modify whole WML objects, again by passing it a table. Function [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]] transforms a WML object into a table, if its second argument is not set to ''true''. All these tables have the same format.

Scalar fields are transformed into WML attributes. For instance, the following Lua table

{
a_bool = true,
an_int = 42,
a_float = 1.25,
a_string = "scout",
a_translation = _ "Hello World!"
}

is equivalent to the content of the following WML object

[dummy]
a_bool = "yes"
an_int = "42"
a_float = "1.25"
a_string = "scout"
a_translation = _ "Hello World!"
[/dummy]

WML child objects are not stored as Lua named fields, since several of them can have the same tag. Moreover, their tags can conflict with the attribute keys. So child objects are stored as pairs string + table in the unnamed fields in definition order. This means that for every subtag appearing in the wml code there is an additional table "layer" in the corresponding WML table of the form {[1] = "tag_name", [2] = {}} which is equivalent to {"tag_name", {}}. [1] etc are the unnamed fields (as opposed to wml attributes). The table under [2] in this subtable then holds the wml attributes from inside the wml subtag. So every subtag other than the toplevel tag corresponds to two nested tables each. For instance, the following Lua table

{
foo = 42,
{ "bar", { v = 1, w = 2 } },
{ "foo", { x = false } },
{ "bar", { y = "foo" } },
{ "foobar", { z = 5, { "barfoo", {} } } }
}

is equivalent to the content of the following WML object

[dummy]
foo = 42
[bar]
v = 1
w = 2
[/bar]
[foo]
x = no
[/foo]
[bar]
y = foo
[bar]
[foobar]
z = 5
[barfoo]
[/barfoo]
[/foobar]
[/dummy]

Both tables above are also equivalent to this WML table, where all unnamed fields are displayed:
{
foo = 42,
[1] = { [1] = "bar", [2] = { v = 1, w = 2 } },
[2] = { [1] = "foo", [2] = { x = false } },
[3] = { [1] = "bar", [2] = { y = "foo" } },
[4] = { [1] = "foobar", [2] = { z = 5, [1] = { [1] = "barfoo", [2] = {} } } }
}

So assuming ''cfg'' contains the above WML object, the following accesses are possible:

a_int = cfg.foo -- "dummy.foo", 42
a_string = cfg[3][2].y -- "dummy.bar[1].y", "foo"
a_table = cfg[4][2] -- "dummy.foobar", { z = 5, { "barfoo", {} } }

Consider using the [[LuaWML:Variables#helper.get_child|helper.get_child]] and [[LuaWML:Variables#helper.child_range|helper.child_range]] to ease the access to subtags.

Functions registered by [[LuaWML:Events#wesnoth.register_wml_action|wesnoth.register_wml_action]] receive their data in a userdata object which has the exact same structure as above. It is read-only however. Accessing fields or children performs variable substitution on the fly. Its '''__parsed''' and '''__literal''' fields provide translations to plain tables (therefore writable). '''__literal''' returns the original text of the data (including dollar symbols in attributes and [insert_tag] children), while '''__parsed''' performs a variable substitution.

For instance, if you cannot stand any longer the fact that '''first_time_only''' is set to yes by default for the '''[event]''' tag, you can redefine it. But we have to be careful not to cause variable substitution, since the engine would perform a second variable substitution afterwards.

local old_event_handler
old_event_handler = register_wml_action("event",
function(cfg)
-- Get the plain text from the user.
local new_cfg = cfg.__literal
-- The expression below is equivalent to cfg.__parsed.first_time_only,
-- only faster. It is needed, since the first_time_only attribute may
-- reference variables.
local first = cfg.first_time_only
-- Modify the default behavior of first_time_only.
if first == nil then first = false end
new_cfg.first_time_only = first
-- Call the engine handler.
old_event_handler(new_cfg)
end
)

Note that, since the object is a userdata and not a table, '''pairs''' and '''ipairs''' are unfortunately not usable on it. So scripts have to work at a lower level. For instance, the following function returns the first sub-tag with a given name and it works both on WML tables and WML userdata:

function get_child(cfg, name)
for i = 1, #cfg do
local v = cfg[i]
if v[1] == name then return v[2] end
end
end

Another approach for handling userdata and tables in the same way, would be to convert the former into the latter beforehand:

if getmetatable(cfg) == "wml object" then cfg = cfg.__parsed end

The WML userdata provides two other special fields: '''__shallow_parsed''' and '''__shallow_literal'''. They return a table corresponding to the WML userdata with variable substitution performed on the attributes (or not). [insert_tag] tags have also been parsed, so the number of children is faithful. But contrarily to '''__parsed''' and '''__literal''', the process is not recursive: all the children are still WML userdata and variable substitution can still happen for them. These shallow translators are meant as optimized versions of the deep ones, when only the toplevel attributes need to be writable.

== Skeleton of a preload event ==

The following event is a skeleton for a prelude enabling Lua in your WML events. It creates a table ''H'' containing the functions from helper.lua and a table ''W'' that serves as a proxy for firing WML actions. It also sets up the global environment so that any access to an undefined global variable is redirected to the persistent WML storage.

[event]
name=preload
first_time_only=no
[lua]
code = <<
H = wesnoth.require "lua/helper.lua"
W = H.set_wml_action_metatable {}
_ = wesnoth.textdomain "my-campaign"

-- Define your global constants here.
-- ...

H.set_wml_var_metatable(_G)

-- Define your global functions here.
-- ...
>>
[/lua]
[/event]

It may be worth putting the whole Lua script above inside a separate file and having the ''preload'' event load it:

[event]
name=preload
first_time_only=no
[lua]
code = << wesnoth.dofile "~add-ons/Whatever/file.lua" >>
[/lua]
[/event]

== Remarks ==

The math.random function is not safe for replays and multiplayer games, since the random values will be different each time and on all the clients. Instead, the Lua code should rely on the [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] tag to synchronize random values.

function random(min, max)
if not max then min, max = 1, min end
wesnoth.fire("set_variable", { name = "LUA_random", rand = string.format("%d..%d", min, max) })
local res = wesnoth.get_variable "LUA_random"
wesnoth.set_variable "LUA_random"
return res
end

[[Category: Lua Reference|*]]
[[Category: WML Reference]]

WritingYourOwnAI

2012-11-27T16:33:54Z

Alarantalara:

== Warning ==
'''THIS PAGE CONTAINS OBSOLETE INFORMATION.'''

== Writing your own AI ==

Wesnoth supports a pluggable AI system that allows programmers to write their own AIs in C++ or Python.
You might like to look this over before starting: [[WhyWritingAWesnothAIIsHard]]

== Python ==

For information on the Python AI API look at [[ReferencePythonAPI]].

== C++ ==

The rest of this page describes the C++ AI API. To write an AI in C++, you need to derive a class from ''ai_interface'' (defined in '''ai.hpp'''), and implement the function ''play_turn()'' which will be called every time your AI is expected to play a turn.

Class ''ai_interface'' contains three important functions
which allow you to execute the three basic types of move available in the game:

* ''attack_enemy()'', which is used to order an attack on an enemy unit,
* ''move_unit()'', which is used to order a unit to move from one location to another, and
* ''recruit()'', which is used to recruit a new unit.

Of course, to decide where units are to move and attack, you must have information about the state of the game - the dimensions and layout of the map, the locations and type of units on the map, the types of units your side can recruit, and information about your allies and enemies.

Firstly, a type ''location'' is defined, which defines any location on the map. It has members ''x'' and ''y''. In '''pathfind.hpp''' there are a number of functions which will tell you useful things about locations -- whether two locations
are adjacent, all the locations adjacent to a certain location,
and the distance between locations.

A type ''move_map'' is defined as a ''std::multimap<location,location>''. Note that ''std::multimap'' is of course a standard C++ container, and cannot be documented here. http://www.sgi.com/tech/stl/ is a good reference on standard C++ containers. The purpose of a ''move_map'' is to show all the possible moves for a side. It can either be a ''source -> destination'' map, which associates the locations of all the units a side has to all the possible places they can move to, or a ''destination -> source'' map, which associates all the locations all the units a side has can get to, to all the places they are now.

The function ''calculate_possible_moves()'' is provided
as a useful utility function. It can give you maps for where all
your units can move, or where all your enemy's movements
can move when it's their turn. This is a very important
function to use to work out all the possible places your units can move to.

''ai_interface'' also defines an ''info'' type. This type contains a number of references to various game objects which you
will need access to in order to make moves. The two most important of these objects are the unit map (unit_map units)
and the game map (gamemap map).

The unit map is of type ''std::map<location,unit>''
and associates locations with units. This object can be used to find the location of, and information about, every unit on the board. See '''unit.hpp''' for a definition of the ''unit'' object.

The game map allows you to inspect the dimensions and layout of the playing board. Given a location, it can tell you the
terrain type at that location. See '''map.hpp''' for a definition of this object. You can combine this class with use of the functions in '''pathfind.hpp''' to find various
information about where units can move to.

The team class (defined in '''team.hpp''') is also very important. Each side is represented by a ''team'' object. The team object can tell you the gold balance of a team, which villages (note that internally, villages are often called 'towers') the team owns, what units the team can recruit,
and which other teams are this teams friends or enemies.

The utility function ''current_team()'' can be used to get a reference to the team that your AI is in control of, but you
can also use the vector ''teams'' inside the info object to get a list of all teams.

If you want to make your AI customizable within the configuration file, you can gain access to any parameters passed to your AI using ''team::ai_parameters()''. This returns an object of type ''config'' (see '''config.hpp'''). These ''config'' objects are representations of WML document fragments. When the user defines your side, if they put an [ai] tag inside it, everything inside the [ai] tag will be returned by ''team::ai_parameters()''.

== Using your AI ==

Finally, when you have your AI ready to go, you can add it to the ''create_ai()'' function in '''ai.cpp'''. Suppose you called your class ''killer_ai'', you could add it like so:

if(name == "killer_ai")
return new killer_ai(info);

Then, you can define a side to use your AI in [[ReferenceWML|WML]]:

ai_algorithm=killer_ai

and when that side is created, it'll use your AI!

== An example ==

Let us conclude with a small sample AI, called ''sample_ai''. How should this AI behave?

* First it should detect if there are any enemies in range,
and if there are it should attack them by moving onto the
best defensive terrain next to them. Attacks should be made with the weapon for which damage*strikes*chance to hit is
the highest.
* If there are no enemies in range, it should move units onto villages that don't already belong to it.
* If there are no enemies or villages in range, it should move toward the enemy leader along the shortest possible route.
* At the end of its turn, it should recruit random units until it runs out of money or doesn't have any space.

In the following example, I will place all functions in-line
rather than in the cpp file. To do this properly, of course you should put them in the cpp file. The entire definition of this AI can be found in '''ai.cpp''' and '''ai.hpp''' in the source distribution.

We start the definition,

class sample_ai : public ai_interface {
public:
sample_ai(info& i) : ai_interface(i) {}

We have defined the constructor which takes an ''info'' object
and passes it straight onto ai_interface. We don't need to
store anything ourselves in this simple AI. (Although it would be fine to have data members if we wanted them.)

Next we define the main function, ''play_turn()'':

void play_turn() {
do_attacks();
get_villages();
do_moves();
do_recruitment();
}

Just a series of calls to functions we are about to write which do the actual work. Firstly, ''do_attacks()''. We start by
calculating all the moves our units can make:

private:
void do_attacks() {
std::map<location,paths> possible_moves;
move_map srcdst, dstsrc;
calculate_possible_moves(possible_moves,srcdst,dstsrc,false);

Note that the ''possible_moves'' thing is of little direct interest. It contains details of exactly which tiles the unit
moves along to get from one tile to another. This is useful for the display to know about when it draws the unit moving, but as an AI programmer, it's not likely you'll ever care about
what it contains. Just pass it along to the ''move_unit()'' function so it can draw the unit moving along the correct path.

The things we're interested in are ''srcdst'', and especially ''dstsrc'', which will tell us all the hexes our units can reach.
We want to check if any of these hexes are next to an enemy unit. Let's walk over the units and see if we can reach any of them:

for(unit_map::const_iterator i = get_info().units.begin(); i != get_info().units.end(); ++i) {
if(current_team().is_enemy(i->second.side()) {

We're iterating over all units, but we're only interested in units that are enemies of our side. So, we access our team object, and ask if the side the unit is on is an enemy. If it is, then we're interested in seeing if any of our units can move to a hex that's adjacent to the enemy unit. We do this by getting the six locations around the enemy unit:

location adjacent_tiles[6];
get_adjacent_tiles(i->first,adjacent_tiles);

This kind of call is very common in the game's code -- make an array of 6 locations, and fill them up with the locations adjacent to a certain location. We actually want to find the position to attack from which gives our unit the best possible defense. So, we initialize some variables to find the best possible defense:

int best_defense = -1;
std::pair<location,location> best_movement;

The value of ''best_defense'' will of course be between 1 and 100, but we give it a value of -1 to mean 'not initialized', since we haven't found any possible attacks at all yet. Variable ''best_movement'' will contain the destination/source pair that gives the best possible defense for our attacking unit.

for(size_t n = 0; n != 6; ++n) {
typedef move_map::const_iterator Itor;
std::pair<Itor,Itor> range = dstsrc.equal_range(adjacent_tiles[n]);

If you don't understand how ''equal_range'' works, then look up documentation on how the standard container multimap works. ''range'' now refers to all the possible movements that can end
with our unit being at ''adjacent_tiles[n]''. Let's iterate over all those movements, and find if any of them give a better defensive rating than our current best defense. We'll start our iteration by creating some aliases that ensure we don't go crazy ;)

while(range.first != range.second) {
const location& dst = range.first->first;
const location& src = range.first->second;

Now let's find out about the unit that we're planning to send to this destination:

const unit_map::const_iterator un = get_info().units.find(src);
assert(un != get_info().units.end());

We can assume that the unit is in that location (hence the assert), because ''calculate_possible_moves()'' said that it's the possible source of a move. Let's find out the type of terrain we're planning to move to:

const gamemap::TERRAIN terrain = get_info().map.get_terrain(dst);

Okay, so we have the unit, and we have the terrain, now we should be able to find out the unit's defensive rating on this terrain.
The ''unit'' class has a convenient ''defense_modifier()'' function which will tell us the chance of hitting that unit on a certain terrain.

const int chance_to_hit = un->second.defense_modifier(get_info().map,terrain);

So, now we have all that, if it's the best chance to hit we've seen so far, or we haven't seen any other chances to hit at all, then we add it as our best option seen.

if(best_defense == -1 || chance_to_hit < best_defense) {
best_defense = chance_to_hit;
best_movement = *range.first;
}

That's it for these two loops. Iterate and close:

++range.first;
}
}

Now if we found a possible move, best_defense will not be -1,
and the movement will be stored in ''best_movement''. So, if ''best_defense'' is -1, we want to move from ''best_movement.second'' to ''best_movement.first''.

if(best_defense != -1) {
move_unit(best_movement.second,best_movement.first,possible_moves);

Remember that ''possible_moves'' thing? That comes in useful here, where we have to give it to the display object so it can know the path to move the unit along. This is the only time we need to touch it.

Immediately after moving, we want to attack. First we need to know which weapon to use. We'll write a ''choose_weapon()''
function later which will choose our weapon. It'll have to take the location of the attacker and the location of the defender, and it'll return an int referring to our weapon of choice. For now we'll just make use of this function:

const int weapon = choose_weapon(best_movement.first,i->first);
attack_enemy(best_movement.first,i->first,weapon);

This will implement our attack. What now? We've attacked once, but we want to attack with as many units as we can attack with, right? We can't use the same move_maps again, because they'll be invalid now that we've moved and attacked. What we'll do is we'll call ''do_attacks()'' all over again, recursively, and return immediately. This way all our maps will be recalculated.

do_attacks();
return;
}
}
}
}

That's the entire function done. It'll keep attacking while it finds attacks, and when it finally runs out of attacks to execute, it'll return nicely. Let's write that ''choose_weapon()'' function now:

int choose_weapon(const location& attacker, const location& defender) {
const unit_map::const_iterator att = get_info().units.find(attacker);
assert(att != get_info().units.end());

const std::vector<a ttack_type>& attacks = att->second.attacks();

unit contains a convenient ''attacks()'' function which returns a vector of all a unit's possible attacks. We'll store the
best attack found so far, and iterate over all attacks:

int best_attack_rating = -1;
int best_attack = -1;
for(int n = 0; n != attacks.size(); ++n) {

There is a nice function called ''evaluate_battle_stats()'' in '''actions.hpp''' which will give us all sorts of information about a potential battle. We make use of it here:

const battle_stats stats = evaluate_battle_stats(get_info().map,
attacker, defender, n, get_info().units,
get_info().state, get_info().gameinfo, 0, false);

A rather complicated function call, but most of the parameters can be pulled straight from ''get_info()''. The last two parameters are a little confusing. The first one of these, ''attacker_terrain_override'', is used if we wanted to know what the combat would look like if the attacker was on different terrain to what it is on now. If this is non-0, the function will assume the attacker is on the type of terrain given. This is useful if you want to test the possibility of moving to many different hexes without actually moving there. The last parameter is false, meaning that strings won't be included in the results. Strings are useful for showing to a player in a dialog,
but not useful for an AI, and are expensive to calculate, so this should always be false from within AI algorithms.

Let's use our stats to come up with a rating for this attack:

const int attack_rating = stats.damage_defender_takes*stats.nattacks*stats.chance_to_hit_defender;

Now if this is the best attack, we can use it,

if(best_attack == -1 || attack_rating > best_attack_rating) {
best_attack = n;
best_attack_rating = attack_rating;
}
}

return best_attack;
}

Now we're done with that, we can move onto our ''get_villages()'' function. We start off by calculating possible moves,

void get_villages() {
std::map<location,paths> possible_moves;
move_map srcdst, dstsrc;
calculate_possible_moves(possible_moves,srcdst,dstsrc,false);

Now it's a simple matter of iterating over possible destinations,
and seeing if they are villages not controlled by us:

for(move_map::const_iterator i = dstsrc.begin(); i != dstsrc.end(); ++i) {
if(get_info().map.is_village(i->first) &&
current_team().owns_village(i->first) == false) {

First it checks whether the destination is a village. The right side of the ''&&'' simply sees if our team owns the village at that location or not. If we don't own the village, we've found the movement we want to make, and we recurse and return.

move_unit(i->second,i->first,possible_moves);
get_villages();
return;
}
}
}

Just a couple more functions now. Firstly, ''do_moves()'' is meant to move our units toward the enemy leader. Well, there may be multiple enemies and thus more than one leader, so we'll just go for the first enemy leader we can find. We start off by trying to find the enemy leader:

void move_units() {
unit_map::const_iterator leader;
for(leader = get_info().units.begin(); leader != get_info().units.end(); ++leader) {

A unit is a leader if it can recruit -- so we use the ''can_recruit()'' function to test if it's a leader.

if(leader->second.can_recruit() && current_team().is_enemy(leader->second.side())) {
break;
}
}

We better have found an enemy leader, otherwise we'll just return...

if(leader == get_info().units.end())
return;

Now, let's find all our unit's possible moves:

std::map<location,paths> possible_moves;
move_map srcdst, dstsrc;
calculate_possible_moves(possible_moves,srcdst,dstsrc,false);

We want to find the move that'll take us as close as possible to the enemy leader. Let's make our variables to show us the best move so far,

int closest_distance = -1;
std::pair<location,location> closest_move;

Now iterate and find the destination closest to the enemy leader:

for(move_map::const_iterator i = dstsrc.begin(); i != dstsrc.end(); ++i) {
const int distance = distance_between(i->first,leader->first);
if(closest_distance == -1 || distance < closest_distance) {
closest_distance = distance;
closest_move = *i;
}
}

If ''closest_distance'' is not -1, we've found a valid move that'll take one of our units toward the enemy leader. We can make the move and recurse

if(closest_distance != -1) {
move_unit(closest_move.second,closest_move.first,possible_moves);
do_moves();
}
}

Okay, all our movement functions are done! Now all we've got left is the recruitment function. We start by getting the units that we can recruit.

void do_recruitment() {
const std::set<std::string>& options = current_team().recruits();

We can choose the number of a unit to recruit at random:

const int choice = (rand()%options.size());
std::set<std::string>::const_iterator i = options.begin();
std::advance(i,choice);
const bool res = recruit(*i);

And if the recruitment succeeds, we will try to recruit another unit,

if(res) {
do_recruitment();
}
}
};

That's it! We've made our ''sample_ai''. All we have to do is add it to ''create_ai'' in '''ai.cpp''' and we're done!

== AI - specific parameters ==

wesnoth --multiplayer --controller1=ai --controller2=ai --algorithm1=z_ai --algorithm2=sample_ai

Use the ''--nogui'' switch before ''--multiplayer'' to make the game run without displaying a GUI. The winner will be reported on stdout.

== See Also ==

* [[DeveloperResources]]
* [[PythonTestScript]] - Simple Python AI test script

[[Category:Create]]
[[Category:AI]]

LuaWML

2012-11-27T16:33:31Z

Alarantalara: Add AI caetgory

Machine Learning Recruiter

2012-11-23T03:52:46Z

Alarantalara: /* Win percentages for different AI Pairs */ Remove result for Ron, since expected release did not occur in time and Ron has since changed

SpellingMistakes

2012-11-19T21:39:30Z

Alarantalara: /* Under the Burning Suns */ Corrected report in trunk

This page is meant to be a list of spelling mistakes in campaigns and other translatable texts in the en_US development version of the game.

Note: The house style of Wesnoth uses a good many words and constructions that are archaic, poetic, or dialectal. If you speak modern English as a second language you may incorrectly read these as errors. Please see [[NotSpellingMistakes]] for a list of things you will encounter that may look like spelling or usage errors but are not. Note that the mainline campaigns are now using correct typography, including sexed quotes and en and em dashes. These will appear as three byte sequences if you are not using a viewer that supports UTF-8.

==Mainline Campaigns==

===An Orcish Incursion===

===Dead Water===

===Delfador’s Memoirs===
* "Yes, close by the southeast wall of our fort across '''the the''' Ford. But they are jealous of their privileges and hold aloof from us." scenario 12_Terror_at_the_Ford_of_Parthyn.cfg:418
* "He is a like a blazing fire". Seems strange to me, however English is not my native language. I would have writen "He is like a blazing fire" or maybe "He is alike a blazing fire" ? scenario 14_Shadows.cfg:304
* "I will send Dudpon, instead with most of my army", I would move the comma : "I will send Dudpon instead, with most of my army" 16_Dark_Sky_Over_Weldyn.cfg:71
* "Defeat all enemies" is using in three scenarios but, at least in one of them (Terror at the Ford of Parthyn) you only need to defeat all enemy '''leaders'''

===Descent into Darkness===

===Eastern Invasion===

===Heir to the Throne===

===Liberty===

===Northern Rebirth===

===Sceptre of Fire===

===Son of the Black Eye===

===The Hammer of Thursagan===

===The Legend of Wesmere===

===The Rise of Wesnoth===

===The South Guard===

===Two Brothers===

==Wesnoth Game==

===Editor===

===Help===

"Undead", 1st paragraph: "An undead creature does not require the constant attention of the necromancer to command and sustain, but can work autonomously according to the commands of it's master." should be changed to "...of '''its''' master."

===Tutorial===

===Manual===

===Manpages===

===Units===

===1.10 Announcement===

===Other (unit descriptions, ...)===

===Multiplayer maps===

===Translation code bugs===

==Unofficial campaigns==

===Invasion from the Unknown===

Machine Learning Recruiter

2012-11-14T00:56:38Z

Alarantalara: /* Win percentages for different AI Pairs */ Add result when Arcanclave Citadel is not included

This page documents the new machine learning recruiter submitted as a patch for Wesnoth 1.11.0. We describe how to run it, discuss experiments showing that the ML Recruiter achieves dramatically better performance than the RCA AI recruiter, describe known issues and suggest a development road map.

Note that the ML Recruiter is a work in progress. We welcome feedback on it. Please discuss it on the thread "Machine Learning Recruiter" at http://forums.wesnoth.org/viewtopic.php?f=10&t=36642.

=Why include ML Recruiter in Wesnoth?=

The ML Recruiter makes use of a small subset of the [http://waffles.sourceforge.net/ Waffles] Machine Learning toolkit adding 13 pairs of .cpp/.h files to Wesnoth. In addition, the neural nets used by ML Recruiter are serialized as .json files, which is a format Wesnoth has not yet contained. So why is this patch worthwhile?
==Why the ML Recruiter will be great for Wesnoth==
# Performance is great. ML Recruiter defeats RCA AI 66-73% of the time. We suspect that this would also translate into better performance against human opponents because it also performs better against the "ron" recruiter included in [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976 AI-Demos], which is a more challenging opponent.
# This superior performance is achieved with comparable "fun factor"
#* Variety of units recruited by recommended ML Recruiter is comparable to or better than RCA AI
# Don't need to eliminate RCA AI recruiter. Campaign designers can choose to use one or the other
# ML Recruiter should be easier to customize than RCA AI because
#* All core logic is in Lua, which is easier to modify than existing C++
#* Performance "out of the box" on known units likely to be strong
#* When new recruitable units are introduced by campaign designers, it can be trained by running c. 600 games in two hours. The new model is included as a .json file with the campaign data
#* Plug and play architecture of machine learning "features" easily allows minor modifications to mainline recruiter or to campaign-specific recruiters
# Easy way to adjust campaign difficulty: Adjusting ML AI for more/less randomness makes is easier/harder to defeat
# Inclusion of ML Recruiter could lead to greater publicity and more contributors to Wesnoth
## SeattleDad plans to submit this work as a scientific paper to a conference such as [http://eldar.mathstat.uoguelph.ca/dashlock/CIG2013/ Computational Intelligence in Games]
## Others might later build on this work by, for instance, trying ML algorithms other than neural nets, adding new features, further generalizing the algorithm, etc.
## The machine learning infrastructure is not specific to recruiting and could be repurposed for, for instance, attack planning, weapon selection, and making "retreat and heal" vs. "attack" decisions
## All of the above is potentially publishable research, so Wesnoth could attract contributions from computer science graduate students
### Note that, having established the basic framework with this patch, future work on machine learning will be much easier

=Using ML Recruiter=
==Applying the patch==
* Get the latest version of the patch from https://gna.org/patch/?3479
* Get the Wesnoth 1.11.0 source as per http://wesnoth.org
* Apply the patch as follows:
patch -p1 -i [path to patch file]
* Compile Wesnoth using CMake, SCons, or XCode

==Playing against the ML Recruiter==
# From the main menu, choose "Multiplayer"
# Choose "Local Game"
# Pick a map and adjust settings as desired. ML Recruiter has been trained with the default setting for village gold and support, but it should work fine on other settings
## Hit Okay
# For one side, Choose Player/Type-->Computer Player and then either ML AI (Recommended) or ML AI (Less Variety, probably stronger)
## For the opponent, either play against it yourself (pick your name), watch it play the default AI (Computer Player-->RCA AI), or watch it play itself (pick ML AI again)

==Watching the ML Recruiter play a single game in nogui mode==
The following command is convenient for watching the ML Recruiter play a single game in nogui mode, which allows you to quickly and easily see the ML Recruiter's decision-making process. In this example, we would be running the ML AI (Recommended mode) for the Knalgan Alliance, while the default AI would be playing the Rebels. Note that when run this way (with --log-info=ai/testing,ai/ml), a lot of logging messages will be printed to the console which will describe how the ML Recruiter is analyzing its options.
Wesnoth --log-info=ai/testing,ai/ml --nogui --multiplayer --controller 1:ai --controller 2:ai --parm 1:gold:100 --parm 2:gold:100 --parm 1:village_gold:2 --parm 2:village_gold:2 --scenario multiplayer_Weldyn_Channel --parm 1:gold:100 --parm 2:gold:100 --ai-config 1:ai/ais/ml_ai.cfg --ai-config 2:ai/dev/default_ai_with_recruit_log.cfg --side 1:"Knalgan Alliance" --side 2:Rebels

==Testing the ML Recruiter in batch mode==

Testing in batch mode is easy with the new version of ai_test2.py included in the patch. After applying the ML Recruiter patch, copy utils/ai_test/ai_test2.cfg to the directory in which you want to run the experiment. Then edit the first line of the .cfg file, "path_to_wesnoth_binary" to point to your Wesnoth executable. Then adjust faction1 and faction2 to point to the factions you want to experiment with and point ai_config1 at the ML configuration file you want to try out. Finally, to make everything easier, add the following to your path:
[Wesnoth_Install]/utils/ai_test/
Now you can test Wesnoth in batch as follows:
ai_test2.py ai_test2.cfg

=Experimental Results=

==Win percentages for different AI Pairs==
{| border="1" cellpadding="20" cellspacing="0"
!AI1
!AI2
!Games
!Win % for AI1
!Comment
|-
|ML Recruiter 0.3 (Less Variety)
|RCA AI
|1179
|69.3%
|"Less variety/probably stronger version". Wins 73.4% of the time on the maps version 0.2 was trained on
|-
|ML Recruiter 0.3 (Recommended)
|RCA AI
|2363
|66.6%
|"Recommended version". Same version as above, but has more randomness in its choice of units. See [http://wiki.wesnoth.org/Machine_Learning_Recruiter#The_Weighted_Random_.28Recommended.29_Recruiter documentation on weighted random recruiter]
|-
|ML Recruiter 0.3
|ML Recruiter 0.2
|1937
|58.0%
|We've made a lot of progress since version 0.2
|-
|ML Recruiter 0.3
|Ron Recruiter 0.11.4
|1186
|54.1%
|Ron Recruit is the recruiter build into [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976&start=405 AI Demos]
|-
|ML Recruiter 0.3
|Ron Recruiter 0.12.0
|1355
|41.8%
|Maps such as Arcanclave Citadel show that recruit location is a significant factor in success. If the games on Arcanclave Citadel are not included, the ML recruiter wins 45.1% of the games.
|-
|ML Recruiter 0.3 (Recommended)
|ML Recruiter 0.3 (Less variety)
|1186
|49.6%
|Difference is not statistically significant, so we pick the variant with more variety as the "Recommended" version. Note, though, that the "Less variety" version does a bit better against the RCA AI as you can see above.
|-
|RCA AI
|RCA AI
|
|50%
|Any AI against itself will win 50% of the time
|-
|RCA AI
|Random
|3,000
|52.7%
|Interesting result. You would expect a completely random choice to get beat by a wider margin
|}

==Faction vs. faction win % for ML Recruiter 0.3 vs. RCA AI==

These results are for the "Recommended" version

<code>
all/data/138 $ analyze_log.py *.log

Overall Stats
AI Wins Win %
default_ai_with_recruit_log 789 33.4%
ml_ai 1574 66.6%
Totals: 2363

Wins Loss Win %
Drakes vs Undead 33 39 45.8%
Drakes vs Northerners 20 39 33.9%
Drakes vs Loyalists 66 11 85.7%
Drakes vs Knalgan Alliance 38 40 48.7%
Drakes vs Drakes 52 19 73.2%
Drakes vs Rebels 46 2 95.8%
Total Drakes 255 150 63.0%

Knalgan Alliance vs Undead 48 19 71.6%
Knalgan Alliance vs Northerners 23 48 32.4%
Knalgan Alliance vs Loyalists 40 14 74.1%
Knalgan Alliance vs Knalgan Alliance 36 23 61.0%
Knalgan Alliance vs Drakes 34 26 56.7%
Knalgan Alliance vs Rebels 46 21 68.7%
Total Knalgan Alliance 227 151 60.1%

Loyalists vs Undead 32 41 43.8%
Loyalists vs Northerners 17 48 26.2%
Loyalists vs Loyalists 58 5 92.1%
Loyalists vs Knalgan Alliance 53 19 73.6%
Loyalists vs Drakes 52 10 83.9%
Loyalists vs Rebels 30 29 50.8%
Total Loyalists 242 152 61.4%

Northerners vs Undead 59 6 90.8%
Northerners vs Northerners 49 21 70.0%
Northerners vs Loyalists 51 9 85.0%
Northerners vs Knalgan Alliance 60 7 89.6%
Northerners vs Drakes 56 14 80.0%
Northerners vs Rebels 55 5 91.7%
Total Northerners 330 62 84.2%

Rebels vs Undead 42 14 75.0%
Rebels vs Rebels 51 15 77.3%
Rebels vs Loyalists 71 8 89.9%
Rebels vs Knalgan Alliance 50 15 76.9%
Rebels vs Drakes 44 22 66.7%
Rebels vs Northerners 21 40 34.4%
Total Rebels 279 114 71.0%

Undead vs Undead 41 37 52.6%
Undead vs Northerners 25 55 31.2%
Undead vs Loyalists 51 18 73.9%
Undead vs Knalgan Alliance 57 6 90.5%
Undead vs Drakes 41 9 82.0%
Undead vs Rebels 26 35 42.6%
Total Undead 241 160 60.1%

</code>

==Units recruited by Recommended ML Recruiter==

Results are for Recommended AI vs. RCA AI for ML Recruiter 0.3

<code>
Grand Totals
Drakes Recruitment Count %
Drake Burner 2925 28.3%
Drake Clasher 909 8.8%
Drake Fighter 2159 20.9%
Drake Glider 1156 11.2%
Saurian Augur 2197 21.3%
Saurian Skirmisher 985 9.5%
Total: 10331

Knalgan Alliance Recruitment Count %
Dwarvish Fighter 1535 14.4%
Dwarvish Guardsman 543 5.1%
Dwarvish Thunderer 4171 39.0%
Dwarvish Ulfserker 767 7.2%
Footpad 1573 14.7%
Gryphon Rider 847 7.9%
Poacher 677 6.3%
Thief 576 5.4%
Total: 10689

Loyalists Recruitment Count %
Bowman 1799 15.6%
Cavalryman 551 4.8%
Fencer 345 3.0%
Heavy Infantryman 1109 9.6%
Horseman 930 8.0%
Mage 934 8.1%
Merman Fighter 852 7.4%
Spearman 5040 43.6%
Total: 11560

Northerners Recruitment Count %
Goblin Spearman 181 1.4%
Naga Fighter 504 3.9%
Orcish Archer 2480 19.1%
Orcish Assassin 1842 14.2%
Orcish Grunt 2524 19.5%
Troll Whelp 4833 37.3%
Wolf Rider 608 4.7%
Total: 12972

Rebels Recruitment Count %
Elvish Archer 1833 17.6%
Elvish Fighter 3213 30.8%
Elvish Scout 1086 10.4%
Elvish Shaman 222 2.1%
Mage 435 4.2%
Merman Hunter 768 7.4%
Wose 2865 27.5%
Total: 10422

Undead Recruitment Count %
Dark Adept 2460 20.7%
Ghost 827 7.0%
Ghoul 1474 12.4%
Skeleton 2386 20.1%
Skeleton Archer 3772 31.7%
Vampire Bat 668 5.6%
Walking Corpse 308 2.6%
Total: 11895
</code>

==Units recruited by Recommended ML Recruiter vs Undead==
As a breakdown of the above, it's interesting to look at the different unit blends that ML Recruiter 0.3 selects vs. the Undead as opposed to the overall totals shown above. MLR's RCA AI opponent recruits a unit blend which consists of just the following four units:

RCA AI Recruitment for Undead:
<code>
Undead Recruitment Count %
Dark Adept 3163 28.4%
Ghost 2451 22.0%
Skeleton 3574 32.1%
Skeleton Archer 1941 17.4%
Total: 11129
</code>
ML Recruiter 0.3 units recruited against the RCA AI Undead. Notice the large increase in the number of units with impact and fire attacks, which would be effective against Skeletons and the decrease in Orcish Assassins and Ghouls, which are ineffective against every Undead unit except Dark Adepts.

<code>
Results for enemy faction:Undead
Drakes Recruitment Count %
Drake Burner 666 37.8%
Drake Clasher 37 2.1%
Drake Fighter 478 27.1%
Drake Glider 339 19.2%
Saurian Augur 91 5.2%
Saurian Skirmisher 152 8.6%
Total: 1763

Knalgan Alliance Recruitment Count %
Dwarvish Fighter 352 17.2%
Dwarvish Guardsman 31 1.5%
Dwarvish Thunderer 259 12.7%
Dwarvish Ulfserker 170 8.3%
Footpad 945 46.2%
Gryphon Rider 153 7.5%
Poacher 66 3.2%
Thief 70 3.4%
Total: 2046

Loyalists Recruitment Count %
Bowman 125 6.7%
Cavalryman 45 2.4%
Fencer 65 3.5%
Heavy Infantryman 533 28.6%
Horseman 20 1.1%
Mage 538 28.8%
Merman Fighter 103 5.5%
Spearman 437 23.4%
Total: 1866

Northerners Recruitment Count %
Goblin Spearman 24 1.1%
Naga Fighter 60 2.8%
Orcish Archer 778 36.9%
Orcish Assassin 43 2.0%
Orcish Grunt 202 9.6%
Troll Whelp 952 45.1%
Wolf Rider 51 2.4%
Total: 2110

Rebels Recruitment Count %
Elvish Archer 92 6.9%
Elvish Fighter 265 19.9%
Elvish Scout 83 6.2%
Elvish Shaman 50 3.8%
Mage 176 13.2%
Merman Hunter 41 3.1%
Wose 625 46.9%
Total: 1332

Undead Recruitment Count %
Dark Adept 548 23.1%
Ghost 56 2.4%
Ghoul 153 6.4%
Skeleton 777 32.7%
Skeleton Archer 669 28.1%
Vampire Bat 80 3.4%
Walking Corpse 94 4.0%
Total: 2377
</code>

=How the ML Recruiter works=

When it's deciding what to recruit, the ML Recruiter works by predicting a "metric" which is a measure of how well a given unit will do in the game in the current situation. A good measure of a unit's usefulness is a tricky question and we will discuss three different metrics below, but let's start with the easiest one, which is the sum of the following quantities for each unit:

# Experience points at the end of the game or when the unit is killed
# Number of villages captured by the unit

Note that this metric is blind to other ways a unit can help you (in particular, it doesn't know about poison, healing, and slowing).

This sum, which we'll call the "metric" is then divided by the unit cost to get metric/cost (think of this as goodness per unit of gold). You can see this in the debugging output that the ML Recruiter prints to stderr when run with the flag --log-info=ai/testing,ai/ml:
unit type metric cost wt cost weighted metric
Elvish Shaman 8.58 15 15.00 0.57
Elvish Fighter 10.42 14 14.00 0.74
Elvish Scout 8.47 18 18.00 0.47
Wose 17.07 20 20.00 0.85
Mage 10.37 20 20.00 0.52
Elvish Archer 8.46 17 17.00 0.50
Merman Hunter 8.55 15 15.00 0.57

This is from the first turn of a game between the Rebels and the Undead. The ML Recruiter is predicting that if it recruits a Wose now, it will end with 17.07 XP + Village Captures. 17.07/20 = 0.85, which is the highest weighted metric at this time, so it picks a Wose as it's top choice.

How does it know to pick a Wose? It looks at the "features" which describe the current situation. Here's another chart from the same game:

unit type metric cost wt cost weighted metric
Elvish Shaman 7.18 15 15.00 0.48
Elvish Fighter 11.82 14 14.00 0.84
Elvish Scout 7.91 18 18.00 0.44
Wose 15.53 20 20.00 0.78
Mage 9.11 20 20.00 0.46
Elvish Archer 9.38 17 17.00 0.55
Merman Hunter 8.36 15 15.00 0.56
Side: 1 Gold: 21 Unit we want: Elvish Fighter
PRERECRUIT:, enemy Dark Adept:1 , enemy Deathblade:1 , enemy Ghost:2 , enemy Skeleton:3 , enemy faction:Undead ,
enemy gold:10 , enemy level3+:0 , enemy total-gold:139 , enemy unit-gold:129 , friendly Elvish Captain:1 ,
friendly Elvish Fighter:1 , friendly Wose:4 , friendly faction:Rebels , friendly gold:21 , friendly level3+:0 ,
friendly total-gold:161 , friendly unit-gold:140 , side:1 , terrain-forest:0.082 , terrain-mountain-hill:0.113 ,
terrain-water-swamp:0.164 , total-gold-ratio:0.537 , turn:4 , village-control-margin:-2 , village-control-ratio:0.417 , village-enemy:7 ,
village-friendly:5 , village-neutral:4 ,

The "features" that it sees are the values following "PRERECRUIT". The ML AI sees that the enemy faction is the Undead and that they have one Deathblade, two ghosts, three Skeletons. The Rebels currently have 4 Wose, 1 Elvish Fighter, and 1 Elvish Captain. It also sees a number of other features like how much gold it and its opponent have, what percentage of each the map is covered by different terrain, and how many friendly, neutral, and enemy villages there are. In this situation, although it still sees that the Wose is likely to score higher on the XP + village capture metric (15.5 vs. 11.8), this isn't enough to overcome the price differential, so it chooses an Elvish Fighter as it's best choice with a weighted metric of 0.84.

Note that these predictions of 15.5 vs. 11.8 are computed by the neural net based on a model built from what the algorithm has seen has happened in similar situations during training.

==Unit Goodness Metrics==
We have experimented with three different unit goodness metrics. All of these metrics are designed to have the property that the higher the value of the metric, the better the unit performed in a a given game. Clearly there is a random element here. In some games when playing against a Skeleton-heavy Undead army, an Elvish Archer, which uses mainly a pierce attack, may get lucky and do better than a Wose, which has an impact attack, but on average the metric should show that the Wose performs better.

The three metrics we've looked at are as follows:

===Experience Point plus Village Capture===
This is the metric used in ML Recruiter 0.2. As noted above, it is the sum of the following quantities:

# Experience points at the end of the game or when the unit is killed
# Number of villages captured by the unit

This metric has the advantage that experience points lead to promotion, which is a very good thing. Also, getting kills should be correlated with how much damage the unit is doing. Adding village captures to experience points is a little flaky, but is intended to give credit to fast units, which are more likely to capture villages.

===Victory===

This metric gives a unit 1.0 if its side wins and 0 if its side loses. The effect is that the neural net's prediction for each unit can be seen as "what is the probability of victory if I recruit this unit in this situation". This is the most natural of all metrics, but experimentally it hasn't performed as well in terms of leading to actual victories as recruiting based on unit-based metrics. Performance has peaked at around a 59% win ratio for a victory metric vs. around 66 - 73% for the XP+VC metric. We think the problem is that the impact of recruiting a single unit of Type A vs. Type B on the victory probability is very small, so the neural net isn't differentiating among the choices enough.

===Gold Yield===

As of ML Recruiter 0.3, this is the new default metric. It is the sum of the following quantities, all of which are intended to quantify a unit's usefulness in terms of how much gold benefit it has yielded for the friendly side plus gold damage done to the enemy side. This metric builds off of a [http://forums.wesnoth.org/viewtopic.php?f=10&t=36642&sid=11062936e4f4c0bab673470b5d211987&start=45#p536132 suggestion] from Sapient.
# Basic Damage Metric: Target unit cost * (Damage inflicted/target max HP). The concept is that you cost your opponent this much gold by destroying this fraction of the unit. Obviously in any given attack, we would calculate this for both the attacker and the defender.
# Village Capture: capturing_unit.variables.ml_gold_yield += wesnoth.game_config.village_income. (Defaults to crediting 2 gold per village capture)
#* The idea, again, is that fast units tend to get more captures than slow units and this gives units credit for being fast.
# Poison: Treated the same as Basic Damage Metric by crediting for the amount of damage done in that turn. On the turn in which the unit is cured, the poisoner is credited with Target Unit Cost * (8/target max HP) to reflect the damage that it would have healed if it hadn't been poisoned (obviously, lessened if it has less than 8 HP of damage)
# Slowing: When a unit is on defense and it slows the attacker, the defender gets no special credit because the attacker just unslows at the end of its turn. When you slow a unit as the attacker, the slowing unit gets credit for the Basic Damage Metric accumulated by the slowed unit until it unslows (the slowed unit would otherwise have done twice as much damage, so you get credit for the damage it didn't do)
# Healing: healing_unit.variables.ml_gold_yield += Healed_unit_cost * (healed amount/healed unit max HP)
#* Directly analogous to the Basic Damage Metric
#* Note that healers also get credit for curing/stopping poison
# Walking Corpse Creation: Credit a unit which gets a kill which creates a unit due to its plague ability with 8 gold (the value of a Walking Corpse). (not implemented)
# Leadership: Credit the leader for the bonus damage inflicted by the unit being led (not implemented)
# Maintenance: Charge units for their share of the maintenance costs, weighted by level. Hence, level 0 units never pay maintenance. Level 2 units pay for twice as much maintenance. (not implemented)

==How MLR makes weighted random choices==
The recommended recruiter is defined in ai/ais/ml_ai.cfg. It is called "Recommended" in the user interface. Although we are currently measuring it as performing roughly the same or slightly worse than the "Less variety/probably stronger" ML AI (ai/ais/ml_ai_less_random.cfg), we recommend it because it allows the player to see a greater variety of opposing units.

The weighted random printout looks like the following:

Turn 13:
unit type metric cost metric/ weighted %
cost m/c of total
Merman Hunter 1.10 15 0.07 0.0000 0.0%
Wose 1.72 20 0.09 0.0000 0.1%
Elvish Shaman 1.66 15 0.11 0.0000 0.4%
Elvish Archer 2.71 17 0.16 0.0000 4.0%
Elvish Fighter 2.54 14 0.18 0.0000 8.5%
Mage 4.18 20 0.21 0.0001 20.1%
Elvish Scout 4.60 18 0.26 0.0003 66.8%
Random Number chosen was 376
Side: 1 Gold: 27 Unit we want: Elvish Scout
PRERECRUIT:, enemy Dark Adept:2 , enemy Revenant:1 , enemy Skeleton:1 , enemy faction:Undead , enemy gold:8 ,
enemy level3+:0 , enemy total-gold:83 , enemy unit-gold:75 , friendly Elder Wose:1 , friendly Elvish Fighter:2 ,
friendly Elvish Ranger:1 , friendly Mage:1 , friendly Wose:3 , friendly faction:Rebels , friendly gold:27 ,
friendly level3+:0 , friendly total-gold:225 , friendly unit-gold:198 , side:1 , terrain-forest:0.082 ,
terrain-mountain-hill:0.113 , terrain-water-swamp:0.164 , total-gold-ratio:0.731 , turn:13 ,
village-control-margin:0 , village-control-ratio:0.5 , village-enemy:8 , village-friendly:8 , village-neutral:0 ,

This situation occurs towards the end of a game that the Rebels are winning. Note that total-gold-ratio (the ratio between the sum of gold + the value of all units on each side) is 0.731, so it's heavily in the Rebels' favor. The ML AI sees an Elvish Scout as being the best choice in this situation with a Mage in second place. The Elvish Scout is probably favored because the game is likely to be won rapidly and only a fast unit will be able to reach the enemy or reach a village fast enough to add to its "experience points + village capture" metric.

The Weighted Random does the following:
# It takes every metric/cost value and raises it to the sixth power. Why? We want to magnify the differences. In this example 0.26/0.21 = 1.23, but (0.26**6)/(0.21**6) = 3.60.
# We then randomly choose a unit with a probability proportional to this weighted value which, in this case, was an Elvish Scout.

The Less Variety/Probably Stronger AI does the same thing, but raises metric/cost to the 24th power instead of the 6th power. This still allows for some randomness, but weights the selection much more strongly towards the more favored units.

=How to train your own ML Recruiter=
utils/ai_test/run_model_and_make_new_model.py is an end-to-end script for running a whole bunch of training games of Wesnoth and then training a new model based on the data output by that run. Documentation on this script can be seen by running
run_model_and_make_new_model.py --help
Note that this script assumes that [http://waffles.sourceforge.net/ the Waffles machine learning toolkit] is installed and that waffles/bin/ is in your path.

=Known issues=
==Bugs==
# Haven't added new Waffles files to Visual C++, so it won't compile under VC++. I need some help with this.
# The default for multiplayer games is that units require only 70% of normal experience to promote, however when a game is run from the command line, it always requires normal 100% of experience to promote. Consequently MLR doesn't see units promote as much as they should in training, which would slightly distort its training data. This is a [https://gna.org/bugs/?19895 limitation of Wesnoth], not MLR.

==Current Limitations==
# Only tested on two-player multiplayer games. Doesn't work when there are more than two leaders on the map.
# Works on all two-player maps except for Hornshark Island, Thousand Stings, Caves of the Basilisk, and Dark Forecast
# As noted above in [http://wiki.wesnoth.org/Machine_Learning_Recruiter#Gold_Yield Gold Yield Metric], we account for all special abilities available in the main-line multiplayer scenarios except for plague, leadership, and unit maintenance costs

=ML Recruiter development roadmap=

* ML Recruiter 0.1: Initial drop
* ML Recruiter 0.1.1: Minor retraining of the model
* ML Recruiter 0.2:
** Logging messages changed from print statements to using lg::log_domain.
** Now have an explicit debug mode by running with --log-debug=ai/ml.
** ML Recruiter can play against itself. Previously could only have ML Recruiter on one side.
** Some work on ML recruiting model (i.e. the core logic). Experimented with different training strategies, but features unchanged from 0.1.
* ML Recruiter 0.3 (10/25/2012) :
** New "gold yield" metric for judging a unit's goodness
** Several new ML features to aid in prediction: alignment, race, time of day, map size, friendly and enemy leader hit point percentage remaining, and nearest enemy unit to friendly leader
** Runs on all 2-player maps except for Hornshark Island, Thousand Stings, Caves of the Basilisk, and Dark Forecast
** Greatly improved ai_test2.py script for running thousands of games to test AI and gather data for the neural net
** New script (run_model_and_make_new_model.py) for running games and building a new neural net based on the data gathered from those games
** Improved performance: Defeats ML Recruiter 0.2 58% of the time
* ML Recruiter 0.4 (11/11/2012):
** Run on all 2-player maps (except Dark Forecast, which has a custom recruiter)
** Refactor code to separate features from predicted values
** Added timeout option to ai_test2.py. Also report time statistics in analyze_log.py
** Improved recruiter for the Ron recruiter. It still underperforms the Ron recruiter on most maps when used with the other Ron CA's, though.
** Move all code into [https://github.com/mattsc/Wesnoth-AI-Demos AI-Demos project on GitHub]. the ML Recruiter 0.4 patch now consists, essentially, of only the C++ code modifications.
* ML Recruiter 0.5 (planned)
** Run on all mainline multiplayer maps
** Experiment with using as the [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976 AI-Demos] recruiter
** Add missing special abilities (plague, leadership, and unit upkeep)
** Add 95% confidence intervals to the win ratios in analyze_log.py and add measures of entropy (randomness) to analyze_recruitment.py. Entropy is a good measure of the variety of units that a recruiter is recruiting--for game play, more is better.

Machine Learning Recruiter

2012-11-14T00:46:39Z

Alarantalara: /* Win percentages for different AI Pairs */ Add results for ML Recruiter 0.3 vs latest Ron recruit to illustrate importance of recruit location

This page documents the new machine learning recruiter submitted as a patch for Wesnoth 1.11.0. We describe how to run it, discuss experiments showing that the ML Recruiter achieves dramatically better performance than the RCA AI recruiter, describe known issues and suggest a development road map.

Note that the ML Recruiter is a work in progress. We welcome feedback on it. Please discuss it on the thread "Machine Learning Recruiter" at http://forums.wesnoth.org/viewtopic.php?f=10&t=36642.

=Why include ML Recruiter in Wesnoth?=

The ML Recruiter makes use of a small subset of the [http://waffles.sourceforge.net/ Waffles] Machine Learning toolkit adding 13 pairs of .cpp/.h files to Wesnoth. In addition, the neural nets used by ML Recruiter are serialized as .json files, which is a format Wesnoth has not yet contained. So why is this patch worthwhile?
==Why the ML Recruiter will be great for Wesnoth==
# Performance is great. ML Recruiter defeats RCA AI 66-73% of the time. We suspect that this would also translate into better performance against human opponents because it also performs better against the "ron" recruiter included in [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976 AI-Demos], which is a more challenging opponent.
# This superior performance is achieved with comparable "fun factor"
#* Variety of units recruited by recommended ML Recruiter is comparable to or better than RCA AI
# Don't need to eliminate RCA AI recruiter. Campaign designers can choose to use one or the other
# ML Recruiter should be easier to customize than RCA AI because
#* All core logic is in Lua, which is easier to modify than existing C++
#* Performance "out of the box" on known units likely to be strong
#* When new recruitable units are introduced by campaign designers, it can be trained by running c. 600 games in two hours. The new model is included as a .json file with the campaign data
#* Plug and play architecture of machine learning "features" easily allows minor modifications to mainline recruiter or to campaign-specific recruiters
# Easy way to adjust campaign difficulty: Adjusting ML AI for more/less randomness makes is easier/harder to defeat
# Inclusion of ML Recruiter could lead to greater publicity and more contributors to Wesnoth
## SeattleDad plans to submit this work as a scientific paper to a conference such as [http://eldar.mathstat.uoguelph.ca/dashlock/CIG2013/ Computational Intelligence in Games]
## Others might later build on this work by, for instance, trying ML algorithms other than neural nets, adding new features, further generalizing the algorithm, etc.
## The machine learning infrastructure is not specific to recruiting and could be repurposed for, for instance, attack planning, weapon selection, and making "retreat and heal" vs. "attack" decisions
## All of the above is potentially publishable research, so Wesnoth could attract contributions from computer science graduate students
### Note that, having established the basic framework with this patch, future work on machine learning will be much easier

=Using ML Recruiter=
==Applying the patch==
* Get the latest version of the patch from https://gna.org/patch/?3479
* Get the Wesnoth 1.11.0 source as per http://wesnoth.org
* Apply the patch as follows:
patch -p1 -i [path to patch file]
* Compile Wesnoth using CMake, SCons, or XCode

==Playing against the ML Recruiter==
# From the main menu, choose "Multiplayer"
# Choose "Local Game"
# Pick a map and adjust settings as desired. ML Recruiter has been trained with the default setting for village gold and support, but it should work fine on other settings
## Hit Okay
# For one side, Choose Player/Type-->Computer Player and then either ML AI (Recommended) or ML AI (Less Variety, probably stronger)
## For the opponent, either play against it yourself (pick your name), watch it play the default AI (Computer Player-->RCA AI), or watch it play itself (pick ML AI again)

==Watching the ML Recruiter play a single game in nogui mode==
The following command is convenient for watching the ML Recruiter play a single game in nogui mode, which allows you to quickly and easily see the ML Recruiter's decision-making process. In this example, we would be running the ML AI (Recommended mode) for the Knalgan Alliance, while the default AI would be playing the Rebels. Note that when run this way (with --log-info=ai/testing,ai/ml), a lot of logging messages will be printed to the console which will describe how the ML Recruiter is analyzing its options.
Wesnoth --log-info=ai/testing,ai/ml --nogui --multiplayer --controller 1:ai --controller 2:ai --parm 1:gold:100 --parm 2:gold:100 --parm 1:village_gold:2 --parm 2:village_gold:2 --scenario multiplayer_Weldyn_Channel --parm 1:gold:100 --parm 2:gold:100 --ai-config 1:ai/ais/ml_ai.cfg --ai-config 2:ai/dev/default_ai_with_recruit_log.cfg --side 1:"Knalgan Alliance" --side 2:Rebels

==Testing the ML Recruiter in batch mode==

Testing in batch mode is easy with the new version of ai_test2.py included in the patch. After applying the ML Recruiter patch, copy utils/ai_test/ai_test2.cfg to the directory in which you want to run the experiment. Then edit the first line of the .cfg file, "path_to_wesnoth_binary" to point to your Wesnoth executable. Then adjust faction1 and faction2 to point to the factions you want to experiment with and point ai_config1 at the ML configuration file you want to try out. Finally, to make everything easier, add the following to your path:
[Wesnoth_Install]/utils/ai_test/
Now you can test Wesnoth in batch as follows:
ai_test2.py ai_test2.cfg

=Experimental Results=

==Win percentages for different AI Pairs==
{| border="1" cellpadding="20" cellspacing="0"
!AI1
!AI2
!Games
!Win % for AI1
!Comment
|-
|ML Recruiter 0.3 (Less Variety)
|RCA AI
|1179
|69.3%
|"Less variety/probably stronger version". Wins 73.4% of the time on the maps version 0.2 was trained on
|-
|ML Recruiter 0.3 (Recommended)
|RCA AI
|2363
|66.6%
|"Recommended version". Same version as above, but has more randomness in its choice of units. See [http://wiki.wesnoth.org/Machine_Learning_Recruiter#The_Weighted_Random_.28Recommended.29_Recruiter documentation on weighted random recruiter]
|-
|ML Recruiter 0.3
|ML Recruiter 0.2
|1937
|58.0%
|We've made a lot of progress since version 0.2
|-
|ML Recruiter 0.3
|Ron Recruiter 0.11.4
|1186
|54.1%
|Ron Recruit is the recruiter build into [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976&start=405 AI Demos]
|-
|ML Recruiter 0.3
|Ron Recruiter 0.12.0
|1355
|41.8%
|Maps such as Arcanclave Citadel show that recruit location is a significant factor in success.
|-
|ML Recruiter 0.3 (Recommended)
|ML Recruiter 0.3 (Less variety)
|1186
|49.6%
|Difference is not statistically significant, so we pick the variant with more variety as the "Recommended" version. Note, though, that the "Less variety" version does a bit better against the RCA AI as you can see above.
|-
|RCA AI
|RCA AI
|
|50%
|Any AI against itself will win 50% of the time
|-
|RCA AI
|Random
|3,000
|52.7%
|Interesting result. You would expect a completely random choice to get beat by a wider margin
|}

==Faction vs. faction win % for ML Recruiter 0.3 vs. RCA AI==

These results are for the "Recommended" version

<code>
all/data/138 $ analyze_log.py *.log

Overall Stats
AI Wins Win %
default_ai_with_recruit_log 789 33.4%
ml_ai 1574 66.6%
Totals: 2363

Wins Loss Win %
Drakes vs Undead 33 39 45.8%
Drakes vs Northerners 20 39 33.9%
Drakes vs Loyalists 66 11 85.7%
Drakes vs Knalgan Alliance 38 40 48.7%
Drakes vs Drakes 52 19 73.2%
Drakes vs Rebels 46 2 95.8%
Total Drakes 255 150 63.0%

Knalgan Alliance vs Undead 48 19 71.6%
Knalgan Alliance vs Northerners 23 48 32.4%
Knalgan Alliance vs Loyalists 40 14 74.1%
Knalgan Alliance vs Knalgan Alliance 36 23 61.0%
Knalgan Alliance vs Drakes 34 26 56.7%
Knalgan Alliance vs Rebels 46 21 68.7%
Total Knalgan Alliance 227 151 60.1%

Loyalists vs Undead 32 41 43.8%
Loyalists vs Northerners 17 48 26.2%
Loyalists vs Loyalists 58 5 92.1%
Loyalists vs Knalgan Alliance 53 19 73.6%
Loyalists vs Drakes 52 10 83.9%
Loyalists vs Rebels 30 29 50.8%
Total Loyalists 242 152 61.4%

Northerners vs Undead 59 6 90.8%
Northerners vs Northerners 49 21 70.0%
Northerners vs Loyalists 51 9 85.0%
Northerners vs Knalgan Alliance 60 7 89.6%
Northerners vs Drakes 56 14 80.0%
Northerners vs Rebels 55 5 91.7%
Total Northerners 330 62 84.2%

Rebels vs Undead 42 14 75.0%
Rebels vs Rebels 51 15 77.3%
Rebels vs Loyalists 71 8 89.9%
Rebels vs Knalgan Alliance 50 15 76.9%
Rebels vs Drakes 44 22 66.7%
Rebels vs Northerners 21 40 34.4%
Total Rebels 279 114 71.0%

Undead vs Undead 41 37 52.6%
Undead vs Northerners 25 55 31.2%
Undead vs Loyalists 51 18 73.9%
Undead vs Knalgan Alliance 57 6 90.5%
Undead vs Drakes 41 9 82.0%
Undead vs Rebels 26 35 42.6%
Total Undead 241 160 60.1%

</code>

==Units recruited by Recommended ML Recruiter==

Results are for Recommended AI vs. RCA AI for ML Recruiter 0.3

<code>
Grand Totals
Drakes Recruitment Count %
Drake Burner 2925 28.3%
Drake Clasher 909 8.8%
Drake Fighter 2159 20.9%
Drake Glider 1156 11.2%
Saurian Augur 2197 21.3%
Saurian Skirmisher 985 9.5%
Total: 10331

Knalgan Alliance Recruitment Count %
Dwarvish Fighter 1535 14.4%
Dwarvish Guardsman 543 5.1%
Dwarvish Thunderer 4171 39.0%
Dwarvish Ulfserker 767 7.2%
Footpad 1573 14.7%
Gryphon Rider 847 7.9%
Poacher 677 6.3%
Thief 576 5.4%
Total: 10689

Loyalists Recruitment Count %
Bowman 1799 15.6%
Cavalryman 551 4.8%
Fencer 345 3.0%
Heavy Infantryman 1109 9.6%
Horseman 930 8.0%
Mage 934 8.1%
Merman Fighter 852 7.4%
Spearman 5040 43.6%
Total: 11560

Northerners Recruitment Count %
Goblin Spearman 181 1.4%
Naga Fighter 504 3.9%
Orcish Archer 2480 19.1%
Orcish Assassin 1842 14.2%
Orcish Grunt 2524 19.5%
Troll Whelp 4833 37.3%
Wolf Rider 608 4.7%
Total: 12972

Rebels Recruitment Count %
Elvish Archer 1833 17.6%
Elvish Fighter 3213 30.8%
Elvish Scout 1086 10.4%
Elvish Shaman 222 2.1%
Mage 435 4.2%
Merman Hunter 768 7.4%
Wose 2865 27.5%
Total: 10422

Undead Recruitment Count %
Dark Adept 2460 20.7%
Ghost 827 7.0%
Ghoul 1474 12.4%
Skeleton 2386 20.1%
Skeleton Archer 3772 31.7%
Vampire Bat 668 5.6%
Walking Corpse 308 2.6%
Total: 11895
</code>

==Units recruited by Recommended ML Recruiter vs Undead==
As a breakdown of the above, it's interesting to look at the different unit blends that ML Recruiter 0.3 selects vs. the Undead as opposed to the overall totals shown above. MLR's RCA AI opponent recruits a unit blend which consists of just the following four units:

RCA AI Recruitment for Undead:
<code>
Undead Recruitment Count %
Dark Adept 3163 28.4%
Ghost 2451 22.0%
Skeleton 3574 32.1%
Skeleton Archer 1941 17.4%
Total: 11129
</code>
ML Recruiter 0.3 units recruited against the RCA AI Undead. Notice the large increase in the number of units with impact and fire attacks, which would be effective against Skeletons and the decrease in Orcish Assassins and Ghouls, which are ineffective against every Undead unit except Dark Adepts.

<code>
Results for enemy faction:Undead
Drakes Recruitment Count %
Drake Burner 666 37.8%
Drake Clasher 37 2.1%
Drake Fighter 478 27.1%
Drake Glider 339 19.2%
Saurian Augur 91 5.2%
Saurian Skirmisher 152 8.6%
Total: 1763

Knalgan Alliance Recruitment Count %
Dwarvish Fighter 352 17.2%
Dwarvish Guardsman 31 1.5%
Dwarvish Thunderer 259 12.7%
Dwarvish Ulfserker 170 8.3%
Footpad 945 46.2%
Gryphon Rider 153 7.5%
Poacher 66 3.2%
Thief 70 3.4%
Total: 2046

Loyalists Recruitment Count %
Bowman 125 6.7%
Cavalryman 45 2.4%
Fencer 65 3.5%
Heavy Infantryman 533 28.6%
Horseman 20 1.1%
Mage 538 28.8%
Merman Fighter 103 5.5%
Spearman 437 23.4%
Total: 1866

Northerners Recruitment Count %
Goblin Spearman 24 1.1%
Naga Fighter 60 2.8%
Orcish Archer 778 36.9%
Orcish Assassin 43 2.0%
Orcish Grunt 202 9.6%
Troll Whelp 952 45.1%
Wolf Rider 51 2.4%
Total: 2110

Rebels Recruitment Count %
Elvish Archer 92 6.9%
Elvish Fighter 265 19.9%
Elvish Scout 83 6.2%
Elvish Shaman 50 3.8%
Mage 176 13.2%
Merman Hunter 41 3.1%
Wose 625 46.9%
Total: 1332

Undead Recruitment Count %
Dark Adept 548 23.1%
Ghost 56 2.4%
Ghoul 153 6.4%
Skeleton 777 32.7%
Skeleton Archer 669 28.1%
Vampire Bat 80 3.4%
Walking Corpse 94 4.0%
Total: 2377
</code>

=How the ML Recruiter works=

When it's deciding what to recruit, the ML Recruiter works by predicting a "metric" which is a measure of how well a given unit will do in the game in the current situation. A good measure of a unit's usefulness is a tricky question and we will discuss three different metrics below, but let's start with the easiest one, which is the sum of the following quantities for each unit:

# Experience points at the end of the game or when the unit is killed
# Number of villages captured by the unit

Note that this metric is blind to other ways a unit can help you (in particular, it doesn't know about poison, healing, and slowing).

This sum, which we'll call the "metric" is then divided by the unit cost to get metric/cost (think of this as goodness per unit of gold). You can see this in the debugging output that the ML Recruiter prints to stderr when run with the flag --log-info=ai/testing,ai/ml:
unit type metric cost wt cost weighted metric
Elvish Shaman 8.58 15 15.00 0.57
Elvish Fighter 10.42 14 14.00 0.74
Elvish Scout 8.47 18 18.00 0.47
Wose 17.07 20 20.00 0.85
Mage 10.37 20 20.00 0.52
Elvish Archer 8.46 17 17.00 0.50
Merman Hunter 8.55 15 15.00 0.57

This is from the first turn of a game between the Rebels and the Undead. The ML Recruiter is predicting that if it recruits a Wose now, it will end with 17.07 XP + Village Captures. 17.07/20 = 0.85, which is the highest weighted metric at this time, so it picks a Wose as it's top choice.

How does it know to pick a Wose? It looks at the "features" which describe the current situation. Here's another chart from the same game:

unit type metric cost wt cost weighted metric
Elvish Shaman 7.18 15 15.00 0.48
Elvish Fighter 11.82 14 14.00 0.84
Elvish Scout 7.91 18 18.00 0.44
Wose 15.53 20 20.00 0.78
Mage 9.11 20 20.00 0.46
Elvish Archer 9.38 17 17.00 0.55
Merman Hunter 8.36 15 15.00 0.56
Side: 1 Gold: 21 Unit we want: Elvish Fighter
PRERECRUIT:, enemy Dark Adept:1 , enemy Deathblade:1 , enemy Ghost:2 , enemy Skeleton:3 , enemy faction:Undead ,
enemy gold:10 , enemy level3+:0 , enemy total-gold:139 , enemy unit-gold:129 , friendly Elvish Captain:1 ,
friendly Elvish Fighter:1 , friendly Wose:4 , friendly faction:Rebels , friendly gold:21 , friendly level3+:0 ,
friendly total-gold:161 , friendly unit-gold:140 , side:1 , terrain-forest:0.082 , terrain-mountain-hill:0.113 ,
terrain-water-swamp:0.164 , total-gold-ratio:0.537 , turn:4 , village-control-margin:-2 , village-control-ratio:0.417 , village-enemy:7 ,
village-friendly:5 , village-neutral:4 ,

The "features" that it sees are the values following "PRERECRUIT". The ML AI sees that the enemy faction is the Undead and that they have one Deathblade, two ghosts, three Skeletons. The Rebels currently have 4 Wose, 1 Elvish Fighter, and 1 Elvish Captain. It also sees a number of other features like how much gold it and its opponent have, what percentage of each the map is covered by different terrain, and how many friendly, neutral, and enemy villages there are. In this situation, although it still sees that the Wose is likely to score higher on the XP + village capture metric (15.5 vs. 11.8), this isn't enough to overcome the price differential, so it chooses an Elvish Fighter as it's best choice with a weighted metric of 0.84.

Note that these predictions of 15.5 vs. 11.8 are computed by the neural net based on a model built from what the algorithm has seen has happened in similar situations during training.

==Unit Goodness Metrics==
We have experimented with three different unit goodness metrics. All of these metrics are designed to have the property that the higher the value of the metric, the better the unit performed in a a given game. Clearly there is a random element here. In some games when playing against a Skeleton-heavy Undead army, an Elvish Archer, which uses mainly a pierce attack, may get lucky and do better than a Wose, which has an impact attack, but on average the metric should show that the Wose performs better.

The three metrics we've looked at are as follows:

===Experience Point plus Village Capture===
This is the metric used in ML Recruiter 0.2. As noted above, it is the sum of the following quantities:

# Experience points at the end of the game or when the unit is killed
# Number of villages captured by the unit

This metric has the advantage that experience points lead to promotion, which is a very good thing. Also, getting kills should be correlated with how much damage the unit is doing. Adding village captures to experience points is a little flaky, but is intended to give credit to fast units, which are more likely to capture villages.

===Victory===

This metric gives a unit 1.0 if its side wins and 0 if its side loses. The effect is that the neural net's prediction for each unit can be seen as "what is the probability of victory if I recruit this unit in this situation". This is the most natural of all metrics, but experimentally it hasn't performed as well in terms of leading to actual victories as recruiting based on unit-based metrics. Performance has peaked at around a 59% win ratio for a victory metric vs. around 66 - 73% for the XP+VC metric. We think the problem is that the impact of recruiting a single unit of Type A vs. Type B on the victory probability is very small, so the neural net isn't differentiating among the choices enough.

===Gold Yield===

As of ML Recruiter 0.3, this is the new default metric. It is the sum of the following quantities, all of which are intended to quantify a unit's usefulness in terms of how much gold benefit it has yielded for the friendly side plus gold damage done to the enemy side. This metric builds off of a [http://forums.wesnoth.org/viewtopic.php?f=10&t=36642&sid=11062936e4f4c0bab673470b5d211987&start=45#p536132 suggestion] from Sapient.
# Basic Damage Metric: Target unit cost * (Damage inflicted/target max HP). The concept is that you cost your opponent this much gold by destroying this fraction of the unit. Obviously in any given attack, we would calculate this for both the attacker and the defender.
# Village Capture: capturing_unit.variables.ml_gold_yield += wesnoth.game_config.village_income. (Defaults to crediting 2 gold per village capture)
#* The idea, again, is that fast units tend to get more captures than slow units and this gives units credit for being fast.
# Poison: Treated the same as Basic Damage Metric by crediting for the amount of damage done in that turn. On the turn in which the unit is cured, the poisoner is credited with Target Unit Cost * (8/target max HP) to reflect the damage that it would have healed if it hadn't been poisoned (obviously, lessened if it has less than 8 HP of damage)
# Slowing: When a unit is on defense and it slows the attacker, the defender gets no special credit because the attacker just unslows at the end of its turn. When you slow a unit as the attacker, the slowing unit gets credit for the Basic Damage Metric accumulated by the slowed unit until it unslows (the slowed unit would otherwise have done twice as much damage, so you get credit for the damage it didn't do)
# Healing: healing_unit.variables.ml_gold_yield += Healed_unit_cost * (healed amount/healed unit max HP)
#* Directly analogous to the Basic Damage Metric
#* Note that healers also get credit for curing/stopping poison
# Walking Corpse Creation: Credit a unit which gets a kill which creates a unit due to its plague ability with 8 gold (the value of a Walking Corpse). (not implemented)
# Leadership: Credit the leader for the bonus damage inflicted by the unit being led (not implemented)
# Maintenance: Charge units for their share of the maintenance costs, weighted by level. Hence, level 0 units never pay maintenance. Level 2 units pay for twice as much maintenance. (not implemented)

==How MLR makes weighted random choices==
The recommended recruiter is defined in ai/ais/ml_ai.cfg. It is called "Recommended" in the user interface. Although we are currently measuring it as performing roughly the same or slightly worse than the "Less variety/probably stronger" ML AI (ai/ais/ml_ai_less_random.cfg), we recommend it because it allows the player to see a greater variety of opposing units.

The weighted random printout looks like the following:

Turn 13:
unit type metric cost metric/ weighted %
cost m/c of total
Merman Hunter 1.10 15 0.07 0.0000 0.0%
Wose 1.72 20 0.09 0.0000 0.1%
Elvish Shaman 1.66 15 0.11 0.0000 0.4%
Elvish Archer 2.71 17 0.16 0.0000 4.0%
Elvish Fighter 2.54 14 0.18 0.0000 8.5%
Mage 4.18 20 0.21 0.0001 20.1%
Elvish Scout 4.60 18 0.26 0.0003 66.8%
Random Number chosen was 376
Side: 1 Gold: 27 Unit we want: Elvish Scout
PRERECRUIT:, enemy Dark Adept:2 , enemy Revenant:1 , enemy Skeleton:1 , enemy faction:Undead , enemy gold:8 ,
enemy level3+:0 , enemy total-gold:83 , enemy unit-gold:75 , friendly Elder Wose:1 , friendly Elvish Fighter:2 ,
friendly Elvish Ranger:1 , friendly Mage:1 , friendly Wose:3 , friendly faction:Rebels , friendly gold:27 ,
friendly level3+:0 , friendly total-gold:225 , friendly unit-gold:198 , side:1 , terrain-forest:0.082 ,
terrain-mountain-hill:0.113 , terrain-water-swamp:0.164 , total-gold-ratio:0.731 , turn:13 ,
village-control-margin:0 , village-control-ratio:0.5 , village-enemy:8 , village-friendly:8 , village-neutral:0 ,

This situation occurs towards the end of a game that the Rebels are winning. Note that total-gold-ratio (the ratio between the sum of gold + the value of all units on each side) is 0.731, so it's heavily in the Rebels' favor. The ML AI sees an Elvish Scout as being the best choice in this situation with a Mage in second place. The Elvish Scout is probably favored because the game is likely to be won rapidly and only a fast unit will be able to reach the enemy or reach a village fast enough to add to its "experience points + village capture" metric.

The Weighted Random does the following:
# It takes every metric/cost value and raises it to the sixth power. Why? We want to magnify the differences. In this example 0.26/0.21 = 1.23, but (0.26**6)/(0.21**6) = 3.60.
# We then randomly choose a unit with a probability proportional to this weighted value which, in this case, was an Elvish Scout.

The Less Variety/Probably Stronger AI does the same thing, but raises metric/cost to the 24th power instead of the 6th power. This still allows for some randomness, but weights the selection much more strongly towards the more favored units.

=How to train your own ML Recruiter=
utils/ai_test/run_model_and_make_new_model.py is an end-to-end script for running a whole bunch of training games of Wesnoth and then training a new model based on the data output by that run. Documentation on this script can be seen by running
run_model_and_make_new_model.py --help
Note that this script assumes that [http://waffles.sourceforge.net/ the Waffles machine learning toolkit] is installed and that waffles/bin/ is in your path.

=Known issues=
==Bugs==
# Haven't added new Waffles files to Visual C++, so it won't compile under VC++. I need some help with this.
# The default for multiplayer games is that units require only 70% of normal experience to promote, however when a game is run from the command line, it always requires normal 100% of experience to promote. Consequently MLR doesn't see units promote as much as they should in training, which would slightly distort its training data. This is a [https://gna.org/bugs/?19895 limitation of Wesnoth], not MLR.

==Current Limitations==
# Only tested on two-player multiplayer games. Doesn't work when there are more than two leaders on the map.
# Works on all two-player maps except for Hornshark Island, Thousand Stings, Caves of the Basilisk, and Dark Forecast
# As noted above in [http://wiki.wesnoth.org/Machine_Learning_Recruiter#Gold_Yield Gold Yield Metric], we account for all special abilities available in the main-line multiplayer scenarios except for plague, leadership, and unit maintenance costs

=ML Recruiter development roadmap=

* ML Recruiter 0.1: Initial drop
* ML Recruiter 0.1.1: Minor retraining of the model
* ML Recruiter 0.2:
** Logging messages changed from print statements to using lg::log_domain.
** Now have an explicit debug mode by running with --log-debug=ai/ml.
** ML Recruiter can play against itself. Previously could only have ML Recruiter on one side.
** Some work on ML recruiting model (i.e. the core logic). Experimented with different training strategies, but features unchanged from 0.1.
* ML Recruiter 0.3 (10/25/2012) :
** New "gold yield" metric for judging a unit's goodness
** Several new ML features to aid in prediction: alignment, race, time of day, map size, friendly and enemy leader hit point percentage remaining, and nearest enemy unit to friendly leader
** Runs on all 2-player maps except for Hornshark Island, Thousand Stings, Caves of the Basilisk, and Dark Forecast
** Greatly improved ai_test2.py script for running thousands of games to test AI and gather data for the neural net
** New script (run_model_and_make_new_model.py) for running games and building a new neural net based on the data gathered from those games
** Improved performance: Defeats ML Recruiter 0.2 58% of the time
* ML Recruiter 0.4 (11/11/2012):
** Run on all 2-player maps (except Dark Forecast, which has a custom recruiter)
** Refactor code to separate features from predicted values
** Added timeout option to ai_test2.py. Also report time statistics in analyze_log.py
** Improved recruiter for the Ron recruiter. It still underperforms the Ron recruiter on most maps when used with the other Ron CA's, though.
** Move all code into [https://github.com/mattsc/Wesnoth-AI-Demos AI-Demos project on GitHub]. the ML Recruiter 0.4 patch now consists, essentially, of only the C++ code modifications.
* ML Recruiter 0.5 (planned)
** Run on all mainline multiplayer maps
** Experiment with using as the [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976 AI-Demos] recruiter
** Add missing special abilities (plague, leadership, and unit upkeep)
** Add 95% confidence intervals to the win ratios in analyze_log.py and add measures of entropy (randomness) to analyze_recruitment.py. Entropy is a good measure of the variety of units that a recruiter is recruiting--for game play, more is better.

PreprocessorRef

2012-11-09T03:32:40Z

Alarantalara: /* #ifver and #ifnver */ Add warning about using version suffixes

{{WML Tags}}
== Overview ==

Wesnoth loads just one configuration file directly: '''data/_main.cfg'''. However the '''WML preprocessor''' allows to include more files. Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.

The preprocessor can interpret a simple language of string expansions known as ''macros''. A macro should always be defined '''before''' the place where it needs to be used.

The preprocessor is applied recursively, so included files will be parsed for macros, and after macro expansion will be parsed for macros again, and so on. As a result, you should not write a recursive macro that references itself, because it will cause errors (but, alas, not necessarily error messages).

== Preprocessor directives ==

The following directives are used to create and use ''macros'', i.e. shortcuts which reduce repetition of information. See [http://www.wesnoth.org/macro-reference.xhtml the macro reference] for the list of predefined core macros.

The preprocessor has changed several times, so don't expect old Wesnoth versions to behave exactly the same as the current stable and development series.

'''Note:''' In multiplayer scenarios, these directives will appear to work only for the host and not for other clients. This is because the preprocessor is run only on the host, and the clients receive the resultant WML from the server. It's particularly important to keep this in mind before using preprocessor conditionals.

=== #define ===

'''Syntax: #define ''symbol'' [''parameters''] ''<newline>'' ''substitution'' #enddef'''

All subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by the contents of the ''substitution'' block, with all occurrences of any parameter {''parameter''} within ''substitution'' replaced by the corresponding value in ''arguments''. For example, the ENEMY_UNIT macro for the [[#Macro inclusions|macro inclusion]] example below could be defined as follows:

#define ENEMY_UNIT TYPE X Y
## the ordering above is important, since the preprocessor does not distinguish
## data into different types; only the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE} ## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2 ## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef

(See [[SingleUnitWML]] for further information on creating units using WML.)

=== #undef ===

'''Syntax:''' '''#undef ''symbol'' '''

Removes the previous definition of the macro named ''symbol''.

=== Inclusion directive {} ===

This directive can be used to include macros, single files or sets of files from a target directory.

==== File/directory inclusions ====

'''Syntax: {''path''}'''

Includes the file with the specified ''path'', which will in turn run the preprocessor on it and perform any required substitutions or inclusions within it. The ''path'' may not contain ''..'' or the inclusion will be skipped.

The exact location in which the ''path'' will be resolved will depend on its prefix:

* '''{''path''}''': If ''path'' isn't a known macro (see below), the game will assume it's a relative path to a file in the main game '''data/''' directory and include it.
* '''{~''path''}''': As above, but instead of the game data directory, the path is resolved relative to the user '''data/''' directory, where user made add-ons can normally be found.
* '''{./''path''}''': The path is resolved relative to the location of the current file containing this inclusion.

Information for locating the user data and game data directories can be found in [[EditingWesnoth]].

Forward slashes ('''/''') should '''always''' be used as the path delimiter, even if your platform uses a different symbol such as colons (''':''') or backslashes ('''\''')! It is also very important to respect the '''actual letter case''' used to name files and directories for compatibility with case-sensitive filesystems on Unix-based operating systems.

When ''path'' points to a directory instead of a file, the preprocessor will include all files found within with the '''.cfg''' extension, in alphabetical order; files without this extension (such as '''.map''' or '''.png''' files) are ignored.

Some directories are handled in a special fashion according to their contents:

* If there's a file named '''_main.cfg''' in the target directory, only that file will be included and preprocessed. It may include other files from its own directory or subdirectories within it, of course. This is used for managing WML directories as self-contained packages, like user made add-ons.
* If there are files named '''_main.cfg''' in subdirectories of the target and there isn't one in the target itself, they will be all preprocessed. Given the following layout:
dir/
dir/a/_main.cfg
dir/a/other.cfg
dir/b/_main.cfg
dir/b/other.cfg
dir/other.cfg
Using '''{dir}''' will cause dir/a/_main.cfg, dir/b/_main.cfg and dir/other.cfg to be included.
* If there's a file named '''_final.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''after'' all the other files in the directory.
* If there's a file named '''_initial.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''before'' all the other files in the directory.

==== Macro inclusions ====

'''Syntax: {''symbol'' [''arguments'']}'''

If the macro named ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' was previously defined as, using ''arguments'' as parameters. The number of arguments must be exactly the same as in the original definition or an error will occur.

You can create multiple word arguments by using parentheses to delimit the contents. For example, in '''{ENEMY_UNIT Wolf Rider 18 24}''' the four words will be interpreted as separate arguments and cause the preprocessor to fail since the macro was defined above with only three; instead, you should use '''{ENEMY_UNIT (Wolf Rider) 18 24}'''.

Using the name of an existing macro as the name of a macro argument is possible, but the argument will always take precedence over the original macro:

#define VARIABLE
#enddef
#define MACRO VARIABLE
{VARIABLE} # is calling for the argument, not for the macro above
#enddef

=== #ifdef and #ifndef ===

Unlike the other preprocessor directives, '''#ifdef''' and '''#ifndef''' are not mere conveniences. They are often necessary to distinguish between different gameplay modes or difficulties (see [[#Built-in macros|Built-in macros]] below).

'''Syntax:''' '''#ifdef ''symbol'' ''substitution-if-defined'' [#else ''substitution-if-not-defined'' ] #endif'''

If ''symbol'' has been defined with '''#define''' or as a built-in macro, the whole block will be replaced by ''substitution-if-stored''. If not, it will be replaced by ''substitution-if-not-stored'' if it is available.

'''#ifndef''' is the exact opposite of '''#ifdef''', reversing the logic:

'''Syntax:''' '''#ifndef ''symbol'' ''substitution-if-not-stored'' [#else ''substitution-if-stored''] #endif'''

=== #ifhave and #ifnhave ===

'''Syntax:''' '''#ifhave ''path'' ''substitution-if-path-exists'' [#else ''substitution-if-path-does-not-exist''] #endif'''

Checks for the existence of a file. Uses the same relative paths as include directives (see below).

Example:

#ifhave ~add-ons/My_Addon/_main.cfg
{MY_ADDON_MACROS}
#endif

'''#ifnhave''' does the opposite of '''#ifhave''':

'''Syntax:''' '''#ifnhave ''path'' ''substitution-if-path-does-not-exist'' [#else ''substitution-if-path-exists''] #endif'''

=== #ifver and #ifnver ===

'''Syntax:''' '''#ifver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-met'' [#else ''substitution-if-condition-not-met''] #endif'''

Compares a version number defined in a macro against an argument for conditional block inclusions, like ''#ifdef'' and ''#ifhave''. ''operator'' is one of ''=='' (equal), ''!='' (not equal), ''<'' (less), ''<='' (less or equal), ''>'' (greater), ''>='' (greater or equal). The specified ''symbol'' should have been previously defined as plain text without more macro inclusions within it, and it must not require any arguments.

Versions with text suffixes are sorted in binary order and come after all versions with the same number. The most common suffix is "+svn", but as it represents multiple possible versions, comparing versions against it is not recommended.

Example:
#ifver WESNOTH_VERSION >= 1.9.7+svn
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7+svn, 1.9.8 or later!"
[/message]
#else
#ifver WESNOTH_VERSION == 1.9.7
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7, and I’ll include some workaround code for bug #9001!"
[/message]
#endif
#endif

'''#ifnver''' does the opposite of '''#ifver''':

'''Syntax:''' '''#ifnver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-not-met'' [#else ''substitution-if-condition-met''] #endif'''

== Built-in macros ==

The following macros are automatically defined with empty contents (unless specified otherwise) by the game engine depending on the configuration or gameplay mode.

* A campaign define symbol (see ''define'' in [[CampaignWML]]): defined when playing a single-player campaign.
* A campaign difficulty level, usually '''EASY''', '''NORMAL''' or '''HARD''' (see ''difficulties'' in [[CampaignWML]]): defined according to the chosen difficulty when starting a single-player campaign, also stored in saved games.
* '''MULTIPLAYER''': defined when in multiplayer mode.
* '''TUTORIAL''': defined when playing the tutorial campaign.
* '''EDITOR''': defined when running the built-in map editor.
* '''DEBUG_MODE''': defined when the game has been launched in debug mode (i.e. with '''-d''' or '''--debug''' in the command line).
* '''APPLE''': defined while processing the main game data when running on Mac OS X.
* '''WESNOTH_VERSION''': defined containing just the game version number when running the WML preprocessor.

== Command-line preprocessor ==

'''Syntax: --preprocess ''<source file/directory>'' ''<target directory>'' '''

Or the short form:

'''Syntax: -p ''<source file/directory>'' ''<target directory>'' '''

You can specify a list of predefined defines with:

'''Syntax: --preprocess-defines=DEFINE1,DEFINE2,etc'''

comma separated list of defines to be used by '--preprocess' command. If 'SKIP_CORE' is in the define list the data/core won't be preprocessed.

The command will preprocess first the common config files in the main game ''data/'' directory, and afterwards the specified ones. You can specify a single file to be preprocessed (if you want to preprocess multiple separate files, you'll need to run a different command line for each one), or an entire directory, which will be preprocessed according to the rules used by the inclusion directive above.

The resulted preprocessed files will be written in the target directory. There will be two types of files: .cfg files --- the normal ones, and .plain files containing line markers and textdomain changes.

If by chance, the simple macro define doesn't suffice, you can use:

'''Syntax: --preprocess-input-macros <file>'''

To import an existing file that contains macros, and they will be available in the defines database before processing the specified files.

There is also the possibility to export the preprocessed defines/macro list with:

'''Syntax: --preprocess-output-macros [<target file>]'''

This file could be fed to the 'input-macros' argument next time you run it. For example, a scenario would be: parsing just the core first time, and for the intended target files, you would add SKIP_CORE but import the generated macros file - that will be faster than preprocessing the core again. If the target file is not specified, the output file will be _MACROS_.cfg in the target directory of the preprocess's command.

If ''file/directory'' and ''target directory'' are not absolute paths, they will be considered relative to the game's executable path.

Some examples:

* Preprocess the entire tutorial dir, and write the results in the ~/result folder:
-p ~/wesnoth/data/campaigns/tutorial ~/result
* Add the MULTIPLAYER define to the list and preprocess a scenario's config file:
-p ~/.wesnoth/data/add-ons/My_Campaign/scenarios/01_First_Scenario.cfg ~/result --preprocess-defines=MULTIPLAYER
* Add the MY_CAMPAIGN and HARD defines before preprocessing a campaign's files:
-p ~/.wesnoth/data/add-ons/My_Campaign ~/result --preprocess-defines=MY_CAMPAIGN,HARD

If you want a more detailed (and potentially overwhelming) log, you can simply add the switches '''--log-debug=all''' or '''--log-info=all''' to the command line, so you can see how things are preprocessed in detail.

== See Also ==

* [[SyntaxWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

Guide to UMC Content

2012-11-06T15:58:59Z

Alarantalara: /* The Roar of the Woses */

''This is a guide to the current (1.10.x/1.11.x) UMC campaigns for players. It aims to provide all the information not only about the story, but also about completion, difficulty and playing style of the campaign. See http://forums.wesnoth.org/viewtopic.php?f=8&t=37476 for further information, for currently non-available UMC-content please refer to http://forums.wesnoth.org/viewtopic.php?f=8&t=36733. Please edit, it is a wiki.''

=== Blueprint ===

'''Status:'''
* Broken = Does not work at all
* Incomplete = Partially written, no progress
* WIP = Partially written, progress
* Complete = Completely written, but buggy as well as potential balance issues.
* Finished = Completely written, minimal to no bugs, slight balance issues possible.

'''Length:'''

'''Author:'''

'''Maintainer:''' if not maintained by the author anymore.

'''Description:'''

'''Version: '''

'''Requirements:'''

'''Difficulty:'''

Please note: Often campaigns introducing new mechanics are listed as expert level on the add-on server, here difficulty means the raw difficulty after the mechanics are understood.

* Unbalanced = If you can't beat the hard mode, it isn't necessarily unbalanced, but if the difficulty changes erraticly from one scenario to the next and only people using the debug mode have seen the final, then it is.
* Easy
* Normal
* Hard

'''Style:'''

Please note: Many campaigns will feature more than one style. Please list the most significant ones.

* Skirmish = small to medium sized armies, your standard Wesnoth gameplay
* Dungeon = long and narrow tunnels (not every underground scenario is a dungeon, a dungeon isn't necessarily underground)
* RPG = role playing game elements such as talking with non-player-characters, item collection, dependency on a party of very few adventurers without or limited recruits
* Survival = being exposed to changing, spawning enemies while remaining on the same map
* Large Battle = Eastern Flank in Northern Rebirth, Civil War in Son of the Black-Eye
* Simulation = campaigns feat. terrain modification, alternative resources
* Boss battle = a recurring feature of Invasion of the Unknown

'''Faction/Era:'''

* Era for the whole campaign and more specifically the faction or unit composition you field.

'''Custom units:'''

* Link to the unit tree for cases that don't feel sufficiently described by Faction / Era entry.

'''Forum:'''

* Links to the feedback and development threads at forums.wesnoth.org

== Battle for Wesnoth 1.10.x - stable ==

''Campaigns available in the 1.10.x stable version.''

=== Aldur The Great ===

''This is a story about Aldur the Great.''

'''Author:''' pintercsabi

'''Status:''' Complete, but unbalanced

'''Length:''' 5 playable scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default

'''Version:''' 1.2.2

'''Forum:''' -

'''Note:''' (Adamant14) Short unbalanced campaign, maybe abandoned. You fight with Peasants, Ruffians and Woodsman against Orcs

=== Alfhelm the Wise ===

''This is the tale of Alfhelm, called by some the Wise, son of Alfric Conqueror. This is the tale of his victories over his enemies, and his rise to power in the clans of Marauderdom. This is the tale of his journey south and his destruction of the Lavinian Empire. And this is the tale of his demise in the dark forests far to the east of his homeland.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 15 gameplay scenarios

'''Difficulty:''' Moderate

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Marauders.

'''Version:''' 0.6.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=17144

[Maintainers Note: Though this campaign is complete and playable the whole way through, the code is four years old and pretty buggy. If you notice any errors while playing, please let me know and I'll incorporate the fixes into my next revision as soon as possible.]

=== Antar, Son of Rheor ===

''This is the story about a young Lord and his first mission; sent by his father the young Lord Antar has to relieve his neighbours; he has to convince the Elves and Dwarves to ally him; he has to fight against hordes of Orcs and Endless Undead; and finally he has to defeat Mal Kazur, the mastermind who is behind all the evil.''

'''Author:''' Adamant14

'''Status:''' WIP

'''Length:''' 8 playable scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Loyalists (feat. fencer as main hero + various allies)

'''Version:''' 0.8.26a

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36075

=== A Story of the Northlands ===

''A story of life and death in a remote village of the Northlands. Your village has been overrun by an orcish raid. You fight for its freedom while you wait for help to arrive.''

'''Author:''' zepko

'''Status:''' Complete

'''Length:''' 10 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default + additions: you play with a custom faction of outlaws and with a custom party of loyalist knights.

'''[http://units.wesnoth.org/1.10/A_Story_of_the_Northlands/en_US/A_Story_of_the_Northlands.html Custom Units]'''

'''Version:''' 0.2.0

=== A Vision Blinded ===

''Defend the northern forest against what appeared like a routine orcish raid, and unravel the greater conspiracies that lie below its waves.''

'''Author:''' LemonTea

'''Maintainer:''' AxalaraFlame

'''Status:''' Complete

'''Length:''' 13 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves (+ Trolls, Outlaws)

'''[http://units.wesnoth.org/1.10/A_Vision_Blinded/en_US/A_Vision_Blinded.html Custom units]'''

'''Version:''' 0.6.6

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23463&hilit=a+vision+blinded

=== Besieged Druids ===

''A elvish school for druids comes under attack by goblins. It seems more than just a routine raid; is there something more sinister behind this attack? - In Beseiged Druids, you control Eärendil, the surviving teacher at the school, and the many and varied initiates. Not all of these are ordinary students; many have been experimenting with other forms of magic, while others are simply overachievers in some area of study. Unfortunately, they are not especially good at combat, at least initially. Together with a very small contingent of surviving guards, it is up to these students to save the island of Aleron from disaster.''

'''Author:''' Celtic Minstrel

'''Status:''' Complete

'''Length:''' 9 scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''[http://units.wesnoth.org/1.10/DruidSiege/en_US/celmin-druid-siege.html Custom units]'''

'''Version:''' 1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37342

=== Cities of the Frontier ===

''Settle a new town in the wilds north of the Great River.''

''This campaign makes several changes to the standard Wesnoth game mechanics, and focuses on city-building and gold management.''

'''Author:''' esci

'''Status:''' Complete

'''Length:''' Not fixed, approximately 6-10 seasons of 36 turns each

'''Difficulty:''' Normal

'''Style:''' Simulation, Survival

'''Faction/Era:''' Default, Loyalist

'''[http://units.wesnoth.org/1.10/Cities_of_the_Frontier/en_US/Cities_of_the_Frontier.html Custom units]'''

'''Version:''' 0.5.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36004

=== Count Kromire ===

''You are the blood son of a vampire lord, however when the might of the celestial crusades comes knocking, and your father is slain, you flee your lands. However you intend to return, to restore the lands of Kromire to the Kromires, to avenge your father, and most importantly, to make sure that no celestial ever dares come into your mountains again.''

'''Author:''' Velensk

'''Maintainer:''' currently none

'''Status:''' Complete

'''Length:''' 9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Era of Myths, Vampires

'''Version:''' 1.3.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=21560

=== The Dark Hordes ===

'''Status:''' Incomplete/WIP

'''Length:''' 11/?

'''Author:''' Circon

'''Maintainer:''' Various

'''Description:''' Lead fugitive dark sorcerer Gwiti Ha’atel to mastery of the undead hordes.

'''Version: '''

'''Requirements:'''

'''Difficulty:'''

'''Style:''' Skirmish

'''Faction/Era:''' Default undead

'''[http://units.wesnoth.org/1.10/The_Dark_Hordes/en_US/The_Dark_Hordes_1.html Custom Units]'''

'''Walkthrough:''' [[TheDarkHordes]]

'''Forum:''' [[http://forums.wesnoth.org/viewtopic.php?f=8&t=16576&]]

=== The Earth's Gut ===

''The year is 515YW. You are the young dwarven leader Hamel. Your tribe in the caves of Knalga is under pressure from its enemies, and resources are growing scarce. In order to forge the weapons required to resist your enemies, you must set forth and collect what ores and minerals remain.''

'''Author:''' Anonymissimus

'''Maintainer:''' Anonymissimus

'''Status:''' Incomplete

'''Length:''' 21 scenarios

'''Difficulty:''' Normal

'''Style:''' Dungeon

'''Faction/Era:''' Default, dwarves.

'''[http://units.wesnoth.org/1.10/The_Earths_Gut/en_US/the_earths_gut.html Custom units]'''

'''Version:''' 0.2.11

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=26800

'''Note:''' This campaign is a "Dwarvish dungeon crawler" and is intended to be challenging for experienced players on hard whilst suitably easy on easy.

=== Elvish Dynasty RPG ===

''You are the new ruler of an elvish kingdom! Can you lead your people to glory? This campaign is highly randomized so it will be different every time you play!''

''Sequel to Ooze Mini-Campaign''

'''Author:''' spencelack

'''Status:''' Complete

'''Length:''' 10 years, in each year choice between dialogue and fighting scenario (selected out of a large pool of possible scenarios)

'''Difficulty:''' Normal

'''Style:''' RPG, Skirmish

'''Faction/Era:''' Default, Elves

'''Version:''' 0.9.9b

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=28627

=== The Epic of Vaniyera ===

''The expansionist Lavinian Legion, led by the Imperator himself, has invaded the northern forests of the Sidhe, or Wild Elves. It is up to Leithan the Thunderblade and his advisor Vaniyera to push its armies back where they came from...''

'''Author:''' oreb, turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 6 scenarios

'''Difficulty:''' Hard (Don't be fooled by "novice level" in the campaign description, this one is very hard.)

[Maintainers note: Working on this issue, the next release (due at the end of November, hah!) should bring easy difficulty back to the level of a reasonable introduction to the IE, while the hard difficulty will also become slightly easier. With any luck, this will be the last release before version 1.0 of the campaign].

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Sidhe.

'''Version:''' 0.9.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=19490

=== Fall of Silvium ===

''You are Caius Regilius, Tribune of the province of Silvia, located in the northmost reaches of the Lavinian Empire at the height of its power. But the Empire has overextended itself, The city of Silvium lies seperated from the rest of the Empire by the mountains of Arendia, and is sandwiched between the Marauders and the Sidhe... war is inevitable, and the province of Silvia will almost certainly fall.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 8 scenarios

'''Difficulty:''' Medium

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Lavinian Legion.

'''Version:''' 0.6

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=31&t=24356

[Note: The final level of this campaign is not supposed to be winnable. It's a final blaze of glory and chance to use all your high-powered units, but to 'win' the campaign, you must lose...the ending is similar to a certain mainline campaign, but predates it.]

=== The Fall of Wesnoth ===

''As the beloved human empire of Wesnoth becomes lazy and arrogant in its peaceful state of happiness, Emperor Dantair demands the creation of another sun in a bid to destroy all evil. Or is it all for a different purpose? A man named Alitar sees it that way, and now he must survive the most evil inhabited lands if he is to stop chaos from rising, and Wesnoth from falling... This is the story of The Fall of Wesnoth.''

'''Author:''' Pewskeepski

'''Status:''' 1st part complete, 2nd WIP.

'''Length:''' 10 playable scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Outlaws

'''[http://units.wesnoth.org/1.10/The_Fall_of_Wesnoth/en_US/The_Fall_of_Wesnoth-1.html Custom units]'''

'''Version:''' 1.0.8

=== Fate of a Princess ===

''Part I: Baldres, a notorious robber baron, flees Wesnoth with his followers and sets off into the northlands to evade the king's justice. The baron's deeds and misdeeds are to change the balance of power between orcs and non-orcs throughout the northlands, and will carry consequences long after his eventual death.''

''Part II: The Greenwood elves face a crisis which demands the return of the queen's estranged half-elven half-sister, Baldres' daughter. Two brave young elves must make a perilous journey to find her and bring her back to her former home. If they fail, the whole northlands will be engulfed in war with the resurgent orcs...''

'''Author:''' SkyOne, mich, simonsmith

'''Status:''' Finished

'''Length:''' 26-29 scenarios (some dialogue-only), 2 parts

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon

'''Faction/Era:''' Default with additions. You play two different, unique cross-faction combinations in each part.

'''[http://units.wesnoth.org/1.10/Fate_of_a_Princess/en_US/Fate_of_a_Princess.html Custom units]'''

'''Version:''' 0.9.17

'''Required Wesnoth version:''' 1.9.12 or later

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=26327

=== Forgotten Kingdom ===

''Help Orlog, a troll chieftan, lead his people to safety in the underground and discover an ancient power long forgotten.''

'''Author:''' Limabean

'''Status:''' Incomplete ( but all scenarios playable and balanced )

'''Length:''' 9 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Goblins, Trolls

'''[http://units.wesnoth.org/1.10/Forgotten_Kingdom/en_US/Forgotten_Kingdom.html Custom units]'''

'''Version:''' 0.1.7

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23483

'''Note:''' (Adamant14) This campaign includes a custom Troll line. A good campaign, sad that Limabean seems to abandon it.

=== Forward they Cried ===

''You are the leader of an advanced detachment that has been tasked with capturing a bridgehead while the main army prepares to attack. It should be a simple enough assignment.''

'''Author:''' Glowing Fish

'''Maintainer:''' Lord-Knightmare

'''Status:''' Finished

'''Length:''' 1 scenario ( rather a single scenario than a campaign )

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default Loyalists

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23656&p=350126&hilit=forward+they+cried#p350126

'''Version:''' 1.0.0

'''Note:''' (Adamant14) Only a single scenario, but a great scenario.
(UnwiseOwl) You wouldn't want to stop thinking for a turn, and it's good for the first few turns, but this one leaves me wanting more.

=== The Founding of Borstep ===

''The chieftain of your tribe has become decadent and weak. Take over, and lead your people to a better home--whether it is already occupied or not. The Northlands in year 9W are a barbaric place, but anyone who stands in your way will learn the power of orcs!''

'''Author:''' Beetlenaut

'''Status:''' Complete

'''Length:''' 10 and 1 dialogue only

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default, Northerners

'''[http://units.wesnoth.org/1.10/The_Founding_of_Borstep/en_US/The_Founding_of_Borstep.html Custom units]'''

'''Version:''' 1.1.1b

''Note(Kanzil): I find the protagonist hard to sympathise with. Also, most scenarios contain interesting twists. For example, in one, each time you killed a boar it gives you extra health.''

''Note(beetlenaut--author): In most Orcish campaigns the leader is heroic or just wants peace. Krag-Ubor wants plunder and battle like all enemy Orcs in other campaigns. I '''hope''' you don't sympathize too strongly, but I don't think you need to in order to enjoy the game play.''

=== Galuldur's First Journey ===

''While the belligerence of orcs is nothing new, their intensifying attacks on a fledgling colony of elves in Pindir Forest begin to show signs of a deeper malice, forcing Galuldur, the young son of the colony's adventurous founder Galur, to venture out of his forest's friendly trees in search of help. His simple errand quickly turns into a frantic quest to unearth the roots of the mysterious evil threatening his people. As you lead him through unknown lands, Galuldur, forced to match wits with unexpected adversaries at nearly every turn in a desperate attempt to save his world, quickly learns that the world is neither a friendly nor a simple place.''

'''Author:''' mattsc

'''Status:''' Complete

'''Length:''' 8-9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''[http://units.wesnoth.org/1.10/Galuldur/en_US/Galuldur.html Custom units]'''

'''Version:''' 1.1.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31895

=== Grnk the Mighty ===

''All his life, puny little goblin Grnk the Frail had been dreaming about leaving the orcs and starting a better life. When he finally arrives in the human town of Shmaltupp, he realizes that the world is not as black and white as he had imagined. He also discovers that he is no ordinary goblin. Follow Grnk the Frail on his path to becoming Grnk the Mighty.''

'''Author:''' mattsc

'''Status:''' Part I complete

'''Length:''' 13 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish, RPG

'''Faction/Era:''' Default, changing (no standard army building gameplay)

'''[http://units.wesnoth.org/1.10/Grnk/en_US/Grnk.html Custom units]'''

'''Version:''' 1.0.5

'''Required Wesnoth version:''' 1.9.5 or later

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34970

=== Invasion from the Unknown ===

''Episode I - Seeking the Light: Long after the Fall, the last forest elves are forced to abandon their safe valley, and find themselves resorting to the dark means of necromancy in order to survive the perils and challenges of this new harsh world. May they finally free the Great Continent from its chaos, or perish in the foolish attempt of restoring peace and life to the lands.''

''Episode II - Armageddon: As the shadow of Chaos covers the entire continent, an assorted group of foolish heroes prepares a counter-attack to the Empire, with one unique goal in their minds: defeat the evil Emperor, whoever it is. Lead these courageous living and non-living warriors to victory, and rediscover lost secrets of the history.''

'''Author:''' shadowmaster

'''Maintainer:''' Espreon

'''Status:''' Finished

'''Length:''' 26 scenarios in two episodes

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon, Boss battle

'''Faction/Era:''' Unique. You play Elves and Undead throughout the campaign + in the 2nd part Northerners and Aragwaithi.

'''Version:''' 1.90.6

''Note (taptap): Despite its acknowledged flaws (generic hero, plot holes, deus ex machina moments, gameplay issues in the 2nd part) this is undoubtedly the most iconic campaign in UMC. It single-handedly redefines the elvish history and sketches a cosmology for the ages after the fall. With the Chaos empire and its various allies it introduces an era worth of factions to single-player play. At the same time it features some of the most beautiful maps in Wesnoth and stunning art on par with mainline campaigns.''

=== Langrisser Sample Campaign ===

''The Imperial Knights of the Rayguard Empire have disrupted the peace of the village that was Hein's hometown, seeking only a girl named Liana. Fight to rescue Liana.''

'''Author:''' Morath

'''Status:''' Finished

'''Length:''' 1 playable scenario

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''Version:''' 0.1.0.5

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36417&hilit=Langrisser

'''Wikipedia:''' [http://en.wikipedia.org/wiki/Langrisser What is Langrisser]

'''Note:''' (Adamant14) Single scenario, different from usual Wesnoth behaviour.

=== Legend of the Invincibles ===

'''''Part I: Shrouded in Darkness''' (5 chapters, 90 scenarios) - A pair of heroes, after stopping an orcish thread, are outcast into caves, where they have no other choice than to become liches in order to survive. They preserved their human appearance and moral principles, and fight in various skirmishes against evil (although using evil methods sometimes), until the Fall, when they are buried alive under the ashes of the third sun.''

'''''Part II: Into the Light''' (2 chapters, 30 scenarios at the moment) - Long after the Fall, the lich heroes awaken. Searching for more power, they manage to resurrect themselves as living beings, but this time more powerful and cleaned from the evil within them. But the evil from inside them continued to exist, and started a skirmish to conquest the world.''

'''Author:''' Dugi

'''Status:''' WiP (but Part I might be considered complete)

'''Length:''' 119 (+6 talk-only) scenarios at the moment

'''Difficulty:''' Normal

'''Style:''' mostly Skirmish and Dungeon (all other styles are present as well, but less frequently)

'''Faction/Era:''' Elves, Loyalists, Undead; but they advance past their usual maximum level

'''Version:''' 2.3.0

''Note: The most unique feature of this campaign is its RPG-like unit development system, enemies drop items units can use, leaders are stronger than most usual units and all units get AMLA (after maximum level advancement) after reaching their maximum level (that is also increased by a load of additional level 4 units).''

=== The Library of Kratemaqht ===

''An ancient story from the old continent.''

'''Author:''' Rich Marinaccio (cephalo)

'''Status:''' Complete

'''Length:''' 17 scenarios

'''Difficulty:''' Unbalanced (some scenarios are Easy - some rather Hard)

'''Style:''' Skirmish, RPG

'''Faction/Era:''' Loyalists and custom units.

'''[http://units.wesnoth.org/1.10/Library_Of_Kratemaqht/en_US/The_Library_Of_Kratemaqht.html Custom units]'''

'''Version:''' 1.0.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37798

'''Notes:''' (Adamant14) This campaign has a thought-out story, shows a great love for detail;
It includes a great custom Dragon, some brilliant custom images (fire, burning houses, burning forest) that makes the scenery / maps look very nice.

=== Panther Lord ===

''The Imperialists ambitions of pushing into the Sea States have been repeatedly thwarted and now they turn their attentions elsewhere. You are an outcast Darklander now living as a mercenary in the Sea States and the rumors you hear indicate that they will be coming to your people. Though an outcast you do not wish to see them subjugated. The spirit whose friendship caused you to be an outcast has a plan that might allow you to save them.''

'''Author:''' Velensk

'''Maintainer:''' Lavender

'''Status:''' Finished

'''Length:''' 14 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Era of Four Moons, Darklanders (+ a wide variety of mercenaries)

'''Version:''' 1.0.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34318

=== Return of the Monster ===

''It was time for Amailoss, born from the naga queen's last egg, to leave home. Time for him to grow into a leader in his own right, and eventually become the guardian and leader of another naga city. But along the way, he became friends with an unusual mud-crawler, they met a strange young monster, discovered that a spirit had escaped from an orc prison, and the mystery of that spirit became a grave challenge for Amailoss and the many races in the region....''

''A naga campaign, involving elves, orcs, saurians, turtle-like races, and some monsters.''

'''Author:''' SkyOne

'''Status:''' Complete

'''Length:''' 16 playable, 2 dialog scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon

'''Faction/Era:''' Default with additions. You play a custom naga faction and carapaces (a turtle-like race).

'''[http://units.wesnoth.org/1.10/Return_of_the_Monster/en_US/Return_of_the_Monster.html Custom units]'''

'''Version:''' 0.7.1

'''Required Wesnoth version:''' 1.10.x

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36438

=== Return to Noelren ===

'''Status:''' Complete.

'''Length:''' 26 scenarios + 7 cut scenes

'''Author:''' Pyrophorus

'''Description:''' ''A story in the first Dark Age of Wesnoth. See how various heroes stick together to shun the threat of black magics, restore the secret kingdom of Noelren and install Garard I on the throne of Wesnoth. This campaign features complex scenarios, unusual objectives and units, emphasizing more on story and adventures than hardcore fighting.''

'''Version: ''' 0.7

'''Requirements:''' BfW 1.10 (not tested on 1.11)

'''Difficulty:''' Easy, unbalanced

'''Style:''' Skirmish, RPG, Large Battle, Simulation

'''Faction/Era:''' Default + custom units

'''[http://units.wesnoth.org/1.10/ReturnToNoelren/en_US/ReturnToNoelren.html Custom Units]'''

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34685#p501026

=== Return to Ruins ===

''The humble farmers of Vertegris are summoned by Erik the General of Weldyn to put an end to an orcish raiding party. If they knew what would befall their former home... They never would have left. This is a relatively short campaign with 8 scenarios, It is still undergoing changes.''

'''Author:''' Ulfsark (Jeff Stevens)

'''Status:''' Complete

'''Length:''' 7 scenarios + 1 dialogue-only

'''Difficulty:''' Easy - Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default,(Loyalists, Outlaws)

'''Version:''' 0.3.0

'''Required Wesnoth version:''' 1.10.x

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37790&sid=9059f18497cda1219f42a626544d0ffd&p=540646#p540646

'''Note:''' (Adamant14) You play a short campaign with just a few units. Playable in a few hours, nevertheless it is fun to play.

=== The Roar of the Woses ===

''When the construction of a dam threatens the existence of her home, Kylix is forced on a journey to stop it.''

'''Author:''' Alarantalara

'''Status:''' Finished

'''Length:''' 10-11 scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default with Additions (primarily Saurians, Nagas, Woses)

'''Version:''' 1.2.7

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=29830

'''Note:''' (author) Potentially unbalanced on Hard difficulty due to experiments with non-standard ways to increase difficulty. This issue does not exist on the lower difficulty levels.

=== Salt Wars ===

''Introductory campaign for the Era of Four Moons.''

''As an officer of one of the Sea States you must defend your organization from aggressive rivals.''

'''Author:''' Velensk

'''Maintainer:''' Lavender

'''Status:''' Complete

'''Length:''' 5 scenarios

'''Difficulty:''' Easy

'''Style:''' Skirmish

'''Faction/Era:''' Era of Four Moons, Sea States

'''Version:''' 0.2.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31498

=== The Sojournings of Grog ===

''Grog (as starred in Under the Burning Suns) goes home.''

'''Author:''' Peter Christopher, Thomas Hockings

'''Maintainer:''' Elvish_Hunter

'''Status:''' Finished

'''Length:''' 18 playable scenarios in 2 parts

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon, Large Battle

'''[http://units.wesnoth.org/1.10/The_Sojournings_of_Grog/en_US/The_Sojournings_of_Grog.html Custom units]'''

'''Faction/Era:''' Default. Most of the time you play trolls and some desert elves accompanying Grog.

'''Version:''' 3.0.1

=== Unlikely Alliance ===

''Play as the members of an alliance between the elves, drakes, and undead after the Fall of Wesnoth.''

'''Author:''' Creativity

'''Status:''' Broken ( Abandoned )

'''Length:''' 2 broken scenarios

'''Difficulty:''' Unbalanced

'''Style:''' -

'''Faction/Era:''' -

'''Version:''' 0.1

'''Forum:''' -

'''Note:''' (Adamant14) Did not work at all. Seems abandoned.

=== Up from Slavery ===

''The Orcei are captives in the imperial city of Lavinium, gladiators performing for the emperor Optus Maximus. All it will take, however, is one orc to lead his people to freedom. The Samnis called Sparxus may be that orc.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 7 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish, Arena (= No recruit, small group gladiator fights)

'''Faction/Era:''' Imperial Era, Orcei Gladiatores

'''Version:''' 0.6.0

[Maintainer's Note: At some point, I am intending to completely re-work this campaign to be a multi-player campaign, with one side led by Sparxus and one by Gravirivus. If anyone would like to take this on or has ideas for how to accomplish this, let us know.]

=== Way of Dragon ===

''The story of what might happen if a person against his will transform into a dragon...''

'''Author:''' DrakeDragon

'''Status:''' Complete but Broken (bug in scenario 07 stops the game)

'''Length:''' 7 playable scenarios + 1 dialogue-only

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish/RPG

'''Faction/Era:''' Default Loyalists

'''Version:''' 1

'''Forum:''' No thread in the Wesnoth forums but a there is a forum in Russian language [http://uporoom.ru/index.php/topic,179.0.html Russian Forum]

'''Note:''' (Adamant14) Short campaign with just a few units, promising but buggy, unbalanced and broken. Most of the text in Cyrillic letters. In some scenarios the objectives too.

== Battle for Wesnoth 1.11.x - development ==

''Campaigns available in the 1.11.x development version.''

''Please note: Battle for Wesnoth 1.11.0 features a bug that messes up the selection of difficulty levels.''

=== Antar, Son of Rheor ===

''This is the story about a young Lord and his first mission; sent by his father the young Lord Antar has to relieve his neighbours; he has to convince the Elves and Dwarves to ally him; he has to fight against hordes of Orcs and Endless Undead; and finally he has to defeat Mal Kazur, the mastermind who is behind all the evil.''

'''Author:''' Adamant14

'''Status:''' WIP

'''Length:''' 8 playable scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Loyalists (feat. fencer as main hero + various allies)

'''Version:''' 0.9.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36075

=== Legend of the Invincibles ===

'''''Part I: Shrouded in Darkness''' (5 chapters, 90 scenarios) - A pair of heroes, after stopping an orcish thread, are outcast into caves, where they have no other choice than to become liches in order to survive. They preserved their human appearance and moral principles, and fight in various skirmishes against evil (although using evil methods sometimes), until the Fall, when they are buried alive under the ashes of the third sun.''

'''''Part II: Into the Light''' (2 chapters, 30 scenarios at the moment) - Long after the Fall, the lich heroes awaken. Searching for more power, they manage to resurrect themselves as living beings, but this time more powerful and cleaned from the evil within them. But the evil from inside them continued to exist, and started a skirmish to conquest the world.''

'''Author:''' Dugi

'''Status:''' WiP (but Part I might be considered complete)

'''Length:''' 119 (+6 talk-only) scenarios at the moment

'''Difficulty:''' Normal

'''Style:''' mostly Skirmish and Dungeon (all other styles are present as well, but less frequently)

'''Faction/Era:''' Elves, Loyalists, Undead; but they advance past their usual maximum level

'''Version:''' 2.3.0

''Note: The most unique feature of this campaign is its RPG-like unit development system, enemies drop items units can use, leaders are stronger than most usual units and all units get AMLA (after maximum level advancement) after reaching their maximum level (that is also increased by a load of additional level 4 units).''

[[Category:Campaigns|*]]

Guide to UMC Content

2012-11-06T15:57:37Z

Alarantalara: /* The Roar of the Woses */

''This is a guide to the current (1.10.x/1.11.x) UMC campaigns for players. It aims to provide all the information not only about the story, but also about completion, difficulty and playing style of the campaign. See http://forums.wesnoth.org/viewtopic.php?f=8&t=37476 for further information, for currently non-available UMC-content please refer to http://forums.wesnoth.org/viewtopic.php?f=8&t=36733. Please edit, it is a wiki.''

=== Blueprint ===

'''Status:'''
* Broken = Does not work at all
* Incomplete = Partially written, no progress
* WIP = Partially written, progress
* Complete = Completely written, but buggy as well as potential balance issues.
* Finished = Completely written, minimal to no bugs, slight balance issues possible.

'''Length:'''

'''Author:'''

'''Maintainer:''' if not maintained by the author anymore.

'''Description:'''

'''Version: '''

'''Requirements:'''

'''Difficulty:'''

Please note: Often campaigns introducing new mechanics are listed as expert level on the add-on server, here difficulty means the raw difficulty after the mechanics are understood.

* Unbalanced = If you can't beat the hard mode, it isn't necessarily unbalanced, but if the difficulty changes erraticly from one scenario to the next and only people using the debug mode have seen the final, then it is.
* Easy
* Normal
* Hard

'''Style:'''

Please note: Many campaigns will feature more than one style. Please list the most significant ones.

* Skirmish = small to medium sized armies, your standard Wesnoth gameplay
* Dungeon = long and narrow tunnels (not every underground scenario is a dungeon, a dungeon isn't necessarily underground)
* RPG = role playing game elements such as talking with non-player-characters, item collection, dependency on a party of very few adventurers without or limited recruits
* Survival = being exposed to changing, spawning enemies while remaining on the same map
* Large Battle = Eastern Flank in Northern Rebirth, Civil War in Son of the Black-Eye
* Simulation = campaigns feat. terrain modification, alternative resources
* Boss battle = a recurring feature of Invasion of the Unknown

'''Faction/Era:'''

* Era for the whole campaign and more specifically the faction or unit composition you field.

'''Custom units:'''

* Link to the unit tree for cases that don't feel sufficiently described by Faction / Era entry.

'''Forum:'''

* Links to the feedback and development threads at forums.wesnoth.org

== Battle for Wesnoth 1.10.x - stable ==

''Campaigns available in the 1.10.x stable version.''

=== Aldur The Great ===

''This is a story about Aldur the Great.''

'''Author:''' pintercsabi

'''Status:''' Complete, but unbalanced

'''Length:''' 5 playable scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default

'''Version:''' 1.2.2

'''Forum:''' -

'''Note:''' (Adamant14) Short unbalanced campaign, maybe abandoned. You fight with Peasants, Ruffians and Woodsman against Orcs

=== Alfhelm the Wise ===

''This is the tale of Alfhelm, called by some the Wise, son of Alfric Conqueror. This is the tale of his victories over his enemies, and his rise to power in the clans of Marauderdom. This is the tale of his journey south and his destruction of the Lavinian Empire. And this is the tale of his demise in the dark forests far to the east of his homeland.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 15 gameplay scenarios

'''Difficulty:''' Moderate

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Marauders.

'''Version:''' 0.6.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=17144

[Maintainers Note: Though this campaign is complete and playable the whole way through, the code is four years old and pretty buggy. If you notice any errors while playing, please let me know and I'll incorporate the fixes into my next revision as soon as possible.]

=== Antar, Son of Rheor ===

''This is the story about a young Lord and his first mission; sent by his father the young Lord Antar has to relieve his neighbours; he has to convince the Elves and Dwarves to ally him; he has to fight against hordes of Orcs and Endless Undead; and finally he has to defeat Mal Kazur, the mastermind who is behind all the evil.''

'''Author:''' Adamant14

'''Status:''' WIP

'''Length:''' 8 playable scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Loyalists (feat. fencer as main hero + various allies)

'''Version:''' 0.8.26a

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36075

=== A Story of the Northlands ===

''A story of life and death in a remote village of the Northlands. Your village has been overrun by an orcish raid. You fight for its freedom while you wait for help to arrive.''

'''Author:''' zepko

'''Status:''' Complete

'''Length:''' 10 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default + additions: you play with a custom faction of outlaws and with a custom party of loyalist knights.

'''[http://units.wesnoth.org/1.10/A_Story_of_the_Northlands/en_US/A_Story_of_the_Northlands.html Custom Units]'''

'''Version:''' 0.2.0

=== A Vision Blinded ===

''Defend the northern forest against what appeared like a routine orcish raid, and unravel the greater conspiracies that lie below its waves.''

'''Author:''' LemonTea

'''Maintainer:''' AxalaraFlame

'''Status:''' Complete

'''Length:''' 13 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves (+ Trolls, Outlaws)

'''[http://units.wesnoth.org/1.10/A_Vision_Blinded/en_US/A_Vision_Blinded.html Custom units]'''

'''Version:''' 0.6.6

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23463&hilit=a+vision+blinded

=== Besieged Druids ===

''A elvish school for druids comes under attack by goblins. It seems more than just a routine raid; is there something more sinister behind this attack? - In Beseiged Druids, you control Eärendil, the surviving teacher at the school, and the many and varied initiates. Not all of these are ordinary students; many have been experimenting with other forms of magic, while others are simply overachievers in some area of study. Unfortunately, they are not especially good at combat, at least initially. Together with a very small contingent of surviving guards, it is up to these students to save the island of Aleron from disaster.''

'''Author:''' Celtic Minstrel

'''Status:''' Complete

'''Length:''' 9 scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''[http://units.wesnoth.org/1.10/DruidSiege/en_US/celmin-druid-siege.html Custom units]'''

'''Version:''' 1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37342

=== Cities of the Frontier ===

''Settle a new town in the wilds north of the Great River.''

''This campaign makes several changes to the standard Wesnoth game mechanics, and focuses on city-building and gold management.''

'''Author:''' esci

'''Status:''' Complete

'''Length:''' Not fixed, approximately 6-10 seasons of 36 turns each

'''Difficulty:''' Normal

'''Style:''' Simulation, Survival

'''Faction/Era:''' Default, Loyalist

'''[http://units.wesnoth.org/1.10/Cities_of_the_Frontier/en_US/Cities_of_the_Frontier.html Custom units]'''

'''Version:''' 0.5.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36004

=== Count Kromire ===

''You are the blood son of a vampire lord, however when the might of the celestial crusades comes knocking, and your father is slain, you flee your lands. However you intend to return, to restore the lands of Kromire to the Kromires, to avenge your father, and most importantly, to make sure that no celestial ever dares come into your mountains again.''

'''Author:''' Velensk

'''Maintainer:''' currently none

'''Status:''' Complete

'''Length:''' 9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Era of Myths, Vampires

'''Version:''' 1.3.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=21560

=== The Dark Hordes ===

'''Status:''' Incomplete/WIP

'''Length:''' 11/?

'''Author:''' Circon

'''Maintainer:''' Various

'''Description:''' Lead fugitive dark sorcerer Gwiti Ha’atel to mastery of the undead hordes.

'''Version: '''

'''Requirements:'''

'''Difficulty:'''

'''Style:''' Skirmish

'''Faction/Era:''' Default undead

'''[http://units.wesnoth.org/1.10/The_Dark_Hordes/en_US/The_Dark_Hordes_1.html Custom Units]'''

'''Walkthrough:''' [[TheDarkHordes]]

'''Forum:''' [[http://forums.wesnoth.org/viewtopic.php?f=8&t=16576&]]

=== The Earth's Gut ===

''The year is 515YW. You are the young dwarven leader Hamel. Your tribe in the caves of Knalga is under pressure from its enemies, and resources are growing scarce. In order to forge the weapons required to resist your enemies, you must set forth and collect what ores and minerals remain.''

'''Author:''' Anonymissimus

'''Maintainer:''' Anonymissimus

'''Status:''' Incomplete

'''Length:''' 21 scenarios

'''Difficulty:''' Normal

'''Style:''' Dungeon

'''Faction/Era:''' Default, dwarves.

'''[http://units.wesnoth.org/1.10/The_Earths_Gut/en_US/the_earths_gut.html Custom units]'''

'''Version:''' 0.2.11

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=26800

'''Note:''' This campaign is a "Dwarvish dungeon crawler" and is intended to be challenging for experienced players on hard whilst suitably easy on easy.

=== Elvish Dynasty RPG ===

''You are the new ruler of an elvish kingdom! Can you lead your people to glory? This campaign is highly randomized so it will be different every time you play!''

''Sequel to Ooze Mini-Campaign''

'''Author:''' spencelack

'''Status:''' Complete

'''Length:''' 10 years, in each year choice between dialogue and fighting scenario (selected out of a large pool of possible scenarios)

'''Difficulty:''' Normal

'''Style:''' RPG, Skirmish

'''Faction/Era:''' Default, Elves

'''Version:''' 0.9.9b

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=28627

=== The Epic of Vaniyera ===

''The expansionist Lavinian Legion, led by the Imperator himself, has invaded the northern forests of the Sidhe, or Wild Elves. It is up to Leithan the Thunderblade and his advisor Vaniyera to push its armies back where they came from...''

'''Author:''' oreb, turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 6 scenarios

'''Difficulty:''' Hard (Don't be fooled by "novice level" in the campaign description, this one is very hard.)

[Maintainers note: Working on this issue, the next release (due at the end of November, hah!) should bring easy difficulty back to the level of a reasonable introduction to the IE, while the hard difficulty will also become slightly easier. With any luck, this will be the last release before version 1.0 of the campaign].

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Sidhe.

'''Version:''' 0.9.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=19490

=== Fall of Silvium ===

''You are Caius Regilius, Tribune of the province of Silvia, located in the northmost reaches of the Lavinian Empire at the height of its power. But the Empire has overextended itself, The city of Silvium lies seperated from the rest of the Empire by the mountains of Arendia, and is sandwiched between the Marauders and the Sidhe... war is inevitable, and the province of Silvia will almost certainly fall.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 8 scenarios

'''Difficulty:''' Medium

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Lavinian Legion.

'''Version:''' 0.6

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=31&t=24356

[Note: The final level of this campaign is not supposed to be winnable. It's a final blaze of glory and chance to use all your high-powered units, but to 'win' the campaign, you must lose...the ending is similar to a certain mainline campaign, but predates it.]

=== The Fall of Wesnoth ===

''As the beloved human empire of Wesnoth becomes lazy and arrogant in its peaceful state of happiness, Emperor Dantair demands the creation of another sun in a bid to destroy all evil. Or is it all for a different purpose? A man named Alitar sees it that way, and now he must survive the most evil inhabited lands if he is to stop chaos from rising, and Wesnoth from falling... This is the story of The Fall of Wesnoth.''

'''Author:''' Pewskeepski

'''Status:''' 1st part complete, 2nd WIP.

'''Length:''' 10 playable scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Outlaws

'''[http://units.wesnoth.org/1.10/The_Fall_of_Wesnoth/en_US/The_Fall_of_Wesnoth-1.html Custom units]'''

'''Version:''' 1.0.8

=== Fate of a Princess ===

''Part I: Baldres, a notorious robber baron, flees Wesnoth with his followers and sets off into the northlands to evade the king's justice. The baron's deeds and misdeeds are to change the balance of power between orcs and non-orcs throughout the northlands, and will carry consequences long after his eventual death.''

''Part II: The Greenwood elves face a crisis which demands the return of the queen's estranged half-elven half-sister, Baldres' daughter. Two brave young elves must make a perilous journey to find her and bring her back to her former home. If they fail, the whole northlands will be engulfed in war with the resurgent orcs...''

'''Author:''' SkyOne, mich, simonsmith

'''Status:''' Finished

'''Length:''' 26-29 scenarios (some dialogue-only), 2 parts

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon

'''Faction/Era:''' Default with additions. You play two different, unique cross-faction combinations in each part.

'''[http://units.wesnoth.org/1.10/Fate_of_a_Princess/en_US/Fate_of_a_Princess.html Custom units]'''

'''Version:''' 0.9.17

'''Required Wesnoth version:''' 1.9.12 or later

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=26327

=== Forgotten Kingdom ===

''Help Orlog, a troll chieftan, lead his people to safety in the underground and discover an ancient power long forgotten.''

'''Author:''' Limabean

'''Status:''' Incomplete ( but all scenarios playable and balanced )

'''Length:''' 9 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Goblins, Trolls

'''[http://units.wesnoth.org/1.10/Forgotten_Kingdom/en_US/Forgotten_Kingdom.html Custom units]'''

'''Version:''' 0.1.7

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23483

'''Note:''' (Adamant14) This campaign includes a custom Troll line. A good campaign, sad that Limabean seems to abandon it.

=== Forward they Cried ===

''You are the leader of an advanced detachment that has been tasked with capturing a bridgehead while the main army prepares to attack. It should be a simple enough assignment.''

'''Author:''' Glowing Fish

'''Maintainer:''' Lord-Knightmare

'''Status:''' Finished

'''Length:''' 1 scenario ( rather a single scenario than a campaign )

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default Loyalists

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23656&p=350126&hilit=forward+they+cried#p350126

'''Version:''' 1.0.0

'''Note:''' (Adamant14) Only a single scenario, but a great scenario.
(UnwiseOwl) You wouldn't want to stop thinking for a turn, and it's good for the first few turns, but this one leaves me wanting more.

=== The Founding of Borstep ===

''The chieftain of your tribe has become decadent and weak. Take over, and lead your people to a better home--whether it is already occupied or not. The Northlands in year 9W are a barbaric place, but anyone who stands in your way will learn the power of orcs!''

'''Author:''' Beetlenaut

'''Status:''' Complete

'''Length:''' 10 and 1 dialogue only

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default, Northerners

'''[http://units.wesnoth.org/1.10/The_Founding_of_Borstep/en_US/The_Founding_of_Borstep.html Custom units]'''

'''Version:''' 1.1.1b

''Note(Kanzil): I find the protagonist hard to sympathise with. Also, most scenarios contain interesting twists. For example, in one, each time you killed a boar it gives you extra health.''

''Note(beetlenaut--author): In most Orcish campaigns the leader is heroic or just wants peace. Krag-Ubor wants plunder and battle like all enemy Orcs in other campaigns. I '''hope''' you don't sympathize too strongly, but I don't think you need to in order to enjoy the game play.''

=== Galuldur's First Journey ===

''While the belligerence of orcs is nothing new, their intensifying attacks on a fledgling colony of elves in Pindir Forest begin to show signs of a deeper malice, forcing Galuldur, the young son of the colony's adventurous founder Galur, to venture out of his forest's friendly trees in search of help. His simple errand quickly turns into a frantic quest to unearth the roots of the mysterious evil threatening his people. As you lead him through unknown lands, Galuldur, forced to match wits with unexpected adversaries at nearly every turn in a desperate attempt to save his world, quickly learns that the world is neither a friendly nor a simple place.''

'''Author:''' mattsc

'''Status:''' Complete

'''Length:''' 8-9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''[http://units.wesnoth.org/1.10/Galuldur/en_US/Galuldur.html Custom units]'''

'''Version:''' 1.1.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31895

=== Grnk the Mighty ===

''All his life, puny little goblin Grnk the Frail had been dreaming about leaving the orcs and starting a better life. When he finally arrives in the human town of Shmaltupp, he realizes that the world is not as black and white as he had imagined. He also discovers that he is no ordinary goblin. Follow Grnk the Frail on his path to becoming Grnk the Mighty.''

'''Author:''' mattsc

'''Status:''' Part I complete

'''Length:''' 13 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish, RPG

'''Faction/Era:''' Default, changing (no standard army building gameplay)

'''[http://units.wesnoth.org/1.10/Grnk/en_US/Grnk.html Custom units]'''

'''Version:''' 1.0.5

'''Required Wesnoth version:''' 1.9.5 or later

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34970

=== Invasion from the Unknown ===

''Episode I - Seeking the Light: Long after the Fall, the last forest elves are forced to abandon their safe valley, and find themselves resorting to the dark means of necromancy in order to survive the perils and challenges of this new harsh world. May they finally free the Great Continent from its chaos, or perish in the foolish attempt of restoring peace and life to the lands.''

''Episode II - Armageddon: As the shadow of Chaos covers the entire continent, an assorted group of foolish heroes prepares a counter-attack to the Empire, with one unique goal in their minds: defeat the evil Emperor, whoever it is. Lead these courageous living and non-living warriors to victory, and rediscover lost secrets of the history.''

'''Author:''' shadowmaster

'''Maintainer:''' Espreon

'''Status:''' Finished

'''Length:''' 26 scenarios in two episodes

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon, Boss battle

'''Faction/Era:''' Unique. You play Elves and Undead throughout the campaign + in the 2nd part Northerners and Aragwaithi.

'''Version:''' 1.90.6

''Note (taptap): Despite its acknowledged flaws (generic hero, plot holes, deus ex machina moments, gameplay issues in the 2nd part) this is undoubtedly the most iconic campaign in UMC. It single-handedly redefines the elvish history and sketches a cosmology for the ages after the fall. With the Chaos empire and its various allies it introduces an era worth of factions to single-player play. At the same time it features some of the most beautiful maps in Wesnoth and stunning art on par with mainline campaigns.''

=== Langrisser Sample Campaign ===

''The Imperial Knights of the Rayguard Empire have disrupted the peace of the village that was Hein's hometown, seeking only a girl named Liana. Fight to rescue Liana.''

'''Author:''' Morath

'''Status:''' Finished

'''Length:''' 1 playable scenario

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''Version:''' 0.1.0.5

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36417&hilit=Langrisser

'''Wikipedia:''' [http://en.wikipedia.org/wiki/Langrisser What is Langrisser]

'''Note:''' (Adamant14) Single scenario, different from usual Wesnoth behaviour.

=== Legend of the Invincibles ===

'''''Part I: Shrouded in Darkness''' (5 chapters, 90 scenarios) - A pair of heroes, after stopping an orcish thread, are outcast into caves, where they have no other choice than to become liches in order to survive. They preserved their human appearance and moral principles, and fight in various skirmishes against evil (although using evil methods sometimes), until the Fall, when they are buried alive under the ashes of the third sun.''

'''''Part II: Into the Light''' (2 chapters, 30 scenarios at the moment) - Long after the Fall, the lich heroes awaken. Searching for more power, they manage to resurrect themselves as living beings, but this time more powerful and cleaned from the evil within them. But the evil from inside them continued to exist, and started a skirmish to conquest the world.''

'''Author:''' Dugi

'''Status:''' WiP (but Part I might be considered complete)

'''Length:''' 119 (+6 talk-only) scenarios at the moment

'''Difficulty:''' Normal

'''Style:''' mostly Skirmish and Dungeon (all other styles are present as well, but less frequently)

'''Faction/Era:''' Elves, Loyalists, Undead; but they advance past their usual maximum level

'''Version:''' 2.3.0

''Note: The most unique feature of this campaign is its RPG-like unit development system, enemies drop items units can use, leaders are stronger than most usual units and all units get AMLA (after maximum level advancement) after reaching their maximum level (that is also increased by a load of additional level 4 units).''

=== The Library of Kratemaqht ===

''An ancient story from the old continent.''

'''Author:''' Rich Marinaccio (cephalo)

'''Status:''' Complete

'''Length:''' 17 scenarios

'''Difficulty:''' Unbalanced (some scenarios are Easy - some rather Hard)

'''Style:''' Skirmish, RPG

'''Faction/Era:''' Loyalists and custom units.

'''[http://units.wesnoth.org/1.10/Library_Of_Kratemaqht/en_US/The_Library_Of_Kratemaqht.html Custom units]'''

'''Version:''' 1.0.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37798

'''Notes:''' (Adamant14) This campaign has a thought-out story, shows a great love for detail;
It includes a great custom Dragon, some brilliant custom images (fire, burning houses, burning forest) that makes the scenery / maps look very nice.

=== Panther Lord ===

''The Imperialists ambitions of pushing into the Sea States have been repeatedly thwarted and now they turn their attentions elsewhere. You are an outcast Darklander now living as a mercenary in the Sea States and the rumors you hear indicate that they will be coming to your people. Though an outcast you do not wish to see them subjugated. The spirit whose friendship caused you to be an outcast has a plan that might allow you to save them.''

'''Author:''' Velensk

'''Maintainer:''' Lavender

'''Status:''' Finished

'''Length:''' 14 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Era of Four Moons, Darklanders (+ a wide variety of mercenaries)

'''Version:''' 1.0.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34318

=== Return of the Monster ===

''It was time for Amailoss, born from the naga queen's last egg, to leave home. Time for him to grow into a leader in his own right, and eventually become the guardian and leader of another naga city. But along the way, he became friends with an unusual mud-crawler, they met a strange young monster, discovered that a spirit had escaped from an orc prison, and the mystery of that spirit became a grave challenge for Amailoss and the many races in the region....''

''A naga campaign, involving elves, orcs, saurians, turtle-like races, and some monsters.''

'''Author:''' SkyOne

'''Status:''' Complete

'''Length:''' 16 playable, 2 dialog scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon

'''Faction/Era:''' Default with additions. You play a custom naga faction and carapaces (a turtle-like race).

'''[http://units.wesnoth.org/1.10/Return_of_the_Monster/en_US/Return_of_the_Monster.html Custom units]'''

'''Version:''' 0.7.1

'''Required Wesnoth version:''' 1.10.x

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36438

=== Return to Noelren ===

'''Status:''' Complete.

'''Length:''' 26 scenarios + 7 cut scenes

'''Author:''' Pyrophorus

'''Description:''' ''A story in the first Dark Age of Wesnoth. See how various heroes stick together to shun the threat of black magics, restore the secret kingdom of Noelren and install Garard I on the throne of Wesnoth. This campaign features complex scenarios, unusual objectives and units, emphasizing more on story and adventures than hardcore fighting.''

'''Version: ''' 0.7

'''Requirements:''' BfW 1.10 (not tested on 1.11)

'''Difficulty:''' Easy, unbalanced

'''Style:''' Skirmish, RPG, Large Battle, Simulation

'''Faction/Era:''' Default + custom units

'''[http://units.wesnoth.org/1.10/ReturnToNoelren/en_US/ReturnToNoelren.html Custom Units]'''

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34685#p501026

=== Return to Ruins ===

''The humble farmers of Vertegris are summoned by Erik the General of Weldyn to put an end to an orcish raiding party. If they knew what would befall their former home... They never would have left. This is a relatively short campaign with 8 scenarios, It is still undergoing changes.''

'''Author:''' Ulfsark (Jeff Stevens)

'''Status:''' Complete

'''Length:''' 7 scenarios + 1 dialogue-only

'''Difficulty:''' Easy - Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default,(Loyalists, Outlaws)

'''Version:''' 0.3.0

'''Required Wesnoth version:''' 1.10.x

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37790&sid=9059f18497cda1219f42a626544d0ffd&p=540646#p540646

'''Note:''' (Adamant14) You play a short campaign with just a few units. Playable in a few hours, nevertheless it is fun to play.

=== The Roar of the Woses ===

''When the construction of a dam threatens the existence of her home, Kylix is forced on a journey to stop it.''

'''Author:''' Alarantalara

'''Status:''' Finished

'''Length:''' 9-10 scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default with Additions (primarily Saurians, Nagas, Woses)

'''Version:''' 1.2.7

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=29830

'''Note:''' (author) Potentially unbalanced on Hard difficulty due to experiments with non-standard ways to increase difficulty. This issue does not exist on the lower difficulty levels.

=== Salt Wars ===

''Introductory campaign for the Era of Four Moons.''

''As an officer of one of the Sea States you must defend your organization from aggressive rivals.''

'''Author:''' Velensk

'''Maintainer:''' Lavender

'''Status:''' Complete

'''Length:''' 5 scenarios

'''Difficulty:''' Easy

'''Style:''' Skirmish

'''Faction/Era:''' Era of Four Moons, Sea States

'''Version:''' 0.2.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31498

=== The Sojournings of Grog ===

''Grog (as starred in Under the Burning Suns) goes home.''

'''Author:''' Peter Christopher, Thomas Hockings

'''Maintainer:''' Elvish_Hunter

'''Status:''' Finished

'''Length:''' 18 playable scenarios in 2 parts

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon, Large Battle

'''[http://units.wesnoth.org/1.10/The_Sojournings_of_Grog/en_US/The_Sojournings_of_Grog.html Custom units]'''

'''Faction/Era:''' Default. Most of the time you play trolls and some desert elves accompanying Grog.

'''Version:''' 3.0.1

=== Unlikely Alliance ===

''Play as the members of an alliance between the elves, drakes, and undead after the Fall of Wesnoth.''

'''Author:''' Creativity

'''Status:''' Broken ( Abandoned )

'''Length:''' 2 broken scenarios

'''Difficulty:''' Unbalanced

'''Style:''' -

'''Faction/Era:''' -

'''Version:''' 0.1

'''Forum:''' -

'''Note:''' (Adamant14) Did not work at all. Seems abandoned.

=== Up from Slavery ===

''The Orcei are captives in the imperial city of Lavinium, gladiators performing for the emperor Optus Maximus. All it will take, however, is one orc to lead his people to freedom. The Samnis called Sparxus may be that orc.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 7 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish, Arena (= No recruit, small group gladiator fights)

'''Faction/Era:''' Imperial Era, Orcei Gladiatores

'''Version:''' 0.6.0

[Maintainer's Note: At some point, I am intending to completely re-work this campaign to be a multi-player campaign, with one side led by Sparxus and one by Gravirivus. If anyone would like to take this on or has ideas for how to accomplish this, let us know.]

=== Way of Dragon ===

''The story of what might happen if a person against his will transform into a dragon...''

'''Author:''' DrakeDragon

'''Status:''' Complete but Broken (bug in scenario 07 stops the game)

'''Length:''' 7 playable scenarios + 1 dialogue-only

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish/RPG

'''Faction/Era:''' Default Loyalists

'''Version:''' 1

'''Forum:''' No thread in the Wesnoth forums but a there is a forum in Russian language [http://uporoom.ru/index.php/topic,179.0.html Russian Forum]

'''Note:''' (Adamant14) Short campaign with just a few units, promising but buggy, unbalanced and broken. Most of the text in Cyrillic letters. In some scenarios the objectives too.

== Battle for Wesnoth 1.11.x - development ==

''Campaigns available in the 1.11.x development version.''

''Please note: Battle for Wesnoth 1.11.0 features a bug that messes up the selection of difficulty levels.''

=== Antar, Son of Rheor ===

''This is the story about a young Lord and his first mission; sent by his father the young Lord Antar has to relieve his neighbours; he has to convince the Elves and Dwarves to ally him; he has to fight against hordes of Orcs and Endless Undead; and finally he has to defeat Mal Kazur, the mastermind who is behind all the evil.''

'''Author:''' Adamant14

'''Status:''' WIP

'''Length:''' 8 playable scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Loyalists (feat. fencer as main hero + various allies)

'''Version:''' 0.9.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36075

=== Legend of the Invincibles ===

'''''Part I: Shrouded in Darkness''' (5 chapters, 90 scenarios) - A pair of heroes, after stopping an orcish thread, are outcast into caves, where they have no other choice than to become liches in order to survive. They preserved their human appearance and moral principles, and fight in various skirmishes against evil (although using evil methods sometimes), until the Fall, when they are buried alive under the ashes of the third sun.''

'''''Part II: Into the Light''' (2 chapters, 30 scenarios at the moment) - Long after the Fall, the lich heroes awaken. Searching for more power, they manage to resurrect themselves as living beings, but this time more powerful and cleaned from the evil within them. But the evil from inside them continued to exist, and started a skirmish to conquest the world.''

'''Author:''' Dugi

'''Status:''' WiP (but Part I might be considered complete)

'''Length:''' 119 (+6 talk-only) scenarios at the moment

'''Difficulty:''' Normal

'''Style:''' mostly Skirmish and Dungeon (all other styles are present as well, but less frequently)

'''Faction/Era:''' Elves, Loyalists, Undead; but they advance past their usual maximum level

'''Version:''' 2.3.0

''Note: The most unique feature of this campaign is its RPG-like unit development system, enemies drop items units can use, leaders are stronger than most usual units and all units get AMLA (after maximum level advancement) after reaching their maximum level (that is also increased by a load of additional level 4 units).''

[[Category:Campaigns|*]]

Guide to UMC Content

2012-11-06T15:57:08Z

Alarantalara: /* The Roar of the Woses */

''This is a guide to the current (1.10.x/1.11.x) UMC campaigns for players. It aims to provide all the information not only about the story, but also about completion, difficulty and playing style of the campaign. See http://forums.wesnoth.org/viewtopic.php?f=8&t=37476 for further information, for currently non-available UMC-content please refer to http://forums.wesnoth.org/viewtopic.php?f=8&t=36733. Please edit, it is a wiki.''

=== Blueprint ===

'''Status:'''
* Broken = Does not work at all
* Incomplete = Partially written, no progress
* WIP = Partially written, progress
* Complete = Completely written, but buggy as well as potential balance issues.
* Finished = Completely written, minimal to no bugs, slight balance issues possible.

'''Length:'''

'''Author:'''

'''Maintainer:''' if not maintained by the author anymore.

'''Description:'''

'''Version: '''

'''Requirements:'''

'''Difficulty:'''

Please note: Often campaigns introducing new mechanics are listed as expert level on the add-on server, here difficulty means the raw difficulty after the mechanics are understood.

* Unbalanced = If you can't beat the hard mode, it isn't necessarily unbalanced, but if the difficulty changes erraticly from one scenario to the next and only people using the debug mode have seen the final, then it is.
* Easy
* Normal
* Hard

'''Style:'''

Please note: Many campaigns will feature more than one style. Please list the most significant ones.

* Skirmish = small to medium sized armies, your standard Wesnoth gameplay
* Dungeon = long and narrow tunnels (not every underground scenario is a dungeon, a dungeon isn't necessarily underground)
* RPG = role playing game elements such as talking with non-player-characters, item collection, dependency on a party of very few adventurers without or limited recruits
* Survival = being exposed to changing, spawning enemies while remaining on the same map
* Large Battle = Eastern Flank in Northern Rebirth, Civil War in Son of the Black-Eye
* Simulation = campaigns feat. terrain modification, alternative resources
* Boss battle = a recurring feature of Invasion of the Unknown

'''Faction/Era:'''

* Era for the whole campaign and more specifically the faction or unit composition you field.

'''Custom units:'''

* Link to the unit tree for cases that don't feel sufficiently described by Faction / Era entry.

'''Forum:'''

* Links to the feedback and development threads at forums.wesnoth.org

== Battle for Wesnoth 1.10.x - stable ==

''Campaigns available in the 1.10.x stable version.''

=== Aldur The Great ===

''This is a story about Aldur the Great.''

'''Author:''' pintercsabi

'''Status:''' Complete, but unbalanced

'''Length:''' 5 playable scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default

'''Version:''' 1.2.2

'''Forum:''' -

'''Note:''' (Adamant14) Short unbalanced campaign, maybe abandoned. You fight with Peasants, Ruffians and Woodsman against Orcs

=== Alfhelm the Wise ===

''This is the tale of Alfhelm, called by some the Wise, son of Alfric Conqueror. This is the tale of his victories over his enemies, and his rise to power in the clans of Marauderdom. This is the tale of his journey south and his destruction of the Lavinian Empire. And this is the tale of his demise in the dark forests far to the east of his homeland.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 15 gameplay scenarios

'''Difficulty:''' Moderate

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Marauders.

'''Version:''' 0.6.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=17144

[Maintainers Note: Though this campaign is complete and playable the whole way through, the code is four years old and pretty buggy. If you notice any errors while playing, please let me know and I'll incorporate the fixes into my next revision as soon as possible.]

=== Antar, Son of Rheor ===

''This is the story about a young Lord and his first mission; sent by his father the young Lord Antar has to relieve his neighbours; he has to convince the Elves and Dwarves to ally him; he has to fight against hordes of Orcs and Endless Undead; and finally he has to defeat Mal Kazur, the mastermind who is behind all the evil.''

'''Author:''' Adamant14

'''Status:''' WIP

'''Length:''' 8 playable scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Loyalists (feat. fencer as main hero + various allies)

'''Version:''' 0.8.26a

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36075

=== A Story of the Northlands ===

''A story of life and death in a remote village of the Northlands. Your village has been overrun by an orcish raid. You fight for its freedom while you wait for help to arrive.''

'''Author:''' zepko

'''Status:''' Complete

'''Length:''' 10 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default + additions: you play with a custom faction of outlaws and with a custom party of loyalist knights.

'''[http://units.wesnoth.org/1.10/A_Story_of_the_Northlands/en_US/A_Story_of_the_Northlands.html Custom Units]'''

'''Version:''' 0.2.0

=== A Vision Blinded ===

''Defend the northern forest against what appeared like a routine orcish raid, and unravel the greater conspiracies that lie below its waves.''

'''Author:''' LemonTea

'''Maintainer:''' AxalaraFlame

'''Status:''' Complete

'''Length:''' 13 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves (+ Trolls, Outlaws)

'''[http://units.wesnoth.org/1.10/A_Vision_Blinded/en_US/A_Vision_Blinded.html Custom units]'''

'''Version:''' 0.6.6

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23463&hilit=a+vision+blinded

=== Besieged Druids ===

''A elvish school for druids comes under attack by goblins. It seems more than just a routine raid; is there something more sinister behind this attack? - In Beseiged Druids, you control Eärendil, the surviving teacher at the school, and the many and varied initiates. Not all of these are ordinary students; many have been experimenting with other forms of magic, while others are simply overachievers in some area of study. Unfortunately, they are not especially good at combat, at least initially. Together with a very small contingent of surviving guards, it is up to these students to save the island of Aleron from disaster.''

'''Author:''' Celtic Minstrel

'''Status:''' Complete

'''Length:''' 9 scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''[http://units.wesnoth.org/1.10/DruidSiege/en_US/celmin-druid-siege.html Custom units]'''

'''Version:''' 1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37342

=== Cities of the Frontier ===

''Settle a new town in the wilds north of the Great River.''

''This campaign makes several changes to the standard Wesnoth game mechanics, and focuses on city-building and gold management.''

'''Author:''' esci

'''Status:''' Complete

'''Length:''' Not fixed, approximately 6-10 seasons of 36 turns each

'''Difficulty:''' Normal

'''Style:''' Simulation, Survival

'''Faction/Era:''' Default, Loyalist

'''[http://units.wesnoth.org/1.10/Cities_of_the_Frontier/en_US/Cities_of_the_Frontier.html Custom units]'''

'''Version:''' 0.5.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36004

=== Count Kromire ===

''You are the blood son of a vampire lord, however when the might of the celestial crusades comes knocking, and your father is slain, you flee your lands. However you intend to return, to restore the lands of Kromire to the Kromires, to avenge your father, and most importantly, to make sure that no celestial ever dares come into your mountains again.''

'''Author:''' Velensk

'''Maintainer:''' currently none

'''Status:''' Complete

'''Length:''' 9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Era of Myths, Vampires

'''Version:''' 1.3.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=21560

=== The Dark Hordes ===

'''Status:''' Incomplete/WIP

'''Length:''' 11/?

'''Author:''' Circon

'''Maintainer:''' Various

'''Description:''' Lead fugitive dark sorcerer Gwiti Ha’atel to mastery of the undead hordes.

'''Version: '''

'''Requirements:'''

'''Difficulty:'''

'''Style:''' Skirmish

'''Faction/Era:''' Default undead

'''[http://units.wesnoth.org/1.10/The_Dark_Hordes/en_US/The_Dark_Hordes_1.html Custom Units]'''

'''Walkthrough:''' [[TheDarkHordes]]

'''Forum:''' [[http://forums.wesnoth.org/viewtopic.php?f=8&t=16576&]]

=== The Earth's Gut ===

''The year is 515YW. You are the young dwarven leader Hamel. Your tribe in the caves of Knalga is under pressure from its enemies, and resources are growing scarce. In order to forge the weapons required to resist your enemies, you must set forth and collect what ores and minerals remain.''

'''Author:''' Anonymissimus

'''Maintainer:''' Anonymissimus

'''Status:''' Incomplete

'''Length:''' 21 scenarios

'''Difficulty:''' Normal

'''Style:''' Dungeon

'''Faction/Era:''' Default, dwarves.

'''[http://units.wesnoth.org/1.10/The_Earths_Gut/en_US/the_earths_gut.html Custom units]'''

'''Version:''' 0.2.11

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=26800

'''Note:''' This campaign is a "Dwarvish dungeon crawler" and is intended to be challenging for experienced players on hard whilst suitably easy on easy.

=== Elvish Dynasty RPG ===

''You are the new ruler of an elvish kingdom! Can you lead your people to glory? This campaign is highly randomized so it will be different every time you play!''

''Sequel to Ooze Mini-Campaign''

'''Author:''' spencelack

'''Status:''' Complete

'''Length:''' 10 years, in each year choice between dialogue and fighting scenario (selected out of a large pool of possible scenarios)

'''Difficulty:''' Normal

'''Style:''' RPG, Skirmish

'''Faction/Era:''' Default, Elves

'''Version:''' 0.9.9b

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=28627

=== The Epic of Vaniyera ===

''The expansionist Lavinian Legion, led by the Imperator himself, has invaded the northern forests of the Sidhe, or Wild Elves. It is up to Leithan the Thunderblade and his advisor Vaniyera to push its armies back where they came from...''

'''Author:''' oreb, turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 6 scenarios

'''Difficulty:''' Hard (Don't be fooled by "novice level" in the campaign description, this one is very hard.)

[Maintainers note: Working on this issue, the next release (due at the end of November, hah!) should bring easy difficulty back to the level of a reasonable introduction to the IE, while the hard difficulty will also become slightly easier. With any luck, this will be the last release before version 1.0 of the campaign].

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Sidhe.

'''Version:''' 0.9.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=19490

=== Fall of Silvium ===

''You are Caius Regilius, Tribune of the province of Silvia, located in the northmost reaches of the Lavinian Empire at the height of its power. But the Empire has overextended itself, The city of Silvium lies seperated from the rest of the Empire by the mountains of Arendia, and is sandwiched between the Marauders and the Sidhe... war is inevitable, and the province of Silvia will almost certainly fall.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 8 scenarios

'''Difficulty:''' Medium

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Lavinian Legion.

'''Version:''' 0.6

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=31&t=24356

[Note: The final level of this campaign is not supposed to be winnable. It's a final blaze of glory and chance to use all your high-powered units, but to 'win' the campaign, you must lose...the ending is similar to a certain mainline campaign, but predates it.]

=== The Fall of Wesnoth ===

''As the beloved human empire of Wesnoth becomes lazy and arrogant in its peaceful state of happiness, Emperor Dantair demands the creation of another sun in a bid to destroy all evil. Or is it all for a different purpose? A man named Alitar sees it that way, and now he must survive the most evil inhabited lands if he is to stop chaos from rising, and Wesnoth from falling... This is the story of The Fall of Wesnoth.''

'''Author:''' Pewskeepski

'''Status:''' 1st part complete, 2nd WIP.

'''Length:''' 10 playable scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Outlaws

'''[http://units.wesnoth.org/1.10/The_Fall_of_Wesnoth/en_US/The_Fall_of_Wesnoth-1.html Custom units]'''

'''Version:''' 1.0.8

=== Fate of a Princess ===

''Part I: Baldres, a notorious robber baron, flees Wesnoth with his followers and sets off into the northlands to evade the king's justice. The baron's deeds and misdeeds are to change the balance of power between orcs and non-orcs throughout the northlands, and will carry consequences long after his eventual death.''

''Part II: The Greenwood elves face a crisis which demands the return of the queen's estranged half-elven half-sister, Baldres' daughter. Two brave young elves must make a perilous journey to find her and bring her back to her former home. If they fail, the whole northlands will be engulfed in war with the resurgent orcs...''

'''Author:''' SkyOne, mich, simonsmith

'''Status:''' Finished

'''Length:''' 26-29 scenarios (some dialogue-only), 2 parts

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon

'''Faction/Era:''' Default with additions. You play two different, unique cross-faction combinations in each part.

'''[http://units.wesnoth.org/1.10/Fate_of_a_Princess/en_US/Fate_of_a_Princess.html Custom units]'''

'''Version:''' 0.9.17

'''Required Wesnoth version:''' 1.9.12 or later

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=26327

=== Forgotten Kingdom ===

''Help Orlog, a troll chieftan, lead his people to safety in the underground and discover an ancient power long forgotten.''

'''Author:''' Limabean

'''Status:''' Incomplete ( but all scenarios playable and balanced )

'''Length:''' 9 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Goblins, Trolls

'''[http://units.wesnoth.org/1.10/Forgotten_Kingdom/en_US/Forgotten_Kingdom.html Custom units]'''

'''Version:''' 0.1.7

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23483

'''Note:''' (Adamant14) This campaign includes a custom Troll line. A good campaign, sad that Limabean seems to abandon it.

=== Forward they Cried ===

''You are the leader of an advanced detachment that has been tasked with capturing a bridgehead while the main army prepares to attack. It should be a simple enough assignment.''

'''Author:''' Glowing Fish

'''Maintainer:''' Lord-Knightmare

'''Status:''' Finished

'''Length:''' 1 scenario ( rather a single scenario than a campaign )

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default Loyalists

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23656&p=350126&hilit=forward+they+cried#p350126

'''Version:''' 1.0.0

'''Note:''' (Adamant14) Only a single scenario, but a great scenario.
(UnwiseOwl) You wouldn't want to stop thinking for a turn, and it's good for the first few turns, but this one leaves me wanting more.

=== The Founding of Borstep ===

''The chieftain of your tribe has become decadent and weak. Take over, and lead your people to a better home--whether it is already occupied or not. The Northlands in year 9W are a barbaric place, but anyone who stands in your way will learn the power of orcs!''

'''Author:''' Beetlenaut

'''Status:''' Complete

'''Length:''' 10 and 1 dialogue only

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default, Northerners

'''[http://units.wesnoth.org/1.10/The_Founding_of_Borstep/en_US/The_Founding_of_Borstep.html Custom units]'''

'''Version:''' 1.1.1b

''Note(Kanzil): I find the protagonist hard to sympathise with. Also, most scenarios contain interesting twists. For example, in one, each time you killed a boar it gives you extra health.''

''Note(beetlenaut--author): In most Orcish campaigns the leader is heroic or just wants peace. Krag-Ubor wants plunder and battle like all enemy Orcs in other campaigns. I '''hope''' you don't sympathize too strongly, but I don't think you need to in order to enjoy the game play.''

=== Galuldur's First Journey ===

''While the belligerence of orcs is nothing new, their intensifying attacks on a fledgling colony of elves in Pindir Forest begin to show signs of a deeper malice, forcing Galuldur, the young son of the colony's adventurous founder Galur, to venture out of his forest's friendly trees in search of help. His simple errand quickly turns into a frantic quest to unearth the roots of the mysterious evil threatening his people. As you lead him through unknown lands, Galuldur, forced to match wits with unexpected adversaries at nearly every turn in a desperate attempt to save his world, quickly learns that the world is neither a friendly nor a simple place.''

'''Author:''' mattsc

'''Status:''' Complete

'''Length:''' 8-9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''[http://units.wesnoth.org/1.10/Galuldur/en_US/Galuldur.html Custom units]'''

'''Version:''' 1.1.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31895

=== Grnk the Mighty ===

''All his life, puny little goblin Grnk the Frail had been dreaming about leaving the orcs and starting a better life. When he finally arrives in the human town of Shmaltupp, he realizes that the world is not as black and white as he had imagined. He also discovers that he is no ordinary goblin. Follow Grnk the Frail on his path to becoming Grnk the Mighty.''

'''Author:''' mattsc

'''Status:''' Part I complete

'''Length:''' 13 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish, RPG

'''Faction/Era:''' Default, changing (no standard army building gameplay)

'''[http://units.wesnoth.org/1.10/Grnk/en_US/Grnk.html Custom units]'''

'''Version:''' 1.0.5

'''Required Wesnoth version:''' 1.9.5 or later

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34970

=== Invasion from the Unknown ===

''Episode I - Seeking the Light: Long after the Fall, the last forest elves are forced to abandon their safe valley, and find themselves resorting to the dark means of necromancy in order to survive the perils and challenges of this new harsh world. May they finally free the Great Continent from its chaos, or perish in the foolish attempt of restoring peace and life to the lands.''

''Episode II - Armageddon: As the shadow of Chaos covers the entire continent, an assorted group of foolish heroes prepares a counter-attack to the Empire, with one unique goal in their minds: defeat the evil Emperor, whoever it is. Lead these courageous living and non-living warriors to victory, and rediscover lost secrets of the history.''

'''Author:''' shadowmaster

'''Maintainer:''' Espreon

'''Status:''' Finished

'''Length:''' 26 scenarios in two episodes

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon, Boss battle

'''Faction/Era:''' Unique. You play Elves and Undead throughout the campaign + in the 2nd part Northerners and Aragwaithi.

'''Version:''' 1.90.6

''Note (taptap): Despite its acknowledged flaws (generic hero, plot holes, deus ex machina moments, gameplay issues in the 2nd part) this is undoubtedly the most iconic campaign in UMC. It single-handedly redefines the elvish history and sketches a cosmology for the ages after the fall. With the Chaos empire and its various allies it introduces an era worth of factions to single-player play. At the same time it features some of the most beautiful maps in Wesnoth and stunning art on par with mainline campaigns.''

=== Langrisser Sample Campaign ===

''The Imperial Knights of the Rayguard Empire have disrupted the peace of the village that was Hein's hometown, seeking only a girl named Liana. Fight to rescue Liana.''

'''Author:''' Morath

'''Status:''' Finished

'''Length:''' 1 playable scenario

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''Version:''' 0.1.0.5

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36417&hilit=Langrisser

'''Wikipedia:''' [http://en.wikipedia.org/wiki/Langrisser What is Langrisser]

'''Note:''' (Adamant14) Single scenario, different from usual Wesnoth behaviour.

=== Legend of the Invincibles ===

'''''Part I: Shrouded in Darkness''' (5 chapters, 90 scenarios) - A pair of heroes, after stopping an orcish thread, are outcast into caves, where they have no other choice than to become liches in order to survive. They preserved their human appearance and moral principles, and fight in various skirmishes against evil (although using evil methods sometimes), until the Fall, when they are buried alive under the ashes of the third sun.''

'''''Part II: Into the Light''' (2 chapters, 30 scenarios at the moment) - Long after the Fall, the lich heroes awaken. Searching for more power, they manage to resurrect themselves as living beings, but this time more powerful and cleaned from the evil within them. But the evil from inside them continued to exist, and started a skirmish to conquest the world.''

'''Author:''' Dugi

'''Status:''' WiP (but Part I might be considered complete)

'''Length:''' 119 (+6 talk-only) scenarios at the moment

'''Difficulty:''' Normal

'''Style:''' mostly Skirmish and Dungeon (all other styles are present as well, but less frequently)

'''Faction/Era:''' Elves, Loyalists, Undead; but they advance past their usual maximum level

'''Version:''' 2.3.0

''Note: The most unique feature of this campaign is its RPG-like unit development system, enemies drop items units can use, leaders are stronger than most usual units and all units get AMLA (after maximum level advancement) after reaching their maximum level (that is also increased by a load of additional level 4 units).''

=== The Library of Kratemaqht ===

''An ancient story from the old continent.''

'''Author:''' Rich Marinaccio (cephalo)

'''Status:''' Complete

'''Length:''' 17 scenarios

'''Difficulty:''' Unbalanced (some scenarios are Easy - some rather Hard)

'''Style:''' Skirmish, RPG

'''Faction/Era:''' Loyalists and custom units.

'''[http://units.wesnoth.org/1.10/Library_Of_Kratemaqht/en_US/The_Library_Of_Kratemaqht.html Custom units]'''

'''Version:''' 1.0.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37798

'''Notes:''' (Adamant14) This campaign has a thought-out story, shows a great love for detail;
It includes a great custom Dragon, some brilliant custom images (fire, burning houses, burning forest) that makes the scenery / maps look very nice.

=== Panther Lord ===

''The Imperialists ambitions of pushing into the Sea States have been repeatedly thwarted and now they turn their attentions elsewhere. You are an outcast Darklander now living as a mercenary in the Sea States and the rumors you hear indicate that they will be coming to your people. Though an outcast you do not wish to see them subjugated. The spirit whose friendship caused you to be an outcast has a plan that might allow you to save them.''

'''Author:''' Velensk

'''Maintainer:''' Lavender

'''Status:''' Finished

'''Length:''' 14 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Era of Four Moons, Darklanders (+ a wide variety of mercenaries)

'''Version:''' 1.0.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34318

=== Return of the Monster ===

''It was time for Amailoss, born from the naga queen's last egg, to leave home. Time for him to grow into a leader in his own right, and eventually become the guardian and leader of another naga city. But along the way, he became friends with an unusual mud-crawler, they met a strange young monster, discovered that a spirit had escaped from an orc prison, and the mystery of that spirit became a grave challenge for Amailoss and the many races in the region....''

''A naga campaign, involving elves, orcs, saurians, turtle-like races, and some monsters.''

'''Author:''' SkyOne

'''Status:''' Complete

'''Length:''' 16 playable, 2 dialog scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon

'''Faction/Era:''' Default with additions. You play a custom naga faction and carapaces (a turtle-like race).

'''[http://units.wesnoth.org/1.10/Return_of_the_Monster/en_US/Return_of_the_Monster.html Custom units]'''

'''Version:''' 0.7.1

'''Required Wesnoth version:''' 1.10.x

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36438

=== Return to Noelren ===

'''Status:''' Complete.

'''Length:''' 26 scenarios + 7 cut scenes

'''Author:''' Pyrophorus

'''Description:''' ''A story in the first Dark Age of Wesnoth. See how various heroes stick together to shun the threat of black magics, restore the secret kingdom of Noelren and install Garard I on the throne of Wesnoth. This campaign features complex scenarios, unusual objectives and units, emphasizing more on story and adventures than hardcore fighting.''

'''Version: ''' 0.7

'''Requirements:''' BfW 1.10 (not tested on 1.11)

'''Difficulty:''' Easy, unbalanced

'''Style:''' Skirmish, RPG, Large Battle, Simulation

'''Faction/Era:''' Default + custom units

'''[http://units.wesnoth.org/1.10/ReturnToNoelren/en_US/ReturnToNoelren.html Custom Units]'''

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34685#p501026

=== Return to Ruins ===

''The humble farmers of Vertegris are summoned by Erik the General of Weldyn to put an end to an orcish raiding party. If they knew what would befall their former home... They never would have left. This is a relatively short campaign with 8 scenarios, It is still undergoing changes.''

'''Author:''' Ulfsark (Jeff Stevens)

'''Status:''' Complete

'''Length:''' 7 scenarios + 1 dialogue-only

'''Difficulty:''' Easy - Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default,(Loyalists, Outlaws)

'''Version:''' 0.3.0

'''Required Wesnoth version:''' 1.10.x

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37790&sid=9059f18497cda1219f42a626544d0ffd&p=540646#p540646

'''Note:''' (Adamant14) You play a short campaign with just a few units. Playable in a few hours, nevertheless it is fun to play.

=== The Roar of the Woses ===

''When the construction of a dam threatens the existence of her home, Kylix is forced on a journey to stop it.''

'''Author:''' Alarantalara

'''Status:''' Finished

'''Length:''' 9-10 scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default with Additions (primarily Saurians, Nagas, Woses)

'''Version:''' 1.2.7

'''Required Wesnoth version:''' 1.10.x

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=29830

'''Note:''' (author) Potentially unbalanced on Hard difficulty due to experiments with non-standard ways to increase difficulty. This issue does not exist on the lower difficulty levels.

=== Salt Wars ===

''Introductory campaign for the Era of Four Moons.''

''As an officer of one of the Sea States you must defend your organization from aggressive rivals.''

'''Author:''' Velensk

'''Maintainer:''' Lavender

'''Status:''' Complete

'''Length:''' 5 scenarios

'''Difficulty:''' Easy

'''Style:''' Skirmish

'''Faction/Era:''' Era of Four Moons, Sea States

'''Version:''' 0.2.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31498

=== The Sojournings of Grog ===

''Grog (as starred in Under the Burning Suns) goes home.''

'''Author:''' Peter Christopher, Thomas Hockings

'''Maintainer:''' Elvish_Hunter

'''Status:''' Finished

'''Length:''' 18 playable scenarios in 2 parts

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon, Large Battle

'''[http://units.wesnoth.org/1.10/The_Sojournings_of_Grog/en_US/The_Sojournings_of_Grog.html Custom units]'''

'''Faction/Era:''' Default. Most of the time you play trolls and some desert elves accompanying Grog.

'''Version:''' 3.0.1

=== Unlikely Alliance ===

''Play as the members of an alliance between the elves, drakes, and undead after the Fall of Wesnoth.''

'''Author:''' Creativity

'''Status:''' Broken ( Abandoned )

'''Length:''' 2 broken scenarios

'''Difficulty:''' Unbalanced

'''Style:''' -

'''Faction/Era:''' -

'''Version:''' 0.1

'''Forum:''' -

'''Note:''' (Adamant14) Did not work at all. Seems abandoned.

=== Up from Slavery ===

''The Orcei are captives in the imperial city of Lavinium, gladiators performing for the emperor Optus Maximus. All it will take, however, is one orc to lead his people to freedom. The Samnis called Sparxus may be that orc.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 7 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish, Arena (= No recruit, small group gladiator fights)

'''Faction/Era:''' Imperial Era, Orcei Gladiatores

'''Version:''' 0.6.0

[Maintainer's Note: At some point, I am intending to completely re-work this campaign to be a multi-player campaign, with one side led by Sparxus and one by Gravirivus. If anyone would like to take this on or has ideas for how to accomplish this, let us know.]

=== Way of Dragon ===

''The story of what might happen if a person against his will transform into a dragon...''

'''Author:''' DrakeDragon

'''Status:''' Complete but Broken (bug in scenario 07 stops the game)

'''Length:''' 7 playable scenarios + 1 dialogue-only

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish/RPG

'''Faction/Era:''' Default Loyalists

'''Version:''' 1

'''Forum:''' No thread in the Wesnoth forums but a there is a forum in Russian language [http://uporoom.ru/index.php/topic,179.0.html Russian Forum]

'''Note:''' (Adamant14) Short campaign with just a few units, promising but buggy, unbalanced and broken. Most of the text in Cyrillic letters. In some scenarios the objectives too.

== Battle for Wesnoth 1.11.x - development ==

''Campaigns available in the 1.11.x development version.''

''Please note: Battle for Wesnoth 1.11.0 features a bug that messes up the selection of difficulty levels.''

=== Antar, Son of Rheor ===

''This is the story about a young Lord and his first mission; sent by his father the young Lord Antar has to relieve his neighbours; he has to convince the Elves and Dwarves to ally him; he has to fight against hordes of Orcs and Endless Undead; and finally he has to defeat Mal Kazur, the mastermind who is behind all the evil.''

'''Author:''' Adamant14

'''Status:''' WIP

'''Length:''' 8 playable scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Loyalists (feat. fencer as main hero + various allies)

'''Version:''' 0.9.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36075

=== Legend of the Invincibles ===

'''''Part I: Shrouded in Darkness''' (5 chapters, 90 scenarios) - A pair of heroes, after stopping an orcish thread, are outcast into caves, where they have no other choice than to become liches in order to survive. They preserved their human appearance and moral principles, and fight in various skirmishes against evil (although using evil methods sometimes), until the Fall, when they are buried alive under the ashes of the third sun.''

'''''Part II: Into the Light''' (2 chapters, 30 scenarios at the moment) - Long after the Fall, the lich heroes awaken. Searching for more power, they manage to resurrect themselves as living beings, but this time more powerful and cleaned from the evil within them. But the evil from inside them continued to exist, and started a skirmish to conquest the world.''

'''Author:''' Dugi

'''Status:''' WiP (but Part I might be considered complete)

'''Length:''' 119 (+6 talk-only) scenarios at the moment

'''Difficulty:''' Normal

'''Style:''' mostly Skirmish and Dungeon (all other styles are present as well, but less frequently)

'''Faction/Era:''' Elves, Loyalists, Undead; but they advance past their usual maximum level

'''Version:''' 2.3.0

''Note: The most unique feature of this campaign is its RPG-like unit development system, enemies drop items units can use, leaders are stronger than most usual units and all units get AMLA (after maximum level advancement) after reaching their maximum level (that is also increased by a load of additional level 4 units).''

[[Category:Campaigns|*]]

Guide to UMC Content

2012-11-06T15:56:34Z

Alarantalara: /* Battle for Wesnoth 1.10.x - stable */ Add Roar of the Woses

''This is a guide to the current (1.10.x/1.11.x) UMC campaigns for players. It aims to provide all the information not only about the story, but also about completion, difficulty and playing style of the campaign. See http://forums.wesnoth.org/viewtopic.php?f=8&t=37476 for further information, for currently non-available UMC-content please refer to http://forums.wesnoth.org/viewtopic.php?f=8&t=36733. Please edit, it is a wiki.''

=== Blueprint ===

'''Status:'''
* Broken = Does not work at all
* Incomplete = Partially written, no progress
* WIP = Partially written, progress
* Complete = Completely written, but buggy as well as potential balance issues.
* Finished = Completely written, minimal to no bugs, slight balance issues possible.

'''Length:'''

'''Author:'''

'''Maintainer:''' if not maintained by the author anymore.

'''Description:'''

'''Version: '''

'''Requirements:'''

'''Difficulty:'''

Please note: Often campaigns introducing new mechanics are listed as expert level on the add-on server, here difficulty means the raw difficulty after the mechanics are understood.

* Unbalanced = If you can't beat the hard mode, it isn't necessarily unbalanced, but if the difficulty changes erraticly from one scenario to the next and only people using the debug mode have seen the final, then it is.
* Easy
* Normal
* Hard

'''Style:'''

Please note: Many campaigns will feature more than one style. Please list the most significant ones.

* Skirmish = small to medium sized armies, your standard Wesnoth gameplay
* Dungeon = long and narrow tunnels (not every underground scenario is a dungeon, a dungeon isn't necessarily underground)
* RPG = role playing game elements such as talking with non-player-characters, item collection, dependency on a party of very few adventurers without or limited recruits
* Survival = being exposed to changing, spawning enemies while remaining on the same map
* Large Battle = Eastern Flank in Northern Rebirth, Civil War in Son of the Black-Eye
* Simulation = campaigns feat. terrain modification, alternative resources
* Boss battle = a recurring feature of Invasion of the Unknown

'''Faction/Era:'''

* Era for the whole campaign and more specifically the faction or unit composition you field.

'''Custom units:'''

* Link to the unit tree for cases that don't feel sufficiently described by Faction / Era entry.

'''Forum:'''

* Links to the feedback and development threads at forums.wesnoth.org

== Battle for Wesnoth 1.10.x - stable ==

''Campaigns available in the 1.10.x stable version.''

=== Aldur The Great ===

''This is a story about Aldur the Great.''

'''Author:''' pintercsabi

'''Status:''' Complete, but unbalanced

'''Length:''' 5 playable scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default

'''Version:''' 1.2.2

'''Forum:''' -

'''Note:''' (Adamant14) Short unbalanced campaign, maybe abandoned. You fight with Peasants, Ruffians and Woodsman against Orcs

=== Alfhelm the Wise ===

''This is the tale of Alfhelm, called by some the Wise, son of Alfric Conqueror. This is the tale of his victories over his enemies, and his rise to power in the clans of Marauderdom. This is the tale of his journey south and his destruction of the Lavinian Empire. And this is the tale of his demise in the dark forests far to the east of his homeland.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 15 gameplay scenarios

'''Difficulty:''' Moderate

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Marauders.

'''Version:''' 0.6.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=17144

[Maintainers Note: Though this campaign is complete and playable the whole way through, the code is four years old and pretty buggy. If you notice any errors while playing, please let me know and I'll incorporate the fixes into my next revision as soon as possible.]

=== Antar, Son of Rheor ===

''This is the story about a young Lord and his first mission; sent by his father the young Lord Antar has to relieve his neighbours; he has to convince the Elves and Dwarves to ally him; he has to fight against hordes of Orcs and Endless Undead; and finally he has to defeat Mal Kazur, the mastermind who is behind all the evil.''

'''Author:''' Adamant14

'''Status:''' WIP

'''Length:''' 8 playable scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Loyalists (feat. fencer as main hero + various allies)

'''Version:''' 0.8.26a

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36075

=== A Story of the Northlands ===

''A story of life and death in a remote village of the Northlands. Your village has been overrun by an orcish raid. You fight for its freedom while you wait for help to arrive.''

'''Author:''' zepko

'''Status:''' Complete

'''Length:''' 10 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default + additions: you play with a custom faction of outlaws and with a custom party of loyalist knights.

'''[http://units.wesnoth.org/1.10/A_Story_of_the_Northlands/en_US/A_Story_of_the_Northlands.html Custom Units]'''

'''Version:''' 0.2.0

=== A Vision Blinded ===

''Defend the northern forest against what appeared like a routine orcish raid, and unravel the greater conspiracies that lie below its waves.''

'''Author:''' LemonTea

'''Maintainer:''' AxalaraFlame

'''Status:''' Complete

'''Length:''' 13 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves (+ Trolls, Outlaws)

'''[http://units.wesnoth.org/1.10/A_Vision_Blinded/en_US/A_Vision_Blinded.html Custom units]'''

'''Version:''' 0.6.6

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23463&hilit=a+vision+blinded

=== Besieged Druids ===

''A elvish school for druids comes under attack by goblins. It seems more than just a routine raid; is there something more sinister behind this attack? - In Beseiged Druids, you control Eärendil, the surviving teacher at the school, and the many and varied initiates. Not all of these are ordinary students; many have been experimenting with other forms of magic, while others are simply overachievers in some area of study. Unfortunately, they are not especially good at combat, at least initially. Together with a very small contingent of surviving guards, it is up to these students to save the island of Aleron from disaster.''

'''Author:''' Celtic Minstrel

'''Status:''' Complete

'''Length:''' 9 scenarios

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''[http://units.wesnoth.org/1.10/DruidSiege/en_US/celmin-druid-siege.html Custom units]'''

'''Version:''' 1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37342

=== Cities of the Frontier ===

''Settle a new town in the wilds north of the Great River.''

''This campaign makes several changes to the standard Wesnoth game mechanics, and focuses on city-building and gold management.''

'''Author:''' esci

'''Status:''' Complete

'''Length:''' Not fixed, approximately 6-10 seasons of 36 turns each

'''Difficulty:''' Normal

'''Style:''' Simulation, Survival

'''Faction/Era:''' Default, Loyalist

'''[http://units.wesnoth.org/1.10/Cities_of_the_Frontier/en_US/Cities_of_the_Frontier.html Custom units]'''

'''Version:''' 0.5.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36004

=== Count Kromire ===

''You are the blood son of a vampire lord, however when the might of the celestial crusades comes knocking, and your father is slain, you flee your lands. However you intend to return, to restore the lands of Kromire to the Kromires, to avenge your father, and most importantly, to make sure that no celestial ever dares come into your mountains again.''

'''Author:''' Velensk

'''Maintainer:''' currently none

'''Status:''' Complete

'''Length:''' 9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Era of Myths, Vampires

'''Version:''' 1.3.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=21560

=== The Dark Hordes ===

'''Status:''' Incomplete/WIP

'''Length:''' 11/?

'''Author:''' Circon

'''Maintainer:''' Various

'''Description:''' Lead fugitive dark sorcerer Gwiti Ha’atel to mastery of the undead hordes.

'''Version: '''

'''Requirements:'''

'''Difficulty:'''

'''Style:''' Skirmish

'''Faction/Era:''' Default undead

'''[http://units.wesnoth.org/1.10/The_Dark_Hordes/en_US/The_Dark_Hordes_1.html Custom Units]'''

'''Walkthrough:''' [[TheDarkHordes]]

'''Forum:''' [[http://forums.wesnoth.org/viewtopic.php?f=8&t=16576&]]

=== The Earth's Gut ===

''The year is 515YW. You are the young dwarven leader Hamel. Your tribe in the caves of Knalga is under pressure from its enemies, and resources are growing scarce. In order to forge the weapons required to resist your enemies, you must set forth and collect what ores and minerals remain.''

'''Author:''' Anonymissimus

'''Maintainer:''' Anonymissimus

'''Status:''' Incomplete

'''Length:''' 21 scenarios

'''Difficulty:''' Normal

'''Style:''' Dungeon

'''Faction/Era:''' Default, dwarves.

'''[http://units.wesnoth.org/1.10/The_Earths_Gut/en_US/the_earths_gut.html Custom units]'''

'''Version:''' 0.2.11

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=26800

'''Note:''' This campaign is a "Dwarvish dungeon crawler" and is intended to be challenging for experienced players on hard whilst suitably easy on easy.

=== Elvish Dynasty RPG ===

''You are the new ruler of an elvish kingdom! Can you lead your people to glory? This campaign is highly randomized so it will be different every time you play!''

''Sequel to Ooze Mini-Campaign''

'''Author:''' spencelack

'''Status:''' Complete

'''Length:''' 10 years, in each year choice between dialogue and fighting scenario (selected out of a large pool of possible scenarios)

'''Difficulty:''' Normal

'''Style:''' RPG, Skirmish

'''Faction/Era:''' Default, Elves

'''Version:''' 0.9.9b

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=28627

=== The Epic of Vaniyera ===

''The expansionist Lavinian Legion, led by the Imperator himself, has invaded the northern forests of the Sidhe, or Wild Elves. It is up to Leithan the Thunderblade and his advisor Vaniyera to push its armies back where they came from...''

'''Author:''' oreb, turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 6 scenarios

'''Difficulty:''' Hard (Don't be fooled by "novice level" in the campaign description, this one is very hard.)

[Maintainers note: Working on this issue, the next release (due at the end of November, hah!) should bring easy difficulty back to the level of a reasonable introduction to the IE, while the hard difficulty will also become slightly easier. With any luck, this will be the last release before version 1.0 of the campaign].

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Sidhe.

'''Version:''' 0.9.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=19490

=== Fall of Silvium ===

''You are Caius Regilius, Tribune of the province of Silvia, located in the northmost reaches of the Lavinian Empire at the height of its power. But the Empire has overextended itself, The city of Silvium lies seperated from the rest of the Empire by the mountains of Arendia, and is sandwiched between the Marauders and the Sidhe... war is inevitable, and the province of Silvia will almost certainly fall.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 8 scenarios

'''Difficulty:''' Medium

'''Style:''' Skirmish

'''Faction/Era:''' Imperial Era, Lavinian Legion.

'''Version:''' 0.6

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=31&t=24356

[Note: The final level of this campaign is not supposed to be winnable. It's a final blaze of glory and chance to use all your high-powered units, but to 'win' the campaign, you must lose...the ending is similar to a certain mainline campaign, but predates it.]

=== The Fall of Wesnoth ===

''As the beloved human empire of Wesnoth becomes lazy and arrogant in its peaceful state of happiness, Emperor Dantair demands the creation of another sun in a bid to destroy all evil. Or is it all for a different purpose? A man named Alitar sees it that way, and now he must survive the most evil inhabited lands if he is to stop chaos from rising, and Wesnoth from falling... This is the story of The Fall of Wesnoth.''

'''Author:''' Pewskeepski

'''Status:''' 1st part complete, 2nd WIP.

'''Length:''' 10 playable scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Outlaws

'''[http://units.wesnoth.org/1.10/The_Fall_of_Wesnoth/en_US/The_Fall_of_Wesnoth-1.html Custom units]'''

'''Version:''' 1.0.8

=== Fate of a Princess ===

''Part I: Baldres, a notorious robber baron, flees Wesnoth with his followers and sets off into the northlands to evade the king's justice. The baron's deeds and misdeeds are to change the balance of power between orcs and non-orcs throughout the northlands, and will carry consequences long after his eventual death.''

''Part II: The Greenwood elves face a crisis which demands the return of the queen's estranged half-elven half-sister, Baldres' daughter. Two brave young elves must make a perilous journey to find her and bring her back to her former home. If they fail, the whole northlands will be engulfed in war with the resurgent orcs...''

'''Author:''' SkyOne, mich, simonsmith

'''Status:''' Finished

'''Length:''' 26-29 scenarios (some dialogue-only), 2 parts

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon

'''Faction/Era:''' Default with additions. You play two different, unique cross-faction combinations in each part.

'''[http://units.wesnoth.org/1.10/Fate_of_a_Princess/en_US/Fate_of_a_Princess.html Custom units]'''

'''Version:''' 0.9.17

'''Required Wesnoth version:''' 1.9.12 or later

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=26327

=== Forgotten Kingdom ===

''Help Orlog, a troll chieftan, lead his people to safety in the underground and discover an ancient power long forgotten.''

'''Author:''' Limabean

'''Status:''' Incomplete ( but all scenarios playable and balanced )

'''Length:''' 9 playable scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Goblins, Trolls

'''[http://units.wesnoth.org/1.10/Forgotten_Kingdom/en_US/Forgotten_Kingdom.html Custom units]'''

'''Version:''' 0.1.7

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23483

'''Note:''' (Adamant14) This campaign includes a custom Troll line. A good campaign, sad that Limabean seems to abandon it.

=== Forward they Cried ===

''You are the leader of an advanced detachment that has been tasked with capturing a bridgehead while the main army prepares to attack. It should be a simple enough assignment.''

'''Author:''' Glowing Fish

'''Maintainer:''' Lord-Knightmare

'''Status:''' Finished

'''Length:''' 1 scenario ( rather a single scenario than a campaign )

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default Loyalists

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=23656&p=350126&hilit=forward+they+cried#p350126

'''Version:''' 1.0.0

'''Note:''' (Adamant14) Only a single scenario, but a great scenario.
(UnwiseOwl) You wouldn't want to stop thinking for a turn, and it's good for the first few turns, but this one leaves me wanting more.

=== The Founding of Borstep ===

''The chieftain of your tribe has become decadent and weak. Take over, and lead your people to a better home--whether it is already occupied or not. The Northlands in year 9W are a barbaric place, but anyone who stands in your way will learn the power of orcs!''

'''Author:''' Beetlenaut

'''Status:''' Complete

'''Length:''' 10 and 1 dialogue only

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Default, Northerners

'''[http://units.wesnoth.org/1.10/The_Founding_of_Borstep/en_US/The_Founding_of_Borstep.html Custom units]'''

'''Version:''' 1.1.1b

''Note(Kanzil): I find the protagonist hard to sympathise with. Also, most scenarios contain interesting twists. For example, in one, each time you killed a boar it gives you extra health.''

''Note(beetlenaut--author): In most Orcish campaigns the leader is heroic or just wants peace. Krag-Ubor wants plunder and battle like all enemy Orcs in other campaigns. I '''hope''' you don't sympathize too strongly, but I don't think you need to in order to enjoy the game play.''

=== Galuldur's First Journey ===

''While the belligerence of orcs is nothing new, their intensifying attacks on a fledgling colony of elves in Pindir Forest begin to show signs of a deeper malice, forcing Galuldur, the young son of the colony's adventurous founder Galur, to venture out of his forest's friendly trees in search of help. His simple errand quickly turns into a frantic quest to unearth the roots of the mysterious evil threatening his people. As you lead him through unknown lands, Galuldur, forced to match wits with unexpected adversaries at nearly every turn in a desperate attempt to save his world, quickly learns that the world is neither a friendly nor a simple place.''

'''Author:''' mattsc

'''Status:''' Complete

'''Length:''' 8-9 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''[http://units.wesnoth.org/1.10/Galuldur/en_US/Galuldur.html Custom units]'''

'''Version:''' 1.1.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31895

=== Grnk the Mighty ===

''All his life, puny little goblin Grnk the Frail had been dreaming about leaving the orcs and starting a better life. When he finally arrives in the human town of Shmaltupp, he realizes that the world is not as black and white as he had imagined. He also discovers that he is no ordinary goblin. Follow Grnk the Frail on his path to becoming Grnk the Mighty.''

'''Author:''' mattsc

'''Status:''' Part I complete

'''Length:''' 13 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish, RPG

'''Faction/Era:''' Default, changing (no standard army building gameplay)

'''[http://units.wesnoth.org/1.10/Grnk/en_US/Grnk.html Custom units]'''

'''Version:''' 1.0.5

'''Required Wesnoth version:''' 1.9.5 or later

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34970

=== Invasion from the Unknown ===

''Episode I - Seeking the Light: Long after the Fall, the last forest elves are forced to abandon their safe valley, and find themselves resorting to the dark means of necromancy in order to survive the perils and challenges of this new harsh world. May they finally free the Great Continent from its chaos, or perish in the foolish attempt of restoring peace and life to the lands.''

''Episode II - Armageddon: As the shadow of Chaos covers the entire continent, an assorted group of foolish heroes prepares a counter-attack to the Empire, with one unique goal in their minds: defeat the evil Emperor, whoever it is. Lead these courageous living and non-living warriors to victory, and rediscover lost secrets of the history.''

'''Author:''' shadowmaster

'''Maintainer:''' Espreon

'''Status:''' Finished

'''Length:''' 26 scenarios in two episodes

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon, Boss battle

'''Faction/Era:''' Unique. You play Elves and Undead throughout the campaign + in the 2nd part Northerners and Aragwaithi.

'''Version:''' 1.90.6

''Note (taptap): Despite its acknowledged flaws (generic hero, plot holes, deus ex machina moments, gameplay issues in the 2nd part) this is undoubtedly the most iconic campaign in UMC. It single-handedly redefines the elvish history and sketches a cosmology for the ages after the fall. With the Chaos empire and its various allies it introduces an era worth of factions to single-player play. At the same time it features some of the most beautiful maps in Wesnoth and stunning art on par with mainline campaigns.''

=== Langrisser Sample Campaign ===

''The Imperial Knights of the Rayguard Empire have disrupted the peace of the village that was Hein's hometown, seeking only a girl named Liana. Fight to rescue Liana.''

'''Author:''' Morath

'''Status:''' Finished

'''Length:''' 1 playable scenario

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Elves

'''Version:''' 0.1.0.5

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36417&hilit=Langrisser

'''Wikipedia:''' [http://en.wikipedia.org/wiki/Langrisser What is Langrisser]

'''Note:''' (Adamant14) Single scenario, different from usual Wesnoth behaviour.

=== Legend of the Invincibles ===

'''''Part I: Shrouded in Darkness''' (5 chapters, 90 scenarios) - A pair of heroes, after stopping an orcish thread, are outcast into caves, where they have no other choice than to become liches in order to survive. They preserved their human appearance and moral principles, and fight in various skirmishes against evil (although using evil methods sometimes), until the Fall, when they are buried alive under the ashes of the third sun.''

'''''Part II: Into the Light''' (2 chapters, 30 scenarios at the moment) - Long after the Fall, the lich heroes awaken. Searching for more power, they manage to resurrect themselves as living beings, but this time more powerful and cleaned from the evil within them. But the evil from inside them continued to exist, and started a skirmish to conquest the world.''

'''Author:''' Dugi

'''Status:''' WiP (but Part I might be considered complete)

'''Length:''' 119 (+6 talk-only) scenarios at the moment

'''Difficulty:''' Normal

'''Style:''' mostly Skirmish and Dungeon (all other styles are present as well, but less frequently)

'''Faction/Era:''' Elves, Loyalists, Undead; but they advance past their usual maximum level

'''Version:''' 2.3.0

''Note: The most unique feature of this campaign is its RPG-like unit development system, enemies drop items units can use, leaders are stronger than most usual units and all units get AMLA (after maximum level advancement) after reaching their maximum level (that is also increased by a load of additional level 4 units).''

=== The Library of Kratemaqht ===

''An ancient story from the old continent.''

'''Author:''' Rich Marinaccio (cephalo)

'''Status:''' Complete

'''Length:''' 17 scenarios

'''Difficulty:''' Unbalanced (some scenarios are Easy - some rather Hard)

'''Style:''' Skirmish, RPG

'''Faction/Era:''' Loyalists and custom units.

'''[http://units.wesnoth.org/1.10/Library_Of_Kratemaqht/en_US/The_Library_Of_Kratemaqht.html Custom units]'''

'''Version:''' 1.0.0

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37798

'''Notes:''' (Adamant14) This campaign has a thought-out story, shows a great love for detail;
It includes a great custom Dragon, some brilliant custom images (fire, burning houses, burning forest) that makes the scenery / maps look very nice.

=== Panther Lord ===

''The Imperialists ambitions of pushing into the Sea States have been repeatedly thwarted and now they turn their attentions elsewhere. You are an outcast Darklander now living as a mercenary in the Sea States and the rumors you hear indicate that they will be coming to your people. Though an outcast you do not wish to see them subjugated. The spirit whose friendship caused you to be an outcast has a plan that might allow you to save them.''

'''Author:''' Velensk

'''Maintainer:''' Lavender

'''Status:''' Finished

'''Length:''' 14 scenarios

'''Difficulty:''' Hard

'''Style:''' Skirmish

'''Faction/Era:''' Era of Four Moons, Darklanders (+ a wide variety of mercenaries)

'''Version:''' 1.0.2

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34318

=== Return of the Monster ===

''It was time for Amailoss, born from the naga queen's last egg, to leave home. Time for him to grow into a leader in his own right, and eventually become the guardian and leader of another naga city. But along the way, he became friends with an unusual mud-crawler, they met a strange young monster, discovered that a spirit had escaped from an orc prison, and the mystery of that spirit became a grave challenge for Amailoss and the many races in the region....''

''A naga campaign, involving elves, orcs, saurians, turtle-like races, and some monsters.''

'''Author:''' SkyOne

'''Status:''' Complete

'''Length:''' 16 playable, 2 dialog scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon

'''Faction/Era:''' Default with additions. You play a custom naga faction and carapaces (a turtle-like race).

'''[http://units.wesnoth.org/1.10/Return_of_the_Monster/en_US/Return_of_the_Monster.html Custom units]'''

'''Version:''' 0.7.1

'''Required Wesnoth version:''' 1.10.x

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36438

=== Return to Noelren ===

'''Status:''' Complete.

'''Length:''' 26 scenarios + 7 cut scenes

'''Author:''' Pyrophorus

'''Description:''' ''A story in the first Dark Age of Wesnoth. See how various heroes stick together to shun the threat of black magics, restore the secret kingdom of Noelren and install Garard I on the throne of Wesnoth. This campaign features complex scenarios, unusual objectives and units, emphasizing more on story and adventures than hardcore fighting.''

'''Version: ''' 0.7

'''Requirements:''' BfW 1.10 (not tested on 1.11)

'''Difficulty:''' Easy, unbalanced

'''Style:''' Skirmish, RPG, Large Battle, Simulation

'''Faction/Era:''' Default + custom units

'''[http://units.wesnoth.org/1.10/ReturnToNoelren/en_US/ReturnToNoelren.html Custom Units]'''

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=34685#p501026

=== Return to Ruins ===

''The humble farmers of Vertegris are summoned by Erik the General of Weldyn to put an end to an orcish raiding party. If they knew what would befall their former home... They never would have left. This is a relatively short campaign with 8 scenarios, It is still undergoing changes.''

'''Author:''' Ulfsark (Jeff Stevens)

'''Status:''' Complete

'''Length:''' 7 scenarios + 1 dialogue-only

'''Difficulty:''' Easy - Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default,(Loyalists, Outlaws)

'''Version:''' 0.3.0

'''Required Wesnoth version:''' 1.10.x

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=37790&sid=9059f18497cda1219f42a626544d0ffd&p=540646#p540646

'''Note:''' (Adamant14) You play a short campaign with just a few units. Playable in a few hours, nevertheless it is fun to play.

=== The Roar of the Woses ===

''When the construction of a dam threatens the existence of her home, Kylix is forced on a journey to stop it.''

'''Author:''' Alarantalara

'''Status:''' Finished

'''Length:''' 9-10 scenarios + 1 dialogue-only

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default with Additions (primarily Saurians, Naga, Woses)

'''Version:''' 1.2.7

'''Required Wesnoth version:''' 1.10.x

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=29830

'''Note:''' (author) Potentially unbalanced on Hard difficulty due to experiments with non-standard ways to increase difficulty. This issue does not exist on the lower difficulty levels.

=== Salt Wars ===

''Introductory campaign for the Era of Four Moons.''

''As an officer of one of the Sea States you must defend your organization from aggressive rivals.''

'''Author:''' Velensk

'''Maintainer:''' Lavender

'''Status:''' Complete

'''Length:''' 5 scenarios

'''Difficulty:''' Easy

'''Style:''' Skirmish

'''Faction/Era:''' Era of Four Moons, Sea States

'''Version:''' 0.2.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=31498

=== The Sojournings of Grog ===

''Grog (as starred in Under the Burning Suns) goes home.''

'''Author:''' Peter Christopher, Thomas Hockings

'''Maintainer:''' Elvish_Hunter

'''Status:''' Finished

'''Length:''' 18 playable scenarios in 2 parts

'''Difficulty:''' Normal

'''Style:''' Skirmish, Dungeon, Large Battle

'''[http://units.wesnoth.org/1.10/The_Sojournings_of_Grog/en_US/The_Sojournings_of_Grog.html Custom units]'''

'''Faction/Era:''' Default. Most of the time you play trolls and some desert elves accompanying Grog.

'''Version:''' 3.0.1

=== Unlikely Alliance ===

''Play as the members of an alliance between the elves, drakes, and undead after the Fall of Wesnoth.''

'''Author:''' Creativity

'''Status:''' Broken ( Abandoned )

'''Length:''' 2 broken scenarios

'''Difficulty:''' Unbalanced

'''Style:''' -

'''Faction/Era:''' -

'''Version:''' 0.1

'''Forum:''' -

'''Note:''' (Adamant14) Did not work at all. Seems abandoned.

=== Up from Slavery ===

''The Orcei are captives in the imperial city of Lavinium, gladiators performing for the emperor Optus Maximus. All it will take, however, is one orc to lead his people to freedom. The Samnis called Sparxus may be that orc.''

'''Author:''' turin

'''Maintainer:''' UnwiseOwl

'''Status:''' Complete

'''Length:''' 7 scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish, Arena (= No recruit, small group gladiator fights)

'''Faction/Era:''' Imperial Era, Orcei Gladiatores

'''Version:''' 0.6.0

[Maintainer's Note: At some point, I am intending to completely re-work this campaign to be a multi-player campaign, with one side led by Sparxus and one by Gravirivus. If anyone would like to take this on or has ideas for how to accomplish this, let us know.]

=== Way of Dragon ===

''The story of what might happen if a person against his will transform into a dragon...''

'''Author:''' DrakeDragon

'''Status:''' Complete but Broken (bug in scenario 07 stops the game)

'''Length:''' 7 playable scenarios + 1 dialogue-only

'''Difficulty:''' Unbalanced

'''Style:''' Skirmish/RPG

'''Faction/Era:''' Default Loyalists

'''Version:''' 1

'''Forum:''' No thread in the Wesnoth forums but a there is a forum in Russian language [http://uporoom.ru/index.php/topic,179.0.html Russian Forum]

'''Note:''' (Adamant14) Short campaign with just a few units, promising but buggy, unbalanced and broken. Most of the text in Cyrillic letters. In some scenarios the objectives too.

== Battle for Wesnoth 1.11.x - development ==

''Campaigns available in the 1.11.x development version.''

''Please note: Battle for Wesnoth 1.11.0 features a bug that messes up the selection of difficulty levels.''

=== Antar, Son of Rheor ===

''This is the story about a young Lord and his first mission; sent by his father the young Lord Antar has to relieve his neighbours; he has to convince the Elves and Dwarves to ally him; he has to fight against hordes of Orcs and Endless Undead; and finally he has to defeat Mal Kazur, the mastermind who is behind all the evil.''

'''Author:''' Adamant14

'''Status:''' WIP

'''Length:''' 8 playable scenarios

'''Difficulty:''' Normal

'''Style:''' Skirmish

'''Faction/Era:''' Default, Loyalists (feat. fencer as main hero + various allies)

'''Version:''' 0.9.1

'''Forum:''' http://forums.wesnoth.org/viewtopic.php?f=8&t=36075

=== Legend of the Invincibles ===

'''''Part I: Shrouded in Darkness''' (5 chapters, 90 scenarios) - A pair of heroes, after stopping an orcish thread, are outcast into caves, where they have no other choice than to become liches in order to survive. They preserved their human appearance and moral principles, and fight in various skirmishes against evil (although using evil methods sometimes), until the Fall, when they are buried alive under the ashes of the third sun.''

'''''Part II: Into the Light''' (2 chapters, 30 scenarios at the moment) - Long after the Fall, the lich heroes awaken. Searching for more power, they manage to resurrect themselves as living beings, but this time more powerful and cleaned from the evil within them. But the evil from inside them continued to exist, and started a skirmish to conquest the world.''

'''Author:''' Dugi

'''Status:''' WiP (but Part I might be considered complete)

'''Length:''' 119 (+6 talk-only) scenarios at the moment

'''Difficulty:''' Normal

'''Style:''' mostly Skirmish and Dungeon (all other styles are present as well, but less frequently)

'''Faction/Era:''' Elves, Loyalists, Undead; but they advance past their usual maximum level

'''Version:''' 2.3.0

''Note: The most unique feature of this campaign is its RPG-like unit development system, enemies drop items units can use, leaders are stronger than most usual units and all units get AMLA (after maximum level advancement) after reaching their maximum level (that is also increased by a load of additional level 4 units).''

[[Category:Campaigns|*]]

Competitive Gaming

2012-11-05T03:37:38Z

Alarantalara: /* Reocurring Events */ spelling

{{Competitive_Gaming/Translations}}
{| style="float:right;"
|
__TOC__
|}
For those interested in competitive multiplayer games on a more formal and organized level there are some unofficial options that are made available by the Wesnoth Community. Have a look to see if anything fits your shoe, and please help us keep the list updated by adding/removing alternatives.

=== Ladders ===

*[http://wesnoth.gamingladder.info/ Ladder of Wesnoth]
:A 1 vs 1 ladder that uses an [http://en.wikipedia.org/wiki/ELO_rating_system Elo rating] and allows the Default era.

=== Recurring Events ===

None at the moment.

== Cheating ==

=== The Facts ===
The following is true for all games that are played remotely & multiplayer in Wesnoth.

There is currently ''no method'' to ''guarantee'' that a persons doesn't cheat in multiplayer. Some of the more obvious ways to cheat are:
* The editing of save files, granted they're used to load a game.
* Observing the opponent with another instance of Wesnoth running, which of course only matters if you play with fog and also allow observers into the game.
* Creating and using a version of the game that gives ''any'' kind of imaginable noticeable and unnoticeable advantages (e.g. by having an AI assist in your decision making). Since the project is open source this only requires some programming skills and the will, as there is currently no way for a normal and official version of the game to know for sure that it's connected to another official version.

Knowing this makes you able to take it into account when participating in or arranging competitive events. As explained, the system as it is today doesn't offer a 100% certainty that your opponent(s) don't cheat. With that said it's perhaps also true that most players you'll come across don't have the skills to deal with the more advanced ways of cheating, and it might be the case that most cheaters are easily discovered if you watch a replay, know the rules of the game and have a decent idea of what the opponent is up to on the map. After all, the game math is known by all of us and all large deviations will get noticed.

=== Effects on competitive play ===
It's hard to know the exact effects that these kinds of problems have on the competitive gaming. For some players this is more than enough to not engage in competitions. For others it doesn't matter, since they themselves don't cheat and trust that most players don't. There are only two sure and interlinked things we can say about the phenomenon:

* There are a few who cheat.
* A great majority doesn't.

The logic behind those statements lead us to the conclusion that competitive gaming is fully possible in Wesnoth and that it should be considered a serious option by those interested in it. Most games will be legit because of the following reasons:

*Discovery - The most common ways of cheating can be spotted and/or prevented.

*Knowledge - A really small minority of the players have the knowledge ''and'' will to alter the source code in order to cheat.

*Your psychology - If you stumble across a cheater and don't discover her/him, it's not certain that this will really affect you since you're not aware that they cheated.

*Cheaters' psychology - There are very few people that play a game for a long time if they're in the need to always cheat when things get rough. Their victory is almost a paradox - they cheat to win, but know them self that they didn't. Most cheaters quit the game pretty fast because of that and other self-evident psychological facts.

*Effect - Even if you don't discover cheaters the number of times you'll play against them are relatively limited, making their overall impact on your gaming experience small or non-existent in the long run.

=== Resolving Cheating Disputes ===
These are two suggested actions:

1) Submit your replay to the administrator of the competitive framework (ladder or tournament admin, etc).
If an RNG cheat was used, speak with Dave about implementing the anti-cheat code.
2) If your replay is different from your rivals:
One of you altered a replay, and its impossible to know who. As the admins of the competitive framework can not tell for sure who is being honest in this case, they can simply record that the game's winner was disputed by both parties. While this gets you nothing as the victim, anyone cheating in this manner more than once will effectively be "caught". As his or her disputes pile up no one will accept matches with them. If the competitive framework uses some kind of identification the cheater will have to create a new account and spend spend time on getting their rating back.
3) Don't make a mess if you can avoid it: If this has only happened to you once it might be an idea to just ignore it as it may not be worth all the hassle, depending on the specifics in the case.

==== What not to do ====
If you ''know'' your opponent has cheated please make sure that you really have evidence that can prove it 100% before claiming that you ''know'' that he/she did. Keep in mind that real evidence would ''prove'' something. If, for example, both of you have a different version of the save file there is no way to prove which one of you faked his/her, hence, the files are not proof of who the cheater is - they only prove that there is one.

Don't ever give an impression about you ''knowing'' the facts if you can't prove them! It matters a lot what words you use since the allegations are very serious and could destroy a player's reputation which he/she has invested a great amount of time in building within the community.

====Reasonable questioning====
In most competitive frameworks you are probably entitled to question something which you don't fully understand, in order to learn more about it, or something which seems odd and could possibly be a bug and/or a cheat. If you suspect that there is something strange going on then please start by talking with the person you suspect is cheating, if there is one. If the answer doesn't calm you down or you get even more suspicious and still don't understand what's going on, you would be best of contacting the admin/mods for the competitive framework you participate in, if any. If the framework is ''the Ladder of Wesnoth'', then please ''don't'' post in the Wesnoth forum about it.

If you're not participating in a competitive framework and just played a casual game then you could post your questions in the official Wesnoth forum along with as much info as possible and preferably a replay.

Remember that if you go public with your questioning, wherever you do it, you're expected to do it like an adult and in a mature manner. Try to be objective and calm, and present your case and thoughts in a way which doesn't insult or in any other way harm the supposed cheater. If you just had a fight with the person it is always a very bad idea to post right away. It could perhaps also be a good idea to not mention the other player's name until some kind of conclusion had been reached ''if'' keeping that player anonymous would help protect his/her integrity. After all, it can't be very pleasant to be accused of something in the open.

Keep in mind that there is no "Wesnoth Court Room" and that nobody is expected to deal with your problems. Players who choose to discuss the matter with you do it as representatives of them self and ''there are no official rulers'', unless of course, this all happens in a competitive framework which happens to have some. You ask for help to get more clarity into what has happened. Some times the answers will be of help, other times they won't.

====Warning====
If English is not your native tongue and you want to express complicated arguments or be sure to be understood correctly but feel uncomfortable using the English language please ask a friend to help you write it all up in proper English.

Finally we'd like to warn you once more about the act of accusation: For many people it is ''very'' stigmatizing and unsettling to be accused, and would maybe become even more so if the person happened to be innocent. Please think things through thoroughly before presenting an accusation of something. Especially what language you use, what you claim, where and why.

Also understand that players who have been around for longer than yourself will ''usually'' have much greater credibility than you, especially if they've been a part of the Wesnoth community for several years.

With all this said, there ''can'' still arise situations that need the extra attention and that a healthy questioning could help resolve. Questioning something is, if done in a proper way, nothing dangerous or harmful at all. Done wrong however it could start tearing apart the community piece by piece. Keep that in mind of moderators react.

[[Category:Playing Wesnoth]]

LuaWML/Display

2012-11-04T17:36:28Z

Alarantalara: /* wesnoth.get_time_of_day */ Note bug

This page describes the [[LuaWML]] functions and helpers for interfacing with the user.

==== wesnoth.message ====

Displays a string in the chat window and dumps it to the lua/info log domain (''--log-info=scripting/lua'' on the command-line).

wesnoth.message "Hello World!"

The chat line header is "<Lua>" by default, but it can be changed by passing a string before the message.

wesnoth.message("Big Brother", "I'm watching you.") -- will result in "<Big Brother> I'm watching you."

See also [[LuaWML:Events#helper.wml_error|helper.wml_error]] for displaying error messages.

==== wesnoth.clear_messages ====

Removes all messages from the chat window. No argument or returned values.

==== wesnoth.textdomain ====

Creates a function proxy for lazily translating strings from the given domain.

-- #textdomain "my-campaign"
-- the comment above ensures the subsequent strings will be extracted to the proper domain
_ = wesnoth.textdomain "my-campaign"
wesnoth.set_variable("my_unit.description", _ "the unit formerly known as Hero")

The metatable of the function proxy appears as '''"message domain"'''. The metatable of the translatable strings (results of the proxy) appears as '''"translatable string"'''.

The translatable strings can be appended to other strings/numbers with the standard '''..''' operator. Translation can be forced with the standard '''tostring''' operator in order to get a plain string.

wesnoth.message(string.format(tostring(_ "You gain %d gold."), amount))

==== wesnoth.delay ====

Delays the engine like the [delay] tag. one argument: time to delay in milliseconds

wesnoth.delay(500)

==== wesnoth.float_label ====

Pops some text above a map tile.

wesnoth.float_label(unit.x, unit.y, "Ouch")

==== wesnoth.get_time_of_day ====

Returns schedule information. First parameter (optional) is the turn number for which to return the information, if unspecified: the current turn ($turn_number). Second argument is an optional table. If present, first and second fields must be valid on-map coordinates and all current time_areas in the scenario are taken into account (if a time area happens to contain the passed hex). If the table isn't present, the scenario main schedule is returned. The table has an optional third parameter (boolean). If true (default: false), time of day modifying units (such as MoL) are taken into account (if the passed hex happens to be affected). The units placement being considered is always the current one.

wesnoth.get_time_of_day(2, { 37, 3, true })

The function returns a table with these named fields:
* '''id''': string (as in [time])
* '''lawful_bonus''': integer (as in [time])
* '''bonus_modified''': integer (bonus change by units)
* '''image''': string (tod image in sidebar)
* '''name''': translatable string
* '''red, green, blue''': integers (color adjustment for this time)

The optional first parameter does not work if there is no turn limit in 1.11.0 and earlier.

==== wesnoth.select_hex ====

Selects the given location in the game map as if the player would have clicked onto it.
Argument 3: boolean, whether to show the movement range of any unit on that location (def: true)
Argument 4: boolean, whether to fire any select events (def: false)

wesnoth.select_hex(14,6, true, true)

==== wesnoth.scroll_to_tile ====

Scrolls the map to the given location. If true is passed as the third parameter, scrolling is disabled if the tile is hidden under the fog. If true is passed as the fourth parameter {{DevFeature1.11}}, the view instantly warps to the location regardless of the scroll speed setting in Preferences.

local u = wesnoth.get_units({ id = "hero" })[1]
wesnoth.scroll_to_tile(u.x, u.y)

==== wesnoth.lock_view ====

{{DevFeature1.11}} Locks or unlocks gamemap view scrolling for human players. If true is passed as the first parameter, the view is locked; pass false to unlock.

Human players cannot scroll the gamemap view as long as it is locked, but Lua or WML actions such as wesnoth.scroll_to_tile still can; the locked/unlocked state is preserved when saving the current game. This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

wesnoth.lock_view(true)
wesnoth.scroll_to_tile(12, 14, false, true)

==== wesnoth.view_locked ====

{{DevFeature1.11}} Returns a boolean indicating whether gamemap view scrolling is currently locked.

==== wesnoth.play_sound ====

Plays the given sound file once, optionally repeating it one or more more times if an integer value is provided as a second argument (note that the sound is ''repeated'' the number of times specified in the second argument, i.e. a second argument of 4 will cause the sound to be played once and then repeated four more times for a total of 5 plays. See the example below).

wesnoth.play_sound "ambient/birds1.ogg"
wesnoth.play_sound("magic-holy-miss-3.ogg", 4) -- played 1 + 4 = 5 times

==== wesnoth.set_music ====

Sets the given table as an entry into the music list. See [[MusicListWML]] for the recognized attributes.

wesnoth.set_music { name = "traveling_minstrels.ogg" }

Passing no argument forces the engine to take into account all the recent changes to the music list. (Note: this is done automatically when sequences of WML commands end, so it is useful only for long events.)

==== wesnoth.show_dialog ====

Displays a dialog box described by a WML table and returns:
* if the dialog was dismissed by a button click, the integer value associated to the button via the "return_value" keyword.
* if the dialog was closed with the enter key, -1.
* if the dialog was closed with the escape key, -2.

The dialog box is equivalent to the resolution section of a GUI window as described in [[GUIToolkitWML#Window_definition|GUIToolkitWML]] and must therefore contain at least the following children: '''[tooltip]''', '''[helptip]''', and '''[grid]'''. The [grid] must contain nested [row], [column] and [grid] tags which describe the layout of the window. (More information can be found in [[GUILayout]]; suffice to say that the basic structure is grid -> row -> column -> widget, where the widget is considered to be in a cell defined by the row and column of the grid. A list of widgets can be found at [[GUIWidgetInstanceWML]].)

Two optional functions can be passed as second and third arguments; the first one is called once the dialog is created and before it is shown; the second one is called once the dialog is closed. These functions are helpful in setting the initial values of the fields and in recovering the final user values. These functions can call the [[#wesnoth.set_dialog_value]], [[#wesnoth.get_dialog_value]], and [[#wesnoth.set_dialog_callback]] functions for this purpose.

This function should be called in conjunction with [[LuaWML:Misc#wesnoth.synchronize_choice|#wesnoth.synchronize_choice]], in order to ensure that only one client displays the dialog and that the other ones recover the same input values from this single client.

The example below defines a dialog with a list and two buttons on the left, and a big image on the right. The ''preshow'' function fills the list and defines a callback on it. This ''select'' callback changes the displayed image whenever a new list item is selected. The ''postshow'' function recovers the selected item before the dialog is destroyed.

local helper = wesnoth.require "lua/helper.lua"
local T = helper.set_wml_tag_metatable {}
local _ = wesnoth.textdomain "wesnoth"

local dialog = {
T.tooltip { id = "tooltip_large" },
T.helptip { id = "tooltip_large" },
T.grid { T.row {
T.column { T.grid {
T.row { T.column { horizontal_grow = true, T.listbox { id = "the_list",
T.list_definition { T.row { T.column { horizontal_grow = true,
T.toggle_panel { T.grid { T.row {
T.column { horizontal_alignment = "left", T.label { id = "the_label" } },
T.column { T.image { id = "the_icon" } }
} } }
} } }
} } },
T.row { T.column { T.grid { T.row {
T.column { T.button { id = "ok", label = _"OK" } },
T.column { T.button { id = "cancel", label = _"Cancel" } }
} } } }
} },
T.column { T.image { id = "the_image" } }
} }
}

local function preshow()
local t = { "Ancient Lich", "Ancient Wose", "Elvish Avenger" }
local function select()
local i = wesnoth.get_dialog_value "the_list"
local ut = wesnoth.unit_types[t[i]].__cfg
wesnoth.set_dialog_value(string.gsub(ut.profile, "([^/]+)$", "transparent/%1"), "the_image")
end
wesnoth.set_dialog_callback(select, "the_list")
for i,v in ipairs(t) do
local ut = wesnoth.unit_types[v].__cfg
wesnoth.set_dialog_value(ut.name, "the_list", i, "the_label")
wesnoth.set_dialog_value(ut.image, "the_list", i, "the_icon")
end
wesnoth.set_dialog_value(2, "the_list")
select()
end

local li = 0
local function postshow()
li = wesnoth.get_dialog_value "the_list"
end

local r = wesnoth.show_dialog(dialog, preshow, postshow)
wesnoth.message(string.format("Button %d pressed. Item %d selected.", r, li))

==== wesnoth.set_dialog_value ====

Sets the value of a widget on the current dialog. The value is given by the first argument; its semantic depends on the type of widget it is applied to. The last argument is the ''id'' of the widget. If it does not point to a unique widget in the dialog, some discriminating parents should be given on its left, making a path that is read from left to right by the engine. The row of a list is specified by giving the ''id' of the list as a first argument and the 1-based row number as the next argument.

-- sets the value of a widget "bar" in the 7th row of the list "foo"
wesnoth.set_value(_"Hello world", "foo", 7, "bar")

Notes: When the row of a list does not exist, it is created. The value associated to a list is the selected row.

==== wesnoth.get_dialog_value ====

Gets the value of a widget on the current dialog. The arguments described the path for reaching the widget (see [[#wesnoth.set_dialog_value]]).

==== wesnoth.set_dialog_active ====

Enables or disables a widget. The first argument is a boolean specifying whether the widget should be active (true) or inactive (false). The remaining arguments are the path to locate the widget in question (see [[#wesnoth.set_dialog_value]]).

==== wesnoth.set_dialog_callback ====

Sets the first argument as a callback function for the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). This function will be called whenever the user modifies something about the widget, so that the dialog can react to it.

==== wesnoth.set_dialog_canvas ====

Sets the WML passed as the second argument as the canvas content (index given by the first argument) of the widget obtained by following the path of the other arguments (see [[#wesnoth.set_dialog_value]]). The content of the WML table is described at [[GUICanvasWML]].

-- draw two rectangles in the upper-left corner of the window (empty path = window widget)
wesnoth.set_dialog_canvas(2, {
T.rectangle { x = 20, y = 20, w = 20, h = 20, fill_color= "0,0,255,255" },
T.rectangle { x = 30, y = 30, w = 20, h = 20, fill_color = "255,0,0,255" }
})

The meaning of the canvas index depends on the chosen widget. It may be the disabled / enabled states of the widget, or its background / foreground planes, or... For instance, overwriting canvas 1 of the window with an empty canvas causes the window to become transparent.

==== wesnoth.get_displayed_unit ====

Returns a proxy to the unit currently displayed in the side pane of the user interface, if any.

local name = tostring(wesnoth.get_displayed_unit().name)

==== wesnoth.theme_items ====

This field is not a function but an associative table. It links item names to the functions that describe their content. These functions are called whenever the user interface is refreshed. The description of an item is a WML table containing '''[element]''' children. Each subtag shall contain either a '''text''' or an '''image''' field that is displayed to the user. It can also contain a '''tooltip''' field that is displayed to the user when moused over, and a "help" field that points to the help section that is displayed when the user clicks on the theme item.

Note that the ''wesnoth.theme_items'' table is originally empty and using ''pairs'' or ''next'' on it will not return the items from the current theme. Its metatable ensures that the drawing functions of existing items can be recovered though, as long as their name is known. The example below shows how to modify the ''unit_status'' item to display a custom status:

local old_unit_status = wesnoth.theme_items.unit_status
function wesnoth.theme_items.unit_status()
local u = wesnoth.get_displayed_unit()
if not u then return {} end
local s = old_unit_status()
if u.status.entangled then
table.insert(s, { "element", {
image = "entangled.png",
tooltip = _"entangled: This unit is entangled. It cannot move but it can still attack."
} })
end
return s
end

==== helper.get_user_choice ====

Displays a WML message box querying a choice from the user. Attributes and options are taken from given tables (see [[InterfaceActionsWML#.5Bmessage.5D|[message]]]). The index of the selected option is returned.

local result = helper.get_user_choice({ speaker = "narrator" }, { "Choice 1", "Choice 2" })

[[Category: Lua Reference]]

Machine Learning Recruiter

2012-10-29T01:57:55Z

Alarantalara: /* Win percentages for different AI Pairs */ Add version of Ron recruiter

This page documents the new machine learning recruiter submitted as a patch for Wesnoth 1.11.0. We describe how to run it, discuss experiments showing that the ML Recruiter achieves dramatically better performance than the RCA AI recruiter, describe known issues and suggest a development road map.

Note that the ML Recruiter is a work in progress. We welcome feedback on it. Please discuss it on the thread "Machine Learning Recruiter" at http://forums.wesnoth.org/viewtopic.php?f=10&t=36642.

=Why include ML Recruiter in Wesnoth?=

The ML Recruiter makes use of a small subset of the [http://waffles.sourceforge.net/ Waffles] Machine Learning toolkit adding 13 pairs of .cpp/.h files to Wesnoth. In addition, the neural nets used by ML Recruiter are serialized as .json files, which is a format Wesnoth has not yet contained. So why is this patch worthwhile?
==Why the ML Recruiter will be great for Wesnoth==
# Performance is great. ML Recruiter defeats RCA AI 66-73% of the time. We suspect that this would also translate into better performance against human opponents because it also performs better against the "ron" recruiter included in [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976 AI-Demos], which is a more challenging opponent.
# This superior performance is achieved with comparable "fun factor"
#* Variety of units recruited by recommended ML Recruiter is comparable to or better than RCA AI
# Don't need to eliminate RCA AI recruiter. Campaign designers can choose to use one or the other
# ML Recruiter should be easier to customize than RCA AI because
#* All core logic is in Lua, which is easier to modify than existing C++
#* Performance "out of the box" on known units likely to be strong
#* When new recruitable units are introduced by campaign designers, it can be trained by running c. 600 games in two hours. The new model is included as a .json file with the campaign data
#* Plug and play architecture of machine learning "features" easily allows minor modifications to mainline recruiter or to campaign-specific recruiters
# Easy way to adjust campaign difficulty: Adjusting ML AI for more/less randomness makes is easier/harder to defeat
# Inclusion of ML Recruiter could lead to greater publicity and more contributors to Wesnoth
## SeattleDad plans to submit this work as a scientific paper to a conference such as [http://eldar.mathstat.uoguelph.ca/dashlock/CIG2013/ Computational Intelligence in Games]
## Others might later build on this work by, for instance, trying ML algorithms other than neural nets, adding new features, further generalizing the algorithm, etc.
## The machine learning infrastructure is not specific to recruiting and could be repurposed for, for instance, attack planning, weapon selection, and making "retreat and heal" vs. "attack" decisions
## All of the above is potentially publishable research, so Wesnoth could attract contributions from computer science graduate students
### Note that, having established the basic framework with this patch, future work on machine learning will be much easier

=Using ML Recruiter=
==Applying the patch==
* Get the latest version of the patch from https://gna.org/patch/?3479
* Get the Wesnoth 1.11.0 source as per http://wesnoth.org
* Apply the patch as follows:
patch -p1 -i [path to patch file]
* Compile Wesnoth using CMake, SCons, or XCode

==Playing against the ML Recruiter==
# From the main menu, choose "Multiplayer"
# Choose "Local Game"
# Pick a map and adjust settings as desired. ML Recruiter has been trained with the default setting for village gold and support, but it should work fine on other settings
## Hit Okay
# For one side, Choose Player/Type-->Computer Player and then either ML AI (Recommended) or ML AI (Less Variety, probably stronger)
## For the opponent, either play against it yourself (pick your name), watch it play the default AI (Computer Player-->RCA AI), or watch it play itself (pick ML AI again)

==Watching the ML Recruiter play a single game in nogui mode==
The following command is convenient for watching the ML Recruiter play a single game in nogui mode, which allows you to quickly and easily see the ML Recruiter's decision-making process. In this example, we would be running the ML AI (Recommended mode) for the Knalgan Alliance, while the default AI would be playing the Rebels. Note that when run this way (with --log-info=ai/testing,ai/ml), a lot of logging messages will be printed to the console which will describe how the ML Recruiter is analyzing its options.
Wesnoth --log-info=ai/testing,ai/ml --nogui --multiplayer --controller 1:ai --controller 2:ai --parm 1:gold:100 --parm 2:gold:100 --parm 1:village_gold:2 --parm 2:village_gold:2 --scenario multiplayer_Weldyn_Channel --parm 1:gold:100 --parm 2:gold:100 --ai-config 1:ai/ais/ml_ai.cfg --ai-config 2:ai/dev/default_ai_with_recruit_log.cfg --side 1:"Knalgan Alliance" --side 2:Rebels

==Testing the ML Recruiter in batch mode==

Testing in batch mode is easy with the new version of ai_test2.py included in the patch. After applying the ML Recruiter patch, copy utils/ai_test/ai_test2.cfg to the directory in which you want to run the experiment. Then edit the first line of the .cfg file, "path_to_wesnoth_binary" to point to your Wesnoth executable. Then adjust faction1 and faction2 to point to the factions you want to experiment with and point ai_config1 at the ML configuration file you want to try out. Finally, to make everything easier, add the following to your path:
[Wesnoth_Install]/utils/ai_test/
Now you can test Wesnoth in batch as follows:
ai_test2.py ai_test2.cfg

=Experimental Results=

==Win percentages for different AI Pairs==
{| border="1" cellpadding="20" cellspacing="0"
!AI1
!AI2
!Games
!Win % for AI1
!Comment
|-
|ML Recruiter 0.3 (Less Variety)
|RCA AI
|1179
|69.3%
|"Less variety/probably stronger version". Wins 73.4% of the time on the maps version 0.2 was trained on
|-
|ML Recruiter 0.3 (Recommended)
|RCA AI
|2363
|66.6%
|"Recommended version". Same version as above, but has more randomness in its choice of units. See [http://wiki.wesnoth.org/Machine_Learning_Recruiter#The_Weighted_Random_.28Recommended.29_Recruiter documentation on weighted random recruiter]
|-
|ML Recruiter 0.3
|ML Recruiter 0.2
|1937
|58.0%
|We've made a lot of progress since version 0.2
|-
|ML Recruiter 0.3
|Ron Recruiter 0.11.4
|1186
|54.1%
|Ron Recruit is the recruiter build into [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976&start=405 AI Demos]
|-
|ML Recruiter 0.3 (Recommended)
|ML Recruiter 0.3 (Less variety)
|1186
|49.6%
|Difference is not statistically significant, so we pick the variant with more variety as the "Recommended" version. Note, though, that the "Less variety" version does a bit better against the RCA AI as you can see above.
|-
|RCA AI
|RCA AI
|
|50%
|Any AI against itself will win 50% of the time
|-
|RCA AI
|Random
|3,000
|52.7%
|Interesting result. You would expect a completely random choice to get beat by a wider margin
|}

==Faction vs. faction win % for ML Recruiter 0.3 vs. RCA AI==

These results are for the "Recommended" version

<code>
all/data/138 $ analyze_log.py *.log

Overall Stats
AI Wins Win %
default_ai_with_recruit_log 789 33.4%
ml_ai 1574 66.6%
Totals: 2363

Wins Loss Win %
Drakes vs Undead 33 39 45.8%
Drakes vs Northerners 20 39 33.9%
Drakes vs Loyalists 66 11 85.7%
Drakes vs Knalgan Alliance 38 40 48.7%
Drakes vs Drakes 52 19 73.2%
Drakes vs Rebels 46 2 95.8%
Total Drakes 255 150 63.0%

Knalgan Alliance vs Undead 48 19 71.6%
Knalgan Alliance vs Northerners 23 48 32.4%
Knalgan Alliance vs Loyalists 40 14 74.1%
Knalgan Alliance vs Knalgan Alliance 36 23 61.0%
Knalgan Alliance vs Drakes 34 26 56.7%
Knalgan Alliance vs Rebels 46 21 68.7%
Total Knalgan Alliance 227 151 60.1%

Loyalists vs Undead 32 41 43.8%
Loyalists vs Northerners 17 48 26.2%
Loyalists vs Loyalists 58 5 92.1%
Loyalists vs Knalgan Alliance 53 19 73.6%
Loyalists vs Drakes 52 10 83.9%
Loyalists vs Rebels 30 29 50.8%
Total Loyalists 242 152 61.4%

Northerners vs Undead 59 6 90.8%
Northerners vs Northerners 49 21 70.0%
Northerners vs Loyalists 51 9 85.0%
Northerners vs Knalgan Alliance 60 7 89.6%
Northerners vs Drakes 56 14 80.0%
Northerners vs Rebels 55 5 91.7%
Total Northerners 330 62 84.2%

Rebels vs Undead 42 14 75.0%
Rebels vs Rebels 51 15 77.3%
Rebels vs Loyalists 71 8 89.9%
Rebels vs Knalgan Alliance 50 15 76.9%
Rebels vs Drakes 44 22 66.7%
Rebels vs Northerners 21 40 34.4%
Total Rebels 279 114 71.0%

Undead vs Undead 41 37 52.6%
Undead vs Northerners 25 55 31.2%
Undead vs Loyalists 51 18 73.9%
Undead vs Knalgan Alliance 57 6 90.5%
Undead vs Drakes 41 9 82.0%
Undead vs Rebels 26 35 42.6%
Total Undead 241 160 60.1%

</code>

==Units recruited by Recommended ML Recruiter==

Results are for Recommended AI vs. RCA AI for ML Recruiter 0.3

<code>
Grand Totals
Drakes Recruitment Count %
Drake Burner 2925 28.3%
Drake Clasher 909 8.8%
Drake Fighter 2159 20.9%
Drake Glider 1156 11.2%
Saurian Augur 2197 21.3%
Saurian Skirmisher 985 9.5%
Total: 10331

Knalgan Alliance Recruitment Count %
Dwarvish Fighter 1535 14.4%
Dwarvish Guardsman 543 5.1%
Dwarvish Thunderer 4171 39.0%
Dwarvish Ulfserker 767 7.2%
Footpad 1573 14.7%
Gryphon Rider 847 7.9%
Poacher 677 6.3%
Thief 576 5.4%
Total: 10689

Loyalists Recruitment Count %
Bowman 1799 15.6%
Cavalryman 551 4.8%
Fencer 345 3.0%
Heavy Infantryman 1109 9.6%
Horseman 930 8.0%
Mage 934 8.1%
Merman Fighter 852 7.4%
Spearman 5040 43.6%
Total: 11560

Northerners Recruitment Count %
Goblin Spearman 181 1.4%
Naga Fighter 504 3.9%
Orcish Archer 2480 19.1%
Orcish Assassin 1842 14.2%
Orcish Grunt 2524 19.5%
Troll Whelp 4833 37.3%
Wolf Rider 608 4.7%
Total: 12972

Rebels Recruitment Count %
Elvish Archer 1833 17.6%
Elvish Fighter 3213 30.8%
Elvish Scout 1086 10.4%
Elvish Shaman 222 2.1%
Mage 435 4.2%
Merman Hunter 768 7.4%
Wose 2865 27.5%
Total: 10422

Undead Recruitment Count %
Dark Adept 2460 20.7%
Ghost 827 7.0%
Ghoul 1474 12.4%
Skeleton 2386 20.1%
Skeleton Archer 3772 31.7%
Vampire Bat 668 5.6%
Walking Corpse 308 2.6%
Total: 11895
</code>

==Units recruited by Recommended ML Recruiter vs Undead==
As a breakdown of the above, it's interesting to look at the different unit blends that ML Recruiter 0.3 selects vs. the Undead as opposed to the overall totals shown above. MLR's RCA AI opponent recruits a unit blend which consists of just the following four units:

RCA AI Recruitment for Undead:
<code>
Undead Recruitment Count %
Dark Adept 3163 28.4%
Ghost 2451 22.0%
Skeleton 3574 32.1%
Skeleton Archer 1941 17.4%
Total: 11129
</code>
ML Recruiter 0.3 units recruited against the RCA AI Undead. Notice the large increase in the number of units with impact and fire attacks, which would be effective against Skeletons and the decrease in Orcish Assassins and Ghouls, which are ineffective against every Undead unit except Dark Adepts.

<code>
Results for enemy faction:Undead
Drakes Recruitment Count %
Drake Burner 666 37.8%
Drake Clasher 37 2.1%
Drake Fighter 478 27.1%
Drake Glider 339 19.2%
Saurian Augur 91 5.2%
Saurian Skirmisher 152 8.6%
Total: 1763

Knalgan Alliance Recruitment Count %
Dwarvish Fighter 352 17.2%
Dwarvish Guardsman 31 1.5%
Dwarvish Thunderer 259 12.7%
Dwarvish Ulfserker 170 8.3%
Footpad 945 46.2%
Gryphon Rider 153 7.5%
Poacher 66 3.2%
Thief 70 3.4%
Total: 2046

Loyalists Recruitment Count %
Bowman 125 6.7%
Cavalryman 45 2.4%
Fencer 65 3.5%
Heavy Infantryman 533 28.6%
Horseman 20 1.1%
Mage 538 28.8%
Merman Fighter 103 5.5%
Spearman 437 23.4%
Total: 1866

Northerners Recruitment Count %
Goblin Spearman 24 1.1%
Naga Fighter 60 2.8%
Orcish Archer 778 36.9%
Orcish Assassin 43 2.0%
Orcish Grunt 202 9.6%
Troll Whelp 952 45.1%
Wolf Rider 51 2.4%
Total: 2110

Rebels Recruitment Count %
Elvish Archer 92 6.9%
Elvish Fighter 265 19.9%
Elvish Scout 83 6.2%
Elvish Shaman 50 3.8%
Mage 176 13.2%
Merman Hunter 41 3.1%
Wose 625 46.9%
Total: 1332

Undead Recruitment Count %
Dark Adept 548 23.1%
Ghost 56 2.4%
Ghoul 153 6.4%
Skeleton 777 32.7%
Skeleton Archer 669 28.1%
Vampire Bat 80 3.4%
Walking Corpse 94 4.0%
Total: 2377
</code>

=How the ML Recruiter works=

When it's deciding what to recruit, the ML Recruiter works by predicting a "metric" which is a measure of how well a given unit will do in the game in the current situation. A good measure of a unit's usefulness is a tricky question and we will discuss three different metrics below, but let's start with the easiest one, which is the sum of the following quantities for each unit:

# Experience points at the end of the game or when the unit is killed
# Number of villages captured by the unit

Note that this metric is blind to other ways a unit can help you (in particular, it doesn't know about poison, healing, and slowing).

This sum, which we'll call the "metric" is then divided by the unit cost to get metric/cost (think of this as goodness per unit of gold). You can see this in the debugging output that the ML Recruiter prints to stderr when run with the flag --log-info=ai/testing,ai/ml:
unit type metric cost wt cost weighted metric
Elvish Shaman 8.58 15 15.00 0.57
Elvish Fighter 10.42 14 14.00 0.74
Elvish Scout 8.47 18 18.00 0.47
Wose 17.07 20 20.00 0.85
Mage 10.37 20 20.00 0.52
Elvish Archer 8.46 17 17.00 0.50
Merman Hunter 8.55 15 15.00 0.57

This is from the first turn of a game between the Rebels and the Undead. The ML Recruiter is predicting that if it recruits a Wose now, it will end with 17.07 XP + Village Captures. 17.07/20 = 0.85, which is the highest weighted metric at this time, so it picks a Wose as it's top choice.

How does it know to pick a Wose? It looks at the "features" which describe the current situation. Here's another chart from the same game:

unit type metric cost wt cost weighted metric
Elvish Shaman 7.18 15 15.00 0.48
Elvish Fighter 11.82 14 14.00 0.84
Elvish Scout 7.91 18 18.00 0.44
Wose 15.53 20 20.00 0.78
Mage 9.11 20 20.00 0.46
Elvish Archer 9.38 17 17.00 0.55
Merman Hunter 8.36 15 15.00 0.56
Side: 1 Gold: 21 Unit we want: Elvish Fighter
PRERECRUIT:, enemy Dark Adept:1 , enemy Deathblade:1 , enemy Ghost:2 , enemy Skeleton:3 , enemy faction:Undead ,
enemy gold:10 , enemy level3+:0 , enemy total-gold:139 , enemy unit-gold:129 , friendly Elvish Captain:1 ,
friendly Elvish Fighter:1 , friendly Wose:4 , friendly faction:Rebels , friendly gold:21 , friendly level3+:0 ,
friendly total-gold:161 , friendly unit-gold:140 , side:1 , terrain-forest:0.082 , terrain-mountain-hill:0.113 ,
terrain-water-swamp:0.164 , total-gold-ratio:0.537 , turn:4 , village-control-margin:-2 , village-control-ratio:0.417 , village-enemy:7 ,
village-friendly:5 , village-neutral:4 ,

The "features" that it sees are the values following "PRERECRUIT". The ML AI sees that the enemy faction is the Undead and that they have one Deathblade, two ghosts, three Skeletons. The Rebels currently have 4 Wose, 1 Elvish Fighter, and 1 Elvish Captain. It also sees a number of other features like how much gold it and its opponent have, what percentage of each the map is covered by different terrain, and how many friendly, neutral, and enemy villages there are. In this situation, although it still sees that the Wose is likely to score higher on the XP + village capture metric (15.5 vs. 11.8), this isn't enough to overcome the price differential, so it chooses an Elvish Fighter as it's best choice with a weighted metric of 0.84.

Note that these predictions of 15.5 vs. 11.8 are computed by the neural net based on a model built from what the algorithm has seen has happened in similar situations during training.

==Unit Goodness Metrics==
We have experimented with three different unit goodness metrics. All of these metrics are designed to have the property that the higher the value of the metric, the better the unit performed in a a given game. Clearly there is a random element here. In some games when playing against a Skeleton-heavy Undead army, an Elvish Archer, which uses mainly a pierce attack, may get lucky and do better than a Wose, which has an impact attack, but on average the metric should show that the Wose performs better.

The three metrics we've looked at are as follows:

===Experience Point plus Village Capture===
This is the metric used in ML Recruiter 0.2. As noted above, it is the sum of the following quantities:

# Experience points at the end of the game or when the unit is killed
# Number of villages captured by the unit

This metric has the advantage that experience points lead to promotion, which is a very good thing. Also, getting kills should be correlated with how much damage the unit is doing. Adding village captures to experience points is a little flaky, but is intended to give credit to fast units, which are more likely to capture villages.

===Victory===

This metric gives a unit 1.0 if its side wins and 0 if its side loses. The effect is that the neural net's prediction for each unit can be seen as "what is the probability of victory if I recruit this unit in this situation". This is the most natural of all metrics, but experimentally it hasn't performed as well in terms of leading to actual victories as recruiting based on unit-based metrics. Performance has peaked at around a 59% win ratio for a victory metric vs. around 66 - 73% for the XP+VC metric. We think the problem is that the impact of recruiting a single unit of Type A vs. Type B on the victory probability is very small, so the neural net isn't differentiating among the choices enough.

===Gold Yield===

As of ML Recruiter 0.3, this is the new default metric. It is the sum of the following quantities, all of which are intended to quantify a unit's usefulness in terms of how much gold benefit it has yielded for the friendly side plus gold damage done to the enemy side. This metric builds off of a [http://forums.wesnoth.org/viewtopic.php?f=10&t=36642&sid=11062936e4f4c0bab673470b5d211987&start=45#p536132 suggestion] from Sapient.
# Basic Damage Metric: Target unit cost * (Damage inflicted/target max HP). The concept is that you cost your opponent this much gold by destroying this fraction of the unit. Obviously in any given attack, we would calculate this for both the attacker and the defender.
# Village Capture: capturing_unit.variables.ml_gold_yield += wesnoth.game_config.village_income. (Defaults to crediting 2 gold per village capture)
#* The idea, again, is that fast units tend to get more captures than slow units and this gives units credit for being fast.
# Poison: Treated the same as Basic Damage Metric by crediting for the amount of damage done in that turn. On the turn in which the unit is cured, the poisoner is credited with Target Unit Cost * (8/target max HP) to reflect the damage that it would have healed if it hadn't been poisoned (obviously, lessened if it has less than 8 HP of damage)
# Slowing: When a unit is on defense and it slows the attacker, the defender gets no special credit because the attacker just unslows at the end of its turn. When you slow a unit as the attacker, the slowing unit gets credit for the Basic Damage Metric accumulated by the slowed unit until it unslows (the slowed unit would otherwise have done twice as much damage, so you get credit for the damage it didn't do)
# Healing: healing_unit.variables.ml_gold_yield += Healed_unit_cost * (healed amount/healed unit max HP)
#* Directly analogous to the Basic Damage Metric
#* Note that healers also get credit for curing/stopping poison
# Walking Corpse Creation: Credit a unit which gets a kill which creates a unit due to its plague ability with 8 gold (the value of a Walking Corpse). (not implemented)
# Leadership: Credit the leader for the bonus damage inflicted by the unit being led (not implemented)
# Maintenance: Charge units for their share of the maintenance costs, weighted by level. Hence, level 0 units never pay maintenance. Level 2 units pay for twice as much maintenance. (not implemented)

==How MLR makes weighted random choices==
The recommended recruiter is defined in ai/ais/ml_ai.cfg. It is called "Recommended" in the user interface. Although we are currently measuring it as performing roughly the same or slightly worse than the "Less variety/probably stronger" ML AI (ai/ais/ml_ai_less_random.cfg), we recommend it because it allows the player to see a greater variety of opposing units.

The weighted random printout looks like the following:

Turn 13:
unit type metric cost metric/ weighted %
cost m/c of total
Merman Hunter 1.10 15 0.07 0.0000 0.0%
Wose 1.72 20 0.09 0.0000 0.1%
Elvish Shaman 1.66 15 0.11 0.0000 0.4%
Elvish Archer 2.71 17 0.16 0.0000 4.0%
Elvish Fighter 2.54 14 0.18 0.0000 8.5%
Mage 4.18 20 0.21 0.0001 20.1%
Elvish Scout 4.60 18 0.26 0.0003 66.8%
Random Number chosen was 376
Side: 1 Gold: 27 Unit we want: Elvish Scout
PRERECRUIT:, enemy Dark Adept:2 , enemy Revenant:1 , enemy Skeleton:1 , enemy faction:Undead , enemy gold:8 ,
enemy level3+:0 , enemy total-gold:83 , enemy unit-gold:75 , friendly Elder Wose:1 , friendly Elvish Fighter:2 ,
friendly Elvish Ranger:1 , friendly Mage:1 , friendly Wose:3 , friendly faction:Rebels , friendly gold:27 ,
friendly level3+:0 , friendly total-gold:225 , friendly unit-gold:198 , side:1 , terrain-forest:0.082 ,
terrain-mountain-hill:0.113 , terrain-water-swamp:0.164 , total-gold-ratio:0.731 , turn:13 ,
village-control-margin:0 , village-control-ratio:0.5 , village-enemy:8 , village-friendly:8 , village-neutral:0 ,

This situation occurs towards the end of a game that the Rebels are winning. Note that total-gold-ratio (the ratio between the sum of gold + the value of all units on each side) is 0.731, so it's heavily in the Rebels' favor. The ML AI sees an Elvish Scout as being the best choice in this situation with a Mage in second place. The Elvish Scout is probably favored because the game is likely to be won rapidly and only a fast unit will be able to reach the enemy or reach a village fast enough to add to its "experience points + village capture" metric.

The Weighted Random does the following:
# It takes every metric/cost value and raises it to the sixth power. Why? We want to magnify the differences. In this example 0.26/0.21 = 1.23, but (0.26**6)/(0.21**6) = 3.60.
# We then randomly choose a unit with a probability proportional to this weighted value which, in this case, was an Elvish Scout.

The Less Variety/Probably Stronger AI does the same thing, but raises metric/cost to the 24th power instead of the 6th power. This still allows for some randomness, but weights the selection much more strongly towards the more favored units.

=How to train your own ML Recruiter=
utils/ai_test/run_model_and_make_new_model.py is an end-to-end script for running a whole bunch of training games of Wesnoth and then training a new model based on the data output by that run. Documentation on this script can be seen by running
run_model_and_make_new_model.py --help
Note that this script assumes that [http://waffles.sourceforge.net/ the Waffles machine learning toolkit] is installed and that waffles/bin/ is in your path.

=Known issues=
==Bugs==
# Haven't added new Waffles files to Visual C++, so it won't compile under VC++. I need some help with this.
# The default for multiplayer games is that units require only 70% of normal experience to promote, however when a game is run from the command line, it always requires normal 100% of experience to promote. Consequently MLR doesn't see units promote as much as they should in training, which would slightly distort its training data. This is a [https://gna.org/bugs/?19895 limitation of Wesnoth], not MLR.

==Current Limitations==
# Only tested on two-player multiplayer games. Doesn't work when there are more than two leaders on the map.
# Works on all two-player maps except for Hornshark Island, Thousand Stings, Caves of the Basilisk, and Dark Forecast
# As noted above in [http://wiki.wesnoth.org/Machine_Learning_Recruiter#Gold_Yield Gold Yield Metric], we account for all special abilities available in the main-line multiplayer scenarios except for plague, leadership, and unit maintenance costs

=ML Recruiter development roadmap=

* ML Recruiter 0.1: Initial drop
* ML Recruiter 0.1.1: Minor retraining of the model
* ML Recruiter 0.2:
** Logging messages changed from print statements to using lg::log_domain.
** Now have an explicit debug mode by running with --log-debug=ai/ml.
** ML Recruiter can play against itself. Previously could only have ML Recruiter on one side.
** Some work on ML recruiting model (i.e. the core logic). Experimented with different training strategies, but features unchanged from 0.1.
* ML Recruiter 0.3 (10/25/2012) :
** New "gold yield" metric for judging a unit's goodness
** Several new ML features to aid in prediction: alignment, race, time of day, map size, friendly and enemy leader hit point percentage remaining, and nearest enemy unit to friendly leader
** Runs on all 2-player maps except for Hornshark Island, Thousand Stings, Caves of the Basilisk, and Dark Forecast
** Greatly improved ai_test2.py script for running thousands of games to test AI and gather data for the neural net
** New script (run_model_and_make_new_model.py) for running games and building a new neural net based on the data gathered from those games
** Improved performance: Defeats ML Recruiter 0.2 58% of the time
* ML Recruiter 0.3.1 (planned):
** Run on all 2-player maps (except maybe Dark Forecast, which seems to have a custom recruiter)
** Refactor code to separate features from predicted values
** Add 95% confidence intervals to the win ratios in analyze_log.py and add measures of entropy (randomness) to analyze_recruitment.py. Entropy is a good measure of the variety of units that a recruiter is recruiting--for game play, more is better.
* ML Recruiter 0.4 (planned)
** Run on all mainline multiplayer maps
** Experiment with using as the [http://forums.wesnoth.org/viewtopic.php?f=10&t=34976 AI-Demos] recruiter
** Add missing special abilities (plague, leadership, and unit upkeep)

Download

2012-08-27T19:31:04Z

Alarantalara: /* Mac OS X (10.5+) */ Add link to OS X download

{{Download/Translations}}
Welcome to the Battle for Wesnoth downloads page. The BFW project team only officially releases the source code. Binary packages are only provided by community volunteers and hosted here. Torrents are also unofficial.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS.2C_etc..5D.3F|FAQ]].

__NOTOC__
Jump to: [[Download#Stable_.281.10_branch.29|Stable Branch]] | [[Download#Stable_.28older_versions.29|Stable Branch (older versions)]] | [[Download#Development_.281.11_branch.29|Development Branch]]

== Stable (1.10 branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.10 branch is compatible to each other.

Version 1.10.4 is the latest stable version. This version is recommended for most players since the 1.10 online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10.4.tar.bz2/download Current Version] (1.10.4, 326.8 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.3/wesnoth-1.10.3.tar.bz2/download Previous Version] (1.10.3, 326.4 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10.4-win32.exe/download Current Version] (1.10.4, 300.6 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.3/wesnoth-1.10.3-win32.exe/download Previous Version] (1.10.3, 300.3 MB)

==== Mac OS X (10.5+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10/Wesnoth_1.10.dmg/download Current Stable Version] (1.10.4 342.1 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.3/Wesnoth_1.10.3.dmg/download Previous Version] (1.10.3, 327.3 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10.4-1.pnd/download Current Version] (1.10.4-1, 319.7 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.3/wesnoth-1.10.3-1.pnd/download Previous Version] (1.10.3-1, 318.7 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10.4.tar.bz2.md5/download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Stable_Version_1.10.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== Stable (older versions) ==
Several operating systems do not offer a binary of the latest stable release. Here is a list of the latest known (stable version) binaries for various systems. For those older versions there often is no (official) multiplayer or addon server available anymore.

==== AmigaOS4 ====
* [http://www.amigasoft.net/pages/games/download/Wesnoth186.lha.lzh Older Version] (1.8.6, 300MB)

==== (Open)Solaris ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.4/wesnoth-1.4.5/wesnoth-solaris-i386-1.4.5.pkg.bz2/download Older Version] (1.4.5, 145.6 MB), not compatible with 1.6.x

==== OS/2 & eComStation ====
* [http://download.smedley.info/wesnoth-1.4.5-os2-20080828.zip Older Version] (1.4.5, 160 MB), not compatible with 1.6.x

==== RISC OS ====
*[http://www.riscos.info/packages/arm/Games/wesnoth_1.4.5-1.zip Older version] (1.4.5-1, 140MB), not compatible with 1.6.x

==== Syllable ====
* [http://downloads.syllable.org/Syllable/i586/applications/contributed/Battle-for-Wesnoth/Battle-for-Wesnoth-1.2.6.application Older Version] (1.2.6, 60.8 MB), not compatible with 1.6.x

== Development (1.11 branch) ==
Version 1.11.x is the latest development version, boasting updated graphics and new exciting features. However, there may be occasional bugs or performance problems in the development versions since heavy changes are taking place all the time. For balanced and stable gaming, it is recommended you use the latest version of the 1.10.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth. People familiar with SVN and compiling can follow the latest development by checking [[WesnothSVN]].

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.0/wesnoth-1.11.0.tar.bz2/download Current Version] (1.11.0, 334.1 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10,4.tar.bz2/download Previous Version] (1.10.4, 326.8 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.0/wesnoth-1.11.0-win32.exe/download Current Version] (1.11.0, 307.8 MB))
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10.4-win32.exe/download Previous Version] (1.10.4, 300.6 MB))

==== Mac OS X (10.5+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.0/Wesnoth_1.11.0.dmg/download Current Development Version] (1.11.0 350.6MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.3/Wesnoth_1.10.3.dmg/download Previous Version] (1.10.3, 327.3 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.0/wesnoth-1.11.0-1.pnd/download Current Version] (1.11.0-1, 326.2 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10.4-1.pnd/download Previous Version] (1.10.4-1, 319.7 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.0/wesnoth-1.11.0.tar.bz2.md5/download md5sum for current source code]
* [http://wiki.wesnoth.org/Download_Xdeltas#Development_Version_1.11.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]
* [http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/wesnoth_compile_mac_1.9.zip/download MacCompileStuff for 1.9]

== License ==
''Main article: [[Wesnoth:Copyrights]]

This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org Free Software Foundation].
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== UMC Editor ==
This is available with Wesnoth 1.9.x and greater (including Wesnoth 1.10.x).
Details and installation steps can be found at: http://eclipse.wesnoth.org

== See also ==
* [http://changelog.wesnoth.org Changelog]
* [[WesnothBinaries| More binaries]]
* [[WesnothSVN]] - bleeding edge version from SVN

[[Category:Building and Installing]]

Download

2012-08-27T19:29:30Z

Alarantalara: /* Mac OS X (10.5+) */ Add link to 1.10.4 binary

{{Download/Translations}}
Welcome to the Battle for Wesnoth downloads page. The BFW project team only officially releases the source code. Binary packages are only provided by community volunteers and hosted here. Torrents are also unofficial.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS.2C_etc..5D.3F|FAQ]].

__NOTOC__
Jump to: [[Download#Stable_.281.10_branch.29|Stable Branch]] | [[Download#Stable_.28older_versions.29|Stable Branch (older versions)]] | [[Download#Development_.281.11_branch.29|Development Branch]]

== Stable (1.10 branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.10 branch is compatible to each other.

Version 1.10.4 is the latest stable version. This version is recommended for most players since the 1.10 online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10.4.tar.bz2/download Current Version] (1.10.4, 326.8 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.3/wesnoth-1.10.3.tar.bz2/download Previous Version] (1.10.3, 326.4 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10.4-win32.exe/download Current Version] (1.10.4, 300.6 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.3/wesnoth-1.10.3-win32.exe/download Previous Version] (1.10.3, 300.3 MB)

==== Mac OS X (10.5+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10/Wesnoth_1.10.dmg/download Current Stable Version] (1.10.4 342.1 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.3/Wesnoth_1.10.3.dmg/download Previous Version] (1.10.3, 327.3 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10.4-1.pnd/download Current Version] (1.10.4-1, 319.7 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.3/wesnoth-1.10.3-1.pnd/download Previous Version] (1.10.3-1, 318.7 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10.4.tar.bz2.md5/download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Stable_Version_1.10.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== Stable (older versions) ==
Several operating systems do not offer a binary of the latest stable release. Here is a list of the latest known (stable version) binaries for various systems. For those older versions there often is no (official) multiplayer or addon server available anymore.

==== AmigaOS4 ====
* [http://www.amigasoft.net/pages/games/download/Wesnoth186.lha.lzh Older Version] (1.8.6, 300MB)

==== (Open)Solaris ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.4/wesnoth-1.4.5/wesnoth-solaris-i386-1.4.5.pkg.bz2/download Older Version] (1.4.5, 145.6 MB), not compatible with 1.6.x

==== OS/2 & eComStation ====
* [http://download.smedley.info/wesnoth-1.4.5-os2-20080828.zip Older Version] (1.4.5, 160 MB), not compatible with 1.6.x

==== RISC OS ====
*[http://www.riscos.info/packages/arm/Games/wesnoth_1.4.5-1.zip Older version] (1.4.5-1, 140MB), not compatible with 1.6.x

==== Syllable ====
* [http://downloads.syllable.org/Syllable/i586/applications/contributed/Battle-for-Wesnoth/Battle-for-Wesnoth-1.2.6.application Older Version] (1.2.6, 60.8 MB), not compatible with 1.6.x

== Development (1.11 branch) ==
Version 1.11.x is the latest development version, boasting updated graphics and new exciting features. However, there may be occasional bugs or performance problems in the development versions since heavy changes are taking place all the time. For balanced and stable gaming, it is recommended you use the latest version of the 1.10.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth. People familiar with SVN and compiling can follow the latest development by checking [[WesnothSVN]].

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.0/wesnoth-1.11.0.tar.bz2/download Current Version] (1.11.0, 334.1 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10,4.tar.bz2/download Previous Version] (1.10.4, 326.8 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.0/wesnoth-1.11.0-win32.exe/download Current Version] (1.11.0, 307.8 MB))
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10.4-win32.exe/download Previous Version] (1.10.4, 300.6 MB))

==== Mac OS X (10.5+) ====
* Current Development Version (1.11.0) not available yet.
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.3/Wesnoth_1.10.3.dmg/download Previous Version] (1.10.3, 327.3 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.0/wesnoth-1.11.0-1.pnd/download Current Version] (1.11.0-1, 326.2 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.4/wesnoth-1.10.4-1.pnd/download Previous Version] (1.10.4-1, 319.7 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.11.0/wesnoth-1.11.0.tar.bz2.md5/download md5sum for current source code]
* [http://wiki.wesnoth.org/Download_Xdeltas#Development_Version_1.11.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]
* [http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/wesnoth_compile_mac_1.9.zip/download MacCompileStuff for 1.9]

== License ==
''Main article: [[Wesnoth:Copyrights]]

This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org Free Software Foundation].
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== UMC Editor ==
This is available with Wesnoth 1.9.x and greater (including Wesnoth 1.10.x).
Details and installation steps can be found at: http://eclipse.wesnoth.org

== See also ==
* [http://changelog.wesnoth.org Changelog]
* [[WesnothBinaries| More binaries]]
* [[WesnothSVN]] - bleeding edge version from SVN

[[Category:Building and Installing]]

UnitsWML

2012-02-17T00:38:37Z

Alarantalara: /* the [units] tag */

{{WML Tags}}
== the [units] tag ==

This tag is a top level WML tag which is in game.cfg.
It defines the set of all units in Wesnoth.

The following subtags are recognized:
* '''[unit_type]''': describes one unit type. See [[UnitTypeWML]] for syntax.
* '''[trait]''': describes a global trait.
All races with the attribute '''ignore_global_traits=no''' will have this trait.
See '''[trait]''': below for syntax.
* '''[movetype]''': used to make shortcuts to describe units with similar terrain handicaps. Units from the same advancement tree should generally have the same movetype.
** '''name''': an ID for this movetype. Units with the attribute '''movetype=''name''''' will be assigned this movetype.
** ''flies'' either 'true' or 'false'(default). A unit with ''flies=true'' does not have its image's height adjusted for different terrains.
** '''[movement_costs]''': describes how fast the unit moves on different terrains. The attribute '''terrain=''speed''''' means that the unit will need to use ''speed'' move points to move onto the terrain with '''name=''terrain''''' (see [[TerrainWML]]).
** '''[defense]''': describes how likely the unit is to be hit on different terrains. The attribute '''terrain=''defense''''' means that the unit will be hit ''defense'' percent of the time in the terrain with '''name=''terrain'''''. If the defense value is negative, then the unit will be hit as though the value were positive with one difference: the number is also the best defense that the unit may have if there is more than one terrain type for the terrain the unit is on.
** '''[resistance]''': describes how much damage the unit takes from different types of attacks. The attribute '''type=''resistance''''' makes the unit receive '''resistance''' percent of damage, or resist '''100-resistance''' percent of damage from attacks with '''type=''type'''''. So for example, a resistance of fire=110 means, this unit will receive 110% of damage, or have a resistance of -10% as displayed in-game. A value of fire=0 would mean, the unit receives no damage and therefore has a resistance of 100%.
* '''[race]''': is used to make shortcuts to describe units with similar names. Units from the same advancement tree should generally have the same race. Also, units with the same race should generally be recruitable by the same sides/factions.
** '''id''': ID for this race. Units with the attribute '''race=''id''''' will be assigned this race. In older versions of WML, the value of the name key was used as id if the id field was missing, but this is no longer the case.
** '''plural_name''': user-visible name for its people (e.g. "Merfolk" or "Elves"). Currently only used in the in-game help.
** '''male_name''': user-visible name for the race of the male units (e.g. "Merman"). Currently only used in the in-game unit status.
** '''female_name''': user-visible name for the race of the female units (e.g. "Mermaid"). Currently only used in the in-game unit status.
** '''name''': the default value for the three keys above. The 'name' key is the default for 'male_name' and 'female_name'. 'id' and 'plural_name' '''must''' be supplied.
** '''description''': description of this race, used in the race page of the in-game help. Note: currently not used by all mainline races because their descriptions are not ready. But this is already supported by the engine.
** '''male_names''', '''female_names''': lists of names (i.e. non-translatable strings). They are inputted into the Markov name generator to generate random names. ''male_names'' describes units with '''gender=male'''; ''female_names'' describes units with '''gender=female'''.
** '''markov_chain_size''': (default 2) number of letters per "syllable". "Syllables" are groupings of names that the Markov name generator uses to determine names. It does this by running a probability algorithm to guess from the name list which syllables fit well together, which can start or end a name, etc.
** '''num_traits''': is the number of non-repeating traits each unit of this race can be assigned.
** '''ignore_global_traits''': 'yes' or 'no'(default). Determines whether global traits (see [traits] above) are applied.
** '''undead_variation''': sets the default undead variation for members of this race.
** '''[topic]''': describes extra help topics for this race.
** '''[trait]''': describes a trait for this race. :
*** '''id''': unique identifier
*** '''availability''': describes whether a trait is "musthave" for a race or is available to "any" unit in a race, including leaders, or "none" if it is not normally available, but should be kept when advancing to this unit type. (Traits not available to the advanced unit type at all, are permanently lost upon advancement.) The default is for a trait to only be available to nonleaders. Currently "any" should not be used for traits available in multiplayer. It can be used for campaign specific traits. (Note that currently "musthave" is somewhat misused to have what are really abilities (''undead'' and ''mechanical'') default from a unit type's race. Ideally someone will eventually extend ''race'' to allow for default abilities. It might also be possible to unify traits and abilities with keys to indicate how you get them and what happens to them when you advance, while allowing them to come from race, unit type and unit definitions. There are also display issues related to doing this.)
*** '''male_name''': text displayed in the status of unit with the trait if the unit is male.
*** '''female_name''': text displayed in the status of unit with the trait if the unit is female.
*** '''name''': text displayed in the status of unit with the trait if none of the two above is used.
*** '''description''': text displayed for the description of the trait.
*** '''[effect]''': described in [[EffectWML]].

* '''[hide_help]''': allow to hide some units from the help. Mainly useful if you can't change these units (e.g. mainline units) and thus can't add a 'hide_help=yes' key to them. The following keys and theirs contents uses an 'OR' logic between them.
** '''type''': list of unit types.
** '''race''': list of races. Equivalent to all unit types of these races.
** '''type_adv_tree''': list of unit types. Equivalent to all these types and their advancement trees.
** '''all''': 'yes' or 'no'(default). 'yes' is equivalent to all unit types (useful before [not])
** '''[not]''': all the previous keys (except 'all') can also be used in [not] sub-tags. And you can use [not] recursively. For example, if you want to only show the Yeti and the human race except the mage tree, use:
[hide_help]
all=yes
[not]
type=Yeti
race=human
[not]
type_adv_tree=Mage
[/not]
[/not]
[/hide_help]

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

UnitsWML

2012-02-16T23:55:13Z

Alarantalara: /* the [units] tag */ Add comment about negative defense values

{{WML Tags}}
== the [units] tag ==

This tag is a top level WML tag which is in game.cfg.
It defines the set of all units in Wesnoth.

The following subtags are recognized:
* '''[unit_type]''': describes one unit type. See [[UnitTypeWML]] for syntax.
* '''[trait]''': describes a global trait.
All races with the attribute '''ignore_global_traits=no''' will have this trait.
See '''[trait]''': below for syntax.
* '''[movetype]''': used to make shortcuts to describe units with similar terrain handicaps. Units from the same advancement tree should generally have the same movetype.
** '''name''': an ID for this movetype. Units with the attribute '''movetype=''name''''' will be assigned this movetype.
** ''flies'' either 'true' or 'false'(default). A unit with ''flies=true'' does not have its image's height adjusted for different terrains.
** '''[movement_costs]''': describes how fast the unit moves on different terrains. The attribute '''terrain=''speed''''' means that the unit will need to use ''speed'' move points to move onto the terrain with '''name=''terrain''''' (see [[TerrainWML]]).
** '''[defense]''': describes how likely the unit is to be hit on different terrains. The attribute '''terrain=''defense''''' means that the unit will be hit ''defense'' percent of the time in the terrain with '''name=''terrain'''''. If the defense value is negative, then the unit will be hit as the though the value were positive with one difference: the number is also the best defense that the unit may have if there is more than one terrain type for the terrain the unit is on.
** '''[resistance]''': describes how much damage the unit takes from different types of attacks. The attribute '''type=''resistance''''' makes the unit receive '''resistance''' percent of damage, or resist '''100-resistance''' percent of damage from attacks with '''type=''type'''''. So for example, a resistance of fire=110 means, this unit will receive 110% of damage, or have a resistance of -10% as displayed in-game. A value of fire=0 would mean, the unit receives no damage and therefore has a resistance of 100%.
* '''[race]''': is used to make shortcuts to describe units with similar names. Units from the same advancement tree should generally have the same race. Also, units with the same race should generally be recruitable by the same sides/factions.
** '''id''': ID for this race. Units with the attribute '''race=''id''''' will be assigned this race. In older versions of WML, the value of the name key was used as id if the id field was missing, but this is no longer the case.
** '''plural_name''': user-visible name for its people (e.g. "Merfolk" or "Elves"). Currently only used in the in-game help.
** '''male_name''': user-visible name for the race of the male units (e.g. "Merman"). Currently only used in the in-game unit status.
** '''female_name''': user-visible name for the race of the female units (e.g. "Mermaid"). Currently only used in the in-game unit status.
** '''name''': the default value for the three keys above. The 'name' key is the default for 'male_name' and 'female_name'. 'id' and 'plural_name' '''must''' be supplied.
** '''description''': description of this race, used in the race page of the in-game help. Note: currently not used by all mainline races because their descriptions are not ready. But this is already supported by the engine.
** '''male_names''', '''female_names''': lists of names (i.e. non-translatable strings). They are inputted into the Markov name generator to generate random names. ''male_names'' describes units with '''gender=male'''; ''female_names'' describes units with '''gender=female'''.
** '''markov_chain_size''': (default 2) number of letters per "syllable". "Syllables" are groupings of names that the Markov name generator uses to determine names. It does this by running a probability algorithm to guess from the name list which syllables fit well together, which can start or end a name, etc.
** '''num_traits''': is the number of non-repeating traits each unit of this race can be assigned.
** '''ignore_global_traits''': 'yes' or 'no'(default). Determines whether global traits (see [traits] above) are applied.
** '''undead_variation''': sets the default undead variation for members of this race.
** '''[topic]''': describes extra help topics for this race.
** '''[trait]''': describes a trait for this race. :
*** '''id''': unique identifier
*** '''availability''': describes whether a trait is "musthave" for a race or is available to "any" unit in a race, including leaders, or "none" if it is not normally available, but should be kept when advancing to this unit type. (Traits not available to the advanced unit type at all, are permanently lost upon advancement.) The default is for a trait to only be available to nonleaders. Currently "any" should not be used for traits available in multiplayer. It can be used for campaign specific traits. (Note that currently "musthave" is somewhat misused to have what are really abilities (''undead'' and ''mechanical'') default from a unit type's race. Ideally someone will eventually extend ''race'' to allow for default abilities. It might also be possible to unify traits and abilities with keys to indicate how you get them and what happens to them when you advance, while allowing them to come from race, unit type and unit definitions. There are also display issues related to doing this.)
*** '''male_name''': text displayed in the status of unit with the trait if the unit is male.
*** '''female_name''': text displayed in the status of unit with the trait if the unit is female.
*** '''name''': text displayed in the status of unit with the trait if none of the two above is used.
*** '''description''': text displayed for the description of the trait.
*** '''[effect]''': described in [[EffectWML]].

* '''[hide_help]''': allow to hide some units from the help. Mainly useful if you can't change these units (e.g. mainline units) and thus can't add a 'hide_help=yes' key to them. The following keys and theirs contents uses an 'OR' logic between them.
** '''type''': list of unit types.
** '''race''': list of races. Equivalent to all unit types of these races.
** '''type_adv_tree''': list of unit types. Equivalent to all these types and their advancement trees.
** '''all''': 'yes' or 'no'(default). 'yes' is equivalent to all unit types (useful before [not])
** '''[not]''': all the previous keys (except 'all') can also be used in [not] sub-tags. And you can use [not] recursively. For example, if you want to only show the Yeti and the human race except the mage tree, use:
[hide_help]
all=yes
[not]
type=Yeti
race=human
[not]
type_adv_tree=Mage
[/not]
[/not]
[/hide_help]

== See Also ==

* [[UnitTypeWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

TerrainGraphicsWML

2012-01-08T16:36:26Z

Alarantalara: /* The toplevel [terrain_graphics] tag */ Explain that center only works for multihex images

{{WML Tags}}

== The toplevel [terrain_graphics] tag ==

For information about the multi-hex tiling system, see [[MultiHexTutorial]]

In terrain graphics, in Wesnoth 1.8.x all images are assumed to be .png and relative to images/terrain/. For example, writing 'image=grassland' means that the image file is images/terrain/grassland.png. In Wesnoth 1.9.x the .png extension is required. This means that TerrainGraphicsWML is incompatible from 1.8.x to 1.9.x.

The multi-hex tiling system adds a new top-level element to WML, [terrain_graphics].
A building rule is used to specify images to place when terrains are in a certain formation.
When a building rule is applied to a map, it is applied once to each coordinate on the map;
when it is applied to a coordinate then that coordinate is considered the ''base''.
All locations in '''[terrain_graphics]''' are relative to the base.

The following keys/tags are recognized:
* '''[tile]''': whenever a building rule is applied, each [tile] tag corresponds to a tile on the map. The corresponding tile must match each condition contained in [tile] for the [tile] tag to match. All [tile] tags must match in order for a rule to match. If the rule for a [tile] tag is applied, each action within [tile] will be executed on the tile corresponding to that [tile] tag
** '''x''','''y''': standard coordinates - the location of the corresponding tile relative to the base.
** '''pos''': a shortcut to specifying coordinates. Used in combination with ''map''
** '''type''': a comma-separated list of terrain codes (See [[TerrainWML]], data/terrain.cfg). In order for a tile to match this condition, it must be one of the terrains specified. However, if the string is preceded by "!", the terrain must not be listed in order to match. If the string is '*', or if it is empty, any tile matches.
** '''set_flag''': a comma-separated list of strings. Attaches flags from that list to the corresponding tile if the rule matches. The only difference a flag makes is being detected by ''has_flag'' and ''no_flag'' in [tile]. This is determined by the order of the [terrain_graphics] tags; a tag after another one cannot influence it. See also ''has_flag'', ''no_flag''
** '''has_flag''': a comma-separated list of strings. Matches if all flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''no_flag''': a comma-separated list of strings. Matches if none of the flags in that list are attached to the corresponding tile. Flags are attached using the ''set_flag'' key.
** '''set_no_flag''': {{DevFeature1.9}} helper combining ''set_flag'' and ''no_flag''. Same effect as using them with the same flags. Added because it's the most common use; ''set_flag'' or ''no_flag'' can still be used to add flags in one group only.
** '''[image]''': images specified as a subtag to '''[tile]''' sets the images for a single tile.
*** '''layer''': an integer, usually negative. The more negative it is, the earlier it is drawn, and thus the farther "back" it is when compositing the terrain images together.
*** '''name''': the image to apply on this tile if appropriate
*** '''random_start''' (default: yes): {{DevFeature1.9}} Tells engine to start animation at random point instead of at the beginning for every tile
*** '''base''': specifies the point at which the image is considered to be for layering purposes. ''base'' is specified as '''x,y''' where x and y indicate distances in pixels from the top-left corner of the '''image'''. This is translated to a certain pixel on the map, and all images with the ''base'' attribute are drawn from top-to-bottom in terms of these specified pixel positions '''on the map'''.
*** '''[variant]''': an alternate image to use for differing times of day
**** '''tod''': the time of day for which this variant applies. {{DevFeature1.9}} Accepts a comma separated list of times of day.
**** '''name''': the image to apply on this tile if appropriate
**** '''random_start''' (default: yes): {{DevFeature1.9}} Tells engine to start animation at random point instead of at the beginning for every tile
* '''[image]''': image may also be used directly in the rule, to specify multihex images. The following additional attributes are recognized for multihex images (as well as all the ones for images within '''[tile]''').
** '''center''': specifies the point which the image will be centered on. If it is not specified, the image will instead be aligned with the top left corner of the tile.
* '''probability''': the percent probability for each position that if the position matches, then the rule will be applied. Default is 100(%). See [[TerrainGraphicsTutorial#Cumulative_Probabilities|Cumulative_Probabilities]] for mathematical complications.
* '''rotations''': 6 comma(''',''') separated input strings. A rule that contains this key is not actually checked against the terrain; it instead is used as a template to create 6 new rules, each corresponding to a rotated version of the current rule. Whenever a rotated version is applied, instances of @(at-sign)R0, @R1, ... @R6 in attributes in the [terrain_graphics] tag will be adjusted by the corresponding amount and replaced with the letters specified by that numbered rotation in the ''rotations'' list. Each value corresponds to the rotated version that is -Pi/3 (60° clockwise) from the previous version; the first value corresponds to the unrotated version. For example, if '''rotations=n,ne,se,s,sw,nw''' and it is being rotated 120°, then "@R0"->"@R2"->"se", "@R1"->"@R3"->"s", ... "@R6"->"@R1"->"ne". Basically the important thing is that this lets the rule be applied in any of the six hex-directions, allowing you to adjust the name of the image files automatically.
* '''set_flag''','''has_flag''', '''no_flag''': shortcuts to putting these in the [tile] subtags; unbound attributes will apply to all [tile] subtags.
* '''map''': a shortcut for defining [tile] tags with ''type'' conditions. Inputs a multi-line string value visually describing the map. The lines are cut into words of 4 characters, which correspond to [tile] tags. The line types alternate between lines corresponding to relatively even-abciss tiles and lines preceded by two spaces corresponding to relatively odd-abciss tiles. Every two lines represent 1 row on the map.

=== Words ===

A ''word'' is a 4-character shortcut to a [tile] tag. There are different types of words:
* Usually a word is interpreted as being the input to the ''type'' key of the corresponding [tile]. That is, it creates a [tile] with the attribute '''type=''word'''''.
* A word can also be a digit followed by 3 spaces. In this case, it is a shortcut to the [tile] with the attribute '''pos=''word'''''. This is called ''anchoring''.

In 1.3, the format is basically the same but the following changes are made
* A ''word'' no longer needs to be 4 characters but is comma separated and spaces and tabs may be used for padding
* The 2 spaces for odd lines in no longer used, instead a leading comma is used on these lines (before the comma spaces and tabs are allowed for padding)
* A ''word'' may only be a dot a star or an anchor. The terrain letter format was not used and hard to support in the new engine, so that support is dropped.

== Examples ==

To define a north-south 2-tile mountain, the following syntax can be used:

[terrain_graphics]
[tile]
x=0
y=0
type=Mm
set_no_flag="base"
[/tile]
[tile]
x=0
y=1
type=Mm
set_no_flag="base"
[/tile]
[image]
name="mountain-n-s.png"
[/image]
[/terrain_graphics]

This represents a tile 1, and its six adjacent tiles 2, in the map notation.

., ., ., .
, ., 2, ., .
., 2, 2, .
, ., 1, ., .
., 2, 2, .
, ., 2, ., .

== See Also ==
* [[MultiHexTutorial]]
* [[ReferenceWML]]
* Ayin's [http://www.anathas.org/ayin/wesnoth/doc/terrain_graphics_wml detailed Terrain Graphics document]
* [[TerrainGraphicsTutorial]] - First half of Ayin's document, wikified
* [[TerrainGraphicsReference]] - Second (partial) half of Ayin's document, wikified

[[Category: WML Reference]]

Download

2011-11-09T03:04:44Z

Alarantalara: /* Mac OS X (10.4+) */ fix link

{{Download/Translations}}
Welcome to the Battle for Wesnoth downloads page. The BFW project team only officially releases the source code. Binary packages are only provided by community volunteers and hosted here. Torrents are also unofficial.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS.2C_etc..5D.3F|FAQ]].

__NOTOC__
Jump to: [[Download#Stable_.281.8_branch.29|Stable Branch]] | [[Download#Stable_.28older_versions.29|Stable Branch (older versions)]] | [[Download#Development_.281.9_branch.29|Development Branch]]

== Stable (1.8 branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.8 branch is compatible to each other.

Version 1.8.6 is the latest stable version. This version is recommended for most players since the 1.8 online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.8/wesnoth-1.8.6/wesnoth-1.8.6.tar.bz2/download Current Version] (1.8.6, 288.2 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.8/wesnoth-1.8.5/wesnoth-1.8.5.tar.bz2/download Previous Version] (1.8.5, 287.1 MB)
* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.8/wesnoth-1.8.6/wesnoth-1.8.6-win32.exe/download Current Version] (1.8.6, 268.6 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.8/wesnoth-1.8.5/wesnoth-1.8.5-win32.exe/download Previous Version] (1.8.5, 267.5 MB)

==== Mac OS X (10.4+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.8/wesnoth-1.8.6/Wesnoth_1.8.6.dmg/download Current Version] (1.8.6, 292.7MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.8/wesnoth-1.8.5/Wesnoth_1.8.5.dmg/download Previous Version] (1.8.5, 291.2MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.8/wesnoth-1.8.6/wesnoth-1.8.6-1.pnd/download Current Version] (1.8.6-1, 289.3 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.8/wesnoth-1.8.5/wesnoth-1.8.5-1.pnd/download Previous Version] (1.8.5-1, 286.2 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.8/wesnoth-1.8.6/wesnoth-1.8.6.tar.bz2.md5/download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Stable_Version_1.8.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== Stable (older versions) ==
Several operating systems do not offer a binary of the latest stable release. Here is a list of the latest known (stable version) binaries for various systems. For those older versions there often is no (official) multiplayer or addon server available anymore.

==== (Open)Solaris ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.4/wesnoth-1.4.5/wesnoth-solaris-i386-1.4.5.pkg.bz2/download Older Version] (1.4.5, 145.6 MB), not compatible with 1.6.x

==== AmigaOS4 ====
* [http://os4depot.net/index.php?function=showfile&file=game/strategy/wesnoth.lha Older Version] (1.4.7, 140 MB), not compatible with 1.6.x

==== OS/2 & eComStation ====
* [http://download.smedley.info/wesnoth-1.4.5-os2-20080828.zip Older Version] (1.4.5, 160 MB), not compatible with 1.6.x

==== RISC OS ====
*[http://www.riscos.info/packages/arm/Games/wesnoth_1.4.5-1.zip Older version] (1.4.5-1, 140MB), not compatible with 1.6.x

==== Syllable ====
* [http://downloads.syllable.org/Syllable/i586/applications/contributed/Battle-for-Wesnoth/Battle-for-Wesnoth-1.2.6.application Older Version] (1.2.6, 60.8 MB), not compatible with 1.6.x

== Development (1.9 branch) ==
Version 1.9.x is the latest development version, boasting updated graphics and new exciting features. However, there may be occasional bugs or performance problems in the development versions since heavy changes are taking place all the time. For balanced and stable gaming, it is recommended you use the latest version of the 1.8.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth. People familiar with SVN and compiling can follow the latest development by checking [[WesnothSVN]].

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.10/wesnoth-1.9.10.tar.bz2/download Current Version] (1.9.10, 324.7 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.9/wesnoth-1.9.9.tar.bz2/download Previous Version] (1.9.9, 324.8 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.10/wesnoth-1.9.10-win32.exe/download Current Version] (1.9.10, 299.1 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.9/wesnoth-1.9.9-win32.exe/download Previous Version] (1.9.9, 299.0 MB)

==== Mac OS X (10.4+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.10/Wesnoth%201.9.10.dmg/download Current Version (for OSX 10.5+)] (1.9.10, 324.3 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.9/Wesnoth_1.9.9.dmg/download Previous Version (for OSX 10.5+)] (1.9.9, 323.7 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.10/wesnoth-1.9.10-1.pnd/download Current Version] (1.9.10-1, 315.6 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.9/wesnoth-1.9.9-1.pnd/download Previous Version] (1.9.9-1, 315.4 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.10/wesnoth-1.9.10.tar.bz2.md5/download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Development_Version_1.9.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]
* [http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/wesnoth_compile_mac_1.9.zip/download MacCompileStuff for 1.9]

== License ==
''Main article: [[Wesnoth:Copyrights]]

This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org Free Software Foundation].
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== UMC Editor ==
This is available just with Wesnoth 1.9.x.
Details and installation steps can be found at: http://eclipse.wesnoth.org

== See also ==
* [http://changelog.wesnoth.org Changelog]
* [[WesnothBinaries| More binaries]]
* [[WesnothSVN]] - bleeding edge version from SVN

[[Category:Building and Installing]]

ImagePathFunctions

2011-10-22T21:47:59Z

Alarantalara: /* Precedence of Functions */ more functions and insert comment about default team coloring

Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).

== Team-Color Function ==
In Wesnoth version 1.2, the only Image Path Function was '''~TC()''', which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file ''data/team-colors.cfg''

=== Syntax ===
'''~TC(''' ''team number'' ''',''' ''source color palette'' ''')'''
*''team number'' - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).
*''source color palette'' - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.

== Re-Color Function ==
May be used to change some colors in an image.
=== Syntax ===
'''~RC(''' ''source color palette'' '''>''' ''color range ID'' ''')'''
*''source color palette'' - the first parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.
*''color range ID'' - this is the second parameter, signifying the ID of a color range defined in the file ''data/core/team-colors.cfg'' (or it may be a custom ID for a color range defined locally).

=== Example ===
In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:

[message]
speaker=narrator
image=units/elves-wood/captain.png~RC(magenta>green)
message=_ "Now I am on the green team."
[/message]

The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended.

== Palette-switch Function ==
May be used to change colors in an image following the specifications of a source and target (new) palette.
=== Syntax ===
'''~PAL(''' ''source color palette'' '''>''' ''target color palette'' ''')'''
*''source color palette'' - the first parameter is a source color palette, such as magenta. Do not surround this parameter with quotes.
*''target color palette'' - the new palette to take the place of the source colors in the image.

== Flip Function ==
May be used to flip an image horizontally and/or vertically
=== Syntax ===
'''~FL(''' ''optional argument list'' ''')'''
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizantally.
*if the argument list is empty, the image will only be flipped horizontally.

== Greyscale Function ==
May be used to greyscale the image (turn to black and white)
=== Syntax ===
'''~GS( )'''

== Crop Function ==
Extracts a rectangular section of an image file.
=== Syntax ===
'''~CROP(x,y,width,height)'''
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.
* ''width'': width of the selected region. Must be less than or equal to the original image's width.
* ''height'': height of the selected region. Must be less than or equal to the original image's height.

== Blit Function ==
{{DevFeature1.9}}
Blit the parameter image on the main image. Example: peasant.png~BLIT(hat.png,30,10)
=== Syntax ===
'''~BLIT(src,x,y)'''
* ''src'': an image file used as source for the blit, other image path functions can be used there.
* ''x'',''y'': top-left corner coordinates where to blit. Must be greater or equal than zero. If missing assume (0,0).

== Color-shift function ==
Performs simple per-channel color shifts by adding the arguments to the respective color channels.
=== Syntax ===
''Multi-channel:'' '''~CS(r,g,b)'''
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''

The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.

The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.

Any color-shift is performed before changing opacity or desaturating the graphic (see ~O() and ~GS()).

== Image-scaling function ==
Scales a graphic up or down.
=== Syntax ===

'''~SCALE( ''new_width'', ''new_height'' )

The ''new_width'' and ''new_height'' parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr.

== Opacity modifying function ==
Changes an image's opacity at render time.
=== Syntax ===

'''~O( ''factor or percentage%'' )'''

If the argument includes the percentage symbol (''%''), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).

Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.

== Blurring function ==
Blurs a graphic at render time using the same algorithm used for in-game dialogs.
=== Syntax ===

'''~BL( ''radius'' )'''

== Overlay function ==
{{DevFeature1.9}}
Puts a time-of-day overlay on the image.
=== Syntax ===

'''~LIGHTEN()'''

'''~DARKEN()'''

== Background coloring function ==
{{DevFeature1.9}}
Sets the color of all the (semi-)transparent pixels of the image.
=== Syntax ===

'''~BG(r,g,b)'''

== Null function ==
Does nothing.
=== Syntax ===

'''~NOP()'''

== Precedence of Functions ==

All functions are applied in left-to-right order, with the exception of RC(), TC() and PAL() which are applied always before any other functions. Standard team coloring for a unit is applied after all custom RC(), TC() and PAL() functions but before any other functions.
That is, stuff like "units/elves-wood/fighter.png~CROP(0,0,20,20)~CROP(10,10,10,10)" would result in taking a crop of the rectangle x=20;y=20;w=40;h=40 and then taking a crop from ''that'' rectangle as x=10;y=10;w=10;h=10 resulting in the area x=30;y=30;w=10;h=10 from the original graphic.

[[Category:WML Reference]]

BuildingScenariosBalancing

2011-08-22T17:00:28Z

Alarantalara: Modernize terrain code

I'm writing this wiki article to talk about some things that came up as I was balancing a couple of the scenarios in the
South Guard Campaign. I'm going to
respond to something that PDF wrote but that I think is a pretty common idea. I don't mean to single him out:

The PDF wrote:
"Adding a difficulty level does not necessarily requires much balancing;
you can, for example, just add or remove gold."

I'm going to argue that that is fundamentally a flawed way to balance campaigns, and should only be used in conjunction
with other balancing methods.

1. '''A Wesnoth scenario as a tactical problem'''

Each scenario in Wesnoth presents a tactical problem. The problem is generally phrased something like this: "Kill the
enemy leader in so much time
while keeping your leader alive," and its most common variation being: "Move your leader to this hex in said amount time with out letting him die." Of course,
there are subtleties to these tactical problems. Because of the bonus gold at the end you want to finish in less then the stated
time. And since you can recall experienced units for harder scenarios you may not want your vetrans to die, and of course there might be other units that you have or want to
keep alive. There may also be certain
units you must kill in order to succeed. At its core however, each scenario is a relatively simple tactical problem.

2. '''Factors that influence the difficulty of a tactical problem in Wesnoth'''

I am going to briefly list the factors (that I perceive) which affect the difficulty of a tactical problem in Wesnoth.
This list is probably not exhaustive, so if
there's something I've missed, post it and I'll add it to the list. They are in no particular order:

a) Terrain
b) Player's starting gold
c) AI's starting gold
d) Player's recriutment list
e) AI's recriutment list
f) Player's recall list
g) Time limitations
h) Size of player's keep
i) Size of AI's keep
j) AI Parameters (more on this in a minute)
k) Distribution of villages
l) Unexpected reinforcements
m) Time of day

Note that the AI's starting gold is one factor among many.

3. '''Varying the difficulty of a tactical problem presented to the player in a scenario'''

Considering the above factors, it is easy (if time consuming for the designer) to present tactical problems of differing
difficulty in a single scenario. For
most of the above factors, I'll give and example and explain in a sentence how if affects the tactical problem:

''a)'' If the map is predominantly a terrain that favors either the player's forces or the ai's forces, it will have a
huge effect on the difficulty of the battle. For example, a player whose units are broadly loyalists will have a
disasterous time trying to root Elves out of woods. The terrain is, however, generally fixed by the nature of the
scenario (i.e. the designer can't really make a whole new map for each difficulty level). I would submit, however, that
80% of the actual
fighting in a typical scenario occurs in less than 10% of the hexes. It is possible to change only one or two hexes and
have a dramatic effect on the outcome of the battle if you can identify those "chokepoint" hexes.

This can either be done my having three different maps (which I suspect is more work) or by using the WML tag [terrain].
For example, the code:

#ifdef EASY
[terrain]
x=4
y=5
letter=Ce
[/terrain]
#endif

will turn the hex at (4,5) into an encampment.

''b)'' If the player has a lot of gold he can make more tactical mistakes because he can recruit more troops to replace
the ones he's lost. Additionally, quantity has a quality all of its own, so if the player's starting gold is much higher
that the AI's starting gold he can employ a swarm of cheap units. Note that this does not simplify the tactical problem,
it only allows more mistakes to be made.

''c)'' If the AI's starting gold is much higher than the players, the player will be unable to make any tactical
mistakes and still win the scenario. I'll talk more
about this in a moment.

''d)'' If the player can only recruit units that will be effective against the enemy's forces, then the tactical problem
is simplified. If I can only recruit heavy
infantry to face a force of skeleton archers, then I have a less difficult tactical decision to make than if I can
recruit heavy infantry and spearmen. Especially
if I don't know the game well.

''e)'' Restricting the enemy to a certain class of units (i.e. melee-only, ranged-only, impact-attacks-only) can
simplify the tactical problem immensely. Consider an enemy who can only recruit thieves and thugs facing a predominantly
loyalist force, who can recruit Bowmen and Spearmen. Bowmen are very good against thugs and thieves because they have a
strong ranged attack. If the enemy can also recruit poachers and footpads, the tactical problem becomes more difficult
because the player must balance the effectiveness of the Bowmen against the thieves and thugs with their (relative) weakness
against footpads and poachers.

''g)'' The turn limit controls to what extent the player is allowed to waste turns not directly accomplishing his
mission. In the most difficult case scenario, a player must move his leader across the map and only enough turns are
allotted such that if he ever moves in any other direction, time will run out. Elongating the turn limit allows an
inexperienced player to turn-costing make mistakes and still be victorious.

''h&i)'' The size of a player's keep determines at what rate he can recruit troops. The size of the enemy's keep
determines at what rate he can recruit troops. Divide one by the other and you get a relative-recruitment-rate (assuming
both have lots of gold). If the relative recruitment rate favors the player, the tactical problem should be easier
because he can replenish losses more easily than the AI player. If the AI player's keep is larger, then any losses by
the human player will be that much more difficult to replace.

''j)'' The AI parameters are perhaps the best way to alter a tactical problem. [[AiWML]] is a particularly important read
for a scenario designer. I'd draw attention to aggression and [target] in particular. attack_depth is also very nice.
These parameters are especially important for building scenarios with tactical problems that are fundamentally different
from the basic kill-his-leader ones.

''k)'' Using the [terrain] WML tag you can easily alter the distribution of villages in a scenario. Move the
distribution towards the player, and things get easier. Move it towards the enemy, and they get harder.

''l)'' Enemy reinforcements complicate the tactical problem. They are a surprise that you have to figure out how to deal
with after you've deployed your troops. (Which should be possible so the player doesn't just re-play the scenario with
knowledge of the reinforcements.)

''m)'' Time of day is an interesting factor. While you are normally not free to change the cycle, changing when the
cycle starts can be a significant influence, timing when (by ToD) the battle begins. On a large or open battlefield, the
player has more control over that, depending on their skill.

== See Also ==

* [[BuildingScenarios]]
* [[ReferenceWML]]

[[Category:Create]]

BuildingScenariosSimple

2011-08-22T16:53:18Z

Alarantalara: /* First part */ remove 'both' to fix grammar

{{BuildingScenariosNav}}

= Learning things step by step =

Here we will show you a very simple scenario file and explain each line of it.
The file is not fully functional, but it will show the basics needed to describe what a scenario is all about.

'''Before reading this, it might prove useful to read something about the syntax of the Wesnoth Markup Language: [[SyntaxWML]]'''

== First part ==

<blockquote>
<pre>
<nowiki>
[scenario]

id=01_test-1
next_scenario=02_test-more

name=A Simple Test Scenario
map_data="{~add-ons/Test_Campaign/maps/testmap}"
turns=20

{DAWN}
{MORNING}
{AFTERNOON}
{DUSK}
{FIRST_WATCH}
{SECOND_WATCH}

music=wesnoth-1.ogg

[event]
name=prestart
[objectives]
side=1
[objective]
description= _ "Defeat Enemy Leader"
condition=win
[/objective]
[objective]
description= _ "Death of Konrad"
condition=lose
[/objective]
[objective]
description= _ "Turns run out"
condition=lose
[/objective]
[/objectives]
[/event]
</nowiki>
</pre>

''continued below''
     ↓ ↓ ↓
</blockquote>
Every scenario must be enclosed in a tag; the <code>[scenario]</code> tag is used for campaign scenarios. The first set of attributes in the scenario tag describe the very basics of this scenario:

* <code>id</code> (short for ''identifier'') is the computer's name for your scenario and is not displayed during the game. However, it will be used to display game statistics (they will be graphed at http://stats.wesnoth.org in numerical order, so it's also a good idea to give the <code>id</code>'s a number). This name is also referenced in other tags and files, ''e.g.,'' inside a <code>[campaign]</code> tag using the <code>first_scenario</code> attribute (see [[BuildingCampaignsTheCampaignFile]]) or inside a <code>[scenario]</code> tag using the <code>next_scenario</code> attribute (see below).

* The value of the <code>next_scenario</code> attribute is the <code>id</code> (see above) of the scenario that is played after this one is won. Units from this scenario will be available for recall (unless you modify the recall list, but that's stuff for later). If your scenario is not part of a campaign, or if this is the last scenario you should either skip this line or put <code>next_scenario=null</code> inside the file. This will tell the game to display the ''End'' screen when this scenario is won.

* The value of the <code>name</code> attribute is shown on the introduction screen before each scenario is played (this may contain a picture of a map or anything else you fancy. See [[BuildingScenariosIntermediate]] for an explanation on how to do that). It's also used to generate the default names of saved files for the level.

* The next attribute, <code>map_data</code> is a little tricky. Normally, the map data (the text that is used to generate a map) goes directly inside of the quotation marks. However, it is often useful to keep that map data in a separate file, and then include that file (still inside the quotation marks) using a [[PreprocessorRef|preprocesser]] command. The code <code>{~add-ons/Test_Campaign/maps/testmap}</code> does just that, telling the wesnoth engine to look in the file <code>add-ons/Test_Campaign/maps/testmap</code> for the map data. The <code>~</code> symbol tells Wesnoth to search for the map file in the ''userdata'' directory (see [[EditingWesnoth]] and [[PreprocessorRef]] for more information). You can create and edit map files using Wesnoth's built-in [[Editor2|map editor]] (see [[BuildingMaps]] for more information).

* Finally, the last attribute in the top set of keys is <code>turns</code>. This is the number of turns a player is given to finish the scenario (it can be changed during the game, but again, that is stuff for later). If the player fails to finish the scenario in the given time, he has lost (''i.e.,'' the ''defeat'' event is triggered. See [[EventWML]] for more.)

The next section is a group of macros which will be processed by Wesnoth's [[PreprocessorRef|preprocesser]]. Macros are essentially [[WML]] shortcuts. They allow you to define certain pieces of code which can be re-used whenever they are needed. Wesnoth provides you with a whole series of standard, pre-written macros to make life easier, but you yourself can write them too (again, stuff for later).
Let's get back to this example! The macros listed above describe how a day in this scenario will progress. The list of macros above is the normal day used throughout Wesnoth. If you want the entire scenario to take place at night, remove all the macros except for <code>{SECOND_WATCH}</code>. Doing this might, for example, be useful if you've set Konrad to fight the Undead and also want the Undead to have the upper hand throughout the scenario. Remember, though, by setting this to a single time of day rather than the normal diurnal progression shown above, your scenario will effectively take place during one day (or night) rather than across many days as most scenarios do.

The <code>music</code> attribute takes for its value the name of a music file (see [[MusicListWML]] for more). This file must be in the <code>music/</code> directory and must be in [http://en.wikipedia.org/wiki/Ogg Ogg] format.

A tag you'll get to know very well when making scenarios is <code>[event]...[/event]</code>. <code>event</code> tags are used to describe what should be done when various sorts of ''events'' take place. The specific type of event is stated in the <code>event</code>'s <code>name</code> attribute. In this case we're describing the so-called <code>prestart</code> event. This event occurs just ''after'' all the introduction screens for the scenario have been shown but just ''before'' the map itself is displayed. This prestart event is used to set the scenario's objectives, i.e. the contents of the ''Scenario Objectives Dialog'' that will appear once the scenario begins. The purpose of the Scenario Objectives Dialog is to inform the player what must be accomplished to win the scenario and what circumstances bring about defeat. These winning and losing circumstances are defined using the <code>[objectives]</code> tag (N.B. that <code>objectives</code> is plural). Further, each circumstance is defined in its own <code>[objective]</code> (N.B. the singular here) tag with winning circumstances setting <code>condition</code> to <code>win</code>, and with losing circumstances setting it to <code>lose</code>. In the example above, <code>objectives</code> states victory to be "Defeat Enemy Leader". For defeat, however, <code>[objectives]</code> gives the player ''two'' possibilities: either "Death of Konrad" or "Turns run out" (any number of either winning or losing <code>[objective]</code> tags may be given). Accordingly, the Scenario Objectives Dialog will look vaguely like:

<table border=1><tr><td>
'''A Simple Test Scenario'''
 '''Victory:'''
 Defeat Enemy Leader
 '''Defeat:'''
 Death of Konrad
 Turns run out
 
        
        
      [ OK ]
</td></tr></table>

Note that the <code>[objectives]</code> tag doesn't define the circumstances of victory or defeat to the game engine. It merely tells the player what they are. Special victory or defeat conditions will have to be coded into the scenario using various [event]s.

The <code>side</code> attribute in <code>[objectives]</code> indicates that the conditions defined here by the <code>[objective]</code> tags are for the faction or alliance ''side 1'' alone (see below). In a single-player game, side 1 would usually indicate the player's faction or alliance). The underscore ("_") facilitates translation using [[GetText|Gettext]].

== Second part ==
So far so good! The last necessary part describes what the players (both human and
computer) start with, what they can do, and what they can't do. Each of the players is described in a <code>[side]</code> tag with the word ''side'' referring to a player's faction, band, or horde.

<blockquote>
    ↑ ↑ ↑
 ''continued from above''
<pre>
<nowiki>
[side]
side=1
controller=human
team_name=2
user_team_name= _ "Konrad's forces"

type=Commander
id=Konrad
canrecruit=yes

recruit=Elvish Fighter,Elvish Archer,Horseman,Mage,Elvish Shaman

{GOLD 100 50 0}
{INCOME 10 5 0}
[/side]
[/scenario]
</nowiki>
</pre>
</blockquote>

Above you can see a sample <code>[side]</code> for the human player, Konrad. The first group of attributes in the <code>[side]</code> tag pertains to the side generally:
* <code>side</code>: the leader of this side is placed on the tile represented by this digit (see [[BuildingMaps]]). It's a number from 1 to 9.
* <code>controller</code> takes either of two possible values: <code>human</code> or <code>ai</code> (''i.e.,'' ''artificial intelligence'', meaning your computer). If you don't specify this attribute, <code>ai</code> is the default.
* <code>team_name</code> describes which team the side is on. It defaults to the same number as <code>side</code>, but setting it to <code>2</code> allies this side with side 2 (if you haven't changed the <code>team_name</code> of side 2).
* <code>user_team_name</code> is the name displayed when you view the side stats (by pressing <tt>alt+s</tt> during gameplay). The underscore ("_") facilitates translation using [[GetText|Gettext]].

The next group of attributes describe the leader of this side:
* <code>canrecruit</code>: This attribute can be set to <code>yes</code> or <code>no</code> (the boolean equivalents <code>1</code> and <code>0</code> or <code>true</code> and <code>false</code> also work). If this is set to <code>no</code>, the leader won't be able to recruit (not much of a leader then, is he?). Any side without a <code>canrecruit=yes</code> attribute statement automatically loses, so be sure to include this attribute.
* <code>type</code> describes what type of unit the leader will be. The possible values are listed in [http://units.wesnoth.org the Wesnoth unit tables].
* <code>id</code> is the name and identifier of the leader.

In a campaign, all of these "leader-describing" attributes are ignored for human players (except <code>canrecruit</code>), since the leader from the previous scenario is carried over into the current one. The exception to this is, of course, the first scenario, because there is no leader from previous scenarios. However, the <code>type</code> attribute is still necessary to prevent the scenario from crashing, so be sure to include it.

The last attribute, <code>recruit</code>, is a comma-separated list of [http://units.wesnoth.org unit types]. These types will become the side's recruitment list. This too is only necessary in a human player's first scenario, because the recruit list is carried over from one scenario to the next.

Finally, two macros are called. The first, <code>GOLD</code> takes three positive numbers. These indicate the amount of money the player will start with on the <var>easy</var>, <var>normal</var>, and <var>hard</var> difficulty levels, respectively. For a human-controlled side (<code>controller=human</code>), this specifies only the minimum amount of gold. The actual amount the player starts with can be larger if the player has retained gold from previous scenarios. The second macro, <code>INCOME</code>, is analogous to <code>GOLD</code> but for the base income. The defaults values for <code>GOLD</code> and <code>INCOME</code> are 100 gold and 2 base income, respectively.

== Making it all work ==
To make this scenario playable, we need to make a campaign for it (see [[BuildingCampaignsTheCampaignFile]]).
This should '''not''' be stored in the main directory <tt>data/campaigns</tt> but rather inside <tt>userdata/data/campaigns</tt>. This prevents the breaking of mainline campaigns or, even worse, the entire game (see [[BuildingCampaignsDirectoryStructure]]).
Please note that all files (''i.e.'', the campaign file and the scenario files for each level) must be saved with the file extension <tt>.cfg</tt> (''e.g.'', <tt>testcampaign.cfg</tt>).
The following is a short, example campaign file:

[campaign]
name= _ "Test Campaign"
first_scenario=test-1
define=CAMPAIGN_TEST_CAMPAIGN
difficulties=EASY,NORMAL,HARD
difficulty_descriptions= _ "&elvish-fighter.png=Easy;*&elvish-hero.png=Medium;&elvish-champion.png=Hard"
icon=elvish-fighter.png
[/campaign]
#ifdef CAMPAIGN_TEST_CAMPAIGN
{~campaigns/test_campaign/scenarios}
#endif

The <code>[campaign]</code> tag describes the campaign. The first attribute, <code>name</code>, is displayed in the campaign selector box during gameplay. The second, <code>first_scenario</code>, is set to the ID number of the first scenario of the campaign. Subsequent scenarios are referenced by the <code>next_scenario</code> attribute of their immediately preceding scenarios (see above in the first part of this tutorial). Since the first scenario, obviously, doesn't have a predecessor, it is referenced here in the <code>campaign</code> tag. To allow wesnoth to actually find the first scenario we need to include the scenarios directory of our campaign. The last statement of the campaign file does that. The inclusion is best guarded by a preprocessor symbol ([[PreprocessorRef]]) that is unique to this campaign so all the scenarios get only included when this campaign is actually selected by the player. The preprocessor symbol for a campaign is given by the <code>define</code> key.

The attribute <code>difficulties=EASY,NORMAL,HARD</code> tells Wesnoth to use the value <code>EASY</code> if the first difficulty choice is chosen during gameplay, <code>NORMAL</code> if the second is chosen, and <code>HARD</code> if the third is chosen.
The expression <code>#ifdef</code> can be used later to test the value of this attribute (see [[PreprocessorRef]]).
It is recommended that you do not use any names other than <code>EASY</code>, <code>NORMAL</code>, or <code>HARD</code> for your macros because doing so will cause some standard macros, such as <code>{GOLD}</code> and <code>{INCOME}</code>, to not work properly.

Two optional attributes are <code>difficulty_descriptions</code> and <code>icon</code>.
As its value, <code>icon</code> holds the filename of an image to represent this campaign which will be displayed in the campaign list during gameplay.
The <code>difficulty_descriptions</code> attribute must have in its value the same number of (quote-enclosed) list items as <code>difficulties</code> has in its (not quote-enclosed) list items. This list length for both attributes is most commonly three. Also note that the list for <code>difficulty_desciptions</code> is not only quote-enclosed, but its items are separated by semicolons rather than commas. Unsurprising, in our example during gameplay <tt>elvish-fighter.png</tt> would display associated with the easy level, <tt>elvish-hero.png</tt> with normal, and <tt>elvish-champion.png</tt> with hard.

Each list item in <code>difficulty_description</code> begins with an ampersand ("&"). This is followed by the filename of the image, then an equal sign ("="), and finally the text to display (i.e., "Easy". Take note that text displayed for the easy level is not "EASY": the text used is that in <code>difficulty_descriptions</code>, not <code>difficulties</code>. Similary, the normal level's text is "Medium").

Optionally you may place an asterisk ("*") before one of list items of <code>difficulty_desciptions</code> which will cause that corresponding difficulty level to be selected as the default during gameplay. In the example above, the normal level (along with its elvish hero) is selected as the default.

== See Also ==
* [[BuildingMaps]] & [[WesnothMapEditor]]
* [[ScenarioWML]] & [[SyntaxWML]]
* [[BuildingScenarios]]

[[Category:Create]]