The Battle for Wesnoth Wiki - User contributions [en]

FilterWML

2010-03-09T09:36:54Z

Tsr: /* Filtering Terrains */ Added village example

{{WML Tags}}
== Filtering in WML ==

A ''filter'' is a special WML block.
Filters are used to describe a set of units, hexes, or weapons.
Filters are defined as matching something if all the keys in the filter match that thing.
For example, if a unit filter contains two keys,
a unit must match both of the keys in order to match the filter.

== Filtering Units ==

Filters are often used in action tags (see [[EventWML]]).
In this case the phrase "standard unit filter" is used in place of the set of standard keys.
Sometimes a filter is used to find the first unit that matches the filter;
for example, the '''[recall]''' tag recalls that unit.

Standard unit filters are also used in the tags '''[filter]''' and '''[filter_second]'''.
These are subtags of '''[event]''' which describe when the event should trigger.
Most event names (see [[EventWML]]) have units related to them called "primary unit" and "secondary unit".
In order for an event to be triggered, ''primary unit'' must match the filter contained in '''[filter]''',
and ''secondary unit'' must match the filter contained in '''[filter_second]'''.

See [[StandardUnitFilter]] for details.

== Filtering Locations ==

As you have seen, standard unit filter can contain a location filter.
Several actions, such as '''[terrain]''', also use location filters.
Location filters are represented on this site by the phrase "standard location filter".

See [[StandardLocationFilter]] for details.

== Filtering Weapons ==

Sometimes weapons are filtered on in WML. See also [[EventWML]], [[EffectWML]], [[AnimationWML]].

These keys are used as filter input for weapon filters.

* '''range''': a range to filter
** '''melee''': only melee weapons pass
** '''ranged''': only ranged weapons pass
* '''name''': filter on the attack's name.
See '''data/units/''' or http://www.wesnoth.org/units/
to find the name of a particular unit's attack.
* '''type''': filter on the attack's type.
Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'arcane'.
* '''damage''': {{DevFeature}} filter on damage value. Can be a specific number or a list of ranges like 'damage=0-5,7-99'
* '''special''': filter on the attack's special power.
For values see [[AbilitiesWML]].

== Filtering Terrains ==

Use '''[filter_location]''' within '''[filter]''' , for example:

[event]
[filter]
[filter_location]
terrain=Ch
[/filter_location]
[/filter]
[/event]

At some places the terrains can be filtered with a
match list. The list is a comma separated list and matching will stop
at the first matched [[TerrainCodesWML|terrain string]]. There's one special character
''!'' which inverts the meaning of a match. Terrain strings can
use the wildcard * to match zero or more following letters, characters
behind the * are not allowed and the result is undefined.

Example 1: <br>
ww* matches ww, www, wwW but not WWW <br>
!, ww returns false if ww found and true if not <br>
!, ww, wa, !, aa returns false if ww or wa found and true if aa found and false if none found.

Example 2: <br>
<nowiki>*</nowiki>^V* matches all village-terrain <br>
Notice how the * can be used separately for both layers (base and overlay layers are separated by the ^-character).

For a list of terrain types and their string codes see [[TerrainCodesWML|TerrainCodesWML]].

== See Also ==

* [[UnitTypeWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

EventWML

2010-02-13T16:08:53Z

Tsr: /* Predefined 'name' Key Values */ side x turn Y cleanup

{{WML Tags}}
== The [event] Tag ==

This tag is a subtag of the [scenario], [unit_type] and [era] tags which is used to describe a set of actions which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit_type] tag, the event will occur in all scenarios in which a unit of that type appears in (only after such a unit appears during the scenario, however). When used in an [era], the event will occur in any scenario which is played using that era.

This tag has keys and child tags that control when and if the event actions will be triggered. Most important of these is the '''name''' key. Without it, no error will be raised but the event will never fire. Therefore, from a practical standpoint, it can be considered mandatory. All of the others can be used or not and the event actions will fire either way.

=== The 'name' Key (Mandatory) ===

Usage:
name=<value>

This is '''not''' like a normal 'name' key. ''It is a basic description of when the event will trigger.'' It also has a very large number of predefined values, one of which must be used for the key to be valid.

'''Lexicon side note:''' ''It is not uncommon to refer to these values as the 'trigger' for an event and, furthermore, to call an event by its 'trigger' name. For example, in an event containing '''name=moveto''', a person might refer to the event as a ''''moveto''' event' and/or refer to the ''''moveto''' trigger' in the event or even talk about the 'event trigger' when referring to the '''moveto''' value of the 'name' key in that event. Some or all of this usage can, in fact, be found throughout this page.''

The '''name''' key can accept a list of comma separated values describing when the event will be triggered.* These values may be either predefined event types or custom event names not matching any predefined type.

For example:

name=attacker misses,defender misses

''* Note that unless you use [[#first_time_only|first_time_only=no]], the event will fire only once, '''not''' once for each listed type.''

==== Predefined 'name' Key Values ====

All predefined event types are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here is a custom event name which can be triggered only by a '''[fire_event]''' tag somewhere else. Spaces in event names can be interchanged with underscores (for example, '''name=new turn''' and '''name=new_turn''' are equivalent).

; preload {{DevFeature}}
: Triggers before a scenario 'prestarts' and when loading a savegame -- before anything is shown on the screen at all. Can be used to set up the [[LuaWML|Lua]] environment: loading libraries, defining helper functions, etc.
: '''Note:''' Unlike prestart and start, the preload event '''must be able to fire more than once!''' This is because it is triggered each time a savegame is loaded in addition to the initial time when it loads before the scenario 'prestart'. This means that it is effectively ''mandatory'' to have the [[#first_time_only|first_time_only=no]] key value in a preload event.

; prestart
: Triggers before a scenario 'starts' -- before anything is shown on the screen at all. Can be used to set up things like village ownership. For things displayed on-screen such as character dialog, use '''start''' instead.
: '''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

; start
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.
: '''Note:''' ''This value makes the [[#first_time_only|first_time_only]] key irrelevant since, by definition, it can only fire once.''

; new turn
: Triggers at the start of every turn (not side turn). See also [[#first_time_only|first_time_only=no]]. Before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.

; side turn
: Triggers when a side is about to start its turn. Before events of this type trigger, the value of the WML variable '''side_number''' is set to the number of the side of the player about to take their turn. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.

; ai turn
: Triggered just before the AI is invoked for a side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side. Note that this event might be called several times per turn in case that fallbacks to human or droiding is involved. I.e. it happens at the middle of turn of human side 1 if the human player droids his side. It happens after the selection of ai to play the turn but before AI is told that new turn has come.
: '''Note:''' ''This event currently breaks replays since it is not explicitly saved in a replay and there is no AI involved in replays...''

; turn refresh
: Like '''side turn''', triggers just before a side is taking control but '''after''' healing, calculating income, and restoring unit movement and status.

; turn ''X''
: Triggers at the start of turn ''X''. It's the first side initialization event. Side initialization events go in the order of:
: 1) '''turn ''X''''' 2) '''new turn''' 3) '''side turn''' 4) '''side ''X'' turn''' 5) '''side ''X'' turn ''Y''''' 6) '''turn refresh'''

; side ''X'' turn ''Y''
: This event triggers at the start of turn ''Y'' of side X {{DevFeature}}

; side ''X'' turn
: This event triggers at the start of any turn of side X {{DevFeature}}
: '''Note:''' ''Of course, [[#first_time_only|first_time_only=no]] is needed for this event to be triggered more than once.''

; time over
: Triggers on turn ''turns''. (''turns'' is specified in [scenario])

; enemies defeated
: Triggers when all units with '''canrecruit=yes''' (that is, all leaders) not allied with side 1 are killed.

; victory
: In this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also: [endlevel], [[DirectActionsWML]])

; defeat
: In this scenario, any tag of the form '''[endlevel] result=defeat [/endlevel]''' will be automatically preceded by all actions in this tag. (See also [endlevel], [[DirectActionsWML]])

Filters can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]

; moveto
: Triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on.<br />''An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.'' {{DevFeature}} $x2 and $y2 refer to the hex the unit came from.

; sighted
: Triggers when the primary unit becomes visible to the secondary unit in particular after not being visible to the secondary unit's side (so if the secondary unit's side doesn't have shroud or fog, the event never triggers). This happens both when the primary unit moves into view during its turn, and when the secondary unit moves to a location where it can see the primary unit. (This editor hasn't tested whether the event triggers multiple times if the primary unit moves into view of multiple units at once, or if not, which one gets chosen to be the secondary unit here.) (Note: it appears that when a sighted event is triggered because an enemy unit moves into your field of view, the game engine cannot determine which unit (on your side) sees the unit that moved, and so it fires a ''name=sighted'' event without setting ''$second_unit''. This means that, for example, using ''speaker=second_unit'' inside a message tag may fail.) (Double note: it also appears that the sighted event in more recent versions of the game (1.6 and 1.7, maybe?) does not fire on enemy turns. That is, it only fires for units that become visible as a result of the motion of another unit, not for units that move into the vision of an enemy. This event is also buggy in general... it's usually better to use a moveto event with a [filter_vision] tag than to use a sighted event (and note that the combination of the two can achieve something like the old sighted event)).

; attack
: Triggers when the primary unit attacks the secondary unit.

; attack end
: Similar to '''attack''', but is triggered ''after'' the fight instead of before. Note that if either unit is killed during the fight, this event triggers before any '''die''' events.

; attacker hits
: Triggers when the the primary unit (the attacker) hits the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the attacker.

; attacker misses
: Same as ''attacker hits'', but is triggered when the attacker misses.

; defender hits
: Triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). The value of the WML variable '''damage_inflicted''' is set to the number of hitpoints inflicted by the defender.

; defender misses
: Same as ''defender hits'', but is triggered when the defender misses.

; stone
: Triggers when the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability). In {{DevFeature}}, this event name is changed to "petrified".

; last breath
: Triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.

; die
: Triggers when the primary unit is killed by the secondary unit. ''Note: The primary unit is not removed from the game until the end of this event. The primary unit can still be manipulated, will block other units from taking its hex, and will still be found by standard unit filters (except [have_unit]). To prevent this behavior, you can use [kill] to remove the unit immediately. However, this will stop any (still unfired) other events that also match the unit from firing afterwards, so use with caution.''

; capture
: Triggers when the primary unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture.

; recruit
: Triggers when the primary unit is recruited. (That is, when a unit is recruited it will trigger this event and this event's filter will filter that unit.).

; prerecruit
: Triggers when the primary unit is recruited but before it is displayed.

; recall
: Triggers after a unit is recalled.

; prerecall
: Triggers when a unit is recalled but before it is displayed.

; advance
: Triggers just before the primary unit is going to advance to another unit.

; post advance
: Triggers just after the primary unit has advanced to another unit.

; select
: Triggers when the primary unit is selected. Also triggers when ending a move, as the game keeps the moving unit selected by selecting it again at the end of movement. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''

; menu item ''X''
: Triggers when a WML menu item with id=''X'' is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''

=== Custom events.

An event with a custom name may be invoked using the [[InternalActionsWML#.5Bfire_event.5D|[fire_event]]] tag. Normally you'll use such custom events as named subroutines to be called by events with predefined types. One common case of this, for example, is that more than one '''sighted''' events might fire the same custom event that changes the scenario objectives.

=== Optional Keys and Tags ===

These keys and tags are more complex ways to filter when an event should trigger:

==== first_time_only ====
: Whether the event should be removed from the scenario after it is triggered. This key takes a [[ConditionalActionsWML#Boolean_Values|boolean]]; for example:
: ''first_time_only=yes''
:: Default behavior if key is omitted. The event will trigger the first time it can and never again.
: ''first_time_only=no''
:: The event will trigger every time the criteria are met instead of only the first time.

==== [filter] ====
: The event will only trigger if the primary unit matches this filter.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_second] ====
: Like [filter], but for the secondary unit.
:* [[StandardUnitFilter]]: selection criteria

==== [filter_attack] ====
: Can be used to set additional filtering criteria for the primary unit and the secondary unit that are not generally available in a standard unit filter. Can be used in events ''attack'', ''attacker hits'', ''attacker misses'', ''defender hits'', ''defender misses'' and ''attack end''. For more information and other filter keys, see [[FilterWML]].
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [filter_second_attack] ====
: Like [filter_attack], but for the secondary unit.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.
:* '''special''': filter on the attack's special power.

==== [event] ====
: A special case 'action', the [event] tag may be used to create a [[#Nested Events|nested event]].

==== delayed_variable_substitution ====
: This key is only relevant inside of a [[#Delayed Variable Substitution|nested event]] and controls when variable substitution will occur in those special case actions.

=== Actions triggered by [event] ===

After the trigger conditions have been met, all action tags within the [event] tag are executed in the order they are written in.

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

Several actions use standard filters to find out which units
to execute the command on. These are denoted by the phrases
"standard unit filter" and "standard location filter".

=== Nested Events ===

There is one special type of action: event creation. By placing an '''[event]''' tag inside another '''[event]''' tag, the nested event is spawned (created) when the parent (outer) event is encountered (when executing the contents of the parent event).

([[#Nested Event Example|See Examples]])

==== Delayed Variable Substitution ====

Variable substitution for a nested event can happen either when it is spawned by the parent event or when it is triggered itself. This is controlled with the key '''delayed_variable_substitution''' which is used in the nested event.

If this key is set to ''yes'', the variables in the nested event will contain values from the turn in which the ''nested'' event was triggered. ''This is the default behavior if the key is omitted.'' If set to ''no'', the variables in the nested event are set at the time the ''parent'' event is triggered.

This behavior can be fine tuned with a special syntax when referencing variables. Instead of the normal '''$variable''' syntax, use '''$|variable''' to cause a variable to contain values relevant to the turn in which the nested event was triggered even when '''delayed_variable_substitution''' is set to ''no''. In this way you can have a mix of variables relevant to the parent and nested event trigger times.

([[#Delayed Variable Substitution Example|See Examples]])

== Multiplayer safety ==

In multiplayer it is only safe to use WML that might require synchronization with other players because of input or random numbers (like [message] with input or options or [unstore_unit] where a unit might advance) in the following events. This is because in these cases WML needs data from other players to work right and/or do the same thing for all players. This data is only available after a network synchronization.

List of synchronized events:
* moveto
* sighted
* attack
* attack_end
* attacker hits
* attacker misses
* defender hits
* defender misses
* stone
* last breath
* die
* capture
* recruit
* prerecruit
* recall
* prerecall
* advance
* post_advance
Events fired from a WML event handler that is synchronized:
* new turn {{DevFeature}}
* side turn {{DevFeature}}
* turn X {{DevFeature}}
* side X turn {{DevFeature}}
* side X turn Y {{DevFeature}}
* turn refresh {{DevFeature}}

There is also the possibility of events that are synchronized when fired by the engine but can be non-synchronized when fired by WML tags from non-synchronized event. So when you are using them you must be extra careful. For example [unstore_unit] may trigger a unit advancement that will fire ''advance'' and ''post advance'' events.

== A Trap for the Unwary ==

It is perfectly possible (and, in fact, useful) to have multiple events with the same predefined name and thus the same trigger condition. However, it is not defined what order such events will fire in, so you need to code so the order
will not matter.

Because of the above, you need to beware of using macros to generate events. If you include a macro expanding to an event definition twice, the event will be executed twice (not once) each time the trigger condition fires. Consider this code:

#define DOUBLE
[event]
name=multiply_by_2
{VARIABLE_OP 2_becomes_4 multiply 2}
[/event]
#enddef

{DOUBLE}
{DOUBLE}

{VARIABLE 2_becomes_4 2}

[fire_event]
name=multiply_by_2
[/fire_event]

{DEBUG_MSG "$2_becomes_4 should be 4"}

After it executes, the debug message will reveal that the variable has been set to 8, not 4.

== Miscellaneous Notes and Examples ==

=== Primary/Secondary Unit Speaker Example ===

In events, the primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the '''speaker''' key. For example:

[event]
name=die
[message]
speaker='''second_unit'''
message= _ "Hahaha! I finally killed you!"
[/message]

[message]
speaker='''unit'''
message= _ "It's not over yet! I'll come back to haunt you!"
[/message]
[/event]

=== Nested Event Example ===

An event is created for a portal that opens on turn 10. The parent (or 'outer') event executes on turn 10 at which point the nested moveto event is created. This nested event executes when a player steps on a certain spot.

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

# moving to 5,8 will trigger this event only on turn 10 and after
[/event]
[/event]

An equivalent way of doing this would be to create a single moveto event with an '''[if]''' statement to check for turn number but using nested '''[event]''' tags is a convenient shortcut to accomplish this task without resorting to '''[if]''' statements.

=== Delayed Variable Substitution Example ===

This code will display the turn on which the nested ''moveto'' event happens.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=yes

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

Since this is the default behavior for the '''delayed_variable_substitution''' key, the following example is identical.

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

This code will always display "Turn 10" when the nested ''moveto'' event happens. This is because the variable substitution is done when the parent event is triggered and spawns the nested event, ''not'' when the nested event is triggered.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $turn_number"}
[/event]
[/event]

Finally, this example is identical to the first two, in that it will display the turn on which the nested ''moveto'' event happens despite the fact that the '''delayed_variable_substitution''' key is set to ''no''. This is because the special '''$|variable''' syntax is used.

[event]
name=turn 10

[event]
name=moveto
delayed_variable_substitution=no

[filter]
x,y=5,8
[/filter]

{DEBUG_MSG "Turn $|turn_number"}
[/event]
[/event]

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

TimeWML

2010-01-04T14:59:24Z

Tsr: /* The [time] and [illuminated_time] tags */ Corrected location of shedules.cfg

{{WML Tags}}

The time of day influences damage done by lawful and chaotic units; this makes timing of your attack important.
Graphically time of day is represented by a picture (landscape with sun or moon) in the status table, and by darkening the screen during night turns.

Scenario author can schedule the times of day in scenario; use the pre-defined time macros, or create new times of day.

== The [time] and [illuminated_time] tags ==

The [time] tag is a subtag of the [scenario] tag. However, most scenarios do not use these directly, but usually use the ready macros '''{DAWN}, {MORNING}, {AFTERNOON}, {DUSK}, {FIRST_WATCH}, {SECOND_WATCH}''' and '''{UNDERGROUND}''' to specify the day-night cycle.
See '''data/core/macros/schedules.cfg''' for the definitions of these IDs.

The [time] tag describes a single turn of a day/night sequence. When a scenario is played, the first turn is described by the first [time] tag; the second described by the second, until there are no more. After all the tags have described a turn, the next turn is described by the first tag again.

The [time] tag recognizes the following keys:

* '''id''': the id by which you can reference this time, e.g. in the ''time_of_day'' tag of [[AiWML]].
* '''name''': (translatable) the name displayed when the cursor is over the day/night image.
* '''image''': the image displayed at the top of the Status Table during turns of this type.
* '''mask''': the image displayed over all hexes during turns of this type.
* '''lawful_bonus''': units with '''alignment=lawful''' do +//lawful_bonus'' % damage during turns of this type. Units with '''alignment=chaotic''' do -''lawful_bonus'' % damage. Units with '''alignment=neutral''' are unaffected by this key. ''lawful_bonus'' can be a negative number. This is useful if you want to give Chaotic units an advantage instead of Lawful ones.
* '''red''', '''green''', '''blue''': describe the tint of the screen during the time period. Appears to be an integer value from -255 to 255. See schedules.cfg for examples.
* '''sound''': a sound to play (in sounds/) when changing into this time of day.

=== Scheduling time ===

The [scenario] tag contains a few [time] tags (or macros).
These time tags are used in a loop, that is: first time tag is used during the first turn, then second one,... and when all time tags passed then again the first one, second one, etc.

The typical day/night cycle looks like this:

{DAWN}
{MORNING}
{AFTERNOON}
{DUSK}
{FIRST_WATCH}
{SECOND_WATCH}

To avoid day/night cycle, use a neutral time of day, for example:

{DAWN}

In underground, use a special time of day.
It works like night; that is it gives advantage to chaotic units and disadvantage to lawful units.

{UNDERGROUND}

== See Also ==

* [[ScenarioWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

InterfaceActionsWML

2010-01-04T09:03:40Z

Tsr: /* Other interface tags */ Added information on animating items using the halo-key

{{WML Tags}}
== Interface actions ==

Interface actions are actions that do not have an effect on gameplay;
instead, they show something to the player. The main interface tags
are '''[message]''' and '''[objectives]''', but several other tags affect
the interface also.

== [message] ==
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.

The following key/tags are accepted for [message]:
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed).<br>'''[message]''' elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image
** '''unit''': the primary unit for the event is speaking
** '''second_unit''': the secondary unit for the event is speaking

* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown.
* '''image''': (default: profile image of speaker) the image to display next to the message.
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed.
* '''duration''': (default: 10) the minimum number of frames for this message to be displayed. (A frame lasts about 30 milliseconds.) During this time any dialog decisions will be disregarded.
* '''sound''': a sound effect (wav file) to play as the message is displayed. This can be a comma-separated list, from which one will be randomly chosen.
* '''[option]''': zero or more '''[option]''' elements may be present. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option.
** '''message''': (translatable) the text displayed for the option (see [[DescriptionWML]])
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[InternalActionsWML]])
** '''[command]''': an element containing actions which are executed if the option is selected.
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message.
** '''variable''': the variable that the user's input will be written to
** '''label''': a text label to the left of the input field
** '''max_chars''': the maximum number of characters that may be typed into the field
** '''text''': text that is written into the field in the beginning
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.

=== Formatting ===

Text formatting options for '''[message]'''. These can also be used in unit names (user_description), objectives, and such.
* A tilde (~) as the first character causes the line to be boldfaced.
* An at symbol (@) as the first character causes the line to be green, as done with victory conditions.
* A pound symbol (#) as the first character causes the line to be red, as done with defeat conditions.
* An asterisk (*) as the first character causes the line to be bigger.
* A backquote (`) as the first character causes the line to be smaller.
* If used, the caption key text is boldfaced.
* An RGB colour code in the beginning causes the line to be the given colour. This can still be preceded by the above characters. Example: ''message=_"<255,0,0>Red!"''

{{DevFeature}} In the 1.7 branch these formatting codes are being discarded in favor of [http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html Pango markup]. Note that it's easiest to use ' for quoting in Pango markup since " is encoded as "" inside a WML string (so you have to modify the Pango examples accordingly if you want to use " quotes). Running wmllint on your campaign will up-convert it, warning you about unusual cases you must fix by hand.

== [objectives] ==
The other tag used for plot development is '''[objectives]'''.
The '''[objectives]''' tag overwrites any previously set objectives,
and displays text which should describe the objectives of the scenario.
Scenario objectives are displayed on the player's first turn after the tag is used,
or as part of the event if it triggers during that player's turn.
Objectives can also be accessed at any time in a scenario using the
"Scenario Objectives" game menu option, making this tag useful for
scenario-specific information that the player may need to refer to during play.

This tag renders the ''objectives'' attribute of [scenario] obsolete (see ''objectives'', [[ScenarioWML]]).
Instead of using ''objectives'', use '''[objectives]''' to set scenario objectives inside a prestart event.
It can also be used to overwrite the starting objectives mid-scenario.

Attributes of '''[objectives]''':
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides.
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives.
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives.
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.

Tags of '''[objectives]''':
* '''[objective]''': describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.
** '''description''': text for the specific win or loss condition.
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only. {{DevFeature}}

=== Macros ===
There are a few predefined macros for Objectives that you can use to shorten the code: [http://www.wesnoth.org/macro-reference.xhtml#SET_OBJECTIVES SET_OBJECTIVES], [http://www.wesnoth.org/macro-reference.xhtml#VICTORY_CONDITION VICTORY_CONDITION], and [http://www.wesnoth.org/macro-reference.xhtml#DEFEAT_CONDITION DEFEAT_CONDITION]. Follow the links for each one to see complete syntax and example usage.

== [set_menu_item] ==
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands.

* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.
* '''description''': the in-game text that will appear for this item in the menu.
* '''image''': the image to display next to this item.
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it false.
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[InternalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.

== Other interface tags ==

The following tags are also action tags:
* '''[item]''': makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros))''</tt>
** '''x''', '''y''': the location to place the item.
** '''image''': the image (in ''images/'' as .png) to place on the hex.
** '''halo''': an image to place centered on the hex. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image. ''Example (where the integer after the colon is the duration of each frame): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''
** '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas.
** '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.
* '''[removeitem]''': removes any graphical items on a given hex
** '''x''', '''y''': the hex to remove items off
** '''image''' if specified, only removes the given image item
* '''[print]''': displays a message across the screen. The message will disappear after a certain time.
** '''text''': (translatable) the text to display.
** '''size''': (default=12) the pointsize of the font to use
** '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
** '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255.
* '''[move_unit_fake]''': moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
** '''type''': the type of the unit whose image to use
** '''x''': a comma-separated list of x locations to move along
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)
** '''side''': the side of the fake unit, used for team-coloring the fake unit
* '''[hide_unit]''': makes the given unit become invisible. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Each '''[hide_unit]''' tag only hides one unit.
** '''x''', '''y''': location of the unit to be hidden. (NOT a standard unit filter! Just x and y.)
* '''[unhide_unit]''': stops the currently hidden unit from being hidden.
* '''[scroll]''': Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
** '''x''', '''y''': the number of pixels to scroll along the x and y axis
* '''[scroll_to]''': Scroll to a given hex
** '''x''', '''y''': the hex to scroll to
** '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* '''[scroll_to_unit]''' Scroll to a given unit
** [[StandardUnitFilter]]
** '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''true'' (don't scroll to fog) and ''false'' (scroll even to fog), with ''false'' as the default.
* '''[sound]''': Plays a sound
** '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg)
** '''repeat''': repeats the sound for a specified additional number of times (default=0)
* '''[sound_source]''': Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.
** '''id''': a unique identification key of the sound source
** '''sounds''': a list of comma separated, randomly played sounds associated with the sound source
** '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play
** '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)
** '''check_fogged''': possible values "true" and "false" - if true the source will not play if its locations are fogged
** '''check_shrouded''': {{DevFeature}} possible values "true" and "false" - if true the source will not play if its locations are shrouded
** '''x,y''': a [[StandardLocationFilter]] for the locations associated with the sound source
** '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly
** '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center
** '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)
* '''[remove_sound_source]''': Removes a previously defined sound source.
** '''id''': the identification key of the sound source to remove
* '''[music]''': Switches to playing different music
** '''name''': the filename of the music to play (in ''music/'' as .ogg)
** see [[MusicListWML]] for the correct syntax
* '''[colour_adjust]''': tints the colour of the screen.
** '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each colour
* '''[delay]''': pauses the game
** '''time''': the time to pause in milliseconds
* '''[redraw]''': redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).
** '''side''': if used, recalculates fog and shroud for that side. Useful if you for example spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).
* '''[unit_overlay]''': sets an image that will be drawn over a particular unit, and follow it around
** '''x''', '''y''': the location of the unit to overlay on
** '''image''': the image to place on the unit
* '''[remove_unit_overlay]''': removes a particular overlayed image from a unit
** '''x''', '''y''': the location of the unit to remove an overlay from
** '''image''': the image to remove from the unit
* '''[animate_unit]''': uses the custom animation of a unit to animate it on screen (if the unit has the corresponding animation)
** '''flag''': the key to find the good custom animation in the unit description see the '''[extra_anim]''' description in [[AnimationWML]] Standar anims can be triggered with the following keywors ''leading recruited standing idling levelin levelout healing healed poisoned movement defend attack death victory pre_teleport post_teleport''
** '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate
** '''[primary_attack]''': if this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation
** '''[secondary_attack]''': same for the second attack
** '''hits''': the hit type to filter unit on
** '''text''': a text to hover during the animation
** '''red''': red value for the text color
** '''green''': green value for the text color
** '''blue''': blue value for the text color
** '''with_bars''': whether to display the status bars or not.
** '''[animate]''': a sub block with the same syntax as the '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously
** '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated
* '''[label]''' places a label on the map.
** '''x''', '''y''': the location of the label
** '''text''': what the label should say
** '''team_name''': if specified, the label will only be visible to the given team.
** '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.
* '''[deprecated_message]''' shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.
** '''message''': the message to show.
* '''[wml_message]''' outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.
** '''message''': the message to show.
** '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.
* '''[open_help]''' opens the in-game help.
** '''topic''': the id of the topic to open
* '''[show_objectives]''': {{DevFeature}} refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)
** '''side''': the side to show the objectives. If not set, all sides are used.

== Useful Macros ==
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{FLOATING_TEXT}''' Float some text over a unit similar to the damage numbers.
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations
* '''{SET_IMAGE}''' Places an image on the map which has no other function.
* '''{QUAKE <soundfile>}''' Creates a tremor like screenshake and plays <soundfile>. ('''{TREMOR}''' is a deprecated version, equivalent to '''{QUAKE (rumble.ogg)}''')
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]
[[Category: ActionsWML]]

User:Tsr

2009-12-03T07:09:58Z

Tsr: /* Tsr wesnoth info */ Moved NM, added TDEM, etc

==Tsr wesnoth info==

Ok, in trying to get things out of my head I've finally decided to create this page. Here I will list the wesnoth related projects I am maintaining, working on and thinking about.

If you want to give feedback, report bugs, etc please do it on [[User_talk:Tsr|my talk page]] or in the linked to forum-threads.

===Whoami===
* wiki: [[User:Tsr|Tsr]] (obviously you are reading this page now)
* forums: [http://www.wesnoth.org/forum/memberlist.php?mode=viewprofile&u=103562 tsr]
* irc: teaser@freenode.net on #wesnoth-dev, etc (but I am not very often there)

===Uploaded add-ons===
* TDEM (tsr's default era mods) - 1.7.9
* WCE (wesnoth collaborative editor) - 1.7.9

===Projects I maintain===
''These are project that I consider done but that I will work on if there is user input about bugs or new features that I deem worthy to add.''

====The default preset advancement era====
A concept era where you can choose what advancement path your units will use if they advance during not your turn. Versions exist for both the 1.6 and 1.7 branches of wesnoth. Now part of TDEM ([http://www.wesnoth.org/forum/viewtopic.php?t=27969 forum-thread])

===Projects I work on===
''These are projects I am actually working on at the moment, to try and get them into a stable state so that I can move them to the maintaining section above''

====MP-map: 2 is a crowd====
A watery 1v1 map where your first decision is what keep to go for. There are currently no versions on the add-on servers but there ia version that works on both 1.6 and 1.8 on the forums. The latest and greatest (or so I hope) in in the [http://www.wesnoth.org/forum/viewtopic.php?f=15&t=27679 forum-thread].

====Wesnoth Collaborative Editor====
This is an online mp collaborative map editor for wesnoth maps. There are some features in it that I will brake out for other uses eventually. It is almost feature complete but needs some more attention before I call it finnished. Be sure to read the README before asking for help. There is only a version for 1.7 (it might work in 1.6 too, I just haven't tried it). ([http://www.wesnoth.org/forum/viewtopic.php?f=15&t=27737 forum-thread])

====Tabletop Default Era====
This is a modification of the Default era that tries to emulate a classic tabletop fighting game. You get to place your units at the beginning of the game and you can't recruit more units later in the game. Also you have to kill all opponents units to win. Now part of TDEM ([http://www.wesnoth.org/forum/viewtopic.php?t=27969 forum-thread])

====No mirror matches in mp====
Implement a default-era-tweak in WML that will ensure that there will not be the same faction in opposing teams in mp games. Now part of TDEM ([http://www.wesnoth.org/forum/viewtopic.php?t=27969 forum-thread]

===Projects I would like to work on===
''These are basically ideas that I hope to get around to work on some day, or that I hope that someone else will find is such a good idea that they will implement it''

====More functional and pretty replay archive====
I would like to build a nicer interface to the replay archive so that we will be able to search for replays based on every aspect you can think of or at least almost - I don't want a cluttered interface either ;)
Things like - one at the time or combined:
* Version played (including compatible versions)
* Players in the game
* Scenario
* Era, specific factions
* Date
* Position (p1, p2, etc)

====Irdya the faction====
Inspired by the concept of [http://en.wikipedia.org/wiki/Gaia_hypothesis Gaia] I want to create a wesnoth faction that represents the planet Irdya (or whatever the wesnoth planet is called). It will consist of units that resemble the available terrains. It will not be a mp-balanced faction but something like a monster faction that can be used in campaigns or scenarios. The units will have characteristics from their element (both in fighting quality, movement and appearance).

====Clickable links====
I think it would be a great idea if we could create links in some places inside the game, like
* linking to an add-ons forum-thread
* linking to whatever in the game-chat (but proabably not lobby-chat
* linking to the [[MP_CodeOfConduct|CoC]] in the mp-servers motd

===Projects I have started and left===
''These are projects that I for various reasons don't take active part in anymore (or actually there is only one reason, since there is only one project here.''

====The wesnoth MP Code of Conduct====
Apparently there was a time when the wesnoth mp-servers where populated with so few users that you couldn't really behave like an ass... When that changed the need for information became evident. After some time trying to keep the standards high without any written rules it became evident, even for me that something had to be done. Hence the birth of the [[MP_CodeOfConduct|CoC]]. (Actually several people had already thought of it; of course, I just happened to be the one that actually wrote the first draft - and I am quite pleased to see that most of it remains)

===Random stuff===
''Things that are related to wesnoth in some ways''

* writing the [[MP_CodeOfConduct|CoC]] earned me the forum title: Forum Regular.
* creating [[#Wesnoth Collaborative Editor|WCE]] earned me the forum title: WML Pioneer.
* I once made an alternative animation of the berserker that drinks coke instead of beer (it was in a wesnoth-funding thread and I can't seem to find the animation anywhere)

User:Tsr

2009-12-01T14:53:22Z

Tsr: /* Projects I work on */ Added Tabletop Default Era

==Tsr wesnoth info==

Ok, in trying to get things out of my head I've finally decided to create this page. Here I will list the wesnoth related projects I am maintaining, working on and thinking about.

If you want to give feedback, report bugs, etc please do it on [[User_talk:Tsr|my talk page]] or in the linked to forum-threads.

===Whoami===
* wiki: [[User:Tsr|Tsr]] (obviously you are reading this page now)
* forums: [http://www.wesnoth.org/forum/memberlist.php?mode=viewprofile&u=103562 tsr]
* irc: teaser@freenode.net on #wesnoth-dev, etc (but I am not very often there)

===Projects I maintain===
''These are project that I consider done but that I will work on if there is user input about bugs or new features that I deem worthy to add.''

====The default preset advancement era====
A concept era where you can choose what advancement path your units will use if they advance during not your turn. Versions exist for both the 1.6 and 1.7 branches of wesnoth. ([http://www.wesnoth.org/forum/viewtopic.php?f=19&t=26039 forum-thread])

===Projects I work on===
''These are projects I am actually working on at the moment, to try and get them into a stable state so that I can move them to the maintaining section above''

====MP-map: 2 is a crowd====
A watery 1v1 map where your first decision is what keep to go for. There are currently no versions on the add-on servers but there ia version that works on both 1.6 and 1.8 on the forums. The latest and greatest (or so I hope) in in the [http://www.wesnoth.org/forum/viewtopic.php?f=15&t=27679 forum-thread].

====Wesnoth Collaborative Editor====
This is an online mp collaborative map editor for wesnoth maps. There are some features in it that I will brake out for other uses eventually. It is almost feature complete but needs some more attention before I call it finnished. Be sure to read the README before asking for help. There is only a version for 1.7 (it might work in 1.6 too, I just haven't tried it). ([http://www.wesnoth.org/forum/viewtopic.php?f=15&t=27737 forum-thread])

====Tabletop Default Era====
This is a modification of the Default era that tries to emulate a classic tabletop fighting game. You get to place your units at the beginning of the game and you can't recruit more units later in the game. Also you have to kill all opponents units to win. ([http://www.wesnoth.org/forum/viewtopic.php?t=27949 forum-thread] - I didn't start the topic, but it is there...)

===Projects I would like to work on===
''These are basically ideas that I hope to get around to work on some day, or that I hope that someone else will find is such a good idea that they will implement it''

====More functional and pretty replay archive====
I would like to build a nicer interface to the replay archive so that we will be able to search for replays based on every aspect you can think of or at least almost - I don't want a cluttered interface either ;)
Things like - one at the time or combined:
* Version played (including compatible versions)
* Players in the game
* Scenario
* Era, specific factions
* Date
* Position (p1, p2, etc)

====No mirror matches in mp====
Implement a default-era-tweak in WML that will ensure that there will not be the same faction in opposing teams in mp games.

====Irdya the faction====
Inspired by the concept of [http://en.wikipedia.org/wiki/Gaia_hypothesis Gaia] I want to create a wesnoth faction that represents the planet Irdya (or whatever the wesnoth planet is called). It will consist of units that resemble the available terrains. It will not be a mp-balanced faction but something like a monster faction that can be used in campaigns or scenarios. The units will have characteristics from their element (both in fighting quality, movement and appearance).

====Clickable links====
I think it would be a great idea if we could create links in some places inside the game, like
* linking to an add-ons forum-thread
* linking to whatever in the game-chat (but proabably not lobby-chat
* linking to the [[MP_CodeOfConduct|CoC]] in the mp-servers motd

===Projects I have started and left===
''These are projects that I for various reasons don't take active part in anymore (or actually there is only one reason, since there is only one project here.''

====The wesnoth MP Code of Conduct====
Apparently there was a time when the wesnoth mp-servers where populated with so few users that you couldn't really behave like an ass... When that changed the need for information became evident. After some time trying to keep the standards high without any written rules it became evident, even for me that something had to be done. Hence the birth of the [[MP_CodeOfConduct|CoC]]. (Actually several people had already thought of it; of course, I just happened to be the one that actually wrote the first draft - and I am quite pleased to see that most of it remains)

===Random stuff===
''Things that are related to wesnoth in some ways''

* writing the [[MP_CodeOfConduct|CoC]] earned me the forum title: Forum Regular.
* creating [[#Wesnoth Collaborative Editor|WCE]] earned me the forum title: WML Pioneer.
* I once made an alternative animation of the berserker that drinks coke instead of beer (it was in a wesnoth-funding thread and I can't seem to find the animation anywhere)

User:Tsr

2009-11-26T00:41:17Z

Tsr: /* Projects I would like to work on */ added replay archive and no mirror era

==Tsr wesnoth info==

Ok, in trying to get things out of my head I've finally decided to create this page. Here I will list the wesnoth related projects I am maintaining, working on and thinking about.

If you want to give feedback, report bugs, etc please do it on [[User_talk:Tsr|my talk page]] or in the linked to forum-threads.

===Whoami===
* wiki: [[User:Tsr|Tsr]] (obviously you are reading this page now)
* forums: [http://www.wesnoth.org/forum/memberlist.php?mode=viewprofile&u=103562 tsr]
* irc: teaser@freenode.net on #wesnoth-dev, etc (but I am not very often there)

===Projects I maintain===
''These are project that I consider done but that I will work on if there is user input about bugs or new features that I deem worthy to add.''

====The default preset advancement era====
A concept era where you can choose what advancement path your units will use if they advance during not your turn. Versions exist for both the 1.6 and 1.7 branches of wesnoth. ([http://www.wesnoth.org/forum/viewtopic.php?f=19&t=26039 forum-thread])

===Projects I work on===
''These are projects I am actually working on at the moment, to try and get them into a stable state so that I can move them to the maintaining section above''

====MP-map: 2 is a crowd====
A watery 1v1 map where your first decision is what keep to go for. There are currently no versions on the add-on servers but there ia version that works on both 1.6 and 1.8 on the forums. The latest and greatest (or so I hope) in in the [http://www.wesnoth.org/forum/viewtopic.php?f=15&t=27679 forum-thread].

====Wesnoth Collaborative Editor====
This is an online mp collaborative map editor for wesnoth maps. There are some features in it that I will brake out for other uses eventually. It is almost feature complete but needs some more attention before I call it finnished. Be sure to read the README before asking for help. There is only a version for 1.7 (it might work in 1.6 too, I just haven't tried it). ([http://www.wesnoth.org/forum/viewtopic.php?f=15&t=27737 forum-thread])

===Projects I would like to work on===
''These are basically ideas that I hope to get around to work on some day, or that I hope that someone else will find is such a good idea that they will implement it''

====More functional and pretty replay archive====
I would like to build a nicer interface to the replay archive so that we will be able to search for replays based on every aspect you can think of or at least almost - I don't want a cluttered interface either ;)
Things like - one at the time or combined:
* Version played (including compatible versions)
* Players in the game
* Scenario
* Era, specific factions
* Date
* Position (p1, p2, etc)

====No mirror matches in mp====
Implement a default-era-tweak in WML that will ensure that there will not be the same faction in opposing teams in mp games.

====Irdya the faction====
Inspired by the concept of [http://en.wikipedia.org/wiki/Gaia_hypothesis Gaia] I want to create a wesnoth faction that represents the planet Irdya (or whatever the wesnoth planet is called). It will consist of units that resemble the available terrains. It will not be a mp-balanced faction but something like a monster faction that can be used in campaigns or scenarios. The units will have characteristics from their element (both in fighting quality, movement and appearance).

====Clickable links====
I think it would be a great idea if we could create links in some places inside the game, like
* linking to an add-ons forum-thread
* linking to whatever in the game-chat (but proabably not lobby-chat
* linking to the [[MP_CodeOfConduct|CoC]] in the mp-servers motd

===Projects I have started and left===
''These are projects that I for various reasons don't take active part in anymore (or actually there is only one reason, since there is only one project here.''

====The wesnoth MP Code of Conduct====
Apparently there was a time when the wesnoth mp-servers where populated with so few users that you couldn't really behave like an ass... When that changed the need for information became evident. After some time trying to keep the standards high without any written rules it became evident, even for me that something had to be done. Hence the birth of the [[MP_CodeOfConduct|CoC]]. (Actually several people had already thought of it; of course, I just happened to be the one that actually wrote the first draft - and I am quite pleased to see that most of it remains)

===Random stuff===
''Things that are related to wesnoth in some ways''

* writing the [[MP_CodeOfConduct|CoC]] earned me the forum title: Forum Regular.
* creating [[#Wesnoth Collaborative Editor|WCE]] earned me the forum title: WML Pioneer.
* I once made an alternative animation of the berserker that drinks coke instead of beer (it was in a wesnoth-funding thread and I can't seem to find the animation anywhere)

User:Tsr

2009-11-25T09:46:17Z

Tsr: New page: ==Tsr wesnoth info== Ok, in trying to get things out of my head I've finally decided to create this page. Here I will list the wesnoth related projects I am maintaining, working on and th...

==Tsr wesnoth info==

Ok, in trying to get things out of my head I've finally decided to create this page. Here I will list the wesnoth related projects I am maintaining, working on and thinking about.

If you want to give feedback, report bugs, etc please do it on [[User_talk:Tsr|my talk page]] or in the linked to forum-threads.

===Whoami===
* wiki: [[User:Tsr|Tsr]] (obviously you are reading this page now)
* forums: [http://www.wesnoth.org/forum/memberlist.php?mode=viewprofile&u=103562 tsr]
* irc: teaser@freenode.net on #wesnoth-dev, etc (but I am not very often there)

===Projects I maintain===
''These are project that I consider done but that I will work on if there is user input about bugs or new features that I deem worthy to add.''

====The default preset advancement era====
A concept era where you can choose what advancement path your units will use if they advance during not your turn. Versions exist for both the 1.6 and 1.7 branches of wesnoth. ([http://www.wesnoth.org/forum/viewtopic.php?f=19&t=26039 forum-thread])

===Projects I work on===
''These are projects I am actually working on at the moment, to try and get them into a stable state so that I can move them to the maintaining section above''

====MP-map: 2 is a crowd====
A watery 1v1 map where your first decision is what keep to go for. There are currently no versions on the add-on servers but there ia version that works on both 1.6 and 1.8 on the forums. The latest and greatest (or so I hope) in in the [http://www.wesnoth.org/forum/viewtopic.php?f=15&t=27679 forum-thread].

====Wesnoth Collaborative Editor====
This is an online mp collaborative map editor for wesnoth maps. There are some features in it that I will brake out for other uses eventually. It is almost feature complete but needs some more attention before I call it finnished. Be sure to read the README before asking for help. There is only a version for 1.7 (it might work in 1.6 too, I just haven't tried it). ([http://www.wesnoth.org/forum/viewtopic.php?f=15&t=27737 forum-thread])

===Projects I would like to work on===
''These are basically ideas that I hope to get around to work on some day, or that I hope that someone else will find is such a good idea that they will implement it''

====Irdya the faction====
Inspired by the concept of [http://en.wikipedia.org/wiki/Gaia_hypothesis Gaia] I want to create a wesnoth faction that represents the planet Irdya (or whatever the wesnoth planet is called). It will consist of units that resemble the available terrains. It will not be a mp-balanced faction but something like a monster faction that can be used in campaigns or scenarios. The units will have characteristics from their element (both in fighting quality, movement and appearance).

====Clickable links====
I think it would be a great idea if we could create links in some places inside the game, like
* linking to an add-ons forum-thread
* linking to whatever in the game-chat (but proabably not lobby-chat
* linking to the [[MP_CodeOfConduct|CoC]] in the mp-servers motd

===Projects I have started and left===
''These are projects that I for various reasons don't take active part in anymore (or actually there is only one reason, since there is only one project here.''

====The wesnoth MP Code of Conduct====
Apparently there was a time when the wesnoth mp-servers where populated with so few users that you couldn't really behave like an ass... When that changed the need for information became evident. After some time trying to keep the standards high without any written rules it became evident, even for me that something had to be done. Hence the birth of the [[MP_CodeOfConduct|CoC]]. (Actually several people had already thought of it; of course, I just happened to be the one that actually wrote the first draft - and I am quite pleased to see that most of it remains)

===Random stuff===
''Things that are related to wesnoth in some ways''

* writing the [[MP_CodeOfConduct|CoC]] earned me the forum title: Forum Regular.
* creating [[#Wesnoth Collaborative Editor|WCE]] earned me the forum title: WML Pioneer.
* I once made an alternative animation of the berserker that drinks coke instead of beer (it was in a wesnoth-funding thread and I can't seem to find the animation anywhere)

Talk:ImprovingConsoleOfFormulaAI

2009-03-22T22:48:49Z

Tsr: New page: I don't know if I'm allowed to do this, but anyway. About your idea to implement a REPEAT command for the formula-console I think it would be much handier if you'd allow the user to go ba...

I don't know if I'm allowed to do this, but anyway.

About your idea to implement a REPEAT command for the formula-console I think it would be much handier if you'd allow the user to go back (say, up to 20 times) and forth in the history using the arrow-keys (like in a regular console). The benefits are twofold: 1. more flexible 2. can easily be ported to chat-console or command-console.

/tsr

Play

2008-04-16T06:11:59Z

Tsr: link to MP_CodeOfConduct

== Getting Battle for Wesnoth ==
* [[Description|About the project]]
* [[Download|Downloads and Source Code Page]]
* [[CompilingWesnoth| Compiling Wesnoth]]

== Playing Battle for Wesnoth ==
<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-1.4-8.jpg http://www.wesnoth.org/images/sshots/wesnoth-1.4-8-175.jpg]
<div class="thumbcaption">The Elves Besieged</div></div>
</div>

* [[GettingStarted|Get Started]]
* [[WesnothManual|Game Manual]]
* [[BasicStrategy|Basic Tactics]]
* [[MainlineCampaigns|Walkthroughs of Official Campaigns]]
* [[UserScenarios | User-made Add-On Campaigns]]
* [[Competitive_Gaming | Competitive Gaming]]
* [[MP_CodeOfConduct | How to behave on the Multiplayer server ]]

* [[FAQ]]

== Advanced Players ==
* [[CommandMode|Debugging and Multiplayer Command Reference]]
* [[AdvancedTactics|Advanced Tactics]]
* [http://units.wesnoth.org/ Units Reference]
* [[MultiplayerServers|Multiplayer Servers]]
* [[How to play...|The "How to play" Series]]

== The world of Wesnoth ==
<div class="thumb tright"><div>
[http://www.wesnoth.org/images/sshots/wesnoth-map-1.jpg http://www.wesnoth.org/images/sshots/wesnoth-map-1-175.jpg]
<div class="thumbcaption">Wesnoth and Surrounding Lands</div></div>
</div>

* [[History of Wesnoth|The history of Wesnoth]]
* [[Geography of Wesnoth|The geography of Wesnoth]]
* [[WesnothFigures|Notable figures of Wesnoth]]
* [[Races|The races of creatures in Wesnoth]]
* [[Poetry of Wesnoth|Wesnothian poetry]]

== Miscellaneous ==
* [[WhatArePlayersSaying|Comments from Wesnoth Players]]
* [[WesnothReviews|Third party Wesnoth reviews]]
* [[Screenshots]]
* [[FAQ#Do_you_want_help_making_this_game.3F_How_can_I_help.3F|Help to improve the game]]
* A Wesnoth [[Glossary]]
* [[The Observer|The Observer]] -- The Unofficial Wesnoth Newspaper
* [http://wesnoth.dbzer0.com/blog/ The Wesnoth Journals] -- A collaborative Wesnoth blog.
* [[RelatedTools|Related Tools]]
__NOTOC__

[[Category:Playing Wesnoth]]

WML Engine Rewrite

2008-04-04T20:45:19Z

Tsr: spelling

Following an irc discussion with the game developers, I have decided to change
my project. See the original wiki page, [[Map Editor Ilor]], for my questionaire
answers.

==Wesnoth Markup Language (WML) engine overhaul.==

===Abstract===
WML is a core element of Wesnoth. This custom markup language is used for
various data files, save games, and network handling. It s a text format, internally stored in the form of "config" objects, and used throughout the entire Wesnoth code for many different purposes. This current representation is, however, rather inefficient, both in terms of memory consumption and processing time. Additionally, some parts of game code dealing with processing WML nodes are written in a crude way that is inefficient and difficult to maintain, notably the main WML event processing function. The aim of this project is to provide a replacement implementation of the WML engine, with better speed and lower memory consumption, as well as refactoring many of the main WML-related functions.

===Description===
The inefficiency of WML has been a major issue in wesnothd, the dedicated Wesnoth server. An alternative, stripped down implementation called simple_wml has been introduced there recently by Sirp, and is several times faster and uses less memory. However, while it shows how inefficient the current implementation is, simple_wml is not a suitable replacement for config because it lacks a great deal of existing functionality, and is difficult to use. The replacement WML implementation will have to be mostly compatible with the current config class, to avoid making a huge amount of changes throughout the entire codebase using WML. Some will be needed anyway, but if possible they should be simple enough to automate or semi-automate.

There are some design decisions to be made regarding technical details of internal WML representation. It should be made easy to replace some crucial bits of the implementation so that different approaches can be compared side by side later, when the project is nearing completion.

====Timeline====
The project milestones would be as follows:
* Refactor the WML commands handling code. Design can take place before the actual beginning of GSoC, the implementation itself should be relatively easy if somewhat time-consuming. I expect this part to be done and tested around half of June.
* Design and implement a method of benchmarking WML performance speed- and memory-wise. This will be important as improved efficiency is a main goal of the project, and since the actual game performance is influenced by many factors, a standalone benchmark will be very useful. Additionally, the benchmarking code can serve as a reasonably comprehensive test suite for the new WML implementation. This part should not take much time, and more tests can always be added later. Most likely the development of the benchmark will be parallel to the next item.
* Design and implement the new internal representation of WML documents and nodes. This is the main part of the project, and will take most of the time. A working, possibly incomplete and not yet optimized version should be ready for the mid-term evaluation, i.e. second week of June
* The final part of the project will involve further optimizations of the code, performing benchmark tests and polishing the interfaces. Then the code will be wired into the Wesnoth codebase, which should be possible to do as automatically as possible. Some final tests of the entire game with the new WML code will be done to see what gains have been made. By the time GSoC ends, the new WML implementation should replace or be ready to replace the current config implementation.

[[Category:Summer of Code]]

Template:WML Tags

2007-08-22T09:47:23Z

Tsr: fixed link for store_side -> internal

{| class="gallery" style="width:175px;float: right;border: 1px solid #B48648; color:#B48648; font-size: 7pt;margin-left;10px;"
|-
|
<span style="float: right;"><small class="editlink noprint plainlinksneverexpand">[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit ]</small></span>
'''WML Tags'''

|-
|''A:''
[[AbilitiesWML|abilities]],
[[CampaignWML#The_.5Babout.5D_tag|about]],
[[UnitWML|advancefrom]],
[[UnitWML|advancement]],
[[StatisticalScenarioWML|advances]],
[[AiWML|ai]],
[[DirectActionsWML|allow_recruit]],
[[DirectActionsWML|allow_undo]],
[[VariablesWML|array]],
[[AttackWML|attack]],
[[StatisticalScenarioWML|attacks]],
[[AiWML|avoid]];
|-
|''B:''
[[UnitWML|base_unit]],[[CampaignWML#The_.5Bbinary_path.5D_tag|binary_path]],[[HelpWML|bold]];
|-
|''C:''
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]], [[DirectActionsWML|capture_village]], [[ReplayWML|choose]],
[[InternalActionsWML|clear_variable]],
[[InterfaceActionsWML|colour_adjust]],
[[ReplayWML|command]];
|-
|''D:''
[[StatisticalScenarioWML|deaths]],[[UnitWML|defend]],[[StatisticalScenarioWML|defends]],
[[UnitWML|defense]],
[[InterfaceActionsWML|delay]],
[[ReplayWML|destination]],
[[DirectActionsWML|disallow_recruit]],
[[InternalActionsWML|do]];
|-
|''E:''
[[EffectWML|effect]],[[InternalActionsWML|else]],[[ReplayWML|end_turn]],
[[DirectActionsWML|endlevel]],
[[EraWML|era]],
[[EventWML|event]],
[[ThemeWML|expenses]];
|-
|''F:''
[[FilterWML|filter]], [[FilterWML|filter_location]], [[FilterWML|filter_second]], [[HelpWML|format]], [[AttackWML|frame]];
|-
|''G:''
[[GameConfigWML|game_config]], [[ScenarioWML|generator]], [[DirectActionsWML|gold]], [[ThemeWML|gold]];
|-
|''H:''
[[InternalActionsWML|have_unit]], [[HelpWML|header]], [[InterfaceActionsWML|hide_unit]];
|-
|''I:''
[[InternalActionsWML|if]], [[TimeWML|illuminated_time]], [[TerrainGraphicsWML|image]],
[[HelpWML|img]], [[ThemeWML|income]], [[HelpWML|italic]], [[InterfaceActionsWML|item]];
|-
|''J:''
[[HelpWML|jump]];
|-
|''K:''
[[DirectActionsWML|kill]], [[StatisticalScenarioWML|killed]];
|-
|''L:''
[[LabelWML|label]] ([[InterfaceActionsWML|map]], [[ThemeWML|theme]]), [[LanguageWML|language]], [[AiWML|leader_goal]];
|-
|''M:''
[[ThemeWML|main_map]],[[ThemeWML|menu]], [[InterfaceActionsWML|message]], [[ThemeWML|mini_map]],
[[AttackWML|missile_frame]], [[SingleUnitWML|modifications]], [[DirectActionsWML|modify_side]],
[[DirectActionsWML|modify_turns]], [[ReplayWML|move]], [[InterfaceActionsWML|move_unit_fake]], [[UnitWML|movement costs]],
[[UnitsWML|movetype]], [[ScenarioWML|multiplayer]], [[EraWML|multiplayer_side]], [[InterfaceActionsWML|music]];
|-
|''N:''
[[FilterWML|not]], [[ThemeWML|num_units]];
|-
|''O:''
[[DirectActionsWML|object]], [[InterfaceActionsWML|objectives]], [[InterfaceActionsWML|objective]],
[[ThemeWML|observers]], [[InterfaceActionsWML|option]], [[InternalActionsWML|or]];
|-
|''P:''
[[ThemeWML|panel]], [[IntroWML|part]], [[DirectActionsWML|place_shroud]], [[ThemeWML|position]],
[[InterfaceActionsWML|print]], [[AiWML|protect_location]], [[AiWML|protect_unit]];
|-
|''R:''
[[UnitsWML|race]], [[ReplayWML|random]], [[ReplayWML|recall]], [[StatisticalScenarioWML|recalls]],
[[ReplayWML|recruit]], [[StatisticalScenarioWML|recruits]], [[InterfaceActionsWML|redraw]],
[[HelpWML|ref]], [[DirectActionsWML|remove_shroud]], [[InterfaceActionsWML|remove_unit_overlay]],
[[InterfaceActionsWML|removeitem]], [[SavefileWML|replay]], [[SavefileWML|replay_start]],
[[UnitWML|resistance]], [[ThemeWML|resolution]], [[ReplayWML|results]], [[InternalActionsWML|role]];
|-
|''S:''
[[SavefileWML|save]], [[ScenarioWML|scenario]],
[[InterfaceActionsWML|scroll]], [[InterfaceActionsWML|scroll_to]],
[[InterfaceActionsWML|scroll_to_unit]], [[HelpWML|section]],
[[InterfaceActionsWML#.5Bset_menu_item.5D_.28SVN_trunk_only.29|set_menu_item]], [[DirectActionsWML|set_recruit]],
[[InternalActionsWML|set_variable]], [[SideWML|side]], [[ThemeWML|side_playing]], [[SavefileWML|snapshot]],
[[InterfaceActionsWML|sound]], [[ReplayWML|source]], [[AbilitiesWMLTechnical1.1.3|specials]]
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],
[[ThemeWML|status]], [[DirectActionsWML|stone]], [[InternalActionsWML|store_gold]], [[InternalActionsWML|store_locations]],
[[InternalActionsWML|store_starting_location]], [[InternalActionsWML|store_side]], [[InternalActionsWML|store_unit]], [[IntroWML|story]];
|-
|''T:''
[[AiWML|target]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],
[[DirectActionsWML|teleport]], [[UnitWML|teleport_anim]],
[[TerrainWML|terrain]], [[DirectActionsWML|terrain]], [[TerrainGraphicsWML|terrain_graphics]], [[TerrainMaskWML|terrain_mask]], [[ScenarioWML#Test_scenario|test]],
[[CampaignWML#The_.5Btextdomain.5D_tag|textdomain]], [[ThemeWML|theme]], [[InternalActionsWML|then]],
[[TerrainGraphicsWML|tile]], [[TimeWML|time]], [[ScenarioWML|time_area]], [[ThemeWML|time_of_day]],
[[HelpWML|topic]], [[HelpWML|toplevel]], [[SingleUnitWML|trait]], [[ThemeWML|turn]], [[ScenarioWML|tutorial]];
|-
|''U:''
[[InterfaceActionsWML|unhide_unit]], unit ([[UnitWML|define]], [[SingleUnitWML|create]]),
[[ThemeWML|unit_abilities]], [[ThemeWML|unit_alignment]], [[ThemeWML|unit_description]],
[[ThemeWML|unit_hp]], [[ThemeWML|unit_image]], [[ThemeWML|unit_level]], [[ThemeWML|unit_moves]],
[[InterfaceActionsWML|unit_overlay]], [[ThemeWML|unit_profile]], [[ThemeWML|unit_status]],
[[ThemeWML|unit_traits]], [[ThemeWML|unit_type]], [[ThemeWML|unit_weapons]], [[ThemeWML|unit_xp]],
[[UnitsWML|units]], [[DirectActionsWML|unstone]], [[DirectActionsWML|unstore_unit]], [[ThemeWML|upkeep]];
|-
| ''V:''
[[InternalActionsWML|variable]], [[VariablesWML|variables]], [[SideWML|village]], [[ThemeWML|villages]];
|-
| ''W:''
[[InternalActionsWML|while]], [[FilterWML|wml_filter]]
|}

InternalActionsWML

2007-06-28T20:58:59Z

Tsr: /* [event] */ Clarified time=stamp

{{WML Tags}}
== Internal actions ==

Internal actions are actions that WML uses internally that do not directly affect gameplay, for example storing a variable.

The internal actions '''[if]''', '''[while]''', and '''[event]''' describe when/whether sets of actions should be executed.

== [if] ==

Executes different sets of actions based on whether the conditions described in the condition tags are true or not.

Condition tags:
* '''[have_unit]''' a unit passing this filter with >0 HP exists
** standard unit filter

* '''[have_location]''' {{DevFeature}} a location passing this filter exists
** standard location filter

* '''[and]''' If an [and] is present, all must evaluate to true in order for the [if] to evaluate true. Useful as a bracket for complex conditions, but not strictly necessary.
** condition tags as in [if] - if these evaluate to true, [and] evaluates to true.

* '''[or]''' If an [or] is present, one must evaluate to true in order for the [if] to evaluate true. ([[AdvancedConditionalWML|Example]])
** condition tags as in [if] - if these evaluate to true, [or] evaluates to true.

* '''[not]''' If a [not] is present, none must evaluate to true in order for the [if] to evaluate true.
** condition tags as in [if] - if these evaluate to true, [not] evaluates to false.

* '''[variable]''' tests something about the value of a WML variable (see [[VariablesWML]])
** ''name'' the name of the variable to test the value of<br>Only one of the following keys should be used for comparing the value of the variable to another value:
** ''equals'' $name is equal (string wise) to this
** ''not_equals'' $name is not equal to this
** ''greater_than'' $name is numerically greater than this
** ''less_than'' $name is less than this
** ''greater_than_equal_to'' $name is not less than this
** ''less_than_equal_to'' $name is not greater than this
** ''numerical_not_equals'' $name is greater than or less than this
** ''numerical_equals'' $name is not greater than or less than this
** ''boolean_equals'' {{DevFeature}} $name has the same boolean value (e.g. off, false, 0, no)

After condition tags:
* '''[then]''' contains a set of action tags which should be executed if all conditions are true, or all conditions in any single [or] are true
* '''[else]''' contains a set of action tags which should be executed if any condition is false, and all [or] tags are false

== [while] ==

executes commands if all conditions are true.
Continues to execute them until a condition is not true.

Executes a maximum of 1024 iterations per invocation.
Condition tags are the same as for [if]

After condition tags:
* '''[do]''' contains actions that should be executed repeatedly until some condition is false.

The [while] tag is useful for iterating over an array.
An ''array'' is a list of values.
The ''number''th value in the array ''array'' is stored in the WML variable '''''array''[number]'''.
Note that if ''number'' is the value of the variable ''variable'',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.
The macros 'FOREACH' and 'NEXT' ([[UtilWML]]) can be used to iterate over an array;
i.e. run a set of actions once per element of the array.

== [event] ==

This adds a new event to the scenario.
The event is in the normal format for an '''[event]''' tag (See [[EventWML]]).
This is useful if you want an event that can only be triggered when a prior event is fulfilled

These tags describe actions that affect the values of WML variables
(see [[VariablesWML]] for information on WML variables,
and [[UtilWML]] for convenient macro shortcuts for some of these):
* '''[set_variable]''' manipulates a WML variable.
** ''name'' the name of the variable to manipulate
** ''value'' set the variable to the given value (can be numeric or string). This only interprets dollars signs if it is the very first character, and then the entire value must be a simple variable name. (in 1.3.2, has the same effect as format. Use literal for no substitution)
** ''literal'' set the variable to the given value (can be numeric or string). This does not interpret any dollars signs. {{DevFeature}}
** ''format'' set the variable to the given value. Interprets the dollar sign to a higher degree than most actions. (see [[VariablesWML]])
** ''to_variable'' Fully processes its value as in ''format'', and then gets the variable with that name.
** ''add'' add the given amount to the variable. To subtract, add a negative number.
** ''multiply'' multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer.
** ''divide'' {{DevFeature}} divide the variable by the given number. The result is an integer.
** ''modulo'' {{DevFeature}} returns the remainder of an integer division. Both variables need to be an integer, the result is also an integer. eg 5 % 2 = 1.
** ''random'' the variable will be randomly set.<br>You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'.<br>You may provide a range of numbers (integers), e.g. 'random=3..5'.<br>You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.
** ''time=stamp'' {{DevFeature}} Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.

* '''[store_unit]''' stores details about units into game variables.<br>Common usage is to manipulate a unit by using [store_unit] to store it into a variable, followed by manipulation of the variable, and then [unstore_unit] to re-create the unit with the modified variables.<br>Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]]
** '''[filter]''' (standard unit filter) all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.
** ''variable'' the name of the variable into which to store the unit(s)
** ''mode'' defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.
** ''kill'' if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.
:When a unit is stored, the following values may be manipulated with '''[set_variable]'''
:* description
:* experience
:* facing
:* gender
:* canrecruit
:* overlays
:* goto_x
:* goto_y
:* hitpoints
:* moves
:* resting
:* side
:* type
:* unrenamable
:* upkeep
:* user_description
:* x
:* y
:* [variables]
:* [status]
:* [modifications]
Variables, status, and modifications are children of the stored unit variable. Example:
[set_variable]
name=unit_store.status.poisoned
value=yes
[/set_variable]

:All keys and tags in the unit definition may be manipulated, including some others. Here is a sample list. If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file.
:* advanceto
:* alignment
:* alpha
:* attacks_left
:* canrecruit
:* controller
:* cost
:* description
:* experience
:* facing
:* flying
:* fog
:* gender
:* get_hit_sound
:* gold
:* goto_x
:* goto_y
:* hitpoints
:* id
:* image
:* image_defensive
:* income
:* language_name (same as the name key in the unit config)
:* level
:* max_attacks
:* max_experience
:* max_hitpoints
:* max_moves
:* movement
:* movement_type
:* moves
:* race
:* resting
:* shroud
:* side
:* team_name
:* type
:* unit_description
:* unrenamable
:* usage
:* value
:* x
:* y
:* zoc
:* [advancement]
:* [/advancement]
:* [movement_costs]
:* [/movement_costs]
:* [defense]
:* [/defense]
:* [resistance]
:* [/resistance]
:* [variables]
:* [/variables]
:* [status]
:* [/status]
:* [attack]
:* [/attack]
:* [modifications_description]
:* [/modifications_description]
:* [modifications]
:* [/modifications]

* '''[store_starting_location]''' Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', and 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed)
** ''side'' the side whose starting location is to be stored
** ''variable'' (default='location'): the name of the variable to store the location in
* '''[store_locations]''' Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type).
** standard location filter- a location or location range which specifies the locations to store. You must specify this or no locations will be stored.
** ''variable'' the name of the variable (array) into which to store the locations
** ''terrain'' a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, locations will only be chosen if the letter of the terrain type of that location is listed. '''''[[User:SkeletonCrew#Branch_terrain|(SVN terrain only)]]''''' Here the list will be a comma separated list of terrains.
** ''radius'' if present, any locations which are within ''radius'' hexes of the location filter will also be stored
** '''[filter]''' (standard unit filter) only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.
* '''[store_villages]''' {{DevFeature}} Stores a series of locations of villages that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type).
** ''side'' a side number. If present, only villages owned by this side will be choosen. If side=0, store the unowned villages.
** ''variable'' the name of the variable (array) into which to store the locations
** ''terrain'' a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, villages will only be chosen if the letter of the terrain type of that location is listed. '''''[[User:SkeletonCrew#Branch_terrain|(SVN terrain only)]]''''' Here the list will be a comma separated list of terrains.
* '''[store_gold]''' stores the gold for a certain side in a variable. ({{DevFeature}} : this tag is no longer available)
** ''side'' (default=1) the side for which the gold should be stored
** ''variable'' (default='gold') the name of the variable to store the gold in
* '''[store_side]''' stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income'.
** ''side'' the side whose information should be stored
** ''variable'' the name of the variable to store the information in
* '''[clear_variable]''' This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario.<br> Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.
** ''name'' the name of the variable to clear.
* '''[role]''' tries to find a unit to assign a role to.<br>This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]).<br>However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [if]) to see whether a role was assigned. This tag uses a Standard Unit Filter with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.
** ''role'' the value to store as the unit's role. This role is not used in the Standard Unit Filter when doing the search for the unit to assign this role to.
** ''type'' a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.

== See Also ==
* [[VariablesWML]]
* [[DirectActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

FAQ

2006-10-07T15:56:17Z

Tsr: /* How do i connect to a multiplayer server, when i sit behind a restrictive Firewall? */ Added TCP detail

=Frequently Asked Questions=

== General ==

===What is Battle for Wesnoth?===
Battle for Wesnoth is a fantasy turn-based strategy game.

===What license is the game distributed under?===
The project is distributed under the [http://www.fsf.org/copyleft/gpl.html GPL]. All contributors retain copyright on the portions of the project that they contribute.

===How to get informed about new releases?===
Subscribe to new releases at [http://freshmeat.net/subscribe/38720/?url=%2Fprojects%2Fwesnoth%2F Freshmeat].

===A new version is out, but where is the download for [Windows, Mac OS, etc.]?===
The downloads are NOT part of the official project. The BFW team only releases the game's source code. Binary executables or applications are always contributed by community volunteers. If not for these volunteers, there would never be any downloads for us to enjoy. The volunteers compile the game and upload it on their own time, and sometimes they cannot do this in a timely fashion (or at all, at times) Although there are usual packagers designated for each operating system, there are times when other members of the community are asked to step in and contribute when the usual people cannot.

Every time a new version is released, the usual volunteers are always notified by the project leaders. '''Please refrain from making forum posts asking where your download is''' because it doesn't help anything - the packagers already know, and they will get to it as soon as they can. In the past, the Windows and Mac communities have come together to produce home-grown unofficial builds for the community to use, and the renewed interest in community and learning how to compile is generally a good thing.

===Why doesn't Wesnoth have my favorite feature?===
Because we are building this game for ourselves, to suit our own preferences. We're not building the game for you, in large part because this is our hobby, not our job; whether you like it or not is immaterial to us.
You may wonder, then, what the point is of soliciting ideas, as we do on the forum. We, the developers, have certainly come up with many good ideas on our own, but our players often do as well, and generally ones we don't think of ourselves. If a player comes up with an idea we like, we might implement it. Not because they asked for it, but because of its own merits as an addition to our game.

The beautiful thing about the license our game is distributed under, as compared to closed-source, commercial games, is that if you want that feature badly enough, you can take the code and art of our game and modify it yourself; you are free to re-use any work in Wesnoth, as long as you follow the rules of the [http://www.fsf.org/copyleft/gpl.html GPL]. From this, you can build a game exactly the way that you like. Just don't expect us to build that game for you. Building this game is our hobby, not our profession, and you did not pay us to make it; rather, we are the ones who have paid for it, in time and labor.

===Do you want help making this game? How can I help?===
Yes, we want your help. Whether you're a programmer, artist, musician, writer, translator, level designer, playtester, or just have some great suggestions, you're welcome to contribute. How? You can:
* join the [http://www.wesnoth.org/wiki/Project Project]
* share your point of view at the [http://www.wesnoth.org/forum/ Forum]
* talk with us on [irc://irc.wesnoth.org/wesnoth IRC]
* report bugs you find at [[ReportingBugs]]
* update the wiki
* play against us via the Multiplayer menu
* vote for Wesnoth at your favorite gaming web site
* Spread the word!

=== What are the system requirements? ===

We are not completely certain, but an x86 running at 400 MHz with 128MB RAM should be adequate for versions 1.02 and below. For versions 1.1 and up we recommend a computer with at least 1 GHz and 512 MB RAM if you run KDE or Gnome as Windowmanager (The game itself needs about 100 MB RAM). Slower machines will have trouble scrolling large maps or processing AI turns with many units. See the [http://www.wesnoth.org/forum/viewtopic.php?t=7384 forum thread] about minimum and recommended system requirements.

=== I'm bored; how do I speed the game up? ===

There are several preferences you can change to shorten the time that the AI takes to make its moves. "Accelerated Speed" will make units move and fight faster. "Skip AI Moves" will not show the AI's units moving from hex to hex. Finally, you can turn off all combat animations via the "Show Combat" option on the Advanced tab.

=== My computer is too slow; how do I speed the game up? ===

First, turn off the music and sound effects. Turning off the color cursors will make your cursor respond faster. If scrolling the map is slow, run the game in "Full Screen" mode, not in a window. Turn off combat animations via the "Show Combat" option on the Advanced tab. You can try turning off halos and combat results, but this might make gameplay more difficult.

== Gameplay and Controls ==

=== How do I learn to play? ===

If you just want to jump right in, start the game and play the tutorial. If you like reading documentation, see [[WesnothManual]], which is also distributed as a PDF file. At any time while playing, you can select help from the menu button (or hit F1). The online help is quite extensive and provides information on terrains, weapons, traits, abilities, units and a good overview of how to play.

=== My unit leveled up but didn't improve. What happened? ===

This is called "After Maximum Level Advancement" or AMLA for short. While most level 0, 1, and 2 units can advance, some cannot. However, some level 3 units can advance to level 4, or even 5. You can see whether a unit can advance further by right clicking and selecting "description."

After a unit reaches the highest level it can get, every time it gains 100 experience it gains 3 hitpoints. It does not heal when this happens. This is a minor bonus so that experience gained by maxed out units is not altogether wasted. It is generally better to give experience to lower level units, rather than continue to advanced units that have reached their maximum level.

If the unit in question is the Necrophage, this is not a bug. The Necrophage eats the corpses of the dead, allowing it to periodically completely heal. Leveling into itself is how this is carried out.

=== I tried to trap an enemy with several weak units, but it still escaped. What happened? ===

Most units exert a zone of control (or ZOC). IF an enemy moves into one of the six adjacent hexes, the zone of control will prevent it from moving any farther. However some weak units are level 0, meaning they are so weak that they do not have a ZOC. You can still surround an enemy unit entirely with level 0 units to keep it from escaping, but if there is any gap in your ranks, it could escape.

Also, some units have the "skirmish" ability, which allows them to ignore ZOCs.

=== How can I see where an enemy unit can move next turn? ===

During you turn you can click on an enemy unit. Wesnoth will highlight all the hexes the unit can move to in the next turn. This is useful when trying to arrange your units to block an enemy's movement.

=== There's too much luck in this game! ===

Sooner or later, you will become frustrated when your archmage with four 70% attacks misses all four times. This does not mean that the AI is cheating or the random number generator is futzed. It means you are noticing random negative events more than positive ones. During the development of the game, many mathematicians have done sophisticated statistical analysis of the combat system. Likewise, programmers have examined the random number generator. No flaws have been found, so streaks of "bad" and "good" luck should just be accepted as part of having randomness in Wesnoth.

Since Wesnoth is GPLed, it is possible that a new development team will someday "fork" the source and produce a version more like Heroes of Might & Magic, with less or no randomness. Until then, don't charge with your horsemen against troll rocklobbers at night...

=== The (random unit) is overpowered/underpowered! ===

The development team has spent years tweaking the units in the game. Each unit has had its gold cost, attack types, combat damage, defensive values, resistances, upgrade paths, and other stats carefully scrutinized and loudly discussed in the forum. However, the game code and the units were being modified right up until the 1.0 release, so some unbalanced units may have slipped through.

If you have evidence to back up your claim, search the forum for past discussions about this unit, and then try posting.

=== The (random scenario) is too hard/easy! ===

See above answer about random units.

=== What do the different difficulty levels do? ===

That depends on the scenario. Usually, the opponent will get more money and be able to recruit higher-level units at higher difficulty levels, and you will have fewer turns available.

== Maps, Scenarios and Campaigns ==

=== How do I beat scenario _______ ? ===

If you are stuck on a scenario in a campaign, you'll probably find a walkthrough at [[MainlineScenarios]]. Or check out the "Strategies and Tips" forum at http://www.wesnoth.org/forum/viewforum.php?f=3

=== Are there any tools to help me create maps and scenarios? ===
Yes, there is a tool called wesnoth_editor. It is a normal map-editor that should be a good help for creating the plain maps. For creating the scenarios there already is a scenario-editor included in the mac build. But this editor is rather outdated and it exists only for MacOS X. At the moment some community members are working on creating a nice and working scenario editor. You can have a look at the [http://www.wesnoth.org/forum/viewtopic.php?t=6925 forum post] about this tool. You will also find more info at [[CampGen]].

=== How do I download user campaigns? ===
Choose "Campaigns" in the main Wesnoth menu. Then scroll down to the bottom and choose "Get More Campaigns..." or since 1.1.5 there is a "Get add-ons" button in the main menu. This connects you to the campaign server. In the campaign server you can view a list of all available campaigns and download them, as well as posting or deleting your own campaigns.

If you are behind a firewall you may not be able to connect to the campaign server. In this case try to download the campaign directly from the campaign server through the web interface at http://wolff.to/campaigns/list.html. If you know how to change your firewall settings, then you should open port 15003 (version 1.1.1 and up) or port 15002 (versions 1.1.0 and lower). For added security, you can restrict traffic over those ports to the campaign server's IP address (currently 88.191.12.200).

=== I already created a campaign and published it on the campaign server. How can I get translations for the campaign? ===
Just have a look at [[WesCamp]]. This project is the easiest way to get translations for your campaign. All the info you need you can find at [[WesCamp]].

===How do I place an object or unit on my map with the map editor?===
You can't. You need to make a multiplayer scenario file. There are more details on the [[BuildingMaps|maps]] page.

== Multiplayer ==

===How do i connect to a multiplayer server, when i sit behind a restrictive Firewall?===

You have to open for TCP on port 14999 to play multiplayer games over the internet. For added security, you can restrict access to the server's IP address (currently 84.207.24.9 for the official server).

===How to find players for multiplayer game?===
Hang around for a while on multiplayer servers and you might find someone to play with. If you observe other people playing you will get informed when someone joins the servers. Maybe you find someone willing to play in the irc channel dedicated to mp: #wesnoth-mp at irc.freenode.net.
You can also join #wesnoth at irc.freenode.net.

===How to save and load a multiplayer game===

Save the game. Give it a good name, so that you can find it among the other saved games.

Create new game. (Give it a name like "private game for X and Y", so that other players will not try joining it, and you do not have to explain or kick them.) The first item in the map/scenario list is "Saved games", select this. Choose the saved game. Wait for the other player(s) to connect. Start the game.

===How can I make my computer into a dedicated Wesnoth server?===

To setup a dedicated Wesnoth server, you have to compile the game with the "--enable-server" flag, and after you install, simply run wesnothd from the console. This will start the server, listening on TCP port 15000. To compile the server only you can use the flags "--disable-game --enable server". If you aren't using a linux or mac operating system, there are a few ways you can compile on Windows...here is one way http://www.wesnoth.org/wiki/CompilingWesnoth/CrossCompiling

===Which versions of Wesnoth can play together?===

I'm on a MAC, and my friends are on XP. I would like to play together with them. Is this currently possible?

YES! All you need is to have the same version number.

For a list of Mac-XP-compatible games (including BfW) see: http://www.insidemacgames.com/forum/index.php?showtopic=21818

== Translations ==

===I selected an asian translation and am not able to see the letters correctly. What happened?===

Since the size of the necessary fonts is too large, you'll need to download them separately (if you don't already have them). After that, simply copy the font to the '''fonts/''' directory in your wesnoth installation.
* Chinese font: [ftp://cle.linux.org.tw/pub/fonts/ttf/unicode/Arphic/gkai00mp.ttf gkai00mp.ttf]
* Japanese font: [http://cvs.sourceforge.jp/cgi-bin/viewcvs.cgi/sqs-xml/sqs-font/sazanami-gothic.ttf sazanami-gothic.ttf]

If you have futher questions have a look at [[WesnothAsianLanguages|this]] page.

== Other Questions You Have ==

The best way to get answers to less-frequently asked questions is by visiting the [http://www.wesnoth.org/forum BFW forum]. There are plenty of people willing to help. Make sure you read ALL of the forum sticky notes and announcements before posting.

Download

2006-10-06T20:15:52Z

Tsr: /* Development */ added 1.1.11 in the special note header

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.

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.0.x_branch.29|Stable Branch]] | [[Download#Development|Development Branch]]

== Stable (1.0.x branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.0.x branch is compatible to each other. This will not happen in the development branch.

Version 1.0.2 is the latest stable version, updated with several important bugfixes. This version is recommended for most players since the 1.0.x online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.0.2.tar.gz?download Current stable version] (1.0.2, 38.2 MB)
* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== [[BeOS]] ====
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth-1.0.2-BeOS-x86.pkg.zip?download Current stable version] (1.0.2, 42.3MB)

==== GNU/Linux ====
* There are specific 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 informations about the binaries for your Distribution.

==== Mac OS X ====
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.0.2.dmg?download Current stable version] (1.0.2, PPC, 53.6 MB)
* [http://lwa.retiaire.org/wesnoth/Wesnoth_MacOSX_1.0.2-lwa.dmg Current stable version - alternate] (1.0.2, PPC, 44MB)
* [http://lwa.retiaire.org/wesnoth/Wesnoth_MacOSX_1.0.2_lite-lwa.dmg Current stable version - lite] (1.0.2, PPC, no art or music, 25MB)

==== MS Windows ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-windows-1.0.2.exe?download Current stable version] (1.0.2, 37.0MB)

==== FreeBSD ====
* /usr/ports/games/wesnoth (1.0.1, 37.3MB)

==== Miscellaneous ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.0.2.tar.gz.md5?download Source code md5sum]
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth-1.0.2-BeOS-x86.pkg.zip.md5?download BeOS md5sum]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Source_code Xdelta for the source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#MS_Windows Xdelta for the Windows binary]

== Development ==
'''Special note for 1.1.8-1.1.11'''

These versions are "stable beta" or "release candidate" versions. They exist so we can iron out bugs, but they will be very close to the final stable 1.2 release. They are generally balanced, stable, and bug-free, but we need your help to catch any remaining problems (which may or may not exist). Do not be afraid to download or play one of these later versions. The next paragraph is our "stock" paragraph about the development version, but because it is so late in the development cycle it's currently not 100% true (whereas it was very true for earlier releases).
<BR><BR><BR>
Version 1.1.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.0.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth.

==== Source code ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.1.11.tar.gz?download Current Version] (1.1.11, 73 MB)
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.1.10.tar.gz?download Previous Version] (1.1.10, 72 MB)
* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.1.11-windows.exe?download Current Version] (1.1.11, 60.7 MB)
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.1.10-windows.exe?download Previous Version] (1.1.10, 59.3 MB)

==== Mac OS X ====
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.1.11.dmg?download Current Version] (1.1.11, Universal, 75.6MB)
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.1.11_lite.dmg?download Current Version - lite] (1.1.11, Universal, no art or music, 45.7MB)
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.1.10.dmg?download Previous Version] (1.1.10, Universal, 74MB
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.1.10_lite.dmg?download Previous Version - lite] (1.1.10, Universal, no art or music, 44.1MB)

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

==== AmigaOS4 ====
* [http://www.amigasoft.net/downloads/Wesnoth.lzh Older Version] (1.1.7, 79MB)

==== OS/2 & eComStation ====
* [http://download.smedley.info/wesnoth-1.1.8-os2.zip Previous Version] (1.1.8, 66MB)

==== Miscellaneous ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.1.11.tar.gz.md5?download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Source_code Xdelta for the source code]
* [http://sourceforge.net/project/showfiles.php?group_id=89495 SourceForge page for current and all previous versions]

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

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

Download

2006-09-21T13:21:40Z

Tsr: /* Source code */

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.

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.0.x_branch.29|Stable Branch]] | [[Download#Development|Development Branch]]

== Stable (1.0.x branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.0.x branch is compatible to each other. This will not happen in the development branch.

Version 1.0.2 is the latest stable version, updated with several important bugfixes. This version is recommended for most players since the 1.0.x online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.0.2.tar.gz?download Current stable version] (1.0.2, 38.2 MB)
* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== [[BeOS]] ====
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth-1.0.2-BeOS-x86.pkg.zip?download Current stable version] (1.0.2, 42.3MB)

==== GNU/Linux ====
* There are specific 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 informations about the binaries for your Distribution.

==== Mac OS X ====
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.0.2.dmg?download Current stable version] (1.0.2, PPC, 53.6 MB)
* [http://lwa.retiaire.org/wesnoth/Wesnoth_MacOSX_1.0.2-lwa.dmg Current stable version - alternate] (1.0.2, PPC, 44MB)
* [http://lwa.retiaire.org/wesnoth/Wesnoth_MacOSX_1.0.2_lite-lwa.dmg Current stable version - lite] (1.0.2, PPC, no art or music, 25MB)

==== MS Windows ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-windows-1.0.2.exe?download Current stable version] (1.0.2, 37.0MB)

==== FreeBSD ====
* /usr/ports/games/wesnoth (1.0.1, 37.3MB)

==== Miscellaneous ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.0.2.tar.gz.md5?download Source code md5sum]
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth-1.0.2-BeOS-x86.pkg.zip.md5?download BeOS md5sum]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Source_code Xdelta for the source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#MS_Windows Xdelta for the Windows binary]

== Development ==
'''Special note for 1.1.8-1.1.10'''

These versions are "stable beta" or "release candidate" versions. They exist so we can iron out bugs, but they will be very close to the final stable 1.2 release. They are generally balanced, stable, and bug-free, but we need your help to catch any remaining problems (which may or may not exist). Do not be afraid to download or play one of these later versions. The next paragraph is our "stock" paragraph about the development version, but because it is so late in the development cycle it's currently not 100% true (whereas it was very true for earlier releases).
<BR><BR><BR>
Version 1.1.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.0.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth.

==== Source code ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.1.10.tar.gz?download Current Version] (1.1.10, 72 MB)
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.1.9.tar.gz?download Previous Version] (1.1.9, 70 MB)
* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.1.9-windows.exe?download Current Version] (1.1.9, 59.1 MB)
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.1.8_windows.exe?download Previous Version] (1.1.8, 58.7 MB)

==== Mac OS X ====
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.1.9.dmg?download Current Version] (1.1.9, Universal, 73.2MB)
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.1.9_lite.dmg?download Current version - lite] (1.1.9, Universal, no art or music, 43.3MB)
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.1.8.dmg?download Previous Version] (1.1.8, Universal, 69MB) ([http://www.wesnoth.org/forum/viewtopic.php?t=12237&start=11 note for Japanese players])
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.1.8_lite.dmg?download Previous version - lite] (1.1.8, Universal, no art or music, 39MB)

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

==== AmigaOS4 ====
* [http://www.amigasoft.net/downloads/Wesnoth.lzh Older Version] (1.1.7, 79MB)

==== OS/2 & eComStation ====
* [http://download.smedley.info/wesnoth-1.1.8-os2.zip Previous Version] (1.1.8, 66MB)

==== Miscellaneous ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.1.9.tar.gz.md5?download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Source_code Xdelta for the source code]
* [http://sourceforge.net/project/showfiles.php?group_id=89495 SourceForge page for current and all previous versions]

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

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

Download

2006-09-21T13:17:10Z

Tsr: /* Development */ Incorporated 1.1.10

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.

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.0.x_branch.29|Stable Branch]] | [[Download#Development|Development Branch]]

== Stable (1.0.x branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.0.x branch is compatible to each other. This will not happen in the development branch.

Version 1.0.2 is the latest stable version, updated with several important bugfixes. This version is recommended for most players since the 1.0.x online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.0.2.tar.gz?download Current stable version] (1.0.2, 38.2 MB)
* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== [[BeOS]] ====
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth-1.0.2-BeOS-x86.pkg.zip?download Current stable version] (1.0.2, 42.3MB)

==== GNU/Linux ====
* There are specific 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 informations about the binaries for your Distribution.

==== Mac OS X ====
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.0.2.dmg?download Current stable version] (1.0.2, PPC, 53.6 MB)
* [http://lwa.retiaire.org/wesnoth/Wesnoth_MacOSX_1.0.2-lwa.dmg Current stable version - alternate] (1.0.2, PPC, 44MB)
* [http://lwa.retiaire.org/wesnoth/Wesnoth_MacOSX_1.0.2_lite-lwa.dmg Current stable version - lite] (1.0.2, PPC, no art or music, 25MB)

==== MS Windows ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-windows-1.0.2.exe?download Current stable version] (1.0.2, 37.0MB)

==== FreeBSD ====
* /usr/ports/games/wesnoth (1.0.1, 37.3MB)

==== Miscellaneous ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.0.2.tar.gz.md5?download Source code md5sum]
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth-1.0.2-BeOS-x86.pkg.zip.md5?download BeOS md5sum]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Source_code Xdelta for the source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#MS_Windows Xdelta for the Windows binary]

== Development ==
'''Special note for 1.1.8-1.1.10'''

These versions are "stable beta" or "release candidate" versions. They exist so we can iron out bugs, but they will be very close to the final stable 1.2 release. They are generally balanced, stable, and bug-free, but we need your help to catch any remaining problems (which may or may not exist). Do not be afraid to download or play one of these later versions. The next paragraph is our "stock" paragraph about the development version, but because it is so late in the development cycle it's currently not 100% true (whereas it was very true for earlier releases).
<BR><BR><BR>
Version 1.1.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.0.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth.

==== Source code ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.1.10.tar.gz?download Current Version] (1.1.10, 70 MB)
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.1.9.tar.gz?download Current Version] (1.1.9, 70 MB)
* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.1.9-windows.exe?download Current Version] (1.1.9, 59.1 MB)
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.1.8_windows.exe?download Previous Version] (1.1.8, 58.7 MB)

==== Mac OS X ====
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.1.9.dmg?download Current Version] (1.1.9, Universal, 73.2MB)
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.1.9_lite.dmg?download Current version - lite] (1.1.9, Universal, no art or music, 43.3MB)
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.1.8.dmg?download Previous Version] (1.1.8, Universal, 69MB) ([http://www.wesnoth.org/forum/viewtopic.php?t=12237&start=11 note for Japanese players])
* [http://prdownloads.sourceforge.net/wesnoth/Wesnoth_MacOSX_1.1.8_lite.dmg?download Previous version - lite] (1.1.8, Universal, no art or music, 39MB)

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

==== AmigaOS4 ====
* [http://www.amigasoft.net/downloads/Wesnoth.lzh Older Version] (1.1.7, 79MB)

==== OS/2 & eComStation ====
* [http://download.smedley.info/wesnoth-1.1.8-os2.zip Previous Version] (1.1.8, 66MB)

==== Miscellaneous ====
* [http://prdownloads.sourceforge.net/wesnoth/wesnoth-1.1.9.tar.gz.md5?download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Source_code Xdelta for the source code]
* [http://sourceforge.net/project/showfiles.php?group_id=89495 SourceForge page for current and all previous versions]

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

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

ThemeWML

2006-08-19T22:41:08Z

Tsr: /* [menu] */ spelling 'senter' -> 'center'

{{WML Tags}}
== the toplevel [theme] tag ==

Themes are used both for the wesnoth game and the wesnoth editor.
Themes allow flexible configuration of how everything is laid out on-screen.

The only key in [theme] is ''name''. This is the name of the theme.

The only tag in [theme] is '''[resolution]''', but each theme can have multiple [resolution] tags.
The [resolution] tags are scanned until the first one which is of the same or lower resolution than is currently being used is found, and this is used as our theme.
This allows us to define themes to work differently on different resolutions,
and will allow us to support both high and low resolutions elegantly.

The following keys and tags are recognized for [resolution]:

* ''width//,//height'' dimensions in pixels

All subtags of [resolution] use the following keys:
* ''rect'' defines the rectangle to display on. Parts of a ''rect=a,b,c,d'' clause may be:
** number : absolute positions
** ''='' : same value as the same field in reference rect (alignment with reference)
** +number or -number : for a and b, add this value to reference's c and d respectively (spacing from reference)
; for c and d, add this value to self's a and b (specify by width and height)
** =+number or =-number : add this value to same field in reference rect (eg. consider reference as a container box)
* ''xanchor//,//yanchor'' control the behavior of how this rectangle changes as the resolution changes.
** 'left' its distance from the left side of the screen always remain the same, while changes in the resolution will change its size by the same amount (top for the y axis).
** 'right' its size always remain the same, as well as its distance to the right side of the screen (bottom for the y axis).
** 'fixed' its co-ordinates in that axis remain constant
** 'proportional' its co-ordinates multiplied by the ratio of the resolution being used to the canonical resolution.

== [main_map] ==

defines where the main game display (i.e. all the hexagons and units) is displayed.

== [mini_map] ==

determines where the mini map is displayed

== [panel] ==

displays an image as a panel on-screen.
* ''image'' the image used for the panel

== [label] ==

displays a text label on screen.
* ''prefix'' a string that will be printed before the text in all language
* ''text'' a text string id to be displayed
* ''postfix'' a string that will be printed after the text in all language
* ''icon'' an image that will be displayed instead of the text if it is available
* ''font_size'' the size of font to use for the label

== [menu] ==

* ''title'' the id of the string to write on the button
* ''title_literal'' a string that will be displayed "as is" in all language after the title
* ''image'' the image to use if available
* ''is_context_menu'' if set to true this menu will not be placed, but displayed on a right click
* ''items'' comma separated list of actions to put in the menu. if there is only one action, it will be executed immediately and no menu will be displayed
** 'cycle' move to next movable unit
** 'endunitturn' consume this unit's move and cycle to the next one
** 'leader' center on the leader
** 'undo' undo last action
** 'redo' redo undone action
** 'zoomin' zoom the map in
** 'zoomout' zoom the map out
** 'zoomdefault' return to default zoom
** 'fullscreen' switch fulscreen mode
** 'accelerated' switch turbo mode
** 'resistance' show resistance table of current unit
** 'terraintable' show terrain table of current unit
** 'describeunit' show unit description
** 'renameunit' change unit name
** 'save' save the game
** 'recruit' recruit a unit
** 'repeatrecruit' repeat last recruitement
** 'recall' recall a unit from previous scenarion
** 'endturn' end current turn
** 'togglegrid' toggle grid display
** 'statustable' show status table
** 'mute' mute all sounds
** 'speak' send message to other players
** 'createunit' debug create a unit on the map
** 'preferences' open preference dialog
** 'objectives' show objective window
** 'unitlist' list units
** 'statistics' show game statistics
** 'quit' quit the game
** 'labelterrain' label current location
** 'clearlabels' clear all labels on map
** 'showenemymoves' show grids reachable by the enemy
** 'bestenemymoves' show grids reachable by the enemy with no zone of control
** 'editnewmap' editor only start a new map
** 'editloadmap' editor only loads an existing map
** 'editsavemap' editor only saves the current map
** 'editsaveas' editor only saves the current map, let you choose a filename
** 'editsetstartpos' editor only set a starting position for a team
** 'editfloodfill' editor only flood the map with a terrain
** 'toggleshroud' toggle the "moving removes shroud" behaviour
** 'updateshroud' removes all possible shroud
** 'AUTOSAVES' expands to a list of all Auto-Save games prior to this one (1.1.3+)

== [status] ==

This tag describes the Status Table.
This tag contains many other tags, which determine where other game statistics, such as the current turn, and a description of selected units go.
For instance, the [time_of_day] tag will determine where the time of day image goes.
Each subtag of [status] can contain the following attributes

** ''font_size'' the size of font to use for the status
** ''rect'' the rectangle as for the main_map attribute
** ''xanchor'' the x-wise anchoring as for the main_map attribute
** ''yanchor'' the y-wise anchoring as for the main_map attribute
** ''prefix'' the string to display before the actual status, this is the string id for internationalisation
** ''prefix_literal'' a string to put after the prefix, but before the label for all languages.
** ''postfix_literal'' a string to put after the status
** ''postfix'' the string to display after the postfix_literal, this is the string id for internationalisation

the following tags are recognized for [status]:
* '''[unit_description]''' the user description of the current unit
* '''[unit_type]''' the type of the current unit
* '''[unit_level]''' the level of the current unit
* '''[unit_traits]''' the traits of the current unit
* '''[unit_status]''' the status of the current unit
* '''[unit_alignment]''' the alignment of the current unit
* '''[unit_abilities]''' the abilities of the current unit
* '''[unit_hp]''' the HP of the current unit
* '''[unit_xp]''' the XP of the current unit
* '''[unit_moves]''' the moves remaining for the current unit
* '''[unit_weapons]''' the attacks of the current unit
* '''[unit_image]''' the icon for the current unit
* '''[unit_profile]'''
* '''[time_of_day]''' the time of day on the current location
* '''[turn]''' the turn number and turn remaining
* '''[gold]''' the gold remaining
* '''[villages]''' the number of villages owned
* '''[num_units]''' the number of units owned
* '''[upkeep]''' the money needed to keep your units every turn
* '''[expenses]''' the money lost each turn when you don't have enough income
* '''[income]''' the income per turn (can be positive)
* '''[terrain]''' the text description of the current terrain
* '''[position]''' the current terrain's position
* '''[side_playing]''' the current playing side
* '''[observers]''' the current observers

== See Also ==

* [[ThemeSystem]]
* [[Using custom themes in campaigns]]
* [[ReferenceWML]]

[[Category: WML Reference]]

Talk:UsefulWMLFragments

2006-08-14T08:33:30Z

Tsr: 2 suggestions

I'm thinking that it would be good to have all pages linked also link back. It would also be good to add this page to the Category: WML, opinions? /tsr

Talk:EffectWML

2006-08-12T17:34:25Z

Tsr:

Ok, don't know if this is the correct place, but I'll give it a try. I noticed that this page doesn't have the WML-menu that the other WML-pages have. I don't know how to fix this, but if anyone shows me I'd be happy to do it. /tsr

It's the ''<nowiki>{{WML Tags}}</nowiki>'' that includes the menu (placed at the top, as you can see on the other pages). /zookeeper

Ok, thanks, now it's fixed. /tsr

EffectWML

2006-08-12T17:33:08Z

Tsr: Added the wml-menu

{{WML Tags}}
== the [effect] tag ==

The tag [effect] is used to describe one modification to a unit.
Any number of [effect] tags can be used to describe a complete
modification.
Modifications are permanent changes to a unit;
currently there is no way of removing a modification.

The following keys are always recognized for [effect]:
* ''unit_type'' only apply this effect if the affected unit's type name matches ''unit_type'' (can be a list of types).
* ''apply_to'' describes what the effect actually affects.
[effect] uses different keys depending on the value of ''apply_to''. ''apply_to'' can take the following values:
* "new_attack" will use all other keys and tags as the description of an attack that will be added to the unit. See [[AttackWML]].
* "attack" find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** ''set_name'' change the attack's name.
** ''set_type'' change the attack type. Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'holy'.
** ''set_special'' change the attack's specials. See [[AbilitiesWML]] for a list of possible values. (depreciated in v1.3+ or SVN trunk)
** ''[set_specials]'' (v1.3+ or SVN trunk only) change the attack's specials. The specials to add are given exactly as in the [specials] tag.
*** ''mode'' if ''append'', adds the given specials to the attack. If ''replace'', replaces the existing specials with the given ones. Default ''replace''.
** ''remove_specials'' (v1.3+ or SVN trunk only) remove the listed specials. The value of this key is the coma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** ''increase_damage'' increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** ''increase_attacks'' increases the number of attack strikes. Like ''increase_damage'', it can be positive or negative, or a percentage.
** ''attack_weight'' {{DevFeature}} change the attack's attack_weight. See [[AttackWML]] for explainations about attack_weight.
** ''defense_weight'' {{DevFeature}} change the attack's defense_weight. See [[AttackWML]] for explainations about defense_weight.
* "hitpoints" modifies the unit's HP and/or max HP.
** ''increase'' the amount to increase the unit's HP.
** ''heal_full'' if present and not set to "no" the unit will be put back to full HP.
** ''increase_total'' will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** ''violate_max'' it the unit ends up with more than its max HP after these modifications, and this key is present, the unit's HP won't be lowered to its max HP.
* "movement" modifies the unit's movement points.
** ''increase'' maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** ''set'' maximum movement is set to a specific value.
* "max_experience" affects the amount of XP the unit needs for the next level.
** ''increase'' how to change the xp; again it can be negative, positive or a percentage.
* "loyal" no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* "movement_costs" {{DevFeature}} speed through specific terrain is modified
** ''replace'' If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** [set_specials]
** [movement_costs] a subtag that describes the new movement costs just like in [[UnitWML]] for describing a unit type
* "defense" {{DevFeature}} Sets unit chance to be hit in specific terrain (100 - defense value)
** ''replace'' If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** [defense] a subtag that describes the new defense just like in [[UnitWML]] for describing a unit type
* "resistance" {{DevFeature}} Sets percent damage taken from combat
** ''replace'' If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** [resistance] a subtag that describes the new resistance just like in [[UnitWML]] for describing a unit type
* "variation" switches the unit into one of its variations.
** ''name'' the name of the variation to invoke.
* "status" modifies the status affecting the unit.
** ''add'' a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** ''remove'' a list of status modifications to remove.

== See Also ==

* [[UnitWML]]
* [[AttackWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

Talk:EffectWML

2006-08-10T13:39:41Z

Tsr: WML-menu where are you?

InterfaceActionsWML

2006-08-10T13:36:15Z

Tsr: /* See Also */ Added Category WML

EffectWML

2006-08-10T13:34:46Z

Tsr: /* See Also */ Added Category WML

== the [effect] tag ==

The tag [effect] is used to describe one modification to a unit.
Any number of [effect] tags can be used to describe a complete
modification.
Modifications are permanent changes to a unit;
currently there is no way of removing a modification.

The following keys are always recognized for [effect]:
* ''unit_type'' only apply this effect if the affected unit's type name matches ''unit_type'' (can be a list of types).
* ''apply_to'' describes what the effect actually affects.
[effect] uses different keys depending on the value of ''apply_to''. ''apply_to'' can take the following values:
* "new_attack" will use all other keys and tags as the description of an attack that will be added to the unit. See [[AttackWML]].
* "attack" find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see [[FilterWML]]. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
** ''set_name'' change the attack's name.
** ''set_type'' change the attack type. Values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'holy'.
** ''set_special'' change the attack's specials. See [[AbilitiesWML]] for a list of possible values. (depreciated in v1.3+ or SVN trunk)
** ''[set_specials]'' (v1.3+ or SVN trunk only) change the attack's specials. The specials to add are given exactly as in the [specials] tag.
*** ''mode'' if ''append'', adds the given specials to the attack. If ''replace'', replaces the existing specials with the given ones. Default ''replace''.
** ''remove_specials'' (v1.3+ or SVN trunk only) remove the listed specials. The value of this key is the coma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
** ''increase_damage'' increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent(''''%''''), the change in damage will be a percentage ratio of the attack's original damage.
** ''increase_attacks'' increases the number of attack strikes. Like ''increase_damage'', it can be positive or negative, or a percentage.
** ''attack_weight'' {{DevFeature}} change the attack's attack_weight. See [[AttackWML]] for explainations about attack_weight.
** ''defense_weight'' {{DevFeature}} change the attack's defense_weight. See [[AttackWML]] for explainations about defense_weight.
* "hitpoints" modifies the unit's HP and/or max HP.
** ''increase'' the amount to increase the unit's HP.
** ''heal_full'' if present and not set to "no" the unit will be put back to full HP.
** ''increase_total'' will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
** ''violate_max'' it the unit ends up with more than its max HP after these modifications, and this key is present, the unit's HP won't be lowered to its max HP.
* "movement" modifies the unit's movement points.
** ''increase'' maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
** ''set'' maximum movement is set to a specific value.
* "max_experience" affects the amount of XP the unit needs for the next level.
** ''increase'' how to change the xp; again it can be negative, positive or a percentage.
* "loyal" no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
* "movement_costs" {{DevFeature}} speed through specific terrain is modified
** ''replace'' If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** [set_specials]
** [movement_costs] a subtag that describes the new movement costs just like in [[UnitWML]] for describing a unit type
* "defense" {{DevFeature}} Sets unit chance to be hit in specific terrain (100 - defense value)
** ''replace'' If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** [defense] a subtag that describes the new defense just like in [[UnitWML]] for describing a unit type
* "resistance" {{DevFeature}} Sets percent damage taken from combat
** ''replace'' If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
** [resistance] a subtag that describes the new resistance just like in [[UnitWML]] for describing a unit type
* "variation" switches the unit into one of its variations.
** ''name'' the name of the variation to invoke.
* "status" modifies the status affecting the unit.
** ''add'' a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [[InternalActionsWML|[store_unit]]] and [[DirectActionsWML|[unstore_unit]]], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], [[SingleUnitWML]].
** ''remove'' a list of status modifications to remove.

== See Also ==

* [[UnitWML]]
* [[AttackWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

DescriptionWML

2006-08-10T13:31:42Z

Tsr: /* See Also */ Added Category WML

{{WML Tags}}
== Description texts ==

A description is a part of the value of a menu attribute.
It is used to represent a single option in the menu which consists of an image(called the ''icon'') followed by text.

A description has the format

* ''';''' if another description precedes it

* '''*''' if it should be the default selection

* '''&''image''=''text''''' image with text description

* '''&''image''=''text''=''text2''''' image with two text descriptions

Single text items are always enclosed in '''"''', and concatenated with '''+'''. This is useful so the text can contain translateable items (the '''_''' before a text), and so it can span multiple lines.

for example:

difficulty_descriptions="&" + "elvish-fighter.png" + "=" + _"Fighter" + "=" + _"(easiest)" +
";*" + "&" + "elvish-hero.png" + "=" + _"Hero" +
";" + "&" + "elvish-champion.png" + "=" + _"Champion" + "=" + _"(hardest)"

The utility macros (see [[UtilWML]]) '''{MENU_IMG_TXT ''icon'' ''text''}'''
and '''{MENU_IMG_TXT2 ''icon'' ''text'' ''text-2''}'''
can be used to create descriptions more easily. The above example would become:

difficulty_descriptions={MENU_IMG_TXT2 "elvish-fighter.png" _"Fighter" _"(easiest)"} +
";*" + {MENU_IMG_TXT "elvish-hero.png" _"Hero"} + ";" +
{MENU_IMG_TXT2 "elvish-champion.png" _"Champion" _"(hardest)"}

== See Also ==

* [[CampaignWML]]
* [[EraWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

AiWML

2006-08-10T13:26:26Z

Tsr: /* See Also */ Added Category WML

{{WML Tags}}
== AI phases ==

When the AI does its turn, it has several 'phases'.
In debug mode, these phases are shown in the upper-left corner.

=== Combat phase ===
It decides who is in range to attack, and whether it's worth attacking them

=== Healing phase ===
It locates injured units and sees if they can be moved to villages to heal

=== Village capturing phase ===
It locates units, and sees if they are in range of villages which they can capture

=== Retreating phase ===
It sees if any units are in grave danger/hopelessly outnumbered, and if they are, it retreats them

=== Movement/targetting phase ===
It decides upon 'targets', assigns those targets values, and moves units toward targets based on how easy it is to get to the targets, and how valuable the targets are.

== the [ai] tag ==

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

The following key/tags can be used in an '''[ai]''' tag:
* ''time_of_day'' the time(s) of day when the AI should use the parameters given in this [ai] tag. Possible values are listed in data/schedules.cfg (See [[TimeWML]]).

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

* ''python_script'' is used when '''ai_algorithm''' has the value '''python_ai''', and specifies the name of the python script the AI should use. The script is looked for in the same pathes as units, specified with '''binary_path'''.

* ''recruitment_pattern'' This key takes a list containing the possible inputs 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI in what order it should recruit different types of units. The AI considers each unit to be one of these types. The type is listed in the unit file in data/units/ (See also [[UnitWML]]).

<ul><li> ''aggression'' This key affects how an AI player will fight.
<br>
It determines how an AI considers the difference between its units and its opponents
by taking the value ''1 - AI unit value in proportion to opponent unit value''.
('Unit value' here means that the AI weights its decision on the chance to kill
a unit or be killed, using a combination of its own units.)
So, to make an AI which considers its units worthless i.e.
only cares about how much damage attacks inflict,
set aggression at ''1 - 0 = 1.0''.
This is the highest meaningful value for aggression; although it is insane, it is used on many HttT levels.
If an AI set on this value can inflict 1 damage and take 0, or inflict 2 damage and take 20 himself,
he'll take the latter option.
To make an AI which considers its units equally as valuable as its opponent's i.e.
only attacks if he feels he can inflict more damage than he receives,
set aggression at ''1 - 1 = 0.0''.
Although an AI which considers its opponent's units worthless is impossible under this scheme,
an AI which, for example, considers its units twice as valuable as its opponent's
can be represented by aggression ''1 - 2 = -1.0''.
having to be able to inflict more damage than he takes for it to be worth his while.
The default is ''1 - 1/2 = 0.5'', which means the AI is content with dealing only
half the damage to his opponent of that which he himself takes.
</ul>

* ''caution'' A number 0.0 or higher (default=0.25) that affects how cautious the AI is in various ways. If it is higher, the AI will want to retreat more (especially to a better defensive terrain), it will dislike moving out of a defensive terrain to attack more, and, if grouping is enabled, it forms bigger groups to protect from enemies when going to a target.

* ''village_value'' A number 0 or higher (default=1) which determines how much the AI tries to capture villages.

* ''leader_value'' A number 0 or higher (default=3) which determines how much the AI targets enemy leaders.

* ''villages_per_scout'' A number 0 or higher which determines how many scouts the AI recruits. Defaults to 4. If 0, the AI doesn't recruit scouts to capture villages.

* ''recruitment_ignore_bad_movement'' if 'yes', the AI will not analyse the terrain to see if the unit is suitable for it.

* ''recruitment_ignore_bad_combat'' if 'yes', the AI will not analyse the units the enemy has fielded to see if the unit is suitable for fighting them.

* ''passive_leader'' if 'yes' the AI leader will never move or attack, except to obey [leader_goal]s.

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

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

* ''scout_village_targetting'' The AI multiplies the value of village targets for scouts by this value. The default is 3.

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

* ''protect_leader'' and ''protect_leader_radius'' - the way these parameters work, is to target any enemy units that come within 'protect_leader_radius' of the AI leader with a value of 'protect_leader' on the units. The default for these values are 1.0 and 20.

* '''[protect_location]''' gives the AI a location to protect. Note that the AI will NOT station any units around the location, it will only send units to attack any enemy units that come within the guarding radius of the target.
** ''x'', ''y'' standard coordinates. These indicate the location the AI is protecting,
** ''radius'' indicates the radius around it to protect
** ''value'' indicates the importance of protecting this location

* '''[protect_unit]''' gives the AI a set of units to protect. Note once again that the AI will not place units around the unit if there are no enemies nearby.
** standard unit filter- the unit(s) to protect
** ''radius'' indicates the radius around it to protect
** ''value'' indicates the importance of protecting this unit

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

* '''[avoid]''' Makes the AI avoid a specific location or unit.
** ''x'', ''y'' standard coordinates- A location for the AI to avoid moving to. The AI will never move a unit to this location except for trying to move its leader to a keep.
** standard unit filter- A set of units for the AI to avoid moving to. This feature is currently not implemented.

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

== See Also ==

* [[ReferenceWML]]

[[Category: WML Reference]]

Creating Shadows Under Units

2006-06-12T13:22:41Z

Tsr: /* The Current Method: */ added information on gaussian blur for the GIMP

by Richard Kettering (Jetryl)

Wesnoth's shadows have evolved through several different iterations of "how they are drawn". This tutorial covers both a quick history of what was done in the past to draw shadows, and what the current "official" method is. As a general note, it should be mentioned that the shadows are part of the same image file as the unit graphics.

===History:===

Wesnoth, at first, used a binary transparency system - a pixel was either completely opaque, or completely see-through (transparent). This is not unlike what .gif images use, in terms of the final effect. The first system actually assigned one color (pure black, for those who are interested) as the transparent color, and anywhere where such a pixel was found in a game image, the engine would not draw it.

The next step was fairly obvious - wesnoth uses the PNG image format, which allows a special part of the image to be built-in to the file. This is essentially another image which tells the computer how transparent each pixel in the image is, and it is called an Alpha Channel. This "alpha channel" is a grayscale image, meaning that each pixel can be set to be not only either completely opaque or completely transparent, but also anywhere in-between. At first, we converted all of our images to PNG, but used only binary transparency. Our shadows were jet black, and obscured the ground completely.

As code support came, we switched to our next system, in which many of our images are in at the time of this writing. This set the shadow of a unit to be 60% opaque, allowing the ground beneath to show through, and looked rather good.

As our terrain improved, however, this began to show its limitations. The shadows had hard edges which were forced to lie on pixel boundaries. This looks unnatural for some of the situations in which we use it, and as such, we moved to our current system. This is simple, has a clear procedure which can be followed to generate it rapidly and correctly, and looks good in all situations. In the following image, compare the dwarf done with the old method, and the elven sylph done with the new method. It's a subtle, but potent difference, and is especially evident when the colored rings are drawn under our units to signify which team they're on:

http://exong.net/wesnoth-attach/files/unitshadows1_148.png

The obvious complaint about the current system is that it might be hard to edit, compared with the previous system. The solution is simple - just delete the previous shadow and recreate one from scratch. Because of how these shadows are made, it is relatively clear which pixels had been opaque in the source layer before blurring, and if a few pixels are different in a new frame, it is often unnoticeable. At most, the process of creating a new shadow will take a few minutes, and for animations, it has the benefit of forcing someone to draw a shadow from scratch (which should be done anyways).

===The Current Method:===

The first two steps in this method are for converting old shadows to the new system. To adapt it to creating a shadow from scratch, start with a new empty layer in your graphics program, and begin at step three. In this tutorial, I'll be using the process I used to create shadows for Neoriceisgood's Saurian Flanker as an example:

1] Select all of the pixels which make up the old shadow:

http://exong.net/wesnoth-attach/files/unitshadows2_123.png

2] "Cut" these into another layer in your graphics program. In photoshop, a wonderful tool for this is in the following menu: '''Layer -> New -> Layer via Cut'''. This acts like cutting the selection from one layer and pasting it as another in the exact same position it was in before.

3] Take this new layer, and draw over all of it in solid black with the pencil tool. When doing this, if you are converting an old shadow, you can use the old one as a guide for where the new shadow should fall. Regardless of what you're creating, however, there is an unusual thing to do in this step, and that is to draw in the entire area that a shadow would fall - not merely the area that is unobscured by the unit, but also in the area that you cannot see. This is important for a later step.

Note that this layer should be moved below all the other layers in the file. It's also very helpful to temporarily make the other layers mostly transparent, as this can guide you in intuiting where the shadow should fall on an imaginary ground:

http://exong.net/wesnoth-attach/files/unitshadows3_202.png

4] I generally duplicate this layer, when finished, and hide the duplicate "backup" layer.

5] Apply a gaussian blur to this layer, with a width of 0.5 pixels (if you're using GIMP use 1.5 pixels):

http://exong.net/wesnoth-attach/files/unitshadows4_193.png

6] Change the opacity of this layer to precisely 60%. If your graphics editor speaks in transparency instead, then set it to 40%, which is the same thing. Either one of these means that 40% of what is underneath will shine through the black. '''It's very important, however, not to deviate from using solid black, and not to deviate from using 60% opacity unless you have a good reason.''' Using these makes our unit imagery consistent.

http://exong.net/wesnoth-attach/files/unitshadows5_481.png

This, then, is what the final result of the example images in this tutorial looks like:

http://exong.net/wesnoth-attach/files/unitshadows6_182.png

== See Also ==
* [[Create]]
* [[Art Tutorials]]

[[Category: Art Tutorials]]