The Battle for Wesnoth Wiki - User contributions [en]

AnimationWML

2009-03-22T12:50:12Z

Nital: switching some more tags to 1.6 WML

{{WML Tags}}

== Introduction ==

This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.

This page will deal with the two problems of animations
* How are animations Chosen
* What exactly is drawn

== How animations are drawn ==
=== Animations ===
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as
* unit is attacking
* unit is idling
* unit is attacking (event) and uses a melee weapon (condition)
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)

events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.

=== Frames ===

An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix

A frame typically describes an image, where an how to render it. It can contain such things as
* the image to display
* how transparent should that image be
* where to draw that image.

At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time

The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned

=== Timing, Clock, Multiple animations ===
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start

This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays it's attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.

The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine

In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.

Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.

==== Example Syntax ====
[attack_anim]
[attack_filter]
name= _ "bow"
[/attack_filter]
'''start_time'''=-350
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
[if]
hits=yes
[frame]
duration=350
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
duration=350
sound=bow-miss.ogg
[/frame]
[/else]
[/attack_anim]

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string>
image_diagonal=<string>
image_mod=<string>
sound=<string>
halo=<progressive string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
offset=<progressive float>
blend_color=< red, green, blue >
blend_ratio=<progressive float>
text=<string>
text_color=< red, green, blue >
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
layer=<progressive int>
[/frame]

==== Progressive parameters ====

Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.

A typical example would be a unit progressively fading out, becoming transparent

To do that, you could use:

alpha=1~0

To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:

alpha=1~0:300,0:300,0~1:300

you could also specify it like that

alpha=1~0,0,0~1

when a timing is missing, the engine will do its best to fill in in a fair way.

a progressive string has a similar syntax

halo=halo1.png:300,halo2.png:300,halo2.png:300

==== Field Description ====

** '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''
** '''end''': (deprecated) see '''begin''' and also [[AnimationWML#Timing.2C_Clock.2C_Multiple_animations|Timing, Clock, Multiple animations]] section for coverage of '''start_time''' which combines with '''duration''' to replace '''begin=''' '''end='''.
** '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''.
** '''image''': the image to display during the frame.
** '''image_diagonal''': the image to display when the attack occurs diagonally (directions ne,se,sw,nw).
** '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images
** '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.
** '''halo''': the halo to display at the time.
** '''halo_x''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_y''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes
** '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.
** '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.
** '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255) this color will be mixed to the frame to give it a tint.
** '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.
** '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).
** '''text_color''': the color of the above floating label.
** '''submerge''': the part of the unit that should drawn with 50% opacity (for units in water)
** '''x''': x offset applied to the frame
** '''y''': y offset applied to the frame
** '''layer''': layer used to draw the frame, see discussion bellow

=== Drawing related animation content ===
==== Syntax summary ====
[animation]
<animation choice related content>
[frame]
<frame content>
[/frame]
[frame]
<frame content>
[/frame]
start_time=<integer>
offset=<progressive float>
image_mod=<string>
blend_with=<r,g,b>
blend_ratio=<progressive float>
halo=<progressive_string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
layer=<progressive int>

[xxx_frame]
<frame content>
[/xxx_frame]
xxx_start_time=<integer>
xxx_image_mod=<string>
xxx_offset=<progressive float>
xxx_blend_with=<r,g,b>
xxx_blend_ratio=<progressive float>
xxx_halo=<progressive_string>
xxx_halo_x=<progressive int>
xxx_halo_y=<progressive int>
xxx_halo_mod=<string>
xxx_submerge=<progressive float>
xxx_x=<progressive int>
xxx_y=<progressive int>
xxx_layer=<progressive int>

[/animation]

==== Parameter handling ====
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame.

The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.

== How animations are chosen ==
Within a unit decription block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played.

Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the folowing movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptioeing animation when moving next to an ennemy unit

Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an ennemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criterias. The engine follow the following rules to select an animation
* Start with all animations
* Drop all animations with a criteria that fails on the current situation
* Take the animations that have the most maching criterias
* If there are more than one animation remaining, take an animation randomly
* If all animations have been droped, the engine will provide a smart default.

here is a pseudo-code explaination of this algorithm

foreach animation
animation_score = 0
foreach filter-criteria
if <criteria-fails>
animation_score = -1;
break;
elsif <criteria-matches>
animation_score++
endfor
if animation_score > max_score
<empty animation list>
max_score = animation_score;
push(animation,animation_list);
elsif animation_score = max_score
push(animation,animation_list);
endfor
<choose an animation randomly from animation_list>

Note that all animations don't have all the filters...

so, if we have a unit with
# an animation for water terrain
# an animation for SE on grassland
# an animation with no criteria
# an animation for N,NE,NW,S,SW,SE
# an animation for NW

* 3. will never be taken, because 4. will always trump it
* on water going NW, it can be 1. 4. 5.
* on water, any direction but NW, it will be 1. or 4.
* on SE grassland it will be 2.
* on other grasslands, it will be 4. (4. or 5. if NW)

=== Generic animation filters available for all animations ===
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''terrain''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]].
* '''[filter]''': this will filter using a standard unit filter on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter]''' blocks in an animation.
* '''[filter_second]''': this will filter using a standard unit filter on the unit in the hex faced. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[filter_second]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail.
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.
* '''[filter_attack]''': a standard attack filter to match on the attacker's attack. See [[FilterWML]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail.
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:
** '''hit''': the attack hits, defender survives.
** '''no''' or '''miss''': the attack misses.
** '''kill''': the attack hits, defender dies.
** '''yes''': is an alias of '''hit,kill'''.
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1).

=== Events trigerring animations and default animations ===
==== standing ====
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered

this is the default "standing image" for the unit

''value='' is not used, and always contains 0

if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used
==== selected ====
This animation is triggered whenever the unit is selected

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''
==== recruited ====
This animation is triggered whenever the unit is recruited or recalled

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=0~1:600''
==== levelin ====
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:600" blend_color=255,255,255''
==== levelout ====
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:600" blend_color=255,255,255''
==== movement ====
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation
* unit stay ''exactly'' 150ms in each hex. so you typically want to have an offset of ''0~1:150,0~1:150,0~1:150,0~1:150,0~1:150'' or something similar
* when a unit enters a hex, the current anim is tested again.
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is
** if it fails, a new movement anim is searched

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"''
==== pre_teleport ====
This animation is triggered whenever the unit teleports, but before it has moved to the target hex

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:150" blend_color=255,255,255''
==== post_teleport ====
This animation is triggered whenever the unit teleports, but after it has moved to the target hex

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:150" blend_color=255,255,255''
==== healing ====
This animation is triggered when the unit has healing powers and uses them

''value='' is the number of points healed

No default is provided by the engine
==== healed ====
This animation is triggered whenever the unit is healed for any reason

''value='' is the number of points healed

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''
and plays the sound ''heal.wav''
==== poisoned ====
This animation is triggered whenever the unit suffers poison dammage

''value='' is the number of points lost

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''
and plays the sound 'poison.ogg''
==== defend ====
This animation is triggered during a strike, of the unit receiving the blow

''value='' is the number of point lost, if any

No default is provided by the engine
==== attack ====
This animation is triggered during a strike, of the unit giving the blow

''value='' is the number of damage dealt, if any

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:150,0.6~0:150"'' for melee attacks
No default is provided for range attacks
==== leading ====
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking

''value='' is not used, and always contains 0

No default is provided by the engine

==== resistance ====
This animation is triggered for units with the resistance special ability affecting neighbouring fights, when the unit they are helping is defending

''value='' is not used, and always contains 0

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit
==== victory ====
This animation is triggered when a unit finishes a fight by killing the other unit

''value='' is not used, and always contains 0

No default is provided by the engine
==== idling ====
This animation is called when the unit has been using its standing animation for a random duration.

''value='' is not used, and always contains 0

No default is provided by the engine

==== default ====

This animation is never triggered, but is used as a base to create new animations

''value='' is used depending of the type of animation it replaces

A single animation made of the base frame is provided by the engine if no default animation is available

==== extra animations ====
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.

Note that WML events can also trigger standard animations.
''value='' is set from the WML event

== Shortcuts, tricks and quirks ==

=== ''[if]'' and ''[else]'' ===

Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that.

Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, but you can't nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):

[if]
hits=no
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound=axe.ogg
[/frame]
[/else]

note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection

=== Simplified animation blocks ===
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported

some of these use extra tags which are translated in the normal ''value='' tag

some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose

* '''[leading_anim]''' is an animation with the following parameters automatically set
apply_to=leading
* '''[recruit_anim]''' is an animation with the following parameters automatically set
apply_to=recruited
* '''[standing_anim]''' is an animation with the following parameters automatically set
apply_to=standing,default
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.

i.e: the animation will be used to build default animations
* '''[idle_anim]''' is an animation with the following parameters automatically set
apply_to=idling
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[healing_anim]''' is an animation with the following parameters automatically set
apply_to=healing
value=<damage= value>
* '''[healed_anim]''' is an animation with the following parameters automatically set
apply_to=healed
value=<healing= value>
[_healed_sound_frame]
sound=heal.wav
[/_healed_sound_frame]
* '''[poison_anim]''' is an animation with the following parameters automatically set
apply_to=poisoned
value=<damage= value>
[_poison_sound_frame]
sound=poison.ogg
[/_poison_sound_frame]
* '''[movement_anim]''' is an animation with the following parameters automatically set
apply_to=movement
offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_with=255,0,0
blend_ratio="0.5:50,0.0:50"
[/frame]

there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned

* '''[attack_anim]''' is an animation with the following parameters automatically set
if the animation contains a missile frame

apply_to=attack
missile_offset="0~0.8"

else

apply_to=attack
offset="0~0.6,0.6~0"

* '''[death]''' is an animation with the following parameters automatically set
apply_to=death
[_death_sound_frame]
sound=<die_sound= of the enclosing [unit] tag>
[/_death_sound_frame]
* '''[victory_anim]''' is an animation with the following parameters automatically set
apply_to=victory
* '''[extra_anim]''' is an animation with the following parameters automatically set
apply_to=<flag= value of the anim>
* '''[teleport_anim]''' will be cut into two at the clock-time 0
everything before zero becomes an animation with the following parameters automatically set
apply_to=pre_teleport
everything after zero becomes an animation with the following parameters automatically set
apply_to=post_teleport

== Layering ==
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.

this value must be between 0 and 100

* the back of haloes is drawn with a value of 10
* when unspecified, a animation is drawn with a value of 40
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50
* orbs and status bars are drawn on layer 80
* when unspecified missile frames are drawn on layer 90

by changing these values, it is easy to have the unit display the way you want

== See Also ==

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

[[Category: WML Reference]]

InterfaceActionsWML

2009-03-22T12:44:21Z

Nital: adding {{DevFeature}} back to show_objectives

{{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. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed). '''[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 description 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 ''' " ''')
* '''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
* note that '''[option]''' and '''[text_input]''' can only be used in moveto events in MP, otherwise they cause OOS

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!"''

== [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'')

=== Macros ===
There are a few predefined macros for Objectives that you can use to shorten the code. '''{SET_OBJECTIVES}''', '''{VICTORY_CONDITION}''' and '''{DEFEAT_CONDITION}'''. There are all used together. For more information look [http://www.wesnoth.org/misc/macro-reference.xhtml here]

== [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.
** '''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/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]''': a [[StandardUnitFilter]] 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}} shows the objectives screen. Has the same effect as if [objectives] were used to replace them with an exact duplicate.
** '''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]]

EventWML

2009-03-22T12:42:27Z

Nital: Undo revision 28998 by Nital (Talk)

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

This tag is a subtag of the [scenario], [unit] 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 definition, the event will occur in all scenarios in which a unit of that type appears in. 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.*

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

==== Valid 'name' Key Values ====

All valid values are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here will '''not''' work ''no matter how logical or awesome you think it sounds.''

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

; start
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.

; new turn
: Triggers whenever the last player ends their turn. See also [[#first_time_only|first_time_only=no]]. When the last player ends their turn, 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.

; 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''
: For ''X'' equals a number greater than 1, this event triggers at the start of turn ''X''. The value of ''X'' cannot be 1 but, if that effect is needed, use '''name=new turn''' and '''first_time_only=yes''' to achieve the equivalent of what '''turn 1''' would do.

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

; 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).

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

; 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. ''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.''

; Other events with a custom name may be invoked from [fire_event]

=== 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. There are two possible values for this key:
: ''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 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''.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.

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

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

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

StandardUnitFilter

2009-03-22T11:58:22Z

Nital: removing {{DevFeature}} tags

From [[FilterWML]], this is the standard way of filtering units.

When a unit filter is applied to a map, first it applies to all units on the field,
based on their coordinates.
Next it applies to units in the recall list.
This is important to remember as it means, for example,
that the tag '''[kill]''' can be used to kill units in the recall list.

You can access the filtered unit within the filter as the ''$this_unit'' variable, see [[SingleUnitWML]] for the possible content of these variables

The following attributes and sub-tags are allowed:

* '''id''': unit matches the given description. This is the same as ''id'' in the [unit] tag. Note that it is independent of a unit's user-visible name, which can be internationalized independent of this. See [[SingleUnitWML]].
* '''speaker''': alias for description
* '''type''': matches the unit's type name (can be a list of types)
* '''race''': the race of the unit type. Races are listed in the unit files ('''data/units/''')
* '''ability''': unit has an ability with the given id; see [[AbilitiesWML]]
* '''side''': the unit is on the given side (can be a list)
* '''has_weapon''': the unit has a weapon with the given name
* '''canrecruit''': yes if the unit can recruit (i.e. is a leader)
* '''gender''': female if the unit is female rather than the default of male
* '''role''': the unit has been assigned the given role; see '''[role]''', [[InternalActionsWML]]
* '''level''': the level of the unit
* '''defense''': current defense of the unit on current tile (chance to hit %, like in movement type definitions)
* '''movement_cost''': current movement cost of the unit on current tile
* '''x,y''': the position of the unit. Note: there is a special case for units on the recall list such that x,y="recall,recall"
* '''find_in''': name of an array or container variable; if present, the unit will not match unless it is also found stored in the variable
* '''[filter_vision]''': this tests whether or not the unit is currently visible
** '''visible''': yes or no, default yes
** '''viewing_side''': the side(s) which you are checking if they are able to see (or not see) the unit. All sides listed here must pass the test. If no side is listed, it will check the visibility all enemy sides.
* '''[filter_wml]''': this is WML level filter for the unit. In it, you can filter on anything that is in the WML description of a unit. This description can be found in any savegame also in [[SingleUnitWML]].
* '''[and]''': an extra unit filter. Unless the unit also matches the [and] filter, then it will not count as a match. ''Note: [and],[or], and [not] filters are considered after the containing filter; they are then processed in the order encountered.''
* '''[or]''': an extra unit filter. If a unit matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.
* '''[not]''': an extra unit filter. If a unit matches the [not] filter, then that unit will not be considered a match by the containing filter.
* '''[filter_adjacent]''': standard unit filter; if present the correct number of adjacent units must match this filter
** '''count''': a number, range, or comma separated range; default "1-6"
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw"
** '''is_enemy''': a boolean specifying whether the adjacent unit must be an enemy or an ally (optional)
* '''[filter_location]''': [[StandardLocationFilter]] - the tile that the unit is standing on matches the location filter.
* '''formula''' : [[FormulaAI]] like formula returning a boolean. The unit filtered is an implicit variable in the call

== A Note about Re-Using the Same Attribute ==
You are limited to having each attribute, such as '''description''', appear once or less in a [[StandardUnitFilter]]. However, this can be worked around. If you have several specific units you want excepted from matching, use a separate [or] subfilters for each one. Also you can use [not] subfilters. For example to kill ([kill] uses the standard unit filter) all units except Gwiti Ha'atel and Tanar you can do the following:
[kill]
[not]
description=Gwiti Ha'atel
[/not]
[not]
description=Tanar
[/not]
[/kill]
:And similarly if you wanted to kill both Gwiti Ha'atel and Tanar, but no one else you could do the following:
[kill]
description=Gwiti Ha'atel
[or]
description=Tanar
[/or]
[/kill]

[[Category: WML Reference]]

Template:WML Tags

2009-03-22T11:56:10Z

Nital:

{| class="gallery" style="width:225px;float: right;border: 1px solid #B48648; color:#B48648; font-size: 7pt;margin-left;10px;"
|-
|
[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit ]
'''WML Tags'''

|-
|''A:''
[[AbilitiesWML|abilities]],
[[CampaignWML|about]],
[[UnitWML|advancefrom]],
[[UnitWML|advancement]],
[[StatisticalScenarioWML|advances]],
[[AiWML|ai]],
[[DirectActionsWML|allow_recruit]],
[[DirectActionsWML|allow_undo]],
[[ConditionalActionsWML#Meta_Condition_Tags|and]],
[[InterfaceActionsWML|animate_unit]],
[[AnimationWML|animation]],
[[VariablesWML|array]],
[[UnitWML|attack]],
[[AnimationWML|attack_filter]],
[[StatisticalScenarioWML|attacks]],
[[AiWML|avoid]];
|-
|''B:''
[[UnitWML|base_unit]], [[CampaignWML#The_.5Bbinary_path.5D_tag|binary_path]], [[HelpWML|bold]], [[EditorWML|brush]];
|-
|''C:''
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]],
[[DirectActionsWML|capture_village]],
[[ConditionalActionsWML#.5Bswitch.5D|case]],
[[ReplayWML|choose]],
[[InternalActionsWML|clear_variable]],
[[InterfaceActionsWML|colour_adjust]],
command([[InterfaceActionsWML|action]], [[ReplayWML|replay]]);
|-
|''D:''
[[AbilitiesWML|damage]],
[[StatisticalScenarioWML|deaths]],
[[InterfaceActionsWML|debug_message]],
[[UnitWML|defend]],
[[StatisticalScenarioWML|defends]],
[[UnitWML|defense]],
[[InterfaceActionsWML|delay]],
[[ReplayWML|destination]],
[[DirectActionsWML|disallow_recruit]],
[[ConditionalActionsWML#.5Bwhile.5D|do]];
|-
|''E:''
[[EditorWML|editor_group]],
[[EditorWML|editor_music]],
[[EditorWML|editor_times]],
[[EditorWML|editor_tool_hint]],
[[EffectWML|effect]],
[[ConditionalActionsWML#Conditional_Actions|else]],
[[ReplayWML|end_turn]],
[[DirectActionsWML|endlevel]],
end_turn ([[DirectActionsWML|action]], [[ReplayWML|replay]]),
[[EraWML|era]],
[[EventWML|event]],
[[ThemeWML|expenses]];
|-
|''F:''
[[FilterWML|filter]], [[AnimationWML|filter_attack]], [[FilterWML|filter_location]], [[FilterWML|filter_second]], [[AnimationWML|filter_second_attack]], [[FilterWML|filter_vision]], [[StandardUnitFilter|filter_wml]], [[InternalActionsWML|fire_event]], [[HelpWML|format]], [[AnimationWML|frame]];
|-
|''G:''
[[GameConfigWML|game_config]],
[[ScenarioWML|generator]],
[[DirectActionsWML|gold]],
[[ThemeWML|gold]];
|-
|''H:''
[[ConditionalActionsWML#Condition_Tags|have_location]],
[[ConditionalActionsWML#Condition_Tags|have_unit]],
[[HelpWML|header]],
[[DirectActionsWML|heal_unit]],
[[InterfaceActionsWML|hide_unit]];
|-
|''I:''
[[ConditionalActionsWML#.5Bif.5D|if]],
[[TimeWML|illuminated_time]],
[[TerrainGraphicsWML|image]],
[[HelpWML|img]],
[[ThemeWML|income]],
[[InternalActionsWML|insert_tag]],
[[HelpWML|italic]],
[[InterfaceActionsWML|item]];
|-
|''J:''
[[HelpWML|jump]],
[[InternalActionsWML|join]];
|-
|''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]],
[[AnimationWML|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:''
[[AnimationWML|neighbour_unit_filter]],
[[ConditionalActionsWML#Meta_Condition_Tags|not]],
[[FilterWML|not]],
[[ThemeWML|num_units]];
|-
|''O:''
[[DirectActionsWML|object]],
[[InterfaceActionsWML|objectives]],
[[InterfaceActionsWML|objective]],
[[ThemeWML|observers]],
[[InterfaceActionsWML|open_help]],
[[InterfaceActionsWML|option]],
[[ConditionalActionsWML#Meta_Condition_Tags|or]];
|-
|''P:''
[[ThemeWML|panel]], [[IntroWML|part]], [[DirectActionsWML|place_shroud]], [[ThemeWML|position]],
[[InterfaceActionsWML|print]], [[AiWML|protect_location]], [[AiWML|protect_unit]];
|-
|''R:''
[[UnitsWML|race]], [[ReplayWML|random]], recall ([[DirectActionsWML|action]],
[[ReplayWML|replay]]), [[StatisticalScenarioWML|recalls]],
[[ReplayWML|recruit]], [[StatisticalScenarioWML|recruits]], [[InterfaceActionsWML|redraw]],
[[HelpWML|ref]], [[DirectActionsWML|remove_shroud]], [[InterfaceActionsWML|remove_unit_overlay]],
[[InterfaceActionsWML|removeitem]], [[InterfaceActionsWML|remove_sound_source]],
[[ReplaceMapWML|replace_map]] [[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]], [[AnimationWML|secondary_attack_filter]], [[AnimationWML|secondary_unit_filter]], [[HelpWML|section]],
[[InterfaceActionsWML#.5Bset_menu_item.5D_.28SVN_trunk_only.29|set_menu_item]], [[DirectActionsWML|set_recruit]],
[[InternalActionsWML|set_variable]], [[InternalActionsWML|set_variables]], [[InterfaceActionsWML|show_objectives]],
[[SideWML|side]], [[ThemeWML|side_playing]], [[SavefileWML|snapshot]],
[[InterfaceActionsWML|sound]], [[InterfaceActionsWML|sound_source]], [[ReplayWML|source]], [[EventWML|special_filter]], [[EventWML|special_filter_second]],
[[InternalActionsWML|split]],
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],
[[ThemeWML|status]], [[DirectActionsWML|stone]], [[InternalActionsWML|store_gold]], [[InternalActionsWML|store_locations]],
[[InternalActionsWML|store_map_dimensions]],
[[InternalActionsWML|store_starting_location]], [[InternalActionsWML|store_side]], [[InternalActionsWML|store_time_of_day]], [[InternalActionsWML|store_unit]], [[InternalActionsWML|store_villages]] [[IntroWML|story]],
[[ConditionalActionsWML#.5Bswitch.5D|switch]];
|-
|''T:''
[[AiWML|target]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],
[[DirectActionsWML|teleport]], [[UnitWML|teleport_anim]],
terrain([[TerrainWML|define]], [[DirectActionsWML|create]]), [[TerrainGraphicsWML|terrain_graphics]], [[TerrainMaskWML|terrain_mask]], [[ScenarioWML#Test_scenario|test]],
[[WesCamp|textdomain]], [[InterfaceActionsWML|text_input]], [[ThemeWML|theme]], [[ConditionalActionsWML#.5Bif.5D|then]],
[[TerrainGraphicsWML|tile]], [[TimeWML|time]], time_area ([[DirectActionsWML|action]], [[ScenarioWML|scenario]]),
[[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]], [[AnimationWML|unit_filter]], [[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:''
[[ConditionalActionsWML#Condition_Tags|variable]],
[[VariablesWML|variables]],
[[SideWML|village]],
[[ThemeWML|villages]];
|-
| ''W:''
[[ConditionalActionsWML#.5Bwhile.5D|while]],
[[InterfaceActionsWML|wml_message]];
|}

AnimationWML

2009-03-22T11:53:59Z

Nital: removing {{DevFeature}} tags

{{WML Tags}}

== Introduction ==

This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.

This page will deal with the two problems of animations
* How are animations Chosen
* What exactly is drawn

== How animations are drawn ==
=== Animations ===
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as
* unit is attacking
* unit is idling
* unit is attacking (event) and uses a melee weapon (condition)
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)

events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.

=== Frames ===

An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix

A frame typically describes an image, where an how to render it. It can contain such things as
* the image to display
* how transparent should that image be
* where to draw that image.

At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time

The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned

=== Timing, Clock, Multiple animations ===
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start

This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays it's attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.

The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine

In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.

Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.

==== Example Syntax ====
[attack_anim]
[attack_filter]
name= _ "bow"
[/attack_filter]
'''start_time'''=-350
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
[if]
hits=yes
[frame]
duration=350
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
duration=350
sound=bow-miss.ogg
[/frame]
[/else]
[/attack_anim]

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string>
image_diagonal=<string>
image_mod=<string>
sound=<string>
halo=<progressive string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
offset=<progressive float>
blend_color=< red, green, blue >
blend_ratio=<progressive float>
text=<string>
text_color=< red, green, blue >
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
layer=<progressive int>
[/frame]

==== Progressive parameters ====

Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.

A typical example would be a unit progressively fading out, becoming transparent

To do that, you could use:

alpha=1~0

To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:

alpha=1~0:300,0:300,0~1:300

you could also specify it like that

alpha=1~0,0,0~1

when a timing is missing, the engine will do its best to fill in in a fair way.

a progressive string has a similar syntax

halo=halo1.png:300,halo2.png:300,halo2.png:300

==== Field Description ====

** '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''
** '''end''': (deprecated) see '''begin''' and also [[AnimationWML#Timing.2C_Clock.2C_Multiple_animations|Timing, Clock, Multiple animations]] section for coverage of '''start_time''' which combines with '''duration''' to replace '''begin=''' '''end='''.
** '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''.
** '''image''': the image to display during the frame.
** '''image_diagonal''': the image to display when the attack occurs diagonally (directions ne,se,sw,nw).
** '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images
** '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.
** '''halo''': the halo to display at the time.
** '''halo_x''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_y''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes
** '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.
** '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.
** '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255) this color will be mixed to the frame to give it a tint.
** '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.
** '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).
** '''text_color''': the color of the above floating label.
** '''submerge''': the part of the unit that should drawn with 50% opacity (for units in water)
** '''x''': x offset applied to the frame
** '''y''': y offset applied to the frame
** '''layer''': layer used to draw the frame, see discussion bellow

=== Drawing related animation content ===
==== Syntax summary ====
[animation]
<animation choice related content>
[frame]
<frame content>
[/frame]
[frame]
<frame content>
[/frame]
start_time=<integer>
offset=<progressive float>
image_mod=<string>
blend_with=<r,g,b>
blend_ratio=<progressive float>
halo=<progressive_string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
layer=<progressive int>

[xxx_frame]
<frame content>
[/xxx_frame]
xxx_start_time=<integer>
xxx_image_mod=<string>
xxx_offset=<progressive float>
xxx_blend_with=<r,g,b>
xxx_blend_ratio=<progressive float>
xxx_halo=<progressive_string>
xxx_halo_x=<progressive int>
xxx_halo_y=<progressive int>
xxx_halo_mod=<string>
xxx_submerge=<progressive float>
xxx_x=<progressive int>
xxx_y=<progressive int>
xxx_layer=<progressive int>

[/animation]

==== Parameter handling ====
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame.

The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.

== How animations are chosen ==
Within a unit decription block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played.

Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the folowing movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptioeing animation when moving next to an ennemy unit

Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an ennemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criterias. The engine follow the following rules to select an animation
* Start with all animations
* Drop all animations with a criteria that fails on the current situation
* Take the animations that have the most maching criterias
* If there are more than one animation remaining, take an animation randomly
* If all animations have been droped, the engine will provide a smart default.

here is a pseudo-code explaination of this algorithm

foreach animation
animation_score = 0
foreach filter-criteria
if <criteria-fails>
animation_score = -1;
break;
elsif <criteria-matches>
animation_score++
endfor
if animation_score > max_score
<empty animation list>
max_score = animation_score;
push(animation,animation_list);
elsif animation_score = max_score
push(animation,animation_list);
endfor
<choose an animation randomly from animation_list>

Note that all animations don't have all the filters...

so, if we have a unit with
# an animation for water terrain
# an animation for SE on grassland
# an animation with no criteria
# an animation for N,NE,NW,S,SW,SE
# an animation for NW

* 3. will never be taken, because 4. will always trump it
* on water going NW, it can be 1. 4. 5.
* on water, any direction but NW, it will be 1. or 4.
* on SE grassland it will be 2.
* on other grasslands, it will be 4. (4. or 5. if NW)

=== Generic animation filters available for all animations ===
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''terrain''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]].
* '''[filter]''': this will filter using a standard unit filter on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[unit_filter]''' blocks in an animation.
* '''[filter_second]''': this will filter using a standard unit filter on the unit in the hex faced. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[secondary_unit_filter]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail.
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.
* '''[filter_attack]''': a standard attack filter to match on the attacker's attack. See [[FilterWML]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail.
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:
** '''hit''': the attack hits, defender survives.
** '''no''' or '''miss''': the attack misses.
** '''kill''': the attack hits, defender dies.
** '''yes''': is an alias of '''hit,kill'''.
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1).

=== Events trigerring animations and default animations ===
==== standing ====
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered

this is the default "standing image" for the unit

''value='' is not used, and always contains 0

if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used
==== selected ====
This animation is triggered whenever the unit is selected

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''
==== recruited ====
This animation is triggered whenever the unit is recruited or recalled

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=0~1:600''
==== levelin ====
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:600" blend_color=255,255,255''
==== levelout ====
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:600" blend_color=255,255,255''
==== movement ====
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation
* unit stay ''exactly'' 150ms in each hex. so you typically want to have an offset of ''0~1:150,0~1:150,0~1:150,0~1:150,0~1:150'' or something similar
* when a unit enters a hex, the current anim is tested again.
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is
** if it fails, a new movement anim is searched

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"''
==== pre_teleport ====
This animation is triggered whenever the unit teleports, but before it has moved to the target hex

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:150" blend_color=255,255,255''
==== post_teleport ====
This animation is triggered whenever the unit teleports, but after it has moved to the target hex

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:150" blend_color=255,255,255''
==== healing ====
This animation is triggered when the unit has healing powers and uses them

''value='' is the number of points healed

No default is provided by the engine
==== healed ====
This animation is triggered whenever the unit is healed for any reason

''value='' is the number of points healed

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''
and plays the sound ''heal.wav''
==== poisoned ====
This animation is triggered whenever the unit suffers poison dammage

''value='' is the number of points lost

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''
and plays the sound 'poison.ogg''
==== defend ====
This animation is triggered during a strike, of the unit receiving the blow

''value='' is the number of point lost, if any

No default is provided by the engine
==== attack ====
This animation is triggered during a strike, of the unit giving the blow

''value='' is the number of damage dealt, if any

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:150,0.6~0:150"'' for melee attacks
No default is provided for range attacks
==== leading ====
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking

''value='' is not used, and always contains 0

No default is provided by the engine

==== resistance ====
This animation is triggered for units with the resistance special ability affecting neighbouring fights, when the unit they are helping is defending

''value='' is not used, and always contains 0

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit
==== victory ====
This animation is triggered when a unit finishes a fight by killing the other unit

''value='' is not used, and always contains 0

No default is provided by the engine
==== idling ====
This animation is called when the unit has been using its standing animation for a random duration.

''value='' is not used, and always contains 0

No default is provided by the engine

==== default ====

This animation is never triggered, but is used as a base to create new animations

''value='' is used depending of the type of animation it replaces

A single animation made of the base frame is provided by the engine if no default animation is available

==== extra animations ====
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.

Note that WML events can also trigger standard animations.
''value='' is set from the WML event

== Shortcuts, tricks and quirks ==

=== ''[if]'' and ''[else]'' ===

Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that.

Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, but you can't nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):

[if]
hits=no
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound=axe.ogg
[/frame]
[/else]

note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection

=== Simplified animation blocks ===
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported

some of these use extra tags which are translated in the normal ''value='' tag

some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose

* '''[leading_anim]''' is an animation with the following parameters automatically set
apply_to=leading
* '''[recruit_anim]''' is an animation with the following parameters automatically set
apply_to=recruited
* '''[standing_anim]''' is an animation with the following parameters automatically set
apply_to=standing,default
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.

i.e: the animation will be used to build default animations
* '''[idle_anim]''' is an animation with the following parameters automatically set
apply_to=idling
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[healing_anim]''' is an animation with the following parameters automatically set
apply_to=healing
value=<damage= value>
* '''[healed_anim]''' is an animation with the following parameters automatically set
apply_to=healed
value=<healing= value>
[_healed_sound_frame]
sound=heal.wav
[/_healed_sound_frame]
* '''[poison_anim]''' is an animation with the following parameters automatically set
apply_to=poisoned
value=<damage= value>
[_poison_sound_frame]
sound=poison.ogg
[/_poison_sound_frame]
* '''[movement_anim]''' is an animation with the following parameters automatically set
apply_to=movement
offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_with=255,0,0
blend_ratio="0.5:50,0.0:50"
[/frame]

there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned

* '''[attack_anim]''' is an animation with the following parameters automatically set
if the animation contains a missile frame

apply_to=attack
missile_offset="0~0.8"

else

apply_to=attack
offset="0~0.6,0.6~0"

* '''[death]''' is an animation with the following parameters automatically set
apply_to=death
[_death_sound_frame]
sound=<die_sound= of the enclosing [unit] tag>
[/_death_sound_frame]
* '''[victory_anim]''' is an animation with the following parameters automatically set
apply_to=victory
* '''[extra_anim]''' is an animation with the following parameters automatically set
apply_to=<flag= value of the anim>
* '''[teleport_anim]''' will be cut into two at the clock-time 0
everything before zero becomes an animation with the following parameters automatically set
apply_to=pre_teleport
everything after zero becomes an animation with the following parameters automatically set
apply_to=post_teleport

== Layering ==
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.

this value must be between 0 and 100

* the back of haloes is drawn with a value of 10
* when unspecified, a animation is drawn with a value of 40
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50
* orbs and status bars are drawn on layer 80
* when unspecified missile frames are drawn on layer 90

by changing these values, it is easy to have the unit display the way you want

== See Also ==

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

[[Category: WML Reference]]

AnimationWML

2009-03-22T11:52:17Z

Nital: /* Generic animation filters available for all animations */

{{WML Tags}}

== Introduction ==

This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.

This page will deal with the two problems of animations
* How are animations Chosen
* What exactly is drawn

== How animations are drawn ==
=== Animations ===
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as
* unit is attacking
* unit is idling
* unit is attacking (event) and uses a melee weapon (condition)
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)

events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.

=== Frames ===

An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix

A frame typically describes an image, where an how to render it. It can contain such things as
* the image to display
* how transparent should that image be
* where to draw that image.

At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time

The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned

=== Timing, Clock, Multiple animations ===
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start

This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays it's attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.

The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine

In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.

Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.

==== Example Syntax ====
[attack_anim]
[attack_filter]
name= _ "bow"
[/attack_filter]
'''start_time'''=-350
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
[if]
hits=yes
[frame]
duration=350
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
duration=350
sound=bow-miss.ogg
[/frame]
[/else]
[/attack_anim]

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string>
image_diagonal=<string>
image_mod=<string>
sound=<string>
halo=<progressive string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
offset=<progressive float>
blend_color=< red, green, blue >
blend_ratio=<progressive float>
text=<string>
text_color=< red, green, blue >
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
layer=<progressive int>
[/frame]

dev denotes a {{DevFeature}}

==== Progressive parameters ====

Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.

A typical example would be a unit progressively fading out, becoming transparent

To do that, you could use:

alpha=1~0

To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:

alpha=1~0:300,0:300,0~1:300

you could also specify it like that

alpha=1~0,0,0~1

when a timing is missing, the engine will do its best to fill in in a fair way.

a progressive string has a similar syntax

halo=halo1.png:300,halo2.png:300,halo2.png:300

==== Field Description ====

** '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''
** '''end''': (deprecated) see '''begin''' and also [[AnimationWML#Timing.2C_Clock.2C_Multiple_animations|Timing, Clock, Multiple animations]] section for coverage of '''start_time''' which combines with '''duration''' to replace '''begin=''' '''end='''.
** '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''.
** '''image''': the image to display during the frame.
** '''image_diagonal''': the image to display when the attack occurs diagonally (directions ne,se,sw,nw).
** '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images
** '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.
** '''halo''': the halo to display at the time.
** '''halo_x''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_y''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes
** '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.
** '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.
** '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255) this color will be mixed to the frame to give it a tint.
** '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.
** '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).
** '''text_color''': the color of the above floating label.
** '''submerge''': the part of the unit that should drawn with 50% opacity (for units in water)
** '''x''': x offset applied to the frame
** '''y''': y offset applied to the frame
** '''layer''': layer used to draw the frame, see discussion bellow

=== Drawing related animation content ===
==== Syntax summary ====
[animation]
<animation choice related content>
[frame]
<frame content>
[/frame]
[frame]
<frame content>
[/frame]
start_time=<integer>
offset=<progressive float>
image_mod=<string>
blend_with=<r,g,b>
blend_ratio=<progressive float>
halo=<progressive_string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
layer=<progressive int>

[xxx_frame]
<frame content>
[/xxx_frame]
xxx_start_time=<integer>
xxx_image_mod=<string>
xxx_offset=<progressive float>
xxx_blend_with=<r,g,b>
xxx_blend_ratio=<progressive float>
xxx_halo=<progressive_string>
xxx_halo_x=<progressive int>
xxx_halo_y=<progressive int>
xxx_halo_mod=<string>
xxx_submerge=<progressive float>
xxx_x=<progressive int>
xxx_y=<progressive int>
xxx_layer=<progressive int>

[/animation]

dev denotes a {{DevFeature}}

==== Parameter handling ====
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame.

The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.

== How animations are chosen ==
Within a unit decription block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played.

Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the folowing movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptioeing animation when moving next to an ennemy unit

Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an ennemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criterias. The engine follow the following rules to select an animation
* Start with all animations
* Drop all animations with a criteria that fails on the current situation
* Take the animations that have the most maching criterias
* If there are more than one animation remaining, take an animation randomly
* If all animations have been droped, the engine will provide a smart default.

here is a pseudo-code explaination of this algorithm

foreach animation
animation_score = 0
foreach filter-criteria
if <criteria-fails>
animation_score = -1;
break;
elsif <criteria-matches>
animation_score++
endfor
if animation_score > max_score
<empty animation list>
max_score = animation_score;
push(animation,animation_list);
elsif animation_score = max_score
push(animation,animation_list);
endfor
<choose an animation randomly from animation_list>

Note that all animations don't have all the filters...

so, if we have a unit with
# an animation for water terrain
# an animation for SE on grassland
# an animation with no criteria
# an animation for N,NE,NW,S,SW,SE
# an animation for NW

* 3. will never be taken, because 4. will always trump it
* on water going NW, it can be 1. 4. 5.
* on water, any direction but NW, it will be 1. or 4.
* on SE grassland it will be 2.
* on other grasslands, it will be 4. (4. or 5. if NW)

=== Generic animation filters available for all animations ===
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''terrain''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]].
* '''[filter]''': this will filter using a standard unit filter on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[unit_filter]''' blocks in an animation.
* '''[filter_second]''': this will filter using a standard unit filter on the unit in the hex faced. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[secondary_unit_filter]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail.
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.
* '''[filter_attack]''': a standard attack filter to match on the attacker's attack. See [[FilterWML]].
* '''[filter_second_attack]''': a standard attack filter to match on the defender's attack. See [[FilterWML]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail.
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:
** '''hit''': the attack hits, defender survives.
** '''no''' or '''miss''': the attack misses.
** '''kill''': the attack hits, defender dies.
** '''yes''': is an alias of '''hit,kill'''.
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1).

=== Events trigerring animations and default animations ===
==== standing ====
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered

this is the default "standing image" for the unit

''value='' is not used, and always contains 0

if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used
==== selected ====
This animation is triggered whenever the unit is selected

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''
==== recruited ====
This animation is triggered whenever the unit is recruited or recalled

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=0~1:600''
==== levelin ====
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:600" blend_color=255,255,255''
==== levelout ====
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:600" blend_color=255,255,255''
==== movement ====
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation
* unit stay ''exactly'' 150ms in each hex. so you typically want to have an offset of ''0~1:150,0~1:150,0~1:150,0~1:150,0~1:150'' or something similar
* when a unit enters a hex, the current anim is tested again.
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is
** if it fails, a new movement anim is searched

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"''
==== pre_teleport ====
This animation is triggered whenever the unit teleports, but before it has moved to the target hex

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:150" blend_color=255,255,255''
==== post_teleport ====
This animation is triggered whenever the unit teleports, but after it has moved to the target hex

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:150" blend_color=255,255,255''
==== healing ====
This animation is triggered when the unit has healing powers and uses them

''value='' is the number of points healed

No default is provided by the engine
==== healed ====
This animation is triggered whenever the unit is healed for any reason

''value='' is the number of points healed

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''
and plays the sound ''heal.wav''
==== poisoned ====
This animation is triggered whenever the unit suffers poison dammage

''value='' is the number of points lost

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''
and plays the sound 'poison.ogg''
==== defend ====
This animation is triggered during a strike, of the unit receiving the blow

''value='' is the number of point lost, if any

No default is provided by the engine
==== attack ====
This animation is triggered during a strike, of the unit giving the blow

''value='' is the number of damage dealt, if any

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:150,0.6~0:150"'' for melee attacks
No default is provided for range attacks
==== leading ====
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking

''value='' is not used, and always contains 0

No default is provided by the engine

==== resistance ====
This animation is triggered for units with the resistance special ability affecting neighbouring fights, when the unit they are helping is defending

''value='' is not used, and always contains 0

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit
==== victory ====
This animation is triggered when a unit finishes a fight by killing the other unit

''value='' is not used, and always contains 0

No default is provided by the engine
==== idling ====
This animation is called when the unit has been using its standing animation for a random duration.

''value='' is not used, and always contains 0

No default is provided by the engine

==== default ====

This animation is never triggered, but is used as a base to create new animations

''value='' is used depending of the type of animation it replaces

A single animation made of the base frame is provided by the engine if no default animation is available

==== extra animations ====
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.

Note that WML events can also trigger standard animations.
''value='' is set from the WML event

== Shortcuts, tricks and quirks ==

=== ''[if]'' and ''[else]'' ===

Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that.

Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, but you can't nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):

[if]
hits=no
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound=axe.ogg
[/frame]
[/else]

note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection

=== Simplified animation blocks ===
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported

some of these use extra tags which are translated in the normal ''value='' tag

some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose

* '''[leading_anim]''' is an animation with the following parameters automatically set
apply_to=leading
* '''[recruit_anim]''' is an animation with the following parameters automatically set
apply_to=recruited
* '''[standing_anim]''' is an animation with the following parameters automatically set
apply_to=standing,default
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.

i.e: the animation will be used to build default animations
* '''[idle_anim]''' is an animation with the following parameters automatically set
apply_to=idling
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[healing_anim]''' is an animation with the following parameters automatically set
apply_to=healing
value=<damage= value>
* '''[healed_anim]''' is an animation with the following parameters automatically set
apply_to=healed
value=<healing= value>
[_healed_sound_frame]
sound=heal.wav
[/_healed_sound_frame]
* '''[poison_anim]''' is an animation with the following parameters automatically set
apply_to=poisoned
value=<damage= value>
[_poison_sound_frame]
sound=poison.ogg
[/_poison_sound_frame]
* '''[movement_anim]''' is an animation with the following parameters automatically set
apply_to=movement
offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_with=255,0,0
blend_ratio="0.5:50,0.0:50"
[/frame]

there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned

* '''[attack_anim]''' is an animation with the following parameters automatically set
if the animation contains a missile frame

apply_to=attack
missile_offset="0~0.8"

else

apply_to=attack
offset="0~0.6,0.6~0"

* '''[death]''' is an animation with the following parameters automatically set
apply_to=death
[_death_sound_frame]
sound=<die_sound= of the enclosing [unit] tag>
[/_death_sound_frame]
* '''[victory_anim]''' is an animation with the following parameters automatically set
apply_to=victory
* '''[extra_anim]''' is an animation with the following parameters automatically set
apply_to=<flag= value of the anim>
* '''[teleport_anim]''' will be cut into two at the clock-time 0
everything before zero becomes an animation with the following parameters automatically set
apply_to=pre_teleport
everything after zero becomes an animation with the following parameters automatically set
apply_to=post_teleport

== Layering ==
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.

this value must be between 0 and 100

* the back of haloes is drawn with a value of 10
* when unspecified, a animation is drawn with a value of 40
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50
* orbs and status bars are drawn on layer 80
* when unspecified missile frames are drawn on layer 90

by changing these values, it is easy to have the unit display the way you want

== See Also ==

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

[[Category: WML Reference]]

Template:WML Tags

2009-03-22T11:52:06Z

Nital: adding a new tag from 1.6

{| class="gallery" style="width:225px;float: right;border: 1px solid #B48648; color:#B48648; font-size: 7pt;margin-left;10px;"
|-
|
[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit ]
'''WML Tags'''

|-
|''A:''
[[AbilitiesWML|abilities]],
[[CampaignWML|about]],
[[UnitWML|advancefrom]],
[[UnitWML|advancement]],
[[StatisticalScenarioWML|advances]],
[[AiWML|ai]],
[[DirectActionsWML|allow_recruit]],
[[DirectActionsWML|allow_undo]],
[[ConditionalActionsWML#Meta_Condition_Tags|and]],
[[InterfaceActionsWML|animate_unit]],
[[AnimationWML|animation]],
[[VariablesWML|array]],
[[UnitWML|attack]],
[[AnimationWML|attack_filter]],
[[StatisticalScenarioWML|attacks]],
[[AiWML|avoid]];
|-
|''B:''
[[UnitWML|base_unit]], [[CampaignWML#The_.5Bbinary_path.5D_tag|binary_path]], [[HelpWML|bold]], [[EditorWML|brush]];
|-
|''C:''
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]],
[[DirectActionsWML|capture_village]],
[[ConditionalActionsWML#.5Bswitch.5D|case]],
[[ReplayWML|choose]],
[[InternalActionsWML|clear_variable]],
[[InterfaceActionsWML|colour_adjust]],
command([[InterfaceActionsWML|action]], [[ReplayWML|replay]]);
|-
|''D:''
[[AbilitiesWML|damage]],
[[StatisticalScenarioWML|deaths]],
[[InterfaceActionsWML|debug_message]],
[[UnitWML|defend]],
[[StatisticalScenarioWML|defends]],
[[UnitWML|defense]],
[[InterfaceActionsWML|delay]],
[[ReplayWML|destination]],
[[DirectActionsWML|disallow_recruit]],
[[ConditionalActionsWML#.5Bwhile.5D|do]];
|-
|''E:''
[[EditorWML|editor_group]],
[[EditorWML|editor_music]],
[[EditorWML|editor_times]],
[[EditorWML|editor_tool_hint]],
[[EffectWML|effect]],
[[ConditionalActionsWML#Conditional_Actions|else]],
[[ReplayWML|end_turn]],
[[DirectActionsWML|endlevel]],
end_turn ([[DirectActionsWML|action]], [[ReplayWML|replay]]),
[[EraWML|era]],
[[EventWML|event]],
[[ThemeWML|expenses]];
|-
|''F:''
[[FilterWML|filter]], [[AnimationWML|filter_attack]], [[FilterWML|filter_location]], [[FilterWML|filter_second]], [[AnimationWML|filter_second_attack]], [[FilterWML|filter_vision]], [[InternalActionsWML|fire_event]], [[HelpWML|format]], [[AnimationWML|frame]];
|-
|''G:''
[[GameConfigWML|game_config]],
[[ScenarioWML|generator]],
[[DirectActionsWML|gold]],
[[ThemeWML|gold]];
|-
|''H:''
[[ConditionalActionsWML#Condition_Tags|have_location]],
[[ConditionalActionsWML#Condition_Tags|have_unit]],
[[HelpWML|header]],
[[DirectActionsWML|heal_unit]],
[[InterfaceActionsWML|hide_unit]];
|-
|''I:''
[[ConditionalActionsWML#.5Bif.5D|if]],
[[TimeWML|illuminated_time]],
[[TerrainGraphicsWML|image]],
[[HelpWML|img]],
[[ThemeWML|income]],
[[InternalActionsWML|insert_tag]],
[[HelpWML|italic]],
[[InterfaceActionsWML|item]];
|-
|''J:''
[[HelpWML|jump]],
[[InternalActionsWML|join]];
|-
|''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]],
[[AnimationWML|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:''
[[AnimationWML|neighbour_unit_filter]],
[[ConditionalActionsWML#Meta_Condition_Tags|not]],
[[FilterWML|not]],
[[ThemeWML|num_units]];
|-
|''O:''
[[DirectActionsWML|object]],
[[InterfaceActionsWML|objectives]],
[[InterfaceActionsWML|objective]],
[[ThemeWML|observers]],
[[InterfaceActionsWML|open_help]],
[[InterfaceActionsWML|option]],
[[ConditionalActionsWML#Meta_Condition_Tags|or]];
|-
|''P:''
[[ThemeWML|panel]], [[IntroWML|part]], [[DirectActionsWML|place_shroud]], [[ThemeWML|position]],
[[InterfaceActionsWML|print]], [[AiWML|protect_location]], [[AiWML|protect_unit]];
|-
|''R:''
[[UnitsWML|race]], [[ReplayWML|random]], recall ([[DirectActionsWML|action]],
[[ReplayWML|replay]]), [[StatisticalScenarioWML|recalls]],
[[ReplayWML|recruit]], [[StatisticalScenarioWML|recruits]], [[InterfaceActionsWML|redraw]],
[[HelpWML|ref]], [[DirectActionsWML|remove_shroud]], [[InterfaceActionsWML|remove_unit_overlay]],
[[InterfaceActionsWML|removeitem]], [[InterfaceActionsWML|remove_sound_source]],
[[ReplaceMapWML|replace_map]] [[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]], [[AnimationWML|secondary_attack_filter]], [[AnimationWML|secondary_unit_filter]], [[HelpWML|section]],
[[InterfaceActionsWML#.5Bset_menu_item.5D_.28SVN_trunk_only.29|set_menu_item]], [[DirectActionsWML|set_recruit]],
[[InternalActionsWML|set_variable]], [[InternalActionsWML|set_variables]], [[InterfaceActionsWML|show_objectives]],
[[SideWML|side]], [[ThemeWML|side_playing]], [[SavefileWML|snapshot]],
[[InterfaceActionsWML|sound]], [[InterfaceActionsWML|sound_source]], [[ReplayWML|source]], [[EventWML|special_filter]], [[EventWML|special_filter_second]],
[[InternalActionsWML|split]],
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],
[[ThemeWML|status]], [[DirectActionsWML|stone]], [[InternalActionsWML|store_gold]], [[InternalActionsWML|store_locations]],
[[InternalActionsWML|store_map_dimensions]],
[[InternalActionsWML|store_starting_location]], [[InternalActionsWML|store_side]], [[InternalActionsWML|store_time_of_day]], [[InternalActionsWML|store_unit]], [[InternalActionsWML|store_villages]] [[IntroWML|story]],
[[ConditionalActionsWML#.5Bswitch.5D|switch]];
|-
|''T:''
[[AiWML|target]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],
[[DirectActionsWML|teleport]], [[UnitWML|teleport_anim]],
terrain([[TerrainWML|define]], [[DirectActionsWML|create]]), [[TerrainGraphicsWML|terrain_graphics]], [[TerrainMaskWML|terrain_mask]], [[ScenarioWML#Test_scenario|test]],
[[WesCamp|textdomain]], [[InterfaceActionsWML|text_input]], [[ThemeWML|theme]], [[ConditionalActionsWML#.5Bif.5D|then]],
[[TerrainGraphicsWML|tile]], [[TimeWML|time]], time_area ([[DirectActionsWML|action]], [[ScenarioWML|scenario]]),
[[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]], [[AnimationWML|unit_filter]], [[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:''
[[ConditionalActionsWML#Condition_Tags|variable]],
[[VariablesWML|variables]],
[[SideWML|village]],
[[ThemeWML|villages]];
|-
| ''W:''
[[ConditionalActionsWML#.5Bwhile.5D|while]],
[[FilterWML|wml_filter]],
[[InterfaceActionsWML|wml_message]];
|}

EventWML

2009-03-22T11:36:55Z

Nital: removing {{DevFeature}} tags

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

This tag is a subtag of the [scenario], [unit] 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 definition, the event will occur in all scenarios in which a unit of that type appears in. 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.*

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

==== Valid 'name' Key Values ====

All valid values are listed here along with a description of when this value will cause the event to be triggered. Any value ''not'' listed here will '''not''' work ''no matter how logical or awesome you think it sounds.''

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

; start
: Triggers after the map is shown but before the scenario begins -- before players can 'do' anything.

; new turn
: Triggers whenever the last player ends their turn. See also [[#first_time_only|first_time_only=no]]. When the last player ends their turn, 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.

; 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''
: For ''X'' equals a number greater than 1, this event triggers at the start of turn ''X''. The value of ''X'' cannot be 1 but, if that effect is needed, use '''name=new turn''' and '''first_time_only=yes''' to achieve the equivalent of what '''turn 1''' would do.

; 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. ''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.'' $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.)

; 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).

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

; 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. ''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.''

; Other events with a custom name may be invoked from [fire_event]

=== 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. There are two possible values for this key:
: ''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 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''.
:* '''name''': the name of the weapon used.
:* '''range''': the range of the weapon used.

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

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

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

InterfaceActionsWML

2009-03-22T11:35:27Z

Nital: removing {{DevFeature}} tags

{{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. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed). '''[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 description 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 ''' " ''')
* '''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
* note that '''[option]''' and '''[text_input]''' can only be used in moveto events in MP, otherwise they cause OOS

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!"''

== [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'')

=== Macros ===
There are a few predefined macros for Objectives that you can use to shorten the code. '''{SET_OBJECTIVES}''', '''{VICTORY_CONDITION}''' and '''{DEFEAT_CONDITION}'''. There are all used together. For more information look [http://www.wesnoth.org/misc/macro-reference.xhtml here]

== [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.
** '''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/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]''': a [[StandardUnitFilter]] 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]''' shows the objectives screen. Has the same effect as if [objectives] were used to replace them with an exact duplicate.
** '''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]]

Template:WML Tags

2009-03-22T11:30:34Z

Nital: removing {{DevFeature}} tags from AnimationWML

{| class="gallery" style="width:225px;float: right;border: 1px solid #B48648; color:#B48648; font-size: 7pt;margin-left;10px;"
|-
|
[{{SERVER}}{{localurl:Template:WML Tags|action=edit}} edit ]
'''WML Tags'''

|-
|''A:''
[[AbilitiesWML|abilities]],
[[CampaignWML|about]],
[[UnitWML|advancefrom]],
[[UnitWML|advancement]],
[[StatisticalScenarioWML|advances]],
[[AiWML|ai]],
[[DirectActionsWML|allow_recruit]],
[[DirectActionsWML|allow_undo]],
[[ConditionalActionsWML#Meta_Condition_Tags|and]],
[[InterfaceActionsWML|animate_unit]],
[[AnimationWML|animation]],
[[VariablesWML|array]],
[[UnitWML|attack]],
[[AnimationWML|attack_filter]],
[[StatisticalScenarioWML|attacks]],
[[AiWML|avoid]];
|-
|''B:''
[[UnitWML|base_unit]], [[CampaignWML#The_.5Bbinary_path.5D_tag|binary_path]], [[HelpWML|bold]], [[EditorWML|brush]];
|-
|''C:''
[[CampaignWML#The_.5Bcampaign.5D_tag|campaign]],
[[DirectActionsWML|capture_village]],
[[ConditionalActionsWML#.5Bswitch.5D|case]],
[[ReplayWML|choose]],
[[InternalActionsWML|clear_variable]],
[[InterfaceActionsWML|colour_adjust]],
command([[InterfaceActionsWML|action]], [[ReplayWML|replay]]);
|-
|''D:''
[[AbilitiesWML|damage]],
[[StatisticalScenarioWML|deaths]],
[[InterfaceActionsWML|debug_message]],
[[UnitWML|defend]],
[[StatisticalScenarioWML|defends]],
[[UnitWML|defense]],
[[InterfaceActionsWML|delay]],
[[ReplayWML|destination]],
[[DirectActionsWML|disallow_recruit]],
[[ConditionalActionsWML#.5Bwhile.5D|do]];
|-
|''E:''
[[EditorWML|editor_group]],
[[EditorWML|editor_music]],
[[EditorWML|editor_times]],
[[EditorWML|editor_tool_hint]],
[[EffectWML|effect]],
[[ConditionalActionsWML#Conditional_Actions|else]],
[[ReplayWML|end_turn]],
[[DirectActionsWML|endlevel]],
end_turn ([[DirectActionsWML|action]], [[ReplayWML|replay]]),
[[EraWML|era]],
[[EventWML|event]],
[[ThemeWML|expenses]];
|-
|''F:''
[[FilterWML|filter]], [[FilterWML|filter_location]], [[FilterWML|filter_second]], [[FilterWML|filter_vision]], [[InternalActionsWML|fire_event]], [[HelpWML|format]], [[AnimationWML|frame]];
|-
|''G:''
[[GameConfigWML|game_config]],
[[ScenarioWML|generator]],
[[DirectActionsWML|gold]],
[[ThemeWML|gold]];
|-
|''H:''
[[ConditionalActionsWML#Condition_Tags|have_location]],
[[ConditionalActionsWML#Condition_Tags|have_unit]],
[[HelpWML|header]],
[[DirectActionsWML|heal_unit]],
[[InterfaceActionsWML|hide_unit]];
|-
|''I:''
[[ConditionalActionsWML#.5Bif.5D|if]],
[[TimeWML|illuminated_time]],
[[TerrainGraphicsWML|image]],
[[HelpWML|img]],
[[ThemeWML|income]],
[[InternalActionsWML|insert_tag]],
[[HelpWML|italic]],
[[InterfaceActionsWML|item]];
|-
|''J:''
[[HelpWML|jump]],
[[InternalActionsWML|join]];
|-
|''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]],
[[AnimationWML|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:''
[[AnimationWML|neighbour_unit_filter]],
[[ConditionalActionsWML#Meta_Condition_Tags|not]],
[[FilterWML|not]],
[[ThemeWML|num_units]];
|-
|''O:''
[[DirectActionsWML|object]],
[[InterfaceActionsWML|objectives]],
[[InterfaceActionsWML|objective]],
[[ThemeWML|observers]],
[[InterfaceActionsWML|open_help]],
[[InterfaceActionsWML|option]],
[[ConditionalActionsWML#Meta_Condition_Tags|or]];
|-
|''P:''
[[ThemeWML|panel]], [[IntroWML|part]], [[DirectActionsWML|place_shroud]], [[ThemeWML|position]],
[[InterfaceActionsWML|print]], [[AiWML|protect_location]], [[AiWML|protect_unit]];
|-
|''R:''
[[UnitsWML|race]], [[ReplayWML|random]], recall ([[DirectActionsWML|action]],
[[ReplayWML|replay]]), [[StatisticalScenarioWML|recalls]],
[[ReplayWML|recruit]], [[StatisticalScenarioWML|recruits]], [[InterfaceActionsWML|redraw]],
[[HelpWML|ref]], [[DirectActionsWML|remove_shroud]], [[InterfaceActionsWML|remove_unit_overlay]],
[[InterfaceActionsWML|removeitem]], [[InterfaceActionsWML|remove_sound_source]],
[[ReplaceMapWML|replace_map]] [[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]], [[AnimationWML|secondary_attack_filter]], [[AnimationWML|secondary_unit_filter]], [[HelpWML|section]],
[[InterfaceActionsWML#.5Bset_menu_item.5D_.28SVN_trunk_only.29|set_menu_item]], [[DirectActionsWML|set_recruit]],
[[InternalActionsWML|set_variable]], [[InternalActionsWML|set_variables]], [[InterfaceActionsWML|show_objectives]],
[[SideWML|side]], [[ThemeWML|side_playing]], [[SavefileWML|snapshot]],
[[InterfaceActionsWML|sound]], [[InterfaceActionsWML|sound_source]], [[ReplayWML|source]], [[EventWML|special_filter]], [[EventWML|special_filter_second]],
[[InternalActionsWML|split]],
[[StatisticalScenarioWML#The_.5Bstatistics.5D_tag|statistics]],
[[ThemeWML|status]], [[DirectActionsWML|stone]], [[InternalActionsWML|store_gold]], [[InternalActionsWML|store_locations]],
[[InternalActionsWML|store_map_dimensions]],
[[InternalActionsWML|store_starting_location]], [[InternalActionsWML|store_side]], [[InternalActionsWML|store_time_of_day]], [[InternalActionsWML|store_unit]], [[InternalActionsWML|store_villages]] [[IntroWML|story]],
[[ConditionalActionsWML#.5Bswitch.5D|switch]];
|-
|''T:''
[[AiWML|target]],
[[StatisticalScenarioWML#The_.5Bteam.5D_tag|team]],
[[DirectActionsWML|teleport]], [[UnitWML|teleport_anim]],
terrain([[TerrainWML|define]], [[DirectActionsWML|create]]), [[TerrainGraphicsWML|terrain_graphics]], [[TerrainMaskWML|terrain_mask]], [[ScenarioWML#Test_scenario|test]],
[[WesCamp|textdomain]], [[InterfaceActionsWML|text_input]], [[ThemeWML|theme]], [[ConditionalActionsWML#.5Bif.5D|then]],
[[TerrainGraphicsWML|tile]], [[TimeWML|time]], time_area ([[DirectActionsWML|action]], [[ScenarioWML|scenario]]),
[[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]], [[AnimationWML|unit_filter]], [[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:''
[[ConditionalActionsWML#Condition_Tags|variable]],
[[VariablesWML|variables]],
[[SideWML|village]],
[[ThemeWML|villages]];
|-
| ''W:''
[[ConditionalActionsWML#.5Bwhile.5D|while]],
[[FilterWML|wml_filter]],
[[InterfaceActionsWML|wml_message]];
|}

BuildingUnits

2009-03-22T11:25:54Z

Nital: removing {{DevFeature}} tags

Making new units is fairly easy. Unit configuration files are plain text files that you can edit with any editor such as Notepad, TextEdit, gedit, pico, vi, emacs, etc. You will need to become familiar with [[UnitWML|WML]] in order to make a new unit. This page contains a more in-depth discussion of Unit WML syntax and will walk you through the creation of a new unit and discuss how you can use it in-game.

== Recommended procedure ==
The easiest way to make a new unit is to copy and paste an existing unit, then modify it. Navigate to the game's data/units directory and copy any unit. When you are editing the unit, pay attention to the property keys. If you forget to modify each key (for example, the unique id key), problems may arise, varying for minor issues such as lack of features on the unit, to game refusing to load the unit file, or, in the worst case, crashing the game. For complete reference on unit properties see [[UnitWML]].

Most of a unit's properties are self-explanatory to anyone who has played Battle for Wesnoth for very long, and the tags in the WML files are brief but descriptive. It is recommmended that you try editing by yourself before consulting the guide. Otherwise, you may find the guide confusing.

== Using your new unit ==
Any unit in the game's ./data/units directory or ''userdata''/data/units will be recognized by the game. If you only want to use it once or twice as a special unit, that's all you need to do. However, just because you made a new unit does NOT mean that it can be recruited. Each scenario and multiplayer era has a specific recruit list. If your unit is not on the list, you can't recruit it. This means you need to modify the ''recruit='' key in the appropriate configuration file. [[BuildingMultiplayer]] describes different ways you do this for multiplayer. To add a unit to a campaign, read about scenarios, sides, and recruit lists in [[BuildingScenarios]].

== Distributing your unit ==
If you made a single unit, post it on the [http://www.wesnoth.org/forum forum]. If you made a whole group of units, you can make them into a multiplayer faction or you can upload a unit pack.

If you want to make a faction, follow the instructions in the [[BuildingFactions]] article. You should create a new era and add your units as one of the factions. You will not be able to add your units to any era that ships with the game.

If you want to make a unit pack, the procedure is easier. Unit packs are distributed for campaign writers who want to use your units in their campaigns/eras. They download your unit pack and copy/paste the units and images into their campaign/era.
* Navigate to the ''userdata''/data/campaigns directory. Everything from now on will occur relative to here. The era we'll use as an example will be called MyUnitPack
* Create a text file called MyUnitPack.cfg. Add the following lines:
# #define USE_MYUNITS #<- replace MYUNITS with something descriptive
# #enddef
# #ifdef USE_MYUNITS #<- replace MYUNITS with something descriptive
# {@campaigns/MyUnitPack/}
# #endif
:* These lines are commented out (with the #). That way when the unit pack ships it won't affect the game. If someone wants the game to be able to see these units, he can uncomment those lines and it will work. However, this usually causes problems in multiplayer (you will be using units no one else has), but it can be fun for campaigns.
:* NOTE: the commenting/uncommenting trick will only work if the units branch off of an existing unit. Custom L1 units will NOT show up in game automatically without editing another configuration file somewhere (scenario config file or multiplayer.cfg)
* Create another text file called MyUnitPack.pbl. (See [[PblWML]] for more details about *.pbl files.) Add the following lines to it:
author="''your name''"
icon="''any image file in the game's ./images directory''"
version="1.0"
title="My Awesome Unit Pack"
description="New race of lizard men."
* Create a folder called MyUnitPack. Navigate to it.
* Create two subdirectories: units and images. Place your unit cfg files and artwork into those subdirectories
* Create a text file called MyUnitPack.cfg (or another name of your choosing). Add the following lines:
[binary_path]
path=data/campaigns/MyUnitPack
[/binary_path]
[+units]
{@campaigns/MyUnitPack/units}
[/units]
* You should be ready to distribute your unit pack on the campaign server now
* PLEASE change the names to something unique before you publish

== Unit WML discussion ==

As of 1.6, unit definitions are enclosed in '''[unit_type]''' tags.

This section only provides some tips and pointers in making a unit. Feel free to add pointers of your own. For the full, current, complete WML reference on what to put in your [unit], see and frequently revisit [[UnitWML|The Unit WML reference page]].
* The first attribute of a unit is the '''id''' attribute, which is a unique identifier for the unit. As value of the '''type''' attribute for these units, the '''id''' key is used. (See [[BuildingScenarios]]).
* When referencing the unit in a '''type''' key, the id must be reproduced verbatim, without typos, and in a case-sensitive manner. If you don't do this, the key won't work. If you can't recruit in a scenario, it's probably because you have a typo in one of the unit ids and the '''recruit''' key was invalidated.
* It also has a '''name''' key, which is the (translatable) name of the unit, and is displayed on the Status Table when a unit of this type is selected. It does not need to be unique (but it helps).
* Do not set movement to 0. It creates weird infinite movement behavior. This might be fixed in the future. For now, to make an immobile unit, set movement to 1 and use [movement_costs] to make it unable to move onto any terrain.

* See [[BuildingScenariosIntermediate]] for more information on attacks.

== See Also ==

* [[Create]]
* [[EditingWesnoth]]
* [[Creating Unit Art]]
* [[CampaignServerWML]]
* [[PblWML]]
* [[BuildingCampaignsThePBLFile]]
* [[Team_Color_Shifting]]

{{Create}}

IntroWML

2009-03-22T11:20:34Z

Nital: removing {{DevFeature}} tags

{{WML Tags}}
== The [story] tag ==

The '''[story]''' tag is a series of images and text to display as the first part of the intro screen.

'''[part]''' is a special tag recognized only beneath '''[story]'''. Each '''[part]''' represents one image and text.
The part is displayed until the user clicks on the "Next>>>" button.

The following key/tags are recognized for '''[part]''':
* '''background''': the image to display. Story images are usually created specially for this purpose, except for the map.
* '''scale_background''': Whether to scale the background, default yes.
* '''story''': (translatable) the text to display below the image.
* '''show_title''': whether to display the title of the scenario at the top
* '''music''': change to this music
* '''[image]''': an image to display.
** '''x''', '''y''': the location in pixels to draw the image. The x,y pixel location is relative to the image specified in background, but not in a normal way. The background image is scaled up or down to fill the screen resolution, but images are never scaled in size. Their coordinates, however, are scaled. It's basically a big pain in the rear. Example: I have a background image at 640x480 and an overlay at 640x480. To horizontally center the overlay on a 1024x768 screen, I want to position it at x=192. This is because 1024-640 = 384 total extra pixel space, then 384/2 = 192. This results in equal space on both sides of the overlay. However, now you have to account for the background scaling. The background image at 640 is scaled up to 1024, a scaling factor of 1.6. All image locations are also scaled up, so the overlay is not drawn at x=192, rather it is drawn at x=192*1.6 or x=307! To compensate for this, divide the desired pixel location by the scaling factor. In the example, x_compensated=192/1.6 or x_compensated=120.
** '''centered''': If "yes", use the center of the image when placing at the x,y coordinates, which is useful since this image is not scaled like the background is (and by centering no need to worry about this).
** '''file''': the image to display.
** '''delay''': the time to delay drawing this image.

The '''[deprecated_message]''', '''[image]''', and '''[insert_tag]''' tags are allowed beneath '''[story]'''. Most other WML tags will not be recognized in this context.

The only other tags currently recognized beneath '''[story]''' are '''[if]'''/'''[then]'''/'''[else]'''. These can be used to show parts conditionally on the values of variables. Note, however, that '''[switch]'''/'''[case]''' will not work in this context.

See also the journey and battle macros, in [[UtilWML]]

== See Also ==

* [[ReferenceWML]]

[[Category: WML Reference]]

PblWML

2009-03-22T11:20:05Z

Nital: Undo revision 28990 by Nital (Talk)

{{WML Tags}}
== .pbl files ==

=== What is a .pbl file? ===
To upload a campaign you have made, you need a .pbl file.

This is a file with name '''data/campaigns/''campaign-name''.pbl'''. [http://exong.net/wesnoth-attach/files/pblexample_111.png Click here for an example of what we're talking about.]

When you upload a campaign, the file '''data/campaigns/''campaign-name''.cfg'''
and the directory '''data/campaigns/''campaign-name''/''' will be published.
Your campaign must be based entirely on these files.
This may cause your campaign not to upload properly,
for example, if you have custom campaign units in '''data/units/'''.
Be aware that translations in the .pbl-files are '''not''' working, so don't mark these strings translateable.

=== What goes into a .pbl file? ===

Note that you should not use special formatting or coloring in any fields when uploading to the official server.

The following keys are recognized for .pbl files:
* '''icon''': an image, displayed leftmost on the "download campaigns" screen. It must be a standard Wesnoth graphic and not a custom one. (Well, a custom graphic will work if the user already has the campaign installed, or if it is a custom graphic from a different campaign that the user has installed.) (Note that the icon used to display your campaign for when it is played can be custom; for more information see [[CampaignWML]].) If the icon is a unit with magenta color, please use [[ImagePathFunctionWML]] to team-color it.
* '''title''': displayed to the right of the icon, it is just text. It should usually be the same as the name of your campaign when it is played.
* '''version''': displayed to the right of the title, it is also just text. However the prefered format is x.y.z where x, y and z are numbers and x > 0 implies the campaign is complete and balanced.
* '''author''': displayed to the right of the version, it is also text. Put your name or nickname here. If several people have contributed significantly to the campaign you should list all of their names and perhaps describe what each person was responsible for.
* '''passphrase''': not displayed, it prevents others from modifying the version of your campaign on the campaign server. You do not need to input a passphrase when initially publishind a campaign; if you do not, one will be randomly generated for you.
* '''description''': is not displayed in the client. However it is visible on the web interface to the campaign server. It can be used to give a brief description of your campaign and for pre 1.0 versions let people know how playable it is.
* '''dependencies''': is an optional list of dependencies. For example
dependencies=Imperial_Era,Era_of_Myths
: could be used when the two specified add-ons need to be installed for a campaign to work.
* '''translate''': if true the campaign will be send and updated with Wescamp (NOTE: this is a new and experimental function, which will automatically update the translations in your campaign. Make sure you make backups of your campaign in case of problems.)
* '''type''': indicates the type of the add-on, used for the downloads manager dialog. Possible values are:
** ''campaign'': single player campaign.
** ''scenario'': single player scenario.
** ''era'': multiplayer era.
** ''faction'': multiplayer stand-alone faction, or add-on for other available era.
** ''map_pack'': multiplayer map-pack.
** ''campaign_mp'': multiplayer campaign.
** ''scenario_mp'': multiplayer scenario.
** ''media'': miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc.
* '''email''': hidden e-mail address used by the server administrators to contact content authors in case of major issues.

Example:

title="My Campaign"
type="campaign"
icon="misc/ball.png"
version="0.1.2"
author="Me, artwork by myself"
passphrase="This is like a password"
description="You get to kill a lot of bad guys. But only the first map is done."
email="name@domain.ltd"

The campaign server keeps track of some other information about uploaded campaigns, including when they were uploaded, what languages they have been at least partly translated into, how large they are on the server and the number of times they have been downloaded. For more information about this you can read [[CampaignServerWML]].

== See Also ==

* [[ReferenceWML]]
* [[BuildingCampaignsThePBLFile]]
* [[CampaignServerWML]]

[[Category: WML Reference]]

PblWML

2009-03-22T11:19:34Z

Nital:

{{WML Tags}}
== .pbl files ==

=== What is a .pbl file? ===
To upload a campaign you have made, you need a .pbl file.

This is a file with name '''data/campaigns/''campaign-name''.pbl'''. [http://exong.net/wesnoth-attach/files/pblexample_111.png Click here for an example of what we're talking about.]

When you upload a campaign, the file '''data/campaigns/''campaign-name''.cfg'''
and the directory '''data/campaigns/''campaign-name''/''' will be published.
Your campaign must be based entirely on these files.
This may cause your campaign not to upload properly,
for example, if you have custom campaign units in '''data/units/'''.
Be aware that translations in the .pbl-files are '''not''' working, so don't mark these strings translateable.

=== What goes into a .pbl file? ===

Note that you should not use special formatting or coloring in any fields when uploading to the official server.

The following keys are recognized for .pbl files:
* '''icon''': an image, displayed leftmost on the "download campaigns" screen. It must be a standard Wesnoth graphic and not a custom one. (Well, a custom graphic will work if the user already has the campaign installed, or if it is a custom graphic from a different campaign that the user has installed.) (Note that the icon used to display your campaign for when it is played can be custom; for more information see [[CampaignWML]].) If the icon is a unit with magenta color, please use [[ImagePathFunctionWML]] to team-color it.
* '''title''': displayed to the right of the icon, it is just text. It should usually be the same as the name of your campaign when it is played.
* '''version''': displayed to the right of the title, it is also just text. However the prefered format is x.y.z where x, y and z are numbers and x > 0 implies the campaign is complete and balanced.
* '''author''': displayed to the right of the version, it is also text. Put your name or nickname here. If several people have contributed significantly to the campaign you should list all of their names and perhaps describe what each person was responsible for.
* '''passphrase''': not displayed, it prevents others from modifying the version of your campaign on the campaign server. You do not need to input a passphrase when initially publishind a campaign; if you do not, one will be randomly generated for you.
* '''description''': is not displayed in the client. However it is visible on the web interface to the campaign server. It can be used to give a brief description of your campaign and for pre 1.0 versions let people know how playable it is.
* '''dependencies''': is an optional list of dependencies. For example
dependencies=Imperial_Era,Era_of_Myths
: could be used when the two specified add-ons need to be installed for a campaign to work.
* '''translate''': if true the campaign will be send and updated with Wescamp (NOTE: this is a new and experimental function, which will automatically update the translations in your campaign. Make sure you make backups of your campaign in case of problems.)
* '''type''': indicates the type of the add-on, used for the downloads manager dialog. Possible values are:
** ''campaign'': single player campaign.
** ''scenario'': single player scenario.
** ''era'': multiplayer era.
** ''faction'': multiplayer stand-alone faction, or add-on for other available era.
** ''map_pack'': multiplayer map-pack.
** ''campaign_mp'': multiplayer campaign.
** ''scenario_mp'': multiplayer scenario.
** ''media'': miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc.
* '''email''': hidden e-mail address used by the server administrators to contact content authors in case of major issues.

Example:

title="My Campaign"
type="campaign"
icon="misc/ball.png"
version="0.1.2"
author="Me, artwork by myself"
passphrase="This is like a password"
description="You get to kill a lot of bad guys. But only the first map is done."
type=campaign
email="name@domain.ltd"

The campaign server keeps track of some other information about uploaded campaigns, including when they were uploaded, what languages they have been at least partly translated into, how large they are on the server and the number of times they have been downloaded. For more information about this you can read [[CampaignServerWML]].

== See Also ==

* [[ReferenceWML]]
* [[BuildingCampaignsThePBLFile]]
* [[CampaignServerWML]]

[[Category: WML Reference]]

PblWML

2009-03-22T11:18:57Z

Nital: removing {{DevFeature}} tags

ScenarioWML

2009-03-22T11:17:34Z

Nital: removing {{DevFeature}} tags

{{WML Tags}}
== the toplevel tags [multiplayer], [test], [tutorial], [scenario] ==

The top level tags '''[multiplayer]''', '''[test]''', '''[tutorial]''' and '''[scenario]''' are all formatted the same way.
The difference between these tags is the way that the scenarios they describe are accessed.

The keys '''id''' and '''next_scenario''' affect how scenarios can be accessed.
Whenever a scenario is won, the scenario with id=''next_scenario'' of the same tag type will be played.
Units from the first scenario will be available for recall in the second.

Some scenarios can be played without playing other scenarios first
(in this case there is nothing on the recall list).
These scenarios are called ''initial scenario''s.

A list of initial scenarios, and how to access them:

* All '''[multiplayer]''' scenarios are initial scenarios listed in the multiplayer scenario selector screen (accessed by the "multiplayer" button).

* The '''[test]''' scenario with the attribute '''id=test''' is an initial scenario. This test scenario can be accessed by running the game in test mode. (note: this is NOT the same as debug mode. It can be accessed using -t or --test) You can speed up scenario development a lot by this when used in a clever way: Move a scenario into ~campaigns (so that it will be read even without its campaign being loaded), change it to a [test] scenario, and change the ID to 'test'. Then run Wesnoth in test mode. This saves about a minute for each time you want to test changes to your scenario. However it should not be used for balancing as there will be no recallable units...

* The '''[tutorial]''' scenario with the attribute '''id=tutorial''' is an initial scenario. The tutorial is accessed by clicking on the "tutorial" button.

* Any '''[scenario]''' scenario with an id listed in the value of ''first_scenario'' in a campaign tag (see [[CampaignWML]]) is an initial scenario accessed by selecting that campaign after clicking on the "campaign" button.

== The [scenario] tag ==

The following keys and tags are recognized in '''[scenario]''' tags:

* '''id''': A unique identifier for this scenario.

* '''next_scenario''': The id of the scenario to load when the current one is won. This can be changed dynamically, to build non-linear campaigns.

* '''description''': (translatable) only for multiplayer maps. Will show up as a tooltip when mousing over the minimap in the multiplayer setup screen.

* '''name''': (translatable) is shown in several places in the level, including the intro screen. It is also the default name for saves on the level.

* '''map_data''': inputs valid Wesnoth map data. See [[BuildingMaps]] for a description of the Wesnoth map syntax.

* '''turns''': sets an event on turn ''turns'' causing the player to lose. Use ''-1'' to have no turn limit. See also [[EventWML]]

* '''turn_at''': the turn to start on (default=1)

* '''random_start_time''': controls random starting time of day. Possible values are yes and no or list of possible start times; starting from 1 to number of times. for example ''random_start_time=2,3,5,6'' (default=no)

* '''music''': the music file relative to ''./music/'' to play during the scenario

* '''[music]''': specifies the music tracks to play during this scenario, see [[MusicListWML]].

* '''defeat_music''': specifies a comma-separated list of music tracks which may be chosen to play on defeat. If not provided, the default in [[GameConfigWML]] is used instead. May be overridden by [[DirectActionsWML|endlevel]] clauses.

* '''victory_music''': specifies a comma-separated list of music tracks which may be chosen to play on victory. If not provided, the default in [[GameConfigWML]] is used instead. May be overridden by [[DirectActionsWML|endlevel]] clauses.

* '''theme''': the UI theme that should be used when playing this scenario. See [[Using_custom_themes_in_campaigns]]

* '''victory_when_enemies_defeated''': when this is set to '''yes''' (default), the player wins once all non-allied units with '''canrecruit=yes''' (aka leaders) are killed. (Currently this only controls the win condition for when all enemies are defeated; it does not prevent the player from losing if he has no leader.) When this value is true the following keys can be used:
** '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
** '''carryover_add''': if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.

* '''disallow_recall''': when this is set to 'no'(default), the player is allowed to recall units from previous scenarios.

* '''experience_modifier''': the percentage that required XP to level up (for all units in the scenario) is multiplied by. Default 100. Note that when used in a campaign, weird things (like units being above the required XP to level up) can happen if this value is different for different scenarios.

* '''[story]''': describes the intro screen. See [[IntroWML]]

* '''[label]''': sets a label
** '''x''', '''y''': location to set label
** '''text''': the label

* '''[time]''', '''[illuminated_time]''': how a day should progress. See [[TimeWML]]

* '''[time_area]''': how a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] and [illuminated_time] tags in the [scenario] tag
** takes x and y coordinates.
** '''[time]''', '''[illuminated_time]''': how a day should progress in those locations. See [[TimeWML]]
** time areas can be used in events, assigned identifiers, and removed at discretion. They also accept complete Standard Location Filters. See [[DirectActionsWML]].

* '''[side]''': describes one player. See [[SideWML]]

* '''[event]''': describes an event that may be triggered at a certain point of the scenario. See [[EventWML]]

* '''map_generation''': another way to generate a map. The map will be generated randomly
** '''default''': the default random map generator

* '''[generator]''' if this is present, the map and scenario will be generated randomly. See [[MapGeneratorWML]]

the following key is additionally recognized in '''[multiplayer]''' scenarios:
* '''allow_new_game''': (default=yes) allow/prevent the scenario to be listed in the game creation interface. This is intended for extra scenarios in multiplayer campaigns

== See Also ==

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

[[Category: WML Reference]]

SideWML

2009-03-22T11:16:27Z

Nital:

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

The [side] tag is used to describe a side in a particular scenario.

The following keys are recognized:

* '''side''': a digit. The leader of this side is placed on the tile represented by this digit (see [[BuildingMaps]]). When defining sides, they must be defined in order since the side number is checked against the number of sides seen so far.

* '''controller''': how moves for this side should be inputted.
** '''ai''': the Wesnoth AI makes this side's moves. This is the default setting.
** '''human''': a player controls this side's moves.
** '''null''': the side doesn't get a turn to move and doesn't have a leader generated from the contents of the [side] tag. (It still can get units from [unit] tags in the [side] tag.)

* '''no_leader''': if "no" (default), then keys describing a unit which will begin on the side's keep will be the remainder of the '''[side]''' tag, See [[SingleUnitWML]]. Note that if the keys '''x''', '''y''' are included, the leader will begin there regardless of keep location. If this side has a recall list from a previous level, then the recall list will be searched for a leader (using '''canrecruit=yes''') and if one is found it will be used instead of the one described in the '''[side]''' tag. Typical keys used for defining the leader unit are '''type''' (mandatory), '''id''', '''name''' and '''unrenamable=yes''', see [[UnitWML]].

* '''recruit''': a list of unit types. At the beginning of the scenario, the side gains recruitment of these units.

* '''gold''': the starting gold for this side. Default 100. (If gold is carried over from a previous scenario, this value is the minimum starting gold.)

* '''income''': the base income for this side, default 0. This is added to ''base_income'', '''[game_config]''' to determine the side's base income. (see [[GameConfigWML]]).

* '''hidden''': if 'yes', side is not shown in status table.

* '''fog''': if 'yes', this side cannot see any tiles it is not within vision of, except at the start. Please note that the AI currently ignores the fog.

* '''shroud''': if 'yes', this side cannot see any tiles it has not moved within sight of. Please note that the AI currently ignores the shroud.

* '''shroud_data''': describes the area which this team has de-shrouded. An example:
|
|00011111000
This would leave the first column on the map unaltered and would change the second column for 11 tiles. A '0' means: shrouded, '1' means unshrouded. You can either call an external file using {@filename} (see [[PreprocessorRef]]) or place the data in quotes. For making an external file see [[BuildingScenariosShroudData]].

* '''persistent''': whether the side exists in any other scenarios. If '1'(yes), then ''save_id''(see below) becomes active for this side. Default '0'(no); when '''controller=human''', this is always '1'.

* '''save_id''': default ''description'' if available, 'Unknown' otherwise. The ID of the side with respect to the previous and next scenarios. Used to carry over the side's recall list (including the side's leader), recruitment list, and starting gold from scenario to scenario. Also used for the side's displayed name in the victory gold-calculation dialog. See [[SideSwitchingWML]].

* '''team_name''': a non translatable string representing the team's description. Sides with the same team_name are allied. Default ''side''.

* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Default ''team_name''.

* '''colour''': May be either a numeric color index or a color name (e.g. 'blue', 'purple', 'orange', etc.). The numeric form is deprecated. The default list of numbers and corresponding colours can be found in data/core/team_colors.cfg.

* '''flag''': a custom flag animation to use instead of the default one to mark captured villages. An automatic side-coloring is applied.
** Example animation that has three frames and loops every 750ms: ''flag=misc/myflag-1.png:250,misc/myflag-2.png:250,misc/myflag-3.png:250''

* '''flag_icon''': a custom flag icon to indicate the side playing in the statusbar (a size of 24x16 is recommended). An automatic side-coloring is applied.

* '''village_gold''': the amount of gold given to this side per village it controls per turn. Default specified in ''village_income'', '''[game_config]''' ([[GameConfigWML]]). '''Note:''' If you need village gold to be 0. Set the variable to -1.

* '''share_maps''': whether sides allied with this side see all terrains that this side sees, if they are on shroud.

* '''share_view''': whether sides allied with this side see the units that this side sees, if they are on FoW (fog).

* '''disallow_observers''': prevents observers from seeing this side turn. (default: no)

* '''[ai]''' if '''controller=ai''', gives parameters to the AI. See [[AiWML]].

* '''[village]''' describes a village the side begins in control of.
** ''x'', ''y'' the location of the village. If the pair of coordinates is not a village or is duplicated in another [village] tag, behaviour is undefined. Recent game engine or wmllint should warn about these.

* '''[unit]''' describes a unit which begins on the side. See [[SingleUnitWML]]. If the side has a recall list and the unit is not given a location, it will start on the recall list. Note that the ''side'' attribute under '''[unit]''' will be ignored, as the side will come from the ''side'' attribute of '''[side]'''.

The following keys are multiplayer only:

* '''allow_player''': if false then this side will not be allowed to be modified and will be hidden during game creation.

* '''team_lock''': if true then this side's team is not allowed to be modified.

* '''colour_lock''': if true then this side's color is not allowed to be modified.

* '''gold_lock''': if true then this side's gold is not allowed to be modified.

* '''income_lock''': if true then this side's income is not allowed to be modified.

* '''faction''': this lock this side to this faction.

* '''faction_from_recruit''': if true then this side will be locked to the faction that matches the recruits better.

== See Also ==
* [[EraWML]]
* [[ScenarioWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

SingleUnitWML

2009-03-22T11:15:04Z

Nital: removing {{DevFeature}} tags

{{WML Tags}}
== How to describe a single unit ==

This tag, '''[unit]''', describes a single unit on the map, for example Konrad.
It is different from the [unit] in [units], which describes a class of units.

The following keys are recognized:
* '''type''': the ID of the unit's unit type. See [[UnitWML]].

* '''side''': the side that the unit is on.

* '''gender''': can be set to male or female to designate the gender of the unit. Default is male, but if the unit has only a female variant it will be female.

* '''x''', '''y''': the location of the unit. If a location isn't provided and the side the unit will belong to has a recall list, the unit will be created on the recall list.

* '''id''': a unique identifier for the unit. This is not displayed to the player, but is to be used only for identifying and filtering for units. If not specified or when a unit is normally recruited, a random one will be generated for the unit to ensure that each unit has a unique ''id'' attribute. In older versions, the '''description''' attribute specified a unique ID.

* '''name''': the user-visible name of the unit. Note that the player may use the "rename unit" action to change this.

* '''generate_name''': if set to "yes", will generate a new name (user-level description only, not internal unique ID) for the unit, as if the unit were a freshly-recruited one

* '''unrenamable''': if 'yes', the user-visible name of the unit cannot be changed by the player (which is only possible when the unit is on the player's side anyway).

* '''traits_description''': the description of the unit's traits which is displayed. However if it is not specified explicitly, the unit's actual traits' names will be used instead, so it is normally not necessary to set this.

* '''random_traits''': "no" will prevent random trait generation for units. You should only need to set this for placed nonleaders in multiplayer games or if you want to give a unit less traits than it would normally get for its unit type. When generating traits for a unit, first traits the unit has already been given are excluded. Then "musthave" traits (undead, mechanical) for the unit type are given. Then for leaders ('''canrecruit=yes''') traits that are not available to "any" (currently that's all of them to avoid a multiplayer OOS issue, but later will be restricted based on multiplayer play balance issues) are removed from consideration. Then traits are added randomly until the maximum allowed for the unit type is reached or there are no more available traits. Random traits can now be used in MP games but only when spawned in an event, so not for leaders and other units in the [side] definition.

* '''random_gender''': "yes" will cause the gender of the unit with male and female variations to be male 50% of the time, female 50% of the time. If the unit has only one gender variant it will always be given the correct one.

* '''canrecruit''': a special key for leaders.
** '''no''': default. Unit cannot recruit.
** '''yes''': unit can recruit.
: Normally when a team controls no units with '''canrecruit=yes''', that team loses. However, even if your team has lost you continue to play with whatever units you still have until the scenario is over. Usually scenarios end when only one team is left with a leader that can recruit, but special victory conditions can be set up in campaigns. Normally you want to set the leader of a side with '''canrecruit=yes'''. If you don't want the leader to recruit, it is usually better to just not give him any unit types to recruit, than to make a special victory condition. Units with '''canrecruit=yes''' are exempt from upkeep costs. So that leaders do not need to be given the ''loyal'' trait.

* '''variation''': the variation of itself the unit should be created as.

* '''upkeep''': the amount of upkeep the unit costs.
** '''loyal''' no upkeep cost. Can be changed by the effect 'loyal' (see [[EffectWML]])
** '''full''': unit costs ''level'' upkeep (see [[UnitWML]]).
** An integer can be used to set the upkeep cost to that number.
** The default is "full".
** Leaders (units with '''canrecruit=yes''') never pay upkeep no matter what upkeep is set to.
** Normally you don't want to muck with this value. If you want to give a side units without upkeep costs, give those units the 'loyal' trait.

* '''overlays''': a list of images that are overlayed on the unit.

* '''goto_x''':, '''goto_y''': UI settings that control courses. Default is 0,0 i.e. the unit is not on a course.

* '''hitpoints''': the HP of the unit. Default is the max HP for ''type''.

* '''experience''': the XP of the unit. Default is 0.

* '''moves''': number of movement points the unit has left. Default is the movement for its unit type.

* '''resting''': whether the unit has not moved yet this turn. Used to decide whether to give a unit rest healing.

* '''role''': used in standard unit filter ([[FilterWML]]). Can be set using [role] (see [[InternalActionsWML]]).

* '''ai_special''': causes the unit to act differently.
** "guardian" the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it).

* '''facing''': which way the unit is facing (this only affects how the unit is displayed).
** Possible values are '''se''', '''s''', '''sw''', '''nw''', '''n''', '''ne'''. Using '''sw''' is preferred for a "reversed" facing (looking to the left) and '''se''' for a normal (looking to the right) facing.

* '''profile''': sets a default portrait image for this unit. If the unit type already has a portrait set, this is used instead for this unit. When the unit advances, if the value of profile is different from the unit-type portrait, that value is preserved. If the profile field is empty or the same as the unit-type portrait, the level-advance changes the unit portrait to the default for the new level and type.

** "unit_image" if given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).

* '''animate''': if ''yes'', fades the unit in like when it's recruited/recalled.

* '''[status]''' the status of the unit. This affects different features of the unit, for example whether the unit loses health each turn. Default for all keys is 'off', but this can be changed by the scenario or by special abilities (see [[AbilitiesWML]]). The status of a unit is displayed on the Status Table; each status modification ''statusmod'' is represented by the image '''misc/statusmod.png'''.
** '''poisoned''': if 'yes', the unit loses 8 HP each turn. See also ''heals'', ''cures'', [[AbilitiesWML]].
** '''slowed''': if 'yes', the unit has 50% of its normal movement and does half damage. When the controller of the unit's turn is over, ''slowed'' is set to 'off'
** '''stone''': if 'yes', the unit cannot move, attack, or be attacked.
** '''hides''': if 'yes', the unit cannot be seen by opponents.
** '''guardian''': this is set to 'yes' by ai_special=guardian and clearing it will allow the unit to act normally again.

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable '''unit'''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

* '''[modifications]''' changes that have been made to the unit.
** '''[trait]''' a trait the unit has. Same format as [trait], [[UnitsWML]].
** '''[object]''' an object the unit has. Same format as [object], [[DirectActionsWML]].

* '''unit_description''': overrides the unit type description for this unit. You will probably want to set up a ''post_advance'' [[EventWML|event]] to override the default description after promotions. Or better, use an object with a profile [[EffectWML|effect(s)]] to filter on unit type and change the unit description and/or portrait.

== See Also ==

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

[[Category:WML Reference]]

TerrainMaskWML

2009-03-22T11:13:00Z

Nital: removing {{DevFeature}} tags

{{WML Tags}}
== The [terrain_mask] tag ==

The [terrain_mask] tag makes map manipulation from within WML much easier.
It uses a Wesnoth map as a "mask" over a given location,
placing it down on top of the scenario map.
Fog('~') and void(' ') are used like alpha in an image; i.e. they cause the previous terrain to be used.

* '''x,y''': the x,y location in the scenario map to place the top-left corner of the mask onto
* '''mask''': a Wesnoth map; see [[BuildingMaps]].
* '''border''': (default=no) Overlay on the border as well as the playable map area. The mask used must have a border_size equal to the map's border size (i.e. it must be a normal map), otherwise it will be ignored
* '''[rule]''': specifies a rule for blending the mask with the scenario.
The terrain on each hex fitting the rule will be changed to the terrain specified in the rule.
** '''old''': a comma-separated list of terrain codes. The rule fits only those hexes that have one of these terrains in the scenario.
** '''new''': a list of terrain letters. The rule fits only those hexes with this terrain specified in the mask.
** '''terrain''': the letter of the terrain to change hexes which fit this rule (i.e. for which the '''new''' terrain code in the mask falls on top of the '''old''' terrain in the scenario) into.
** '''layer''': (overlay|base|both, default=both) only change the specified layer.
** '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.

As an example, suppose you want to lay down a road somewhere. You could specify by hand the path the road takes using
[terrain], or you could use
[terrain_mask]:

<pre>
[terrain_mask]
x,y=12,10
mask="border_size=1
usage=map

Re, Re, _f, _f, _f, _f, _f, _f, _f, _f, _f, _f
Re, Re, _f, _f, _f, _f, _f, _f, _f, _f, _f, _f
Re, Re, _f, _f, _f, _f, _f, _f, _f, _f, _f, _f
_f, _f, Re, _f, _f, _f, _f, _f, _f, _f, _f, _f
_f, _f, Re, _f, _f, _f, _f, _f, _f, _f, _f, _f
Re, Re, _f, _f, _f, _f, _f, _f, _f, _f, _f, _f
_f, _f, Re, _f, _f, Re, Re, _f, _f, _f, _f, _f
_f, _f, _f, Re, Re, Re, _f, Re, Re, _f, _f, _f
_f, _f, _f, _f, _f, _f, _f, Re, _f, _f, _f, _f
_f, _f, _f, _f, _f, _f, _f, Re, Re, _f, _f, _f
_f, _f, _f, _f, _f, _f, _f, Re, Re, Re, Re, Re
_f, _f, _f, _f, _f, _f, _f, Re, Re, Re, Re, Re
"
[/terrain_mask]
</pre>

For instance, suppose you want snow to fall in an area. You want villages (v) to turn into snowed-villages (V), forest
(f) to turn into snowed-forest (F), hills
(h) to turn into snowed-hills (H), and grassland (g) and roads (r) to turn into snow (S), while other terrain remains
untouched. You could look over your
destination map and work out which terrain type is which and draw your mask, but that's alot of effort, you want to just
draw a simple mask which has
areas of snow and areas of no snow, and make the game work out the rest.

You can do it like this:

[terrain_mask]
x,y=1,1
mask="border_size=1
usage=map

_f, _f, Aa, _f, _f, _f, Aa, _f, _f
_f, _f, Aa, _f, _f, _f, Aa, _f, _f
_f, _f, Aa, _f, Aa, _f, Aa, _f, _f
Aa, Aa, _f, _f, Aa, Aa, Aa, _f, _f
_f, _f, Aa, Aa, Aa, Aa, Aa, Aa, Aa
_f, _f, _f, Aa, Aa, Aa, Aa, Aa, Aa
_f, _f, _f, _f, Aa, Aa, _f, _f, _f
_f, _f, _f, _f, Aa, Aa, _f, _f, _f"
[rule]
old=Gg^Vh
new=Aa
terrain=Aa^Vha
[/rule]
[rule]
old=Gs^Fp
new=Aa
terrain=Aa^Fpa
[/rule]
[rule]
old=Hh
new=Aa
terrain=Ha
[/rule]

[rule]
old=Gg,Re
new=Aa
#don't specify terrain and it just uses the new terrain
[/rule]

#default: Will match everything, since 'old' and 'new' aren't
#specified. Set 'use_old=yes' to signal no change.
[rule]
use_old=yes
[/rule]
[/terrain_mask]

TerrainWML

2009-03-22T11:12:04Z

Nital: removing {{DevFeature}} tags

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

The [terrain] tag describes a terrain in WML.
Terrains are usually described in the terrain.cfg file

the [terrain] tag has the following keys and subtags
* '''symbol_image''': an image used for this terrain in the minimap
* '''editor_image''': an image used for this terrain in the map editor if not defined uses symbol_image
* '''name''': the name of the terrain
* '''string''': this is the string that represents the terrain in maps and scenarions
* '''unit_height_adjust''': how much the unit graphic should be moved up or down when on that terrain
* '''submerge''': float, between 0 and 1: stems how much of the unit graphic should be submerged by the terrain
* '''light''': signed value: this will modified local light level on that hex by that amount for gameplay
* '''heals''': signed value: this value is the amount of HP an unit will be healed at the start of every turn. (If set to true a unit on that terrain will be healed 8 HP at the start of every turn, this notation is deappriciated and support might stop at some point.)
* '''gives_income''': if set to true, this terrain will give income every turn when flagged as if it were a village
* '''recruit_onto''': if set to true, it is possible to recruit or recall on that terrain
* '''recruit_from''': if set to true it is possible to recruit when a unit that can recruit is on that terrain
* '''aliasof''': comma separated string representing terrains that this terrain will be an alias of. This is a list of characters, with the + and - signs having special meanings. the string is read left to right taking the best value. when a minus sign is encountered, it starts taking the worst instead. the plus sign reverts it back to the best (note after a + or - a comma is also required. In order to include a + sign the entire line must be placed between double quotes.)
* '''def_alias''': like ''aliasof'' but overides it for defense calculation only
* '''mvt_alias''': like ''aliasof'' but overides it for movement calculation only
* '''income_description''': for terrains with ''gives_income'' and owned by nobody this text is shown in the terrain description in the top bar before the brackets. This tag is optional, if not supplied Wesnoth will assume the terrain is a village and sets an appropriate message.
* '''income_description_ally''': like ''income_description'' but if owned by an ally
* '''income_description_enemy''': like ''income_description'' but if owned by an enemy
* '''income_description_own''': like ''income_description'' but if owned by yourself
* '''editor_group''': a comma separated list of editor_group ids to which this terrain belongs.
* '''hidden''': (boolean) if set to 'yes', makes this terrain not appear in the map editor palettes.

== See Also ==

* [[ReferenceWML]]
* [[TerrainCodesWML]]
* [[EditorGroupWML]]

[[Category: WML Reference]]

CampaignServerWML

2009-03-22T11:11:10Z

Nital: removing {{DevFeature}} tags

= Campaign Server WML =

This page describes the WML commands exchanged between campaign download clients and a campaign server.

== Listing Available Campaigns ==

This request is used to retrieve a list of campaigns available on the server and some overview information about them.

* Request
** '''[request_campaign_list]'''
*** '''after''': only select campaigns last updated after the indicated time. ''after'' is in seconds relative to either the time when the command is processed or the [http://wikipedia.org/wiki/Unix_epoch Unix epoch]. As an example, to select campaigns last updated after Mon Oct 10 21:42:41 2005 GMT, you could not specify a value for ''times_relative_to'' (to use the default of relative to the [http://wikipedia.org/wiki/Unix_epoch Unix epoch]) and specify ''after'' = "1128980561".
*** '''before''': only select campaigns last updated before the indicated time. ''before'' is in seconds relative to either the time when the command is processed or the [http://wikipedia.org/wiki/Unix_epoch Unix epoch]. As an example, to select campaigns last updated over a day ago, you could specify ''times_relative_to'' = "now" and ''before'' = "-86400".
*** '''language''': return information only about campaigns that appear to be translated into this language. These names will normally be POSIX locale names. Typically you will want to either use a two letter language code (e.g. "de") or a two letter language code followed by a two character region code (e.g. "pt_BR"). Note that "pt" will not match "pt_BR".
*** '''name''': return information for this campaign. If the name is specified and not the empty string then only information about campaigns with matching names (unless something changes there will be at most one such campaign) will be returned.
*** '''times_relative_to''': "now" means that ''before'' and ''after'' are in seconds relative to the time when the request is processed by the campaign server. Any other value, or if it is not set, indicates that ''before'' and ''after'' are in seconds relative to the [http://wikipedia.org/wiki/Unix_epoch Unix epoch].
* Response
** '''timestamp''': what time the campaign server thought it was when this response was generated. You shouldn't count on this as a guaranty that no new campaigns will appear with previous update times. This could be used to detect significant clock skew or possibly used as an approximate time for how far you need to look back for updated campaigns.
** '''[campaigns]'''
*** '''[campaign]'''
**** '''author''': author(s) of the campaign.
**** '''dependencies''': list of add-on dependencies
**** ''description'': (current trunk only) description of the campaign. For pre 1.0 campaigns this should also describe the playability.
**** '''downloads''': the number times the campaign (including previous versions) has been downloaded directly from the campaign server.
**** '''filename''': filename campaign is stored in (currently the same as ''name'').
**** '''icon''': path to an image in the standard image directory for Wesnoth. This path must use forward slashes (/). It cannot refer to custom images included with the campaign. It is allowed to use [[ImagePathFunctionWML]]. This image is displayed as an icon by the campaign client built into Wesnoth.
**** '''name''': the name of the campaign. Note this is not the title and shouldn't have spaces in it.
**** '''size''': the size of the campaign in bytes on the campaign server.
**** '''timestamp''': when this version of the campaign was uploaded.
**** '''title''': campaign title. This is not a translatable string.
**** '''translate''': whether the campaign will be automatically send to wescamp and updated from wescamp.
**** '''uploads''': (current trunk only) number of uploads (initial upload gets 1)
**** '''version''': version of the campaign. The recommended format is x.y.z where x, y and z are decimal strings. x should be 0 for campaigns that are not yet complete.
**** '''type''': indicates the type of the add-on, used for the downloads manager dialog. Possible values are described in [[PblWML]].
**** '''[translation]'''
***** '''language''': a language that this campaign has appeared to have been at least partially translated into. The following heuristic is used when a campaign is uploaded to extract a list of languages. The list of directories in the uploaded campaign is recursively searched. If a directory named 'LC_MESSAGES' is found then the name of the object containing this '''[dir]''' (normally the parent directory, but could be the campaign name if someone did something silly) is added to the list of translations. Directories named "LC_MESSAGES" are not searched for further matches. The normal naming convention is to use Posix locale names. This will usually be a two letter language code (e.g. "de") or a two letter language code followed by a two letter region code (e.g. "pt_BR"). Since "en_US" is the base language, this language will not be listed as an available translation.

== Downloading a Campaign ==

This command is used to download a specified campaign from the campaign server.

* Request
** '''[request_campaign]'''
*** '''name''': the name of the campaign. Note this is not the title and shouldn't have spaces in it.
* Response
** '''author''': author(s) of the campaign.
** '''campaign_name''': the name of the campaign. Note this is not the title and shouldn't have spaces in it.
** '''description''': description of the campaign. For pre 1.0 campaigns this should also describe the playability.
** '''icon''': path to an image in the standard image directory for Wesnoth. This path must use forward slashes (/). It cannot refer to custom images included with the campaign. It is allowed to use [[ImagePathFunctionWML]]. This image is displayed as an icon by the campaign client built into Wesnoth.
** '''name''': this field will always be empty. Client code would treat it as a directory name if it was not empty.
** '''timestamp''': the time the campaign was last uploaded to the campaign server. This is a decimal string containing the number of seconds since the unix epoch.
** '''title''': the title of the campaign. This is not a translatable string.
** '''version''': version of the campaign. The recommended format is x.y.z where x, y and z are decimal strings. x should be 0 for campaigns that are not yet complete.
** '''type''': indicates the type of the add-on, used for the downloads manager dialog. Possible values are described in [[PblWML]].
** '''[file]'''
*** '''name''': the name of the file. This does not include any path information.
*** '''contents''': the content of the file (binary data). This data should have no zero bytes. A byte with the code of 1 is an escape byte. The next byte will be data, but its value should be reduced by 1. Normally only byte codes of 0 and 1 are escaped.
** '''[dir]'''
*** '''name''': the name of the directory. This does not include any path information.
*** This tag may contain '''[file]''' or '''[dir]''' subtags (the latter are recursive).

== Uploading a Campaign ==

This command is used to upload a new or updated version of an add on campaign to the campaign server.

* Request
** '''[upload]'''
*** '''author''': author(s) of the campaign.
*** '''description''': description of the campaign. For pre 1.0 campaigns this should also describe the playability.
*** '''icon''': path to an image in the standard image directory for Wesnoth. This path must use forward slashes (/). It cannot refer to custom images included with the campaign. It is allowed to use [[ImagePathFunctionWML]]. This image is displayed as an icon by the campaign client built into Wesnoth.
*** '''name''': the name of the campaign. Note this is not the title and shouldn't have spaces in it.
*** '''passphrase''': this is used to control updates to campaigns on the server. For existing campaigns, if the passphrase doesn't match, the update will be rejected. You can't easily change the passphrase yourself. If you lose or need to change the passphrase you need to contact the server administrator.
*** '''email''': it is used by campaign server administrators to contact authors in case of important problems with their add-ons (incompatibilities, broken data files, violation of server [[Distributing_content#License|policies]], etc.).
*** '''title''': the title of the campaign. This is not a translatable string.
*** '''version''': version of the campaign. The recommended format is x.y.z where x, y and z are decimal strings. x should be 0 for campaigns that are not yet complete.
*** '''type''': indicates the type of the add-on, used for the downloads manager dialog. Possible values are described in [[PblWML]].
*** '''[data]'''
**** '''[file]'''
***** '''name''': the name of the file. This does not include any path information.
***** '''contents''': the content of the file (binary data). This data should have no zero bytes. A byte with the code of 1 is an escape byte. The next byte will be data, but its value should be reduced by 1. Normally only byte codes of 0 and 1 are escaped.
**** '''[dir]'''
***** '''name''': the name of the directory. This does not include any path information.
***** This tag may contain '''[file]''' or '''[dir]''' subtags (the latter are recursive).
* Response
** '''[message]'''
*** '''message''': translatable string that indicates that the campaign upload was successful.

== Changing the Passphrase for a Campaign ==

This command is used to change the passphrase for a campaign. Currently the normal client doesn't have a way to use this. However, you can use the perl script campaign_passphrase.pl to do it, if you have a copy of the source tree.

* Request
** '''[change_passphrase]'''
*** '''name''': The name of campaign.
*** '''passphrase''': The old passphrase.
*** '''new_passphrase''': The new passphrase.
* Respose
** '''[message]'''
*** '''message''': Translatable string that says that the passphrase was changed.

== Deleting a Campaign ==

This command is used to delete an existing campaign from the campaign server.

* Request
** '''[delete]'''
*** '''name''': The name of the campaign to delete.
*** '''passphrase''': This must match the passphrase on record for the campaign or the master_password in order for the campaign to be deleted. Master_password.
* Response
** '''[message]'''
*** '''message''': Translatable string that says that the campaign was deleted.

== Request License Information ==

Retrieve the terms of the license used for any uploaded campaigns. You may not upload a campaign if you don't (or can't) aggree to the license. Wesnoth requires campaigns (including images and sound) to be licensed under the GPL. For more information on licensing, see [[Wesnoth:Copyrights]].

* Request
** '''[request_terms]'''
* Response
** '''[message]'''
*** '''message''': translatable string containing the text of the license.

== Developer commands ==

* Request
** '''[validate_scripts]'''
*** '''name''': The name of the campaign to sign.
*** '''master_password''': The signing password.
* Response
** '''[message]'''
*** '''message''': Translatable(?) string that says that the campaign was signed.

== See Also ==

* [[UserScenarios#Campaign_Server_Web_Access]]
* [[PblWML]]
* [[BuildingCampaignsThePBLFile]]

[[Category:WML Reference]]

CampaignServerWML

2009-03-22T11:10:29Z

Nital: removing {{DevFeature}} tags

= Campaign Server WML =

This page describes the WML commands exchanged between campaign download clients and a campaign server.

== Listing Available Campaigns ==

This request is used to retrieve a list of campaigns available on the server and some overview information about them.

* Request
** '''[request_campaign_list]'''
*** '''after''': only select campaigns last updated after the indicated time. ''after'' is in seconds relative to either the time when the command is processed or the [http://wikipedia.org/wiki/Unix_epoch Unix epoch]. As an example, to select campaigns last updated after Mon Oct 10 21:42:41 2005 GMT, you could not specify a value for ''times_relative_to'' (to use the default of relative to the [http://wikipedia.org/wiki/Unix_epoch Unix epoch]) and specify ''after'' = "1128980561".
*** '''before''': only select campaigns last updated before the indicated time. ''before'' is in seconds relative to either the time when the command is processed or the [http://wikipedia.org/wiki/Unix_epoch Unix epoch]. As an example, to select campaigns last updated over a day ago, you could specify ''times_relative_to'' = "now" and ''before'' = "-86400".
*** '''language''': return information only about campaigns that appear to be translated into this language. These names will normally be POSIX locale names. Typically you will want to either use a two letter language code (e.g. "de") or a two letter language code followed by a two character region code (e.g. "pt_BR"). Note that "pt" will not match "pt_BR".
*** '''name''': return information for this campaign. If the name is specified and not the empty string then only information about campaigns with matching names (unless something changes there will be at most one such campaign) will be returned.
*** '''times_relative_to''': "now" means that ''before'' and ''after'' are in seconds relative to the time when the request is processed by the campaign server. Any other value, or if it is not set, indicates that ''before'' and ''after'' are in seconds relative to the [http://wikipedia.org/wiki/Unix_epoch Unix epoch].
* Response
** '''timestamp''': what time the campaign server thought it was when this response was generated. You shouldn't count on this as a guaranty that no new campaigns will appear with previous update times. This could be used to detect significant clock skew or possibly used as an approximate time for how far you need to look back for updated campaigns.
** '''[campaigns]'''
*** '''[campaign]'''
**** '''author''': author(s) of the campaign.
**** '''dependencies''': list of add-on dependencies
**** ''description'': (current trunk only) description of the campaign. For pre 1.0 campaigns this should also describe the playability.
**** '''downloads''': the number times the campaign (including previous versions) has been downloaded directly from the campaign server.
**** '''filename''': filename campaign is stored in (currently the same as ''name'').
**** '''icon''': path to an image in the standard image directory for Wesnoth. This path must use forward slashes (/). It cannot refer to custom images included with the campaign. It is allowed to use [[ImagePathFunctionWML]]. This image is displayed as an icon by the campaign client built into Wesnoth.
**** '''name''': the name of the campaign. Note this is not the title and shouldn't have spaces in it.
**** '''size''': the size of the campaign in bytes on the campaign server.
**** '''timestamp''': when this version of the campaign was uploaded.
**** '''title''': campaign title. This is not a translatable string.
**** '''translate''': whether the campaign will be automatically send to wescamp and updated from wescamp.
**** '''uploads''': (current trunk only) number of uploads (initial upload gets 1)
**** '''version''': version of the campaign. The recommended format is x.y.z where x, y and z are decimal strings. x should be 0 for campaigns that are not yet complete.
**** '''type''': indicates the type of the add-on, used for the downloads manager dialog. Possible values are described in [[PblWML]].
**** '''[translation]'''
***** '''language''': a language that this campaign has appeared to have been at least partially translated into. The following heuristic is used when a campaign is uploaded to extract a list of languages. The list of directories in the uploaded campaign is recursively searched. If a directory named 'LC_MESSAGES' is found then the name of the object containing this '''[dir]''' (normally the parent directory, but could be the campaign name if someone did something silly) is added to the list of translations. Directories named "LC_MESSAGES" are not searched for further matches. The normal naming convention is to use Posix locale names. This will usually be a two letter language code (e.g. "de") or a two letter language code followed by a two letter region code (e.g. "pt_BR"). Since "en_US" is the base language, this language will not be listed as an available translation.

== Downloading a Campaign ==

This command is used to download a specified campaign from the campaign server.

* Request
** '''[request_campaign]'''
*** '''name''': the name of the campaign. Note this is not the title and shouldn't have spaces in it.
* Response
** '''author''': author(s) of the campaign.
** '''campaign_name''': the name of the campaign. Note this is not the title and shouldn't have spaces in it.
** '''description''': description of the campaign. For pre 1.0 campaigns this should also describe the playability.
** '''icon''': path to an image in the standard image directory for Wesnoth. This path must use forward slashes (/). It cannot refer to custom images included with the campaign. It is allowed to use [[ImagePathFunctionWML]]. This image is displayed as an icon by the campaign client built into Wesnoth.
** '''name''': this field will always be empty. Client code would treat it as a directory name if it was not empty.
** '''timestamp''': the time the campaign was last uploaded to the campaign server. This is a decimal string containing the number of seconds since the unix epoch.
** '''title''': the title of the campaign. This is not a translatable string.
** '''version''': version of the campaign. The recommended format is x.y.z where x, y and z are decimal strings. x should be 0 for campaigns that are not yet complete.
** '''type''': {{DevFeature}} indicates the type of the add-on, used for the downloads manager dialog. Possible values are described in [[PblWML]].
** '''[file]'''
*** '''name''': the name of the file. This does not include any path information.
*** '''contents''': the content of the file (binary data). This data should have no zero bytes. A byte with the code of 1 is an escape byte. The next byte will be data, but its value should be reduced by 1. Normally only byte codes of 0 and 1 are escaped.
** '''[dir]'''
*** '''name''': the name of the directory. This does not include any path information.
*** This tag may contain '''[file]''' or '''[dir]''' subtags (the latter are recursive).

== Uploading a Campaign ==

This command is used to upload a new or updated version of an add on campaign to the campaign server.

* Request
** '''[upload]'''
*** '''author''': author(s) of the campaign.
*** '''description''': description of the campaign. For pre 1.0 campaigns this should also describe the playability.
*** '''icon''': path to an image in the standard image directory for Wesnoth. This path must use forward slashes (/). It cannot refer to custom images included with the campaign. It is allowed to use [[ImagePathFunctionWML]]. This image is displayed as an icon by the campaign client built into Wesnoth.
*** '''name''': the name of the campaign. Note this is not the title and shouldn't have spaces in it.
*** '''passphrase''': this is used to control updates to campaigns on the server. For existing campaigns, if the passphrase doesn't match, the update will be rejected. You can't easily change the passphrase yourself. If you lose or need to change the passphrase you need to contact the server administrator.
*** '''email''': {{DevFeature}} it is used by campaign server administrators to contact authors in case of important problems with their add-ons (incompatibilities, broken data files, violation of server [[Distributing_content#License|policies]], etc.).
*** '''title''': the title of the campaign. This is not a translatable string.
*** '''version''': version of the campaign. The recommended format is x.y.z where x, y and z are decimal strings. x should be 0 for campaigns that are not yet complete.
*** '''type''': {{DevFeature}} indicates the type of the add-on, used for the downloads manager dialog. Possible values are described in [[PblWML]].
*** '''[data]'''
**** '''[file]'''
***** '''name''': the name of the file. This does not include any path information.
***** '''contents''': the content of the file (binary data). This data should have no zero bytes. A byte with the code of 1 is an escape byte. The next byte will be data, but its value should be reduced by 1. Normally only byte codes of 0 and 1 are escaped.
**** '''[dir]'''
***** '''name''': the name of the directory. This does not include any path information.
***** This tag may contain '''[file]''' or '''[dir]''' subtags (the latter are recursive).
* Response
** '''[message]'''
*** '''message''': translatable string that indicates that the campaign upload was successful.

== Changing the Passphrase for a Campaign ==

This command is used to change the passphrase for a campaign. Currently the normal client doesn't have a way to use this. However, you can use the perl script campaign_passphrase.pl to do it, if you have a copy of the source tree.

* Request
** '''[change_passphrase]'''
*** '''name''': The name of campaign.
*** '''passphrase''': The old passphrase.
*** '''new_passphrase''': The new passphrase.
* Respose
** '''[message]'''
*** '''message''': Translatable string that says that the passphrase was changed.

== Deleting a Campaign ==

This command is used to delete an existing campaign from the campaign server.

* Request
** '''[delete]'''
*** '''name''': The name of the campaign to delete.
*** '''passphrase''': This must match the passphrase on record for the campaign or the master_password in order for the campaign to be deleted. Master_password.
* Response
** '''[message]'''
*** '''message''': Translatable string that says that the campaign was deleted.

== Request License Information ==

Retrieve the terms of the license used for any uploaded campaigns. You may not upload a campaign if you don't (or can't) aggree to the license. Wesnoth requires campaigns (including images and sound) to be licensed under the GPL. For more information on licensing, see [[Wesnoth:Copyrights]].

* Request
** '''[request_terms]'''
* Response
** '''[message]'''
*** '''message''': translatable string containing the text of the license.

== Developer commands ==

* Request
** '''[validate_scripts]'''
*** '''name''': The name of the campaign to sign.
*** '''master_password''': The signing password.
* Response
** '''[message]'''
*** '''message''': Translatable(?) string that says that the campaign was signed.

== See Also ==

* [[UserScenarios#Campaign_Server_Web_Access]]
* [[PblWML]]
* [[BuildingCampaignsThePBLFile]]

[[Category:WML Reference]]

ImagePathFunctions

2009-03-22T11:09:21Z

Nital: removing {{DevFeature}} tags

Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).

== Team-Color Function ==
In Wesnoth version 1.2, the only Image Path Function was '''~TC()''', which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file ''data/team-colors.cfg''

=== Syntax ===
'''~TC(''' ''team number'' ''',''' ''source color palette'' ''')'''
*''team number'' - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).
*''source color palette'' - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.

== Re-Color Function ==
May be used to change some colors in an image.
=== Syntax ===
'''~RC(''' ''source color palette'' '''>''' ''color range ID'' ''')'''
*''source color palette'' - the first parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.
*''color range ID'' - this is the second parameter, signifying the ID of a color range defined in the file ''data/core/team-colors.cfg'' (or it may be a custom ID for a color range defined locally).

In 1.6, the following syntax changes the RC function behavior for simply replacing colors matching the source color palette with colors of the target color palette:

'''~RC(''' ''source color palette'' '''=''' ''target color palette'' ''')'''

=== Example ===
In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:

[message]
speaker=narrator
image=units/elves-wood/captain.png~RC(magenta>green)
message=_ "Now I am on the green team."
[/message]

The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended

== Flip Function ==
May be used to flip an image horizontally and/or vertically
=== Syntax ===
'''~FL(''' ''optional argument list'' ''')'''
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizantally.
*if the argument list is empty, the image will only be flipped horizantally.

== Greyscale Function ==
May be used to greyscale the image (turn to black and white)
=== Syntax ===
'''~GS( )'''

== Crop Function ==
Extracts a rectangular section of an image file.
=== Syntax ===
'''~CROP(x,y,width,height)'''
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.
* ''width'': width of the selected region. Must be less than or equal to the original image's width.
* ''height'': height of the selected region. Must be less than or equal to the original image's height.

== Color-shift function ==
Performs simple per-channel color shifts by adding the arguments to the respective color channels.
=== Syntax ===
''Multi-channel:'' '''~CS(r,g,b)'''
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''

The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.

The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.

Any color-shift is performed before changing opacity or desaturating the graphic (see ~O() and ~GS()).

== Image-scaling function ==
Scales a graphic up or down.
=== Syntax ===

'''~SCALE( ''new_width'', ''new_height'' )

The ''new_width'' and ''new_height'' parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr.

== Opacity modifying function ==
Changes an image's opacity at render time.
=== Syntax ===

'''~O( ''factor or percentage%'' )'''

If the argument includes the percentage symbol (''%''), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).

Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.

== Blurring function ==
Blurs a graphic at render time using the same algorithm used for in-game dialogs.
=== Syntax ===

'''~BL( ''radius'' )'''

== Precedence of Functions ==

All functions are applied in left-to-right order, with the exception of RC() and TC() which are applied always before any other functions.
That is, stuff like "units/elves-wood/fighter.png~CROP(0,0,20,20)~CROP(10,10,10,10)" would result in taking a crop of the rectangle x=20;y=20;w=40;h=40 and then taking a crop from ''that'' rectangle as x=10;y=10;w=10;h=10 resulting in the area x=30;y=30;w=10;h=10 from the original graphic.

[[Category:WML Reference]]

ImagePathFunctions

2009-03-22T11:08:23Z

Nital: removing {{DevFeature}} tags

Image Path Functions provide a simple method for WML coders to alter the way their specified images will be displayed in the game. All of the function parameters are included at the end of an image path and should not contain any spaces or special characters (other than those specified here).

== Team-Color Function ==
In Wesnoth version 1.2, the only Image Path Function was '''~TC()''', which took two comma-separated parameters: the team number and the source color palette. The valid values for both of these parameters are defined in the file ''data/team-colors.cfg''

=== Syntax ===
'''~TC(''' ''team number'' ''',''' ''source color palette'' ''')'''
*''team number'' - this is the first parameter, a number 1-9 signifying the team number of a unit. Number 1 typically means the red team, 2 typically means the blue team, and so on (unless the scenario color settings for any side have been altered).
*''source color palette'' - the second parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.

== Re-Color Function ==
May be used to change some colors in an image.
=== Syntax ===
'''~RC(''' ''source color palette'' '''>''' ''color range ID'' ''')'''
*''source color palette'' - the first parameter is a source color palette, usually magenta. Do not surround this parameter with quotes.
*''color range ID'' - this is the second parameter, signifying the ID of a color range defined in the file ''data/core/team-colors.cfg'' (or it may be a custom ID for a color range defined locally).

{{DevFeature}} In the development version, the following syntax changes the RC function behavior for simply replacing colors matching the source color palette with colors of the target color palette:

'''~RC(''' ''source color palette'' '''=''' ''target color palette'' ''')'''

=== Example ===
In the following example, the magenta regions in an elvish captain's image are turned a healthy shade of green:

[message]
speaker=narrator
image=units/elves-wood/captain.png~RC(magenta>green)
message=_ "Now I am on the green team."
[/message]

The IDs of the color ranges may be the lowercased English name of the palette's base color (e.g. 'red', 'brown', etc.). They may also be numeric color indices from the palette WML included with the game, but this is not recommended

== Flip Function ==
May be used to flip an image horizontally and/or vertically
=== Syntax ===
'''~FL(''' ''optional argument list'' ''')'''
*''vertical'' - if the string "vert" is found anywhere in the argument list, the image will be flipped vertically.
*''horizontal'' - if the string "horiz" is found anywhere in the argument list, the image will be flipped horizantally.
*if the argument list is empty, the image will only be flipped horizantally.

== Greyscale Function ==
May be used to greyscale the image (turn to black and white)
=== Syntax ===
'''~GS( )'''

== Crop Function {{DevFeature}} ==
Extracts a rectangular section of an image file.
=== Syntax ===
'''~CROP(x,y,width,height)'''
* ''x'',''y'': top-left corner coordinates for the rectangular section extracted. Must be greater or equal than zero, and inside the image's bounds.
* ''width'': width of the selected region. Must be less than or equal to the original image's width.
* ''height'': height of the selected region. Must be less than or equal to the original image's height.

== Color-shift function {{DevFeature}} ==
Performs simple per-channel color shifts by adding the arguments to the respective color channels.
=== Syntax ===
''Multi-channel:'' '''~CS(r,g,b)'''
''Single-channel:'' '''~R(v)''', '''~G(v)''', '''~B(v)'''

The multichannel syntax assumes all arguments are set to zero initially, so one can use, e.g. ~CS(2,4) to add +2 and +4 units to the red and green channels respectively, leaving the blue channel intact. Arguments may be negative to diminish a channel's value; this can be used to change an image's brightness. Checks for out-of-range arguments or results (less than 0 or greater than 255) are made, so the resultant values are truncated if necessary.

The single channel syntax behaves exactly the same, except that only single-channel modifications are made per function. However, one can stack them to produce the same behavior as ~CS(), e.g. ~R(r)~G(g)~B(b), but that tends to be just a performance loss.

Any color-shift is performed before changing opacity or desaturating the graphic (see ~O() and ~GS()).

== Image-scaling function {{DevFeature}} ==
Scales a graphic up or down.
=== Syntax ===

'''~SCALE( ''new_width'', ''new_height'' )

The ''new_width'' and ''new_height'' parameters are taken as the image's original width or height, respectively, if one of them happens to be zero. Negative values are treated in the same way, but an error is printed in stderr.

== Opacity modifying function {{DevFeature}} ==
Changes an image's opacity at render time.
=== Syntax ===

'''~O( ''factor or percentage%'' )'''

If the argument includes the percentage symbol (''%''), it will be treated as a percentage of full (real) opacity; an image will be displayed at its native opacity with ~O(100%).

Without the percentage symbol, the argument is assumed to be a factor by which the image's native opacity should be multiplied. Thus, ~O(0.5) and ~O(50%) are equivalent forms of specifying to reduce an image's opacity by half.

== Blurring function {{DevFeature}} ==
Blurs a graphic at render time using the same algorithm used for in-game dialogs.
=== Syntax ===

'''~BL( ''radius'' )'''

== Precedence of Functions ==

All functions are applied in left-to-right order, with the exception of RC() and TC() which are applied always before any other functions.
That is, stuff like "units/elves-wood/fighter.png~CROP(0,0,20,20)~CROP(10,10,10,10)" would result in taking a crop of the rectangle x=20;y=20;w=40;h=40 and then taking a crop from ''that'' rectangle as x=10;y=10;w=10;h=10 resulting in the area x=30;y=30;w=10;h=10 from the original graphic.

[[Category:WML Reference]]

LabelWML

2009-03-22T11:04:31Z

Nital: removing {{DevFeature}} tags

{{WML Tags}}
== The [label] tag ==

The following keys and tags are recognized in '''[label]''' tag:

* '''text''': Visible text in label.

* '''team_name''': Name of the team that can see the label. Label is visible to everyone if this is empty.

* '''colour''': colour of the label. Format is ''r,g,b'' where r, g and b are number between 0 and 255.

* '''x''': Location for the label

* '''y''': Location for the label

* '''fogged'''(Yes/No): Controls if the label is to be hidden under fog or not (by default all labels are hidden under fog)
[[Category:WML Reference]]

Maintenance tools

2009-03-22T11:01:59Z

Nital: removing {{DevFeature}} tags

The Wesnoth source code distribution includes a couple of tools intended to help authors maintain campaigns, faction & unit packs, and other WML resources. These
are:

; wmlscope: a cross-reference lister, useful for finding unresolved macro and resource-file references.

; wmllint: a utility for sanity-checking WML syntax and porting your old WML to the current version of WML.

; wmlindent: a utility for reindenting WML to a uniform style.

You will need a Python interpreter on your system to use these tools. Linux, *BSD, and Mac OS/X should already have Python installed; for Windows it's a free download
from http://www.python.org. You will also need to know how to run command-line tools
on your system.

All three tools will require you to supply a directory list. This is a set of directories containing the WML files you want to work on.

Note to Windows Users: This means you have to run it from the '''Command Line'''. The command line may be reached by hitting Start, then Run, then "cmd" or "command" depending on your version of Windows.

Example uses:
python wmllint --oldversion=1.3.4 path\to\files
python wmlindent path\to\files

Another example:
"C:\Program Files\Python2.4\python.exe" data\tools\wmllint --dryrun data\core data\{multiplayer,themes} data\campaigns
(You have to specify the full directory path to the executable if you don't have your environment variables set up correctly).
The first thing you type is the path to your python executable, followed by a space. The second thing you type is the path to the desired script to run, followed by a space. The third thing you type is the path to the folder (or file) to be processed.

== wmlscope ==

The main use for <tt>wmlscope</tt> is to find WML macro references without definitions and references to resource files (sounds and images) that don't exist. These are difficult to spot from in-game because they usually result in silence or a missing image rather than actual broken game logic. They may happen because of typos in your WML, or because the name of a macro or the location of a resource file changed between versions of the game.

<tt>wmlscope</tt> also checks macro invocations for consistency. It will complain
if a macro is called with the wrong number of arguments. In most cases it can deduce information about the type of the literal expected to be passed to a given macro argument by looking at the name of the formal.

<table border="1"><tr>
<th>Type</th>
<th>Meanining</th>
<th>Formals requiring this type</th>
<th>Literals of this type</th>
</tr>
<tr>
<td>macro</td>
<td>A macro invocation</td>
<td></td>
<td>{.*}</td>
</tr>
<tr>
<td>numeric</td>
<td>a numeric literal</td>
<td>SIDE, X, Y, RED, GREEN, BLUE, TURN, RADIUS, *NUMBER, *AMOUNT, *COST, *_X, *_Y</td>
<td>\-?[0-9]+</td>
</tr>
<tr>
<td>position</td>
<td>a coordinate, coordinate range, or set of coordinate ranges</td>
<td>POSITION</td>
<td>([0-9]+\-[0-9]+,?|[0-9]+,?)+</td>
</tr>
<tr>
<td>span</td>
<td>a coordinate, coordinate range, or set of coordinate ranges</td>
<td>*_SPAN</td>
<td>"melee" or "ranged"</td>
</tr>
<tr>
<td>range</td>
<td>an attack range</td>
<td>RANGE</td>
<td>"melee" or "ranged"</td>
</tr>
<tr>
<td>alignment</td>
<td>an alignment keyword</td>
<td>ALIGN</td>
<td>"lawful" or "neutral" or "chaotic"</td>
</tr><tr>
<td>image</td>
<td>an image name</td>
<td>IMAGE</td>
<td>string ending in .png or .jpg</td>
</tr>
<tr>
<td>terrain</td>
<td>a terrain code</td>
<td>TERRAIN</td>
<td>[A-Z][a-z]+\^[A-Z][a-z\\|/]+\Z</td>
</tr>
<tr>
<td>sound</td>
<td>a music or sound resource</td>
<td>MUSIC, SOUND</td>
<td>\.wav|\.ogg</td>
</tr>
<tr>
<td>affix</td>
<td>a prefix, suffix, or infix for a variable name</td>
<td>AFFIX</td>
<td>an ID or nothing </td>
</tr>
<tr>
<td>image</td>
<td>an image name</td>
<td>IMAGE</td>
<td>string ending in .png or .jpg</td>
</tr><tr>
<td>filter</td>
<td>filter expression</td>
<td>FILTER</td>
<td>any non-quoted string containing "="</td>
</tr>
<tr>
<td>WML</td>
<td>a WML fragment</td>
<td>*_WML</td>
<td>any non-quoted string containing "=", or the empty string</td>
</tr>
<tr>
<td>name</td>
<td>a name or ID</td>
<td>NAME, VAR, IMAGESTEM, ID</td>
<td>[A-Z][a-z]+\^[A-Z][a-z\\|/]+\Z</td>
</tr>
<tr>
<td>string</td>
<td>a nonempty string not matching any of the preceding types</td>
<td>TYPE, TEXT, *_TEXT</td>
<td>Anything surrounded by doublequotes,
'''or'' anything with embedded spaces that doesn't match one of the preceding types</td>
</tr>
<tr>
<td>optional string</td>
<td>a string value (may be empty)</td>
<td>DESCRIPTION, USER_DESCRIPTION</td>
<td>Anything surrounded by doublequotes,
'''or'' anything with embedded spaces that doesn't match one of the preceding types</td>
</tr>
<tr>
<td>value</td>
<td>anything</td>
<td>*VALUE</td>
<td>anything</td>
</tr>
</table>

Any numeric or position is accepted by a span argument. Any image or name is accepted for a string argument. Any actual argument that is a macro is accepted for any formal. Otherwise, if the formal has an identifiable type, <tt>wmlscope</tt> will complain if the actual literal does not match it.

The argument type check only works in macro calls that fit on a single line.

<tt>wmlscope</tt> has many options for changing the reports it generates; the more advanced ones are intended for Wesnoth developers. Invocations for the most commonly useful reports it generates are included in data/tools/Makefile of the source distribution. Here are some of those reports:

; make unresolved: Report on unresolved macro calls and resource references; also report macro argument-type mismatches. (This is what you are most likely to want to do).

; make all: Report all macro and resource file references, not just unresolved ones.

; make collisions: Report on duplicate resource files.

For more advanced users, or those who want to understand what the canned Makefile invocations are doing, here is a summary of <tt>wmlscope</tt>'s options. Some of the more advanced options will require you to understand
[http://docs.python.org/lib/re-syntax.html Python regular expressions].

; -h, --help: Emit a help message and quit
; -c, --crossreference: Report resolved macro references (implies -w 1)
; -C, --collisions: Report duplicate resource files
; -d, --deflist: Make definition list. (This one is for campaign server maintainers.)
; -e regexp, --exclude regexp: Ignore files matching the specified regular expression.
; -f dir, --from dir: Report only on macros defined under dir
; -l, --listfiles: List files that will be processed
; -r ddd, --refcount=ddd: Report only on macros with references in exactly ddd files.
; -u, --unresolved: Report unresolved macro references
; -w, --warnlevel: Set to 1 to warn of duplicate macro definitions
; --force-used reg: Ignore reference count 0 on names matching regexp
; --extracthelp: Extract help from macro definition comments.

== wmllint ==

<tt>wmllint</tt> is a tool for migrating your WML to the current version. It handles two problems:

* Resource files and macro names may change between versions of the game. <tt>wmllint</tt> knows about these changes and will tweak your WML to fit where it can.

* Between 1.2.x and 1.3.1 the terrain-coding system used in map files underwent a major change. It changed again in a minor way between 1.3.1 and 1.3.2. <tt>wmllint</tt> will translate your maps for you, unless you use custom terrains in which case you will have to do it by hand.

<tt>wmllint</tt> also performs various sanity-checking operations, reporting:

* unbalanced tags
* strings that need a translation mark and do not have them
* strings that have a translation mark and should not
* translatable strings containing macro references
* filter references by description= (id= in 1.5) not matched by an actual unit
* abilities or traits without matching special notes, or vice-versa
* consistency between recruit= and recruitment_pattern= instances
* double space after punctuation in translatable strings.
* unknown races or movement types in units

<tt>wmllint</tt> takes a directory-path argument specifying the WML directories to work on. It will modify any cfg and map files under those directories that need to be changed. Here is a summary of its options:

; -h, --help: Emit a help message and quit.
; -d, --dryrun: List changes but don't perform them.
; -v, --verbose: Set verbosity; more details below.
; -c, --clean: Clean up -bak files.
; -D, --diff: Show diffs between unconverted and unconverted files.
; -r, --revert: Revert the conversion from the -bak files.
; -n, --nolift: Suppress lifting, do sanity checks only

The verbosity option works like this:

; -v: lists changes.
; -v -v: warns of maps already converted.
; -v -v -v: names each file before it's processed.
; -v -v -v -v: shows verbose parse details (developers only).

The recommended procedure is this:

# Run it with --dryrun first to see what it will do.
# If the messages look good, run without --dryrun; the old content will be left in backup files with a -bak extension.
# Eyeball the changes with the --diff option.
# Use wmlscope, with a directory path including the Wesnoth mainline WML, to check that you have no unresolved references.
# Test the conversion.
# Use either --clean to remove the -bak files or --revert to undo the conversion.

Wmllint now in 1.6 has the additional feature that it tries to locate a spell checker on your system and spell-checks storyline and message strings. It will work automatically with either aspell, myspell, or ispell provided you have the <tt>enchant.py</tt> Python library installed.

== wmlindent ==

Call with no arguments to filter WML on standard input to reindented WML on
standard output. If arguments are specified, they are taken to be files to be
re-indented in place; interrupting will be safe, as each reindenting
will be done to a copy that is atomically renamed when it's done. This
code never modifies anything but blank lines and leading and trailing whitespace on non-blank lines.

The indent unit is four spaces. Absence of an option to change this is
deliberate; the purpose of this tool is to prevent style wars, not encourage
them.

If you don't apply this tool to your own WML, the mainline-campaign maintainers
will do it when and if your code is accepted into the tree.

Note: This tool does not include a parser. It will produce bad results on WML
that is syntactically unbalanced. Unbalanced double quotes that aren't part
of a multiline literal will also confuse it. You will receive warnings
oiif there's an indent open at end of file or if a closer occurs with
indent already zero; these two conditions strongly suggest unbalanced WML.

[[Category:Create]]
[[Category:Tools]]

MultiplayerServerWML

2009-03-22T10:59:35Z

Nital: removing {{DevFeature}} tags

= Multiplayer Server WML =
This page describes the WML used to communicate with the multiplayer server (wesnothd).

== The login procedure ==

* server request (optional)
** '''[version]'''

* client response
** '''[version]'''
*** '''version''': The client's version string.

* server request
** '''[mustlogin]'''

* client response
** '''[login]'''
*** '''username''': The username the client would like to have.
*** '''password_reminder''': If "yes" the client requests the server to send a password reminder for the provided username.
*** '''password''': The hashed password, created from the username, the password and salt received from the server.

* server response
** '''[join_lobby]''' or
** '''[error]'''
*** '''message''': The error message.
*** '''password_request''': If not empty the server asks the client to provide a password for its desired username.
*** '''phpbb_encryption''': If "yes" the client will encrypt the password using phpbb's algorithm.
*** '''random_salt''': Random salt sent to the client for mixing with the password hash.
*** '''hash_seed''': Salt generated from the original hash that is required to recreate it.
*** '''salt''': Salt generated from the original hash that is required to recreate it.
*** '''force_confirmation''': Display an ok/cancel dialog with the content of the 'message' key.

* server response
** '''[gamelist]'''
*** '''[game]''' (repeated)
**** '''id''': A unique id of the game.
**** '''name''': The title of the game.
**** '''mp_scenario''': The id of the scenario.
**** '''mp_era''': The id of the used era.
**** '''mp_use_map_settings''': Does the game use the map settings specified in the scenario.
**** '''mp_fog''': Does the game use fog.
**** '''mp_shroud''': Does the game use shroud.
**** '''mp_village_gold''': The number of gold per village.
**** '''experience_modifier''': The experience setting.
**** '''mp_countdown''': Does the game use a timer.
**** '''mp_countdown_reservoir_time''': Upper limit of the possibly available time.
**** '''mp_countdown_init_time''': Initial time.
**** '''mp_countdown_action_bonus''': Time bonus per action.
**** '''mp_countdown_turn_bonus''': Time bonus per turn.
**** '''map_data''': The map data.
**** '''hash''': The hash value of the map_data.
**** '''observer''': Are observers allowed or not.
**** '''human_sides''': The number of sides played by humans.
**** '''slots''': The number of vacant/max slots.
**** '''turn''': The current turn/max turn.
** '''[user]''' (repeated)
*** '''name''': The username of the player.
*** '''game_id''': The ID of the game the player is in (version 1.3.7+svn).
*** '''location''': The name of the game the player is in.
*** '''available''': "yes" if the player is in the lobby; "no" if in a game.
Many of the keys under [game] are described more indepth on the [[ScenarioWML]] page.

== Error messages ==

* '''[error]'''
** '''message''': The error message.

== Chat (lobby and in-game) ==

* '''[message]'''
** '''sender''': (optional - filled by the server) The sender of the message.
** '''message''': The message itself.
* '''[whisper]'''
** '''receiver''': The receiver of the whisper
** '''sender''': (optional - filled by the server) The sender of the whisper.
** '''message''': The message itself.

== Nick registration related commands (lobby and in-game) ==

* '''[nickserv]'''
** '''[register]'''
*** '''password''': The password for the nick.
*** '''mail''': The email address for the nick.
** '''[drop]''': Drop this username.
** '''[set]''': Set a detail (e.g. email address) for this nick.
*** '''detail''': The detail, e.g. "mail".
*** '''value''': The new value for this detail, e.g. "user@edomain"
** '''[info]''': Request info about another username.
*** '''name''': The username.

== Updating the lobby state ==

* '''[gamelist_diff]''': server message - basically a diff from two [gamelist]s; the keys listed are the ones that actually occure in practice
** '''index''': The index of a user.
** '''[insert_child]''' A new user logged on.
*** '''[user]'''
**** '''name''': The name of the user.
**** '''available''' "yes"
*** '''[delete_child]''' A user logged off.
** '''[change_child]'''
*** '''[user]'''
**** '''[insert]''': A user joined/left a game.
***** '''available''': "yes" when the user left a game. "no" when the user joined a game
***** '''location''': The name of the game the user joined.
**** '''[delete]'''
***** '''location''': "x" when a game was left.
*** '''[gamelist]'''
**** '''index''': Index of the game in question.
**** '''[insert_child]''': A game started.
***** '''[game]''' All the usual keys of [game] possible, see above.
**** '''[delete_child]''': A game ended.
***** '''[game]'''
**** '''[change_child]''': Something changed in a game.
***** '''[game]'''
****** '''[insert]'''
******* '''slots''': The number of free slots in the form: free/max slots
******* '''turn''': The turn number in the form: current turn/max turns
****** '''[delete]'''
******* '''map''': "x" comes with every ''turn'' or ''slots'' change for games with shroud
******* '''mp_scenario''': "x" comes with ''turn'' and ''slots'' changes for games with no scenario id

* '''[observer]''' or '''[observer_quit]''': server message - players joining([observer_quit] - quitting the lobby "game")/quitting([observer] - joining the lobby "game") a game
** '''name''': Username of the player/observer.

== Game setup (the phase from creation to start) ==
To create a game the client sends:
* '''[create_game]'''
** '''name''': The title of the game.

followed by a message with the scenario options as under [game] (see above) plus the scenario data ([time], [era], [side], etc. see [[ScenarioWML]])

* '''[join]'''
** '''id''': The id of the game.
** '''observe''': Join the game as an observer.

* '''[scenario_diff]''': [[ScenarioWML]] diff (side changes, etc.)

* '''[start_game]''': sent by the host to start a game
* '''[leave_game]''': sent by the client when it leaves a game; sent by the server to make a client leave a game

== In-game communication ==

* '''[store_next_scenario]''': sent by the host - the scenario data (see [[ScenarioWML]]) to advance to the next scenario
* '''[notify_next_scenario]''': sent by the server to tell players that the data for the next scenario is available
* '''[load_next_scenario]''': sent by the client to request the data for the next scenario
* '''[next_scenario]''': data for the next scenario (see [[ScenarioWML]]), sent by the server on request

* '''[info]''': sent by the host on game end - info about the game state
** '''type''': "termination"
** '''condition''': the termination reason

* '''[change_controller]''': a player (un)droids one of his sides or assigns control to someone else (The host can assign control for any side.)
** '''side''': the side to change controller
** '''player''': the nick of the player to take control
** '''controller''': the new controller: "human" or "human_ai"
** '''own_side''': "yes"

If a player leaves this is sent to the host for all sides he owned.
* '''side_drop''': The number of a side that dropped because a player left.
* '''controller''': The controller of that side. ("ai", "network")

* '''[muteall]''': the host mutes/unmutes all observers - toggles
* '''[mute]''': the host mutes an observer - toggles
** '''username''': the username of the observer - if not specified the servers returns a list of muted usernames
* '''[kick]''' or '''[ban]''': the host kicks/bans a player/observer
** '''username''': the username of the player/observer

* '''[turn]'''
** '''[command]''': (repeated) can contain all the tags you can find in a replay: [recruit], [move], [end_turn], etc.
*** '''[speak]'''
**** '''message''': text of the message
**** '''id''': the sender
**** '''team_name''': the name of the team the message is for - empty if it's a public message

== Administrative commands ==
* '''[query]'''
** '''type''': The type of query. See [[ServerAdministration]] for details.

[[Category:WML Reference]]

Authoring tools

2009-03-22T10:46:36Z

Nital: removing {{DevFeature}} tags

This page collects information about tools in the Wesnoth source tree that are intended to help you write campaign WML. At present there is only one such tool: <tt>trackplacer</tt>.

== trackplacer ==

'''trackplacer''' is a tool for visually editing journey tracks. Journey tracks are the sequences of dots, crossed-sword, and flag symbols (track markers) that march across the story screens at the beginning of many Wesnoth scenarios.

A 'journey' is an object containing a map file name and a (possibly empty) list of tracks, each with a name and each consisting of a sequence of track markers. This program exists to visually edit journeys represented as specially delimited sections in in .cfg files.

When you run '''trackplacer''', it will pop up a file selection dialog asking you to select either a map image or a .cfg file. When you select a map image, you will be starting a new set of journey tracks on that map. If you select a .cfg, the .cfg will be scanned for macros describing journey tracks. All other content in the .cfg, except for some magic special comments interpreted by '''trackplacer''' (which will be described later on) is ignored.

Once you have a map (and possibly also a set of track for it), there is always a currently selected track (shown in red) and possibly one or more unselected tracks (shown in white). You can add journey markers to the select track by clicking the left mouse button; they will appear on the screen. The rule for adding markers to the track is as follows: if the two markers closest to the mouse pointer are adjacent on the track, insert the new marker between them in the track order. Otherwise, append it to the end of the track.

You can click on and drag a marker with the middle mouse button to move it. Moving a marker preserves its place in the track order. The right mouse button pops up an information window describing all features overlapping the pointer; it will disappear when you release.

Radiobuttons in the upper-left-hand corner of the '''trackplacer''' window let you select placing battle markers (crossed swords) and rest markers (a flag). If you click the trashcan icon, clicking on track markers will remove them. If you click the copy/convert button, clicking on unselected track markers will copy them.

When copying, '''trackplacer''' looks under the mouse pointer for a marker from an unselected track. If it finds one, it creates a matching new icon on the selected track, preserving its pixel coordinates exactly. This can be useful when you want two named tracks to end at exactly the same spot.

The '''Animate''' button erases all icons, then redisplays them in order with a delay between each redraw, so you can see the track order.

The '''Save''' button saves your work. Your track will be saved on .cfg format as a sequence of macro definitions that you can insert in the story parts of your campaign. Conventionally, the place to put this .cfg is in a file named 'journey.cfg' in the 'utils/' directory of your campaign, near your private macro files (if you have any). Then the definitions will automatically be available in your scenario files.

The '''Properties''' button brings up a dialog that allows you to edit key/value pairs associated with the track that may affect the behavior of '''trackplacer'''. Currently only two such properties are defined: "map" has the name of the track's base file as its value, and "prefix" sets the prefix to be used when generating macro names (defaulting to '''JOURNEY''').

The '''Tracks''' button pops up a list of controls, one for each track. You can change the state of the checkboxes to control which tracks are visible. The radiobuttons can be used to select a track for editing. You can also add and rename tracks here. Hover over the controls for tooltips.

The Help button displays documentation.

The Quit button ends your session, asking for confirmation if you have unsaved changes.

To understand what your 'journey.cfg' does, you need to know that journey-track markers can be put on your story screens by two different sets of macros. One, used for 'new' marks, is displayed in color with quarter-second delays; the other, 'old' set displays marks in white with no delay. Your journey track is divided into stages by battle and rest markers; conventionally, you want to display the latest (most recent) stage with the new macros and all previous stages with the old ones.

Your track will be saved in .cfg format as a sequence of macro definitions with names like '''JOURNEY_STAGE_1''', '''JOURNEY_STAGE_2''' and so on. '''JOURNEY_STAGE_1''' will draw the first stage in the 'new' color parts. '''JOURNEY_STAGE_2''' will draw the first stage in the 'old' color and the second stage in the 'new' one; '''JOURNEY_STAGE_3''' will draw the first and second stages in the 'old' color parts and the third stage in the 'new' one; and so on.

There will be a final macro '''JOURNEY_COMPLETE''' that displays the entire track in the 'old' color. This will be useful when you are piecing together multiple tracks, say for a campaign with branches.

The track information in your journey.cfg will be enclosed in special comments
that look like this:

# trackplacer: tracks begin
# trackplacer: tracks end

'''trackplacer''' will not alter anything it finds outside these comments, and will always enclose everything it writes in them.

Special comments may appear in your ''journey.cfg'', looking like this:

<tt># trackplacer: <property>=<value></tt>

These set properties that '''trackplacer''' may use. At present there is only one such property: <tt>map</tt>, which records the name of the mapfile on which your track is laid. Don't remove this comment, '''trackplacer''' needs it.

'''trackplacer''' has one known bug: you can confuse it (or possibly the underlying toolkit, or X) by dragging markers rapidly across other markers. If this happens to you, click '''Animate''' to refresh and slow down.

ReplaceMapWML

2009-03-22T10:45:22Z

Nital: removing {{DevFeature}} tags

{{WML Tags}}
== The [replace_map] tag ==
The [replace_map] tag allows a complete change of the map in a scenario. Unlike [[TerrainMaskWML|terrain_mask]], changing the map size is possible, although requires special attention. Since the map is changed completely, there is no equivalent of terrain_mask "alpha channel" feature.

* '''map''': a Wesnoth map; see [[BuildingMaps]].
* '''expand''': (default=no) allow the map size to increase (in either dimension)
* '''shrink''': (default=no) allow the map size to decrease (in either direction)

Expanding maps are generally more predictable than shrinking maps. When shrinking, units left off the new map area will be added to a recall list if there is one, and removed otherwise (and an error message is issued).

The expansion direction is currently always bottom-right.

CampaignWML

2009-03-22T10:40:21Z

Nital: removing {{DevFeature}} tags

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



This page describes how the campaign is displayed in the "Campaign" menu, and how it starts.

'''[campaign]''' describes a campaign
* '''id''': the internal campaign identifier used to classify saved games
* '''icon''': the image displayed in the campaign selection menu
* '''name''': (translatable) name displayed in the campaign selection menu
* '''abbrev''': (translatable) abbreviation used as a prefix for savefile names made from this campaign
* '''image''': the image shown in the information pane when this campaign is selected in the campaign selection menu (typically 205×205 pixels)
* '''description''': (translatable) text shown in the information pane when this campaign is selected in the campaign selection menu
* '''define'''='''''CAMPAIGN_SYMBOL''''' when this campaign is started, the preprocessor symbol '''''CAMPAIGN_SYMBOL''''' will be defined. See '''#ifdef''' in [[PreprocessorRef]] for how this can be used to isolate parts of the campaign file from other campaigns. Only the tags '''[campaign]''' and '''[binary_path]''' (see [[BinaryPathWML]]) should go outside of '''#ifdef ''CAMPAIGN_SYMBOL'''''. This symbol will be defined ''before'' any .cfg is preprocessed.
* '''extra_defines''': a comma(''',''') separated list of preprocessor symbols. Those symbols will be defined ''before'' any .cfg is preprocessed.
* '''difficulties''': a comma(''',''') separated list of preprocessor symbols, exactly one of which will be stored depending on the difficulty setting chosen when the campaign is started. The symbols '''EASY''', '''NORMAL''', and '''HARD''' are usually used, and there are several macros in utils.cfg (see [[UtilWML]]) which check for these values to set WML keys to different values depending on difficulty. If you use different difficulty symbols, you may need to define your own versions of these macros.
* '''difficulty_descriptions''': the menu of difficulties; this is a list of descriptions (see [[DescriptionWML]]) that correspond to different difficulty levels. Since each description is a menu option for a difficulty level, this must provide the same number of descriptions as there are levels in the ''difficulties'' list.
* '''first_scenario''': the ID of the first scenario in the campaign; see ''id'' in [[ScenarioWML]]
* '''rank''': a number that determines the order of campaigns in the campaign selection menu. Lower ''rank'' campaigns appear earlier, with unranked campaigns at the end. Currently the mainline campaigns use multiples of 10 from 0 to 399, with 0-99 for Novice campaigns, 100-199 for Intermediate campaigns, and 200-399 for Expert campaigns; if you specify this, it should not be less than 400. (Note: This replaces an older convention that topped out at 50.)
* '''[about]''': inserts your own credits into the game's list of credits. The campaign's name automatically is inserted at the top of the rolling credits followed by title/text key pairs. There can be any number of '''[about]''' tags inside a '''[campaign]''' tag, but none of them will display credits if there is no "id" key present inside [campaign] (see above). The '''[about]''' tag has the following keys:
** '''title''': (translatable) large text used to start a new subsection (writers, artists, units, balancing) in the rolling credits
** '''text''': (translatable, but you probably won't want to make it such) smaller text which is displayed before the contributor names
** '''[entry]''': Contains information about a single contributor. Only the ''name'' key will be used in-game, the other three keys are for display on the Credits website.
*** '''name''': The name of the contributor
*** '''comment''': Optional short note about what that person did
*** '''email''': Optional email address
*** '''wikiuser''': Optional, the user name on the wiki
** '''end_text''': Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End".
** '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500.

== See Also ==

* [[PreprocessorRef]]
* [[ScenarioWML]]
* [[ReferenceWML]]
* [[PblWML]]

[[Category: WML Reference]]

AnimationWML

2009-03-22T10:39:55Z

Nital: removing {{DevFeature}} tags (not finished yet)

{{WML Tags}}

== Introduction ==

This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.

This page will deal with the two problems of animations
* How are animations Chosen
* What exactly is drawn

== How animations are drawn ==
=== Animations ===
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as
* unit is attacking
* unit is idling
* unit is attacking (event) and uses a melee weapon (condition)
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)

events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.

=== Frames ===

An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix

A frame typically describes an image, where an how to render it. It can contain such things as
* the image to display
* how transparent should that image be
* where to draw that image.

At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time

The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned

=== Timing, Clock, Multiple animations ===
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start

This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays it's attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.

The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine

In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.

Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.

==== Example Syntax ====
[attack_anim]
[attack_filter]
name= _ "bow"
[/attack_filter]
'''start_time'''=-350
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
[if]
hits=yes
[frame]
duration=350
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
duration=350
sound=bow-miss.ogg
[/frame]
[/else]
[/attack_anim]

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string>
image_diagonal=<string>
image_mod=<string>
sound=<string>
halo=<progressive string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
offset=<progressive float>
blend_color=< red, green, blue >
blend_ratio=<progressive float>
text=<string>
text_color=< red, green, blue >
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
layer=<progressive int>
[/frame]

dev denotes a {{DevFeature}}

==== Progressive parameters ====

Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.

A typical example would be a unit progressively fading out, becoming transparent

To do that, you could use:

alpha=1~0

To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:

alpha=1~0:300,0:300,0~1:300

you could also specify it like that

alpha=1~0,0,0~1

when a timing is missing, the engine will do its best to fill in in a fair way.

a progressive string has a similar syntax

halo=halo1.png:300,halo2.png:300,halo2.png:300

==== Field Description ====

** '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''
** '''end''': (deprecated) see '''begin''' and also [[AnimationWML#Timing.2C_Clock.2C_Multiple_animations|Timing, Clock, Multiple animations]] section for coverage of '''start_time''' which combines with '''duration''' to replace '''begin=''' '''end='''.
** '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''.
** '''image''': the image to display during the frame.
** '''image_diagonal''': the image to display when the attack occurs diagonally (directions ne,se,sw,nw).
** '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images
** '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.
** '''halo''': the halo to display at the time.
** '''halo_x''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_y''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes
** '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.
** '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.
** '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255) this color will be mixed to the frame to give it a tint.
** '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.
** '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).
** '''text_color''': the color of the above floating label.
** '''submerge''': the part of the unit that should drawn with 50% opacity (for units in water)
** '''x''': x offset applied to the frame
** '''y''': y offset applied to the frame
** '''layer''': layer used to draw the frame, see discussion bellow

=== Drawing related animation content ===
==== Syntax summary ====
[animation]
<animation choice related content>
[frame]
<frame content>
[/frame]
[frame]
<frame content>
[/frame]
start_time=<integer>
offset=<progressive float>
image_mod=<string>
blend_with=<r,g,b>
blend_ratio=<progressive float>
halo=<progressive_string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
submerge=<progressive float>
x=<progressive int>
y=<progressive int>
layer=<progressive int>

[xxx_frame]
<frame content>
[/xxx_frame]
xxx_start_time=<integer>
xxx_image_mod=<string>
xxx_offset=<progressive float>
xxx_blend_with=<r,g,b>
xxx_blend_ratio=<progressive float>
xxx_halo=<progressive_string>
xxx_halo_x=<progressive int>
xxx_halo_y=<progressive int>
xxx_halo_mod=<string>
xxx_submerge=<progressive float>
xxx_x=<progressive int>
xxx_y=<progressive int>
xxx_layer=<progressive int>

[/animation]

dev denotes a {{DevFeature}}

==== Parameter handling ====
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame.

The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.

== How animations are chosen ==
Within a unit decription block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played.

Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the folowing movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptioeing animation when moving next to an ennemy unit

Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an ennemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criterias. The engine follow the following rules to select an animation
* Start with all animations
* Drop all animations with a criteria that fails on the current situation
* Take the animations that have the most maching criterias
* If there are more than one animation remaining, take an animation randomly
* If all animations have been droped, the engine will provide a smart default.

here is a pseudo-code explaination of this algorithm

foreach animation
animation_score = 0
foreach filter-criteria
if <criteria-fails>
animation_score = -1;
break;
elsif <criteria-matches>
animation_score++
endfor
if animation_score > max_score
<empty animation list>
max_score = animation_score;
push(animation,animation_list);
elsif animation_score = max_score
push(animation,animation_list);
endfor
<choose an animation randomly from animation_list>

Note that all animations don't have all the filters...

so, if we have a unit with
# an animation for water terrain
# an animation for SE on grassland
# an animation with no criteria
# an animation for N,NE,NW,S,SW,SE
# an animation for NW

* 3. will never be taken, because 4. will always trump it
* on water going NW, it can be 1. 4. 5.
* on water, any direction but NW, it will be 1. or 4.
* on SE grassland it will be 2.
* on other grasslands, it will be 4. (4. or 5. if NW)

=== Generic animation filters available for all animations ===
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''terrain''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]].
* '''[unit_filter]''': this will filter using a standard unit filter on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[unit_filter]''' blocks in an animation. ({{DevFeature}} renamed to [filter])
* '''[secondary_unit_filter]''': this will filter using a standard unit filter on the unit in the hex faced. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[secondary_unit_filter]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail. ({{DevFeature}} renamed to [filter_second])
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.
* '''[attack_filter]''': a standard attack filter to match on the attacker's attack. See [[FilterWML]]. ({{DevFeature}} renamed to [filter_attack])
* '''[secondary_attack_filter]''': a standard attack filter to match on the defender's attack. See [[FilterWML]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail. ({{DevFeature}} renamed to [filter_second_attack])
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:
** '''hit''': the attack hits, defender survives.
** '''no''' or '''miss''': the attack misses.
** '''kill''': the attack hits, defender dies.
** '''yes''': is an alias of '''hit,kill'''.
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1).

=== Events trigerring animations and default animations ===
==== standing ====
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered

this is the default "standing image" for the unit

''value='' is not used, and always contains 0

if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used
==== selected ====
This animation is triggered whenever the unit is selected

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''
==== recruited ====
This animation is triggered whenever the unit is recruited or recalled

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=0~1:600''
==== levelin ====
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:600" blend_color=255,255,255''
==== levelout ====
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:600" blend_color=255,255,255''
==== movement ====
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation
* unit stay ''exactly'' 150ms in each hex. so you typically want to have an offset of ''0~1:150,0~1:150,0~1:150,0~1:150,0~1:150'' or something similar
* when a unit enters a hex, the current anim is tested again.
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is
** if it fails, a new movement anim is searched

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"''
==== pre_teleport ====
This animation is triggered whenever the unit teleports, but before it has moved to the target hex

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:150" blend_color=255,255,255''
==== post_teleport ====
This animation is triggered whenever the unit teleports, but after it has moved to the target hex

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:150" blend_color=255,255,255''
==== healing ====
This animation is triggered when the unit has healing powers and uses them

''value='' is the number of points healed

No default is provided by the engine
==== healed ====
This animation is triggered whenever the unit is healed for any reason

''value='' is the number of points healed

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''
and plays the sound ''heal.wav''
==== poisoned ====
This animation is triggered whenever the unit suffers poison dammage

''value='' is the number of points lost

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''
and plays the sound 'poison.ogg''
==== defend ====
This animation is triggered during a strike, of the unit receiving the blow

''value='' is the number of point lost, if any

No default is provided by the engine
==== attack ====
This animation is triggered during a strike, of the unit giving the blow

''value='' is the number of damage dealt, if any

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:150,0.6~0:150"'' for melee attacks
No default is provided for range attacks
==== leading ====
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking

''value='' is not used, and always contains 0

No default is provided by the engine

==== resistance ====
This animation is triggered for units with the resistance special ability affecting neighbouring fights, when the unit they are helping is defending

''value='' is not used, and always contains 0

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit
==== victory ====
This animation is triggered when a unit finishes a fight by killing the other unit

''value='' is not used, and always contains 0

No default is provided by the engine
==== idling ====
This animation is called when the unit has been using its standing animation for a random duration.

''value='' is not used, and always contains 0

No default is provided by the engine

==== default ====

This animation is never triggered, but is used as a base to create new animations

''value='' is used depending of the type of animation it replaces

A single animation made of the base frame is provided by the engine if no default animation is available

==== extra animations ====
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.

Note that WML events can also trigger standard animations.
''value='' is set from the WML event

== Shortcuts, tricks and quirks ==

=== ''[if]'' and ''[else]'' ===

Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that.

Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, but you can't nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):

[if]
hits=no
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound=axe.ogg
[/frame]
[/else]

note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection

=== Simplified animation blocks ===
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported

some of these use extra tags which are translated in the normal ''value='' tag

some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose

* '''[leading_anim]''' is an animation with the following parameters automatically set
apply_to=leading
* '''[recruit_anim]''' is an animation with the following parameters automatically set
apply_to=recruited
* '''[standing_anim]''' is an animation with the following parameters automatically set
apply_to=standing,default
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.

i.e: the animation will be used to build default animations
* '''[idle_anim]''' is an animation with the following parameters automatically set
apply_to=idling
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[healing_anim]''' is an animation with the following parameters automatically set
apply_to=healing
value=<damage= value>
* '''[healed_anim]''' is an animation with the following parameters automatically set
apply_to=healed
value=<healing= value>
[_healed_sound_frame]
sound=heal.wav
[/_healed_sound_frame]
* '''[poison_anim]''' is an animation with the following parameters automatically set
apply_to=poisoned
value=<damage= value>
[_poison_sound_frame]
sound=poison.ogg
[/_poison_sound_frame]
* '''[movement_anim]''' is an animation with the following parameters automatically set
apply_to=movement
offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_with=255,0,0
blend_ratio="0.5:50,0.0:50"
[/frame]

there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned

* '''[attack_anim]''' is an animation with the following parameters automatically set
if the animation contains a missile frame

apply_to=attack
missile_offset="0~0.8"

else

apply_to=attack
offset="0~0.6,0.6~0"

* '''[death]''' is an animation with the following parameters automatically set
apply_to=death
[_death_sound_frame]
sound=<die_sound= of the enclosing [unit] tag>
[/_death_sound_frame]
* '''[victory_anim]''' is an animation with the following parameters automatically set
apply_to=victory
* '''[extra_anim]''' is an animation with the following parameters automatically set
apply_to=<flag= value of the anim>
* '''[teleport_anim]''' will be cut into two at the clock-time 0
everything before zero becomes an animation with the following parameters automatically set
apply_to=pre_teleport
everything after zero becomes an animation with the following parameters automatically set
apply_to=post_teleport

== Layering ==
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.

this value must be between 0 and 100

* the back of haloes is drawn with a value of 10
* when unspecified, a animation is drawn with a value of 40
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50
* orbs and status bars are drawn on layer 80
* when unspecified missile frames are drawn on layer 90

by changing these values, it is easy to have the unit display the way you want

== See Also ==

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

[[Category: WML Reference]]

UnitTypeWML

2009-03-22T10:35:39Z

Nital: removing {{DevFeature}} tags

{{WML Tags}}
== The [unit] tag ==

Each '''[unit]''' tag defines one unit type. (for the use of [unit] to create a unit, see [[SingleUnitWML]]) Note: this tag has been renamed and is now '''[unit_type]'''.

Unit animation syntax is described in [[AnimationWML]].

The following key/tags are recognized:
{| class="gallery" style="text-align:left;"
|-
! advancefrom
| the previous level unit on the advancement tree
- allows a campaign-specific unit to be spliced into an already existing advancement tree. It should generally be used only inside a campaign ifdef, to prevent changes to other campaigns. This tag makes changes to the ''advances_to'' and ''experience'' keys of a base unit to make it advance into this unit. It takes these keys: ** ''unit'' the id of the base unit from which this unit advances. This adds the unit into the list of units which ''unit'' can advance into. ** [[experience]] is optional. If present and lower than the experience already required for the base unit to advance, then the experience to advance is lowered. Note: this will also lower the experience required to advance to other units which the base unit can advance into.
|-
! advances_to
| When this unit has experience greater than or equal to [[experience]], it is replaced by a unit of the type that the value of [[advances_to]] refers to. All modifications that have been done to the unit are applied to the unit it is replaced by. The special value 'null' says that the unit does not advance but gets an AMLA instead.
|-
! alignment
| how the unit's damage should be affected by its lawful bonus (See [[TimeWML]]).
|-
! attacks
| the number of times that this unit can attack each turn.
|-
! cost
| when a player recruits a unit of this type, the player loses ''cost'' gold. If this would cause gold to drop below 0, the unit cannot be recruited.
|-
! description
| (translatable) the text displayed in the unit descriptor box for this unit. Default 'No description available...'.
|-
! do_not_list
| Not used by the game, but by tools for browsing and listing the unit tree. If this is 'yes', the unit will be ignored by these tools.
|-
! ellipse
| the ellipse image to display under the unit, which is normally team-colored. Default is the normal ellipse; "misc/ellipse-nozoc" is a dashed ellipse that should be used for units without zone of control.
|-
! experience
| When this unit has experience greater than or equal to ''experience'', it is replaced by a unit with 0 experience of the type that the value of ''advances_to'' refers to. All modifications that have been done to the unit are applied to the unit it is replaced by.
|-
! gender
| has a value of either ''male'' or ''female'', and determines which of the keys ''male_names'' and ''female_names'' should be read. When a unit of this type is recruited, it will be randomly assigned a name by the random name generator, which will use these names as a base.
|-
! hide_help
| determines if the unit type will appear in the in-game help. Possible values ''true'' and ''false'', defaults to ''false''.
|-
! hitpoints
| the maximum HP that the unit has, and the HP it has when it is created.
|-
! id
|the value of the ''type'' key for units of this type. An ''id'' should consist only of alphanumerics and spaces (or underscores). ''type'' keys are found in [[SingleUnitWML]] and [[FilterWML]]. For example, id=Drake Flare
WARNING : characters "$", "&", "*", "(" and ")" are illegal for use in the unit id and must be avoided because they might lead to corrupted saved games
|-
! level
| the amount of upkeep the unit costs. After this unit fights, its opponent gains ''level'' experience. See also kill_experience ([[GameConfigWML]]), and leadership ([[AbilitiesWML]]).
|-
! movement
| the number of move points that this unit recieves each turn.
|-
! movetype
| See '''[[movetype]]''', [[UnitsWML]]. Note that the tags '''[[movement_costs]]''', '''[[defense]]''', and '''[[resistance]]''' can be used to modify this movetype.
|-
! name
|(translatable) displayed in the Status Table for units of this type.
|-
! num_traits
| the number of traits that units of this type should receive when they are recruited, overriding the value set in the [race] tag.
|-
! profile
| the portrait image to use for this unit type. You can also set a portrait for an individual unit instead of the whole unit type (see [[SingleUnitWML]]). There are some changes for the portraits in the ingame dialog (this will change again post 1.6 but the time's to short to write a new API). The engine now first looks for the image in the transparent subdirectory and if found that image is used. If not found it will use the image as-is. Depending on the size the engine will or will not scale the image, the cuttoff currently is at 300x300. For images which should only be shown on the right side in the dialog append ~RIGHT() to the image.
|-
! race
| See '''[race]''', [[UnitsWML]]. Also used in standard unit filter (see [[FilterWML]]).
|-
! undead_variation
| Which image to use when a unit of this type is killed by a unit with the plague ability.
|-
! usage
| the way that the AI should recruit this unit, as determined by the scenario designer. (See ''recruitment_pattern'', [[AiWML]]). The following are conventions on usage: ** ''scout'': Fast, mobile unit meant for exploration and village grabbing. ** ''fighter'': Melee fighter, melee attack substantially more powerful than ranged. ** ''archer'': Ranged fighter, ranged attack substantially more powerful than melee. ** ''mixed fighter'': Melee and ranged fighter, melee and ranged attacks roughly equal. ** ''healer'': Specialty 'heals' or 'cures'. Note that this field affects only recruitment, not the AI's behavior in combat; that is always computed from attack power and hitpoints.
|-
! zoc
| if "yes" the unit will have a zone of control regardless of level. If present but set to anything other than "yes," the unit will have no zone of control. If the tag is omitted, zone of control is dictated by unit level (level 0 = no zoc, level 1+ = has zoc).
|}
==== After max level advancement (AMLA) ====
* '''[advancement]''': describes what happens to a unit when it reaches the XP required for advancement. It is considered as an advancement in the same way as advancement described by '''advances_to'''; however, if the player chooses this advancement, the unit will have one or more effects applied to it instead of advancing.
** '''always_display''': if set to true displays the AMLA option even if it is the only available one.
** '''description''': a description (see [[DescriptionWML]]) displayed as the option for this advancement if there is another advancement option that the player must choose from; otherwise, the advancement is chosen automatically and this key is irrelevant.
** '''image''': an image to display next to the description in the advancement menu.
** '''max_times''': default 1. The maximum times the unit can be awarded this advancement.
** '''strict_amla''': (yes|no) default=no. Disable the AMLA if the unit can advance to another unit.
** '''require_amla''': An optional list of AMLA ''id'' keys that act as prerequisites for this advancement to become available. Order is not important, and an AMLA id can be repeated any number of times to indicate that another advancement must be chosen several times before this advancement option will become available.
*** example: <tt>require_amla=tough,tough,incr_damage</tt> assumes there exist other [advancement] options called ''id=tough'' and ''id=incr_damage''. Once ''tough'' is chosen twice and ''incr_damage'' is chosen once, then the current [advancement] will become available.
*** ''require_amla=tough,incr_damage,tough'' is an equivalent way of expressing this.
** '''[effect]''': A modification applied to the unit whenever this advancement is chosen. See [[EffectWML]]

==== Other tags ====
* '''[base_unit]''': Contains one attribute, '''id''', which must be the ID of a unit type. If specified, the UnitWML for that unit is copied into this one. Subsequent attributes modify the copy. (1.3.7 and later versions only.)
* '''[attack]''': one of the unit's attacks.
** '''description''': a translatable text for name of the attack, to be displayed to the user.
** '''name''': the name of the attack. Used as a default description, if ''description'' is not present, and to determine the default icon, if ''icon'' is not present (if ''name=x'' then ''icon=attacks/x.png'' is assumed unless present). Non-translatable. Used for the ''has_weapon'' key; see [[FilterWML]]
** '''type''': the damage type of the attack. Used in determining resistance to this attack (see '''[resistances]''', [[UnitsWML]]). Possible values are 'blade', 'pierce', 'impact', 'fire', 'cold', and 'arcane'.
** '''[specials]''': contains the specials of the attack. See [[AbilitiesWML]].
** '''icon''': the image to use as an icon for the attack in the attack choice menu, as a path relative to the images directory.
** '''range''': the range of the attack. Used to determine the enemy's retaliation, which will be of the same type. Also displayed on the status table in parentheses; 'melee'(default) displays "melee", while 'ranged' displays "ranged". Range can be anything. Standard values are now "melee" and "ranged". From now on, ''short'' and ''long'' will be treated as totally different ranges. You can create any number of ranges now (with any name), and units can only retaliate against attacks for which they have a corresponding attack of the same range. This value is translatable.
** '''damage''': the damage of this attack
** '''number''': the number of strikes per attack this weapon has
For those two following settings, the engine usually chooses the attack with the best average total damages * weight (default weight = 1.0).
** '''attack_weight''': helps the AI to choose which attack to use when attacking; highly weighted attacks are more likely to be used. Setting it to 0 disables the attack on attack
** '''defense_weight''': used to determine which attack is used for retaliation. This affects gameplay, as the player is not allowed to determine his unit's retaliation weapon. Setting it to 0 disable the attacks on defense
** '''movement_used''': determines how many movement points using this attack expends. By default all movement is used up, set this to 0 to make attacking with this attack expend no movement.

** '''[animation]'''
:: This describes an animation for this attack. If multiple animations are present, one will be randomly chosen each time the unit attacks. See [[AnimationWML]] for possible keys.

* '''[defend]''': See [[AnimationWML]]
* '''[death]''': See [[AnimationWML]]
* '''[teleport_anim]''': See [[AnimationWML]]
* '''[extra_anim]''': See [[AnimationWML]]
* '''[event]''': Any [event] written inside the [unit] tag will get included into any scenario where a unit of this type appears in. Note that such events get included when a unit of this type first appears in the scenario, not automatically when the scenario begins (meaning that ''name=prestart'' events, for example, would usually never trigger). See [[EventWML]] and [[WML_Abilities]]

* '''[variation]''': Defines a variation of a unit. Variations are invoked with an [effect] tag. They are currently used for graphical variations (giving character sprites new weapons) but theoretically you could do anything with it.
** '''variation_name''': The name of the variation.
** '''inherit''': if ''yes'', inherits all the properties of the base unit.
: All other keys in '''[variation]''' are the same as for '''[unit]''' itself.

* '''[male]''', '''[female]''': They can contain all '''[unit]''' tags, to specify a variation of different gender for a unit.
** '''inherit''': if ''yes'', inherits all the properties of the base unit. defaults to yes

* '''[abilities]''': Defines the abilities of a unit. See [[AbilitiesWML]]

== See Also ==

* [[AnimationWML]]
* [[ReferenceWML]]
* [[TerrainWML]]

[[Category: WML Reference]]

GameConfigWML

2009-03-22T10:31:45Z

Nital: removing {{DevFeature}} tags

{{WML Tags}}
== The [game_config] tag ==

This tag is a top level WML tag which can only be used once because
it defines basic settings that are used everywhere in the game.
In official versions of Wesnoth it is in ''game.cfg''; values used there are labeled 'standard'.

The following keys are recognised
* '''base_income''': (standard 2) how much your leader earns without any villages
* '''rest_heal_amount''': (standard 2) how much HP a unit gains each turn it rests
* '''recall_cost''': (standard 20) how much it costs to recall a unit; this cost is independent of level.
* '''kill_experience''': (standard 8) killing a unit with ''level=X'' will give ''X''*''kill_experience'' experience to the killing unit. However, if a unit has ''level=0'', it will still give half of ''X'' experience.

* '''icon''': (standard 'wesnoth-icon.png') the game icon file
* '''title''': (standard 'misc/title.png') the title screen image
* '''logo''': (standard 'misc/logo.png') the wesnoth logo which will be put over the title image
* '''default_defeat_music''': (standard 'defeat.ogg,defeat2.ogg') default list of music tracks that are chosen to play on player's defeat; this can be overriden per-scenario
* '''default_victory_music''': (standard 'victory.ogg,victory2.ogg') default list of music tracks that are chosen to play on player's victory; this can be overriden per-scenario
* '''title_music''': (standard 'main_menu.ogg') the music to play at the title screen
* '''logo_x''': (standard 292) the x position of the logo on the title screen
* '''logo_y''': (standard 120) the y position of the logo on the title screen
* '''buttons_x''': (standard 760) the x position of the buttons on the title screen
* '''buttons_y''': (standard 330) the y position of the buttons on the title screen
* '''buttons_padding''': (standard 20) space between buttons, and border in main menu
* '''tip_x''': (standard 100) space between the button panel left edge and the tip-of-the-day panel right edge
* '''tip_y''': (standard 500) not used (the bottom right corner of the tip-of-the-day panel is pegged to align with the bottom of the button panel)
* '''tip_width''': (standard 495) max width in pixels of the tip-of-the-day panel. The width will actually adjust to be the smallest size necessary to fit the text. Once the max width is reached, if text must flow onto multiple lines, then the height will also automatically adjust.
* '''tip_padding''': (standard 20) space between the edge of the tip-of-the-day panel and an imaginary bounding box containing the text inside the panel

* '''map_image''': (standard 'maps/wesnoth.png') the background image for the "About" screen
* '''sidebar_image''': (standard 'misc/rightside.png') border of window when displaying unit statistics
* '''sidebar_image_bottom''': (standard 'misc/rightside-bottom.png') border of image when displaying unit statistics
* '''energy_image''': (standard 'misc/bar-energy.png') the images used to display hp/xp bars.
* '''moved_ball_image''': (standard 'misc/ball-moved.png') the orb image to add on top of the hp bar for player's moved units; see 'Orbs', [[WesnothManual]]
* '''unmoved_ball_image''': (standard 'misc/ball-unmoved.png') like '''moved_ball_image''', but for player's unmoved units
* ''partmoved_ball_image''': (standard 'misc/ball-partmoved.png') like '''moved_energy_image''', but for player's partially moved units
* '''flag_image''': (standard 'image/flag'terrain/flag-1.png:150,terrain/flag-2.png:150,terrain/flag-3.png:150,terrain/flag-4.png:150') the default flag animation to mark captured villages (if no custom flag is defined in the [side] tag). By example, this animation has 4 frames of 150ms each. An automatic side-coloring is applied.
* '''flag_icon_image''': (standard 'flags/flag-icon.png') the default flag icon to indicate the side playing in the statusbar (if no custom flag_icon is defined in the [side] tag). An automatic side-coloring is applied.

* '''cross_image''': (standard 'misc/cross.png') the cross image displayed on the map at start of scenarios; see [[IntroWML]]
* '''dot_image''': (standard 'misc/dot.png') the dot image used to draw a path on the map before scenarios

* '''footprint_left_nw''', '''footprint_left_n''', '''footprint_right_nw''', '''footprint_right_n''': images used to display the path that a unit would take to the tile the cursor is on.
The first image of each key is used for tiles which would take only 1 movement point for the selected unit to move onto;
the second for ones which would take more.
The 'n' and 'nw' designations distinguish between tiles which are moved from orthogonally and diagonally in the same way as described in '''[missile_frame]''', [[AnimationWML]].
The 'left' and 'right' designations are used alternately throughout the path;
however, the standard values are the same for 'left' and 'right'.

* '''terrain_mask_image''': (standard 'terrain/alphamask.png') used to give a hex-shape from a rectangular image.
* '''grid_image''': (standard 'terrain/grid.png') the image used by the grid option
* '''unreachable_image''': (standard 'terrain/darken.png') the stripes mask used to show unreachable locations

* '''missile_n_image''': (standard 'projectiles/missile-n.png') orthogonal missile image to use if none is specified; see ''image'', '''[missile_frame]''', [[AnimationWML]]
* '''missile_ne_image''': (standard 'projectiles/missile-ne.png') diagonal missile image to use if none is specified; see ''image_diagonal'', '''[missile_frame]''', [[AnimationWML]]
* '''observer_image''': (standard 'misc/eye.png') the image to use for observer in multi-player games. (The eye in the upper right hand corner.)
* '''download_campaign_image''': (standard no image) the icon for the "Download more Campaigns" campaign menu option.

== See Also ==

* [[ReferenceWML]]

[[Category: WML Reference]]

PreprocessorRef

2009-03-22T10:30:39Z

Nital: removing {{DevFeature}} tags

{{WML Tags}}
== The WML preprocessor ==

Wesnoth loads just one configuration file directly: '''data/_main.cfg'''.
However the WML preprocessor allows game.cfg to load in more files.
Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.

The preprocessor can interpret a simple language of string-expansions known as "macros." A macro should always be defined '''before''' the place where it needs to be used.

The preprocessor is applied recursively, so included files will
be parsed for macros, and after macro expansion will be parsed for macros
again, and so on. As a result, you should not write a recursive macro,
because it will cause errors
(but, alas, not necessarily error messages).

The following directives are used to create and use ''macros'',
i.e. shortcuts which reduce repetition of information.
See [[UtilWML]], [[UsefulWMLFragments]] for examples and [http://www.wesnoth.org/macro-reference.xhtml the macro reference] for the predefined core macros.
* '''#define ''symbol'' [''parameters''] ''newline'' ''substitution'' #enddef''' all subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by ''substitution'' with all occurences of any parameter {''parameter''} within ''substitution'' replaced by the parameter's corresponding value in ''arguments''. For example, the UNIT macro used below would be defined:

#define UNIT TYPE X Y## the ordering is important here;
## since WML does not distinguish
## data into different types, only
## the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE}## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef
(See [[SingleUnitWML]] for information on creating units using WML.)
* '''{''symbol'' [''arguments'']}''' if ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' is defined as, using ''arguments'' as parameters. You can create multiple word arguments by using parentheses to restrain the argument. For example, while '''{UNIT Wolf Rider 18 24}''' will attempt to create a "Wolf" at (Rider,18), causing Wesnoth to crash, the macro '''{UNIT (Wolf Rider) 18 24}''' will create a "Wolf Rider" at (18,24) as it should. ('''UNIT''' is defined above). See the ''#define'' preprocessor instruction above for information on defining symbols, including symbols with arguments. Several symbols are defined in the normal game code; for reference they are listed in [[UtilWML]].

Unlike the other preprocessor directives, #ifdef and #ifndef are not
mere conveniences.
They are necessary to distinguish between different modes of play.
* '''#ifdef ''symbol'' ''substitution-if-stored'' [#else ''substitution-if-not-stored''] #endif''' If ''symbol'' has been stored, the whole block will be replaced by ''substitution-if-stored''. If not, it will be replaced by ''substitution-if-not-stored'' if it is available. ''symbol'' can take the following values:
** a campaign difficulty level. Usually '''EASY''', '''NORMAL''', or '''HARD''', it is decided by the key ''difficulties'' (see [[CampaignWML]]).
** a campaign ID. Each campaign stores a preprocessor ID. See ''define'', [[CampaignWML]].
** '''MULTIPLAYER''' is stored when the player is playing or setting up a multiplayer game (i.e. a game with '''scenario_type=multiplayer''').
** '''TUTORIAL''' is stored when the player is playing the tutorial.
** '''APPLE''' is stored if the computer Wesnoth is being run on is an Apple. (this one is only available to the configuration of the game)
** '''PYTHON''' is stored if Python support is built in and available. Use this to for example show a warning when starting a campaign that uses Python AI's, if Python isn't available.
* '''#ifndef''' behaves exactly like '''#ifdef''', except that it inverts the test sense; guarded text is included only if ''symbol'' has not been stored.
''#undef'' can be useful too if ''#ifdef'' is not enough.
* '''#undef ''symbol'' ''' erases ''symbol''

These directives expand a file by including other files, ''filename'' may not contain '..' or the directive will be skipped:
* '''{''filename''}''' if ''filename'' isn't a predefined symbol (see above), Wesnoth will assume it's a path to a file in the main '''data/''' subdirectory of Wesnoth and include the file it points to here "as is". Forward slashes('''/''') should be used to separate directories from their elements, even if your platform uses a different symbol such as colon (''':''') or backslash ('''\''').
* '''{~''filename''}''' similar to above, but the preprocessor assumes that the filename is relative to the user data directory. The ''user data directory'' varies depending on platform:

Platform | User Data Directory
-------------------------
UNIX | ~/.wesnoth/data/
Mac OS X | ~/Library/Preferences/Wesnoth or ~/.wesnoth/data
Windows | "main Wesnoth folder"\userdata

* '''{@''filename''}''' is a convenient way to make Wesnoth look for a file by that name in both the main and the user data directory. It is equivalent to writing '''{''filename''}{~''filename''}'''.
* '''{./''filename''}''' is similar to the '''{''filename''}''' directive, but is assumed to be relative to the directory which contains the file in which this appears. For example, if used in game.cfg, it is equivalent to '''{''filename''}'''.
* If ''filename'' points to a directory, the preprocessor will include all files in the directory ''filename'', non-recursively and in alphabetical order. Starting in 1.3.3, some files in such directories are handled specially.

If there is a file named ''dir/_main.cfg'' in a directory referenced as '''{''dir''}''', only that ''_main.cfg'' file is processed; it may include other files in itself, of course . This feature is useful for creating WML directories that are self-contained WML packages with their own initializations (like campaigns). This can replace the older convention of having a ''dir.cfg'' at the same level as ''dir'' which does '''{''dir''}''' somewhere in itself.

If there are files named ''dir/*/_main.cfg'' in a directory referenced as '''{''dir''}''', where * is any subdirectories ''dir'', then they all are processed (except if there is also a file named ''dir/_main.cfg''). This means that if you have a layout like this:
dir/
dir/a/_main.cfg
dir/a/other.cfg
dir/b/_main.cfg
dir/b/other.cfg
dir/other.cfg
Then '''{dir}''' will process (in alphabetical order): dir/a/_main.cfg, dir/b/main.cfg, dir/other.cfg.

If there is a file named ''dir/_final.cfg'' in a directory referenced as '''{''dir''}''' (and no ''main.cfg'', so that all files in the directory are processed normally) the ''_final.cfg'' is guaranteed to be processed ''after'' all other files in the directory.

If there is a file named ''dir/_initial.cfg'' in a directory referenced as '''{''dir''}''' (and no ''main.cfg'', so that all files in the directory are processed normally) the ''_initial.cfg'' is guaranteed to be processed ''before'' all other files in the directory.

Note that the parser was changed various times, so don't expect older Wesnoth version to behave exactly the same.

== See Also ==
* [[SyntaxWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

SyntaxWML

2009-03-22T10:30:03Z

Nital: removing {{DevFeature}} tags

{{WML Tags}}
Wesnoth syntax has two basic elements: ''tags'' and ''attributes''.
Further, ''attributes'' consist of ''keys'' and ''values''.
Tag names and keys cannot contain whitespace.
Any line beginning with a pound ('''#''') sign is considered by
WML as a comment, except for preprocessor declarations beginning
with #.
* '''[tag-name] ''data'' [/tag-name]''' is a tag. Tags are used to partition information. A ''top level'' tag is one that is not inside any other tag. Each top level tag describes something about the game. Different tags work differently. For information about how a certain tag works, see [[ReferenceWML]].
* '''[+tag-name] ''data'' [/tag-name]''' means that ''data'' will be considered as part of the data for the most recent [''tag-name''] tag. The ''data'' of '''[+tag-name]''' will be considered as coming after all data in '''[tag-name]''', so attributes of '''[+tag-name]''' will replace attributes of the original '''[tag-name]'''.
* '''''key=value newline''''' is an ''attribute'', or an assignment of a value to a key. When this line is processed, the value of ''key'' for the tag that the attribute is in is set or changed to ''value''. All text from '=' until the end of the line is considered to be part of ''value''. Note that ''key'' is not a WML variable (with the exception of [[VariablesWML]]); the value it is set to has a use which is determined by C++ code, not WML code. In order to change the value of a WML variable, you need to use '''[set_variable]''' (see [[InternalActionsWML]]). '''There should be no space between the key and the '=' symbol!''' If there is whitespace, the attribute assignment is ignored. Note that ''key'' should contain only alphanumerics or underscores (''a-zA-Z0-9_''); no ''+'' or ''-'' characters are allowed.
* '''''key1,key2,key3=value1,value2,value3 newline''''' is a multiple assignment. If there are extra keys, they will be set to an empty value. If there are extra values the last key will be set to the comma separated list of all remaining values. It is the same as
key1=value1
key2=value2
key3=value3

Although a value can be just text corresponding to a function of
its key (these values are displayed in quotes (') in
[[ReferenceWML]]), a value can also be encoded:
* '''"''multiple-line-value''"''' a multiple-line value must be enclosed in quotes, to prevent it being interpreted as a single-line value. Note that ''multiple-line-value'' doesn't have to have multiple lines; it can simply be a single-line value enclosed in quotes for clarity.
* '''''_ "text"''''' is a ''translatable'' value. ''text'' is English (US) text that will be displayed in-game at some point. Gettext (see [[GetText]]) is used to determine what to display if English (US) is not the current language.
* '''''"value-1" + "value-2"''''' can be used to concatenate two different strings. If you want to have a value that actually has a plus sign ('''+''') in it, you need to enclose the string containing the '''+''' character in quotes (see '''''"multiple-line-value"''''' above).
* '''''"double ""quote marks"" within quote marks"''''' can be used to create quote marks within a quoted string.
* '''''$variable-name''''' a ''variable'' value depends on the value of the WML variable ''variable-name''. See [[VariablesWML]] for more information on WML-variable based values.
* '''''$(formula-expression)''''' a ''$( ... )'' value depends on the value of the ''formula-expression'' when evaluated. See [[FormulaAI]] for more information on Formula Basics, Data Types, and Built-in functions.

=== Empty Values ===
Usually, wesnoth does not distinguish between a key that has not been provided, and a key that has been assigned an empty value.

Some tags permit a workaround to provide a key with an empty value. You can write
key=$empty
where 'empty' is a WML variable that has not been assigned yet. (This is not technically an empty value, and hence wesnoth will notice that this key has been provided, but will become empty during variable substitution.)

For example, to check if a variable has been initialized, you could write
[variable]
name=to_be_tested
equals=$empty
[/variable]

However, some tags actually do the variable substitution ''before'' they check if the value is empty. This applies to some [[EventWML]] commands, including the crucial [[InternalActionsWML|set_variable]] tag. For example, consider the problem of copying the value another_variable to some_variable. You might write
[set_variable]
name=some_variable
format="$another_variable"
# does not work with another_variable is empty
[/set_variable]

The above example looks okay, because the format= key does not seem empty. However, if another_variable was empty, then wesnoth perform the substitution, resulting in format="" being an empty key. Then wesnoth will ignore the set_variable command, and some_variable would retain its value instead of becoming empty.

The workaround in this case is to write
[set_variable]
name=some_variable
to_variable="another_variable"
[/set_variable]

=== Example ===
[scenario]
id=Elves Besieged
[side]
side,gold=1,100
[/side]
[+side]
recruit=Elvish Fighter,Elvish Archer
[/side]
[/scenario]
In this example, [scenario] is a top level tag. When these
lines are read, WML will know that there is a scenario with
the ID "Elves Besieged". Later, when WML is told to play
that scenario, it will read the [side] tag and give 100 gold
to side 1. Then it will read the [+side] tag.
It interprets this tag as belonging to side 1, since the
most recent [side] belonged to side 1. So the [+side] tag
allows side 1 to recruit Elvish Fighters and Elvish Archers.
(Then it will crash, as the leader of side 1 has no unit type.
But this isn't really important.)

Notes: Normally the order and indentation of attributes and tags
does not matter, as long as the levels within tags are not changed.
So the above example could have been written:
[scenario]
[side]
gold=100
side=1
[/side]
id=Elves Besieged
[+side]
recruit=Elvish Fighter,Elvish Archer
[/side]
[/scenario]
Data inside tags should be separated with tabbing; see [[ConventionsWML]].

== See Also ==

* [[PreprocessorRef]]
* [[ReferenceWML]]

[[Category: WML Reference]]

ThemeWML

2009-03-22T10:28:36Z

Nital: removing {{DevFeature}} tags

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

== [main_map_border] ==
Defines the border of the main map area. It has the following keys.

* '''border_size''': the size of the border, the value should be between 0.0 and 0.5. The images which are used by default are sized for 0.5. If the border gets smaller the images still need the same size. They're simply cut off at the right spot.
* '''background_image''': the filename of the image to use as background.
* '''tile_image''': the filename of the image to use for the _off^_usr tile. The image in the minimal can't be controlled only the image in the main map. This image must be in the terrain directory and a png image. When specifying the image the 'terrain/' prefix and '.png' suffix _must_ be ommitted.
* '''corner_image_top_left''': filename for the image in the top left corner.
* '''corner_image_bottom_left''': filename for the image in the top left corner.
* '''corner_image_top_right_odd''': filename for the image in the top right corner, if the x value of the corner is odd. This x value is the value seen in game (and thus not in the source).
* '''corner_image_top_right_even''': filename for the image in the top right corner, if the x value of the corner is even. This x value is the value seen in game (and thus not in the source).
* '''corner_image_bottom_right_odd''': filename for the image in the bottom right corner, if the x value of the corner is odd. This x value is the value seen in game (and thus not in the source).
* '''corner_image_bottom_right_even''': filename for the image in the bottom right corner, if the x value of the corner is even. This x value is the value seen in game (and thus not in the source).
* '''border_image_left''': filename for the image at the left border.
* '''border_image_right''': filename for the image at the right border.
* '''border_image_top_odd''': filename for the image at the top border, if the x value of the tile is odd. This x value is the value seen in game (and thus not in the source).
* '''border_image_top_even''': filename for the image at the top border, if the x value of the tile is even. This x value is the value seen in game (and thus not in the source).
* '''border_image_bottom_odd''': filename for the image at the bottom border, if the x value of the tile is odd. This x value is the value seen in game (and thus not in the source).
* '''border_image_bottom_even''': filename for the image at the bottom border, if the x value of the tile is even. This x value is the value seen in game (and thus not in the source).

== [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 languages
* '''text''': a text string id to be displayed
* '''postfix''': a string that will be printed after the text in all languages
* '''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

== [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. Note: this tag is now obsolete
* '''[unit_name]''': the user description of the current unit
* '''[unit_type]''': the type of the current unit
* '''[unit_race]''': the race of the current unit
* '''[unit_level]''': the level of the current unit
* '''[unit_side]''': the side of the current unit (flag)
* '''[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]''': the portait for the current unit
* '''[unit_advancement_options]''': the advancement(s) of the current unit appear in the tooltip of this element
* '''[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 (flag)
* '''[observers]''': the current observers

== See Also ==

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

[[Category: WML Reference]]

User:Nital

2009-03-19T23:13:12Z

Nital:

Welcome to my userpage! You can read about my ideas and projects connected with Wesnoth here.

==My ideas==

My main interest as for now is easing the process of patching Wesnoth binaries. That is mainly because my friends has requested a method that would allow them upgrade without downloading ~200 MB every time.
Another reason is because Ivanovic told me than nobody bothered about that before, and I see this part quite important ;)

===Wesnoth binary patch problem===

Be warned - since my friends are using Windows, this problem will be considered mostly from Windows perspective. However, it may be applicable to other OSes as well, I don't know.
As everyone knows, official Wesnoth packages are getting bigger and bigger with each release. It is obvious that downloading a >100 MB file every time isn't convenient.

====Solutions so far====
There was a try with providing xdeltas (read more here: [[Download Xdeltas]]) for Windows binaries, but as it's stated there - xdeltas of binaries have two major cons:
* They are incremental, no patch unification is possible (to upgrade from 1.2.3 to 1.2.5 you have to download 1.2.3->1.2.4 and 1.2.4->1.2.5 xdeltas, unless devs provide 1.2.3->1.2.5 xdelta)
* Due to unstable character of inner structure of the installation binary, xdeltas of these tend to have large sizes.
However, developers of professional games somehow manage to keep their patches small, working and sometimes even quite unified (so the patch can handle updating several different versions). They usually achieve that by working on an already installed game and that is also my approach.

====Goal====

The goal is to make creating patches for stable branch easy. Patch in this context means a small executable that user:
# Copies to his/her wesnoth folder from 1.6
# Runs it.
# Removes it. (optional)
# Forgets about the process and starts enjoying upgraded Wesnoth.
I mentioned stable version because of three reasons:
* not many files are (or should be) changed and added during development of stable branch
* there is a good starting point upon which the unified patch would be created, i.e. first release of the branch (for example release 1.6 for 1.6.x branch)
* it is aimed to be used by the majority of Wesnoth players.

====Overview====

My approach is simple: compare two filetrees "wesnoth1.6/" and "wesnoth1.6.5/" and include in one package all files that have been added or changed between these two. Then compress it with 7-Zip and make it a self-extracting archive.
Benefits of this approach:
* Patches are not incremental, a 1.6.7 patch will work with 1.6.6 as good as with 1.6.1 or 1.6.
* Allows easy exclusions of patched files (for example Hungary fansite will be able to provide substantially smaller patches with only English and Hungarian translations included)
* Cross-platform (will work on all OSes that 7-Zip supports)

Some statistics of 7-zipped data:
{| border="1"
|Part
|Original MB
|7-zipped MB
|-
|wesnoth.exe
|13.6
|2.55
|-
|translations/
|56.8
|8.85
|-
|data/ * (see below)
|~5
|~0.5
|}
data/ - excluding graphics, sounds, music and campaigns (only because campaigns contained lots of new graphics and I was too lazy to exclude them manually from their directories)

It can be seen that if there are no changes to graphics or sounds, the patch size can be easily kept below 20 MB (even below 10 MB if you don't want to update translations).
Concerning translations, there could be two patch files for one release - one containing only English[US] update for English people and others that care only about gameplay fixes. The second one would contain all translations, and would be about 9 MB bigger.

====Things that should be avoided====
To keep patch files as small as possible, developers should avoid (in stable branch):
* Adding/changing graphics and sounds (especially sounds). Since their formats are already compressed, changing a 6 MB ogg file will result in a 6 MB larger patch.
* Reorganizing structure of wesnoth/ tree (i.e. renaming or moving files or directories). Unless there is a better tool developed, it's a very bad idea since every file and dir which changed location will be included in the patch, even if it wasn't changed at all.
* Adding any references to Wesnoth version in default menu Start shortcuts etc. since it doesn't introduce anything useful to average player and increases the difficulty of patching it correctly.

====Progress====

I am currently working on getting first working beta. It is being written in Python, like the rest of Wesnoth tools.

==My contributions==
[https://gna.org/patch/index.php?1124 patch #1124] - adding "hidden" attribute to [[SideWML]]

User:Nital

2009-03-19T23:06:54Z

Nital: /* Overview */

Welcome at my userpage! You can read about my ideas and projects connected with Wesnoth here.

==My ideas==

My main interest as for now is easing the process of patching Wesnoth binaries. That is mainly because my friends has requested a method that would allow them upgrade without downloading ~200 MB every time.
Another reason is because Ivanovic told me than nobody bothered about that before, and I see this part quite important ;)

===Wesnoth binary patch problem===

Be warned - since my friends are using Windows, this problem will be considered mostly from Windows perspective. However, it may be applicable to other OSes as well, I don't know.
As everyone knows, official Wesnoth packages are getting bigger and bigger with each release. It is obvious that downloading a >100 MB file every time isn't convenient.

====Solutions so far====
There was a try with providing xdeltas (read more here: [[Download Xdeltas]]) for Windows binaries, but as it's stated there - xdeltas of binaries have two major cons:
* They are incremental, no patch unification is possible (to upgrade from 1.2.3 to 1.2.5 you have to download 1.2.3->1.2.4 and 1.2.4->1.2.5 xdeltas, unless devs provide 1.2.3->1.2.5 xdelta)
* Due to unstable character of inner structure of the installation binary, xdeltas of these tend to have large sizes.
However, developers of professional games somehow manage to keep their patches small, working and sometimes even quite unified (so the patch can handle updating several different versions). They usually achieve that by working on an already installed game and that is also my approach.

====Goal====

The goal is to make creating patches for stable branch easy. Patch in this context means a small executable that user:
# Copies to his/her wesnoth folder from 1.6
# Runs it.
# Removes it. (optional)
# Forgets about the process and starts enjoying upgraded Wesnoth.
I mentioned stable version because of three reasons:
* not many files are (or should be) changed and added during development of stable branch
* there is a good starting point upon which the unified patch would be created, i.e. first release of the branch (for example release 1.6 for 1.6.x branch)
* it is aimed to be used by the majority of Wesnoth players.

====Overview====

My approach is simple: compare two filetrees "wesnoth1.6/" and "wesnoth1.6.5/" and include in one package all files that have been added or changed between these two. Then compress it with 7-Zip and make it a self-extracting archive.
Benefits of this approach:
* Patches are not incremental, a 1.6.7 patch will work with 1.6.6 as good as with 1.6.1 or 1.6.
* Allows easy exclusions of patched files (for example Hungary fansite will be able to provide substantially smaller patches with only English and Hungarian translations included)
* Cross-platform (will work on all OSes that 7-Zip supports)

Some statistics of 7-zipped data:
{| border="1"
|Part
|Original MB
|7-zipped MB
|-
|wesnoth.exe
|13.6
|2.55
|-
|translations/
|56.8
|8.85
|-
|data/ * (see below)
|~5
|~0.5
|}
data/ - excluding graphics, sounds, music and campaigns (only because campaigns contained lots of new graphics and I was too lazy to exclude them manually from their directories)

It can be seen that if there are no changes to graphics or sounds, the patch size can be easily kept below 20 MB (even below 10 MB if you don't want to update translations).
Concerning translations, there could be two patch files for one release - one containing only English[US] update for English people and others that care only about gameplay fixes. The second one would contain all translations, and would be about 9 MB bigger.

====Things that should be avoided====
To keep patch files as small as possible, developers should avoid (in stable branch):
* Adding/changing graphics and sounds (especially sounds). Since their formats are already compressed, changing a 6 MB ogg file will result in a 6 MB larger patch.
* Reorganizing structure of wesnoth/ tree (i.e. renaming or moving files or directories). Unless there is a better tool developed, it's a very bad idea since every file and dir which changed location will be included in the patch, even if it wasn't changed at all.
* Adding any references to Wesnoth version in default menu Start shortcuts etc. since it doesn't introduce anything useful to average player and increases the difficulty of patching it correctly.

====Progress====

I am currently working on getting first working beta. It is being written in Python, like the rest of Wesnoth tools.

==My contributions==
[https://gna.org/patch/index.php?1124 patch #1124] - adding "hidden" attribute to [[SideWML]]

User:Nital

2009-03-19T23:06:24Z

Nital: New page: Welcome at my userpage! You can read about my ideas and projects connected with Wesnoth here. ==My ideas== My main interest as for now is easing the process of patching Wesnoth binaries....

Welcome at my userpage! You can read about my ideas and projects connected with Wesnoth here.

==My ideas==

My main interest as for now is easing the process of patching Wesnoth binaries. That is mainly because my friends has requested a method that would allow them upgrade without downloading ~200 MB every time.
Another reason is because Ivanovic told me than nobody bothered about that before, and I see this part quite important ;)

===Wesnoth binary patch problem===

Be warned - since my friends are using Windows, this problem will be considered mostly from Windows perspective. However, it may be applicable to other OSes as well, I don't know.
As everyone knows, official Wesnoth packages are getting bigger and bigger with each release. It is obvious that downloading a >100 MB file every time isn't convenient.

====Solutions so far====
There was a try with providing xdeltas (read more here: [[Download Xdeltas]]) for Windows binaries, but as it's stated there - xdeltas of binaries have two major cons:
* They are incremental, no patch unification is possible (to upgrade from 1.2.3 to 1.2.5 you have to download 1.2.3->1.2.4 and 1.2.4->1.2.5 xdeltas, unless devs provide 1.2.3->1.2.5 xdelta)
* Due to unstable character of inner structure of the installation binary, xdeltas of these tend to have large sizes.
However, developers of professional games somehow manage to keep their patches small, working and sometimes even quite unified (so the patch can handle updating several different versions). They usually achieve that by working on an already installed game and that is also my approach.

====Goal====

The goal is to make creating patches for stable branch easy. Patch in this context means a small executable that user:
# Copies to his/her wesnoth folder from 1.6
# Runs it.
# Removes it. (optional)
# Forgets about the process and starts enjoying upgraded Wesnoth.
I mentioned stable version because of three reasons:
* not many files are (or should be) changed and added during development of stable branch
* there is a good starting point upon which the unified patch would be created, i.e. first release of the branch (for example release 1.6 for 1.6.x branch)
* it is aimed to be used by the majority of Wesnoth players.

====Overview====

My approach is simple: compare two filetrees "wesnoth1.6/" and "wesnoth1.6.5/" and include in one package all files that have been added or changed between these two. Then compress it with 7-Zip and make it a self-extracting archive.
Benefits of this approach:
* Patches are not incremental, a 1.6.7 patch will work with 1.6.6 as good as with 1.6.1 or 1.6.
* Allows easy exclusions of patched files (for example Hungary fansite will be able to provide substantially smaller patches with only English and Hungarian translations updated)
* Cross-platform (will work on all OSes that 7-Zip supports)

Some statistics of 7-zipped data:
{| border="1"
|Part
|Original MB
|7-zipped MB
|-
|wesnoth.exe
|13.6
|2.55
|-
|translations/
|56.8
|8.85
|-
|data/ * (see below)
|~5
|~0.5
|}
data/ - excluding graphics, sounds, music and campaigns (only because campaigns contained lots of new graphics and I was too lazy to exclude them manually from their directories)

It can be seen that if there are no changes to graphics or sounds, the patch size can be easily kept below 20 MB (even below 10 MB if you don't want to update translations).
Concerning translations, there could be two patch files for one release - one containing only English[US] update for English people and others that care only about gameplay fixes. The second one would contain all translations, and would be about 9 MB bigger.

====Things that should be avoided====
To keep patch files as small as possible, developers should avoid (in stable branch):
* Adding/changing graphics and sounds (especially sounds). Since their formats are already compressed, changing a 6 MB ogg file will result in a 6 MB larger patch.
* Reorganizing structure of wesnoth/ tree (i.e. renaming or moving files or directories). Unless there is a better tool developed, it's a very bad idea since every file and dir which changed location will be included in the patch, even if it wasn't changed at all.
* Adding any references to Wesnoth version in default menu Start shortcuts etc. since it doesn't introduce anything useful to average player and increases the difficulty of patching it correctly.

====Progress====

I am currently working on getting first working beta. It is being written in Python, like the rest of Wesnoth tools.

==My contributions==
[https://gna.org/patch/index.php?1124 patch #1124] - adding "hidden" attribute to [[SideWML]]

SummerOfCodeIdeas

2009-03-13T21:51:06Z

Nital: /* I want to be one of your Google Summer of Code students, what should I do... */

This is a compilation of ideas from ML. Needs to be refined (more detailed description, deliverables, workload estimation?):

== I want to be one of your Google Summer of Code students, what should I do... ==

Here is a quick list of things to do to get you started
* Create an account on gna.org
* Create an account on the wesnoth forum
* Join the irc channel (#wesnoth-dev on irc.freenode.net) and introduce yourself. We will not give formal interviews, but we will clearly favor people we have learnt to know during the selection process
* Contact one of our SummerOfCode people (Ivanovic, Sirp, Boucman, Mordante) to have your forum nick marked as a Summer of code student

* Start a wiki page about your idea, add a link on the bottom of this page and add this information on it:
** List your account names (gna, forum, irc nick) so that we can recognize you
** Fill the questionnaire on this page: [[SoC_Information_for_Google#Does_your_organization_have_an_application_template_you_would_like_to_see_students_use.3F_If_so.2C_please_provide_it_now.| List of questions to answer]]
** Detail your idea as much as possible, look at other students pages, and please give milestones and studies you've done

* Though not mandatory, it is highly advisable to go to the [[EasyCoding]] and [[NotSoEasyCoding]] pages and implement one of these ideas (or any idea of similar scope) so we have an idea how you work. Be sure to use your gna account when submitting these patches so we know who it is coming from. You can also implement some features from our feature request database at gna. When you implement something, also list it on your own page with a reference to the patch.

* For working on Wesnoth you have to be able to compile trunk. To do so you should have a look at the [[WesnothSVN|page about svn]] and afterwards [[CompilingWesnoth|compile Wesnoth svn]].

* Once you have everything done here and think your idea is okay, go to [http://groups.google.com/group/google-summer-of-code-announce/web/guide-to-the-gsoc-web-app-for-student-applicants page at google] to submit your application. You have to submit it before '''Date to be supplied later''' or you have no chance to get in!

== List of Ideas for the Project (Suggestions from the wesnoth developers) ==

Here is only a short description of possible Ideas we have, each has a page of its own with a more detailed version on it.

=== Optimize implementation of WML for memory usage ===

Based on this idea: [http://dave.wesnoth.org/?p=9] optimize WML to minimize its memory usage. High memory usage has been a problem for Wesnoth, and this project will aim to reduce it.

=== Implement campaign statistics reports on stats.wesnoth.org ===

Wesnoth has an infrastructure which records details of campaigns that players play into a centralized MySQL database. However, we only have rudimentary reports based on this MySQL database available at this time, at [http://stats.wesnoth.org].

This project would involve writing a stats reporting web site which would take the data from the MySQL database and produce reports in chart and table form. Campaign designers would be able to use these reports to gather feedback on their campaigns and get ideas for improvements.

A student could largely make their choice of infrastructure for creating the Website -- whether they prefer Python, Perl, Ruby, PHP, etc. This is a great opportunity for someone who doesn't want to dive into hardcore C++ to make a valuable contribution to Wesnoth.

=== Extending the Multiplayer server ===

Our multiplayer community is generally strong and healthy, but we believe its growth is limited by some problems in the interface of the multiplayer lobby.

[[SoC Ideas Multiplayer server]] - Full version of the idea, with detailed information

=== Addon server ===
Wesnoth has an addon server which offers users to upload user
made content (UMC). This allows all other users of Wesnoth
to easily download and install this content. The server was
originally written for user-made campaigns but contains a lot
more types of addons nowadays. Both the server side and the
client side need to be improved.

[[SoC Ideas Addon Server]] - Full version of the idea, with detailed information

=== WML validation schemes ===
Wesnoth uses WML as basic data structure. Over the years
this language has evolved and got more complex. At the
moment the WML is validated at runtime and in case of a
problem the engine stops. With schemes these problems can
be validated when loading the WML, making it easier to find
problems before running into them.

[[SoC Ideas Schemes]] - Full version of the idea, with detailed information

=== Write a primitive library for Formula AI ===

Wesnoth has always had a simple C++ based AI. David (our lead developer) has been working on a simple language to write AI in Wesnoth: [[FormulaAI]]

The Wesnoth AI is used as an opponent in most campaigns, and as such is an important piece of code for the Wesnoth project. Unfortunately, because the skills required to understand and modify it are rather arcane, it is also one of the most neglected parts of the Wesnoth code. This is a place where a lot of research and useful work could be done. But keep in mind that [[WhyWritingAWesnothAIIsHard|writing an AI for Wesnoth is difficult]].

Writing a whole AI is so complicated that we believe it can't be done in a single Summer of code. All proposals should keep that in mind and try to identify an interesting subset that would be workable in the limited time of a summer of code

[[SoC Ideas FormulaAI]] - Full version of the idea, with detailed information

=== Savegame reorganization ===
The savegame formats of Wesnoth for single player campaigns
and multiplayer differ from each other. And they are processed
differently as well. Now there is an additional request coming
up: Multiplayer campaigns. The task will be to unify the savegames
for all types of scenarios in order to provide a maintainable code
again.

[[SoC Ideas Savegame]] - Full version of the idea, with detailed information

=== Other possible ideas to be fleshed out ===
A MapGenerator rewrite - better scalable for outdoor maps, plus the possibility to define areas (similar to the caverns in the cave generator) etc.

=== Make your own ideas ===
If you have your own idea the best thing is to join IRC wesnoth-dev at irc.freenode.net and discuss the idea with the developers there. If the developers think your idea is interesting and like the feature you can start to turn it into a full proposal. Once done discuss it again on IRC so the developers can accept your idea.

== Information about our Project ==
The information we provided google with about our project can be looked up at the site [[SoC Information for Google]].

Also see the [[DeveloperResources]] link (from the [[Project]] page).

== People to bug on IRC ==
We have prepared a list of people with their "area of competence". This is to give you an idea on which areas those people can be of help for you. Of course you should always just ask in the IRC chan, but those are the most likely ones to answer questions in the respective area. And here is the list:

[[SoC People to bug on IRC]]

== GSoC Student Applicant Ideas ==

Every student interested to work on Wesnoth as part of Summer of Code should create a page of his own where several things should be listed. Here is a short list of what should be mentioned on the list (the more info for us, the better...):

* Who are you? Please list your IRC and forum nickname in here and describe yourself so that we get you to know.
* What do you want to work on? Please flesh out your personal ideas, so that we get to know what you plan to work on.
* If you already submitted patches, please list those so that we have a reference.

[[Category:Summer of Code|*]]

SummerOfCodeIdeas

2009-03-13T21:50:44Z

Nital: /* Write a primitive library for Formual AI */

This is a compilation of ideas from ML. Needs to be refined (more detailed description, deliverables, workload estimation?):

== I want to be one of your Google Summer of Code students, what should I do... ==

Here is a quick list of things to do to get you started
* Create an account on gna.org
* Create an account on the wesnoth forum
* Join the irc channel (#wesnoth-dev on irc.freenode.net) and introduce yourself. We will not give formal interviews, but we will clearly favor people we have learnt to know during the selection process
* Contact one of our SummerOfCode people (Ivanovic, Sirp, Boucman, Mordante) to have your forum nick marked as a Summer of code student

* Start a wiki page about your idea, add a link on the bottom of this page and add this information on it:
** List your account names (gna, forum, irc nick) so that we can recognize you
** Fill the questionnaire on this page: [[SoC_Information_for_Google#Does_your_organization_have_an_application_template_you_would_like_to_see_students_use.3F_If_so.2C_please_provide_it_now.| List of questions to answer]]
** Detail your idea as much as possible, look at other students pages, and please give milestones and studies you've done

* Though not mandatory, it is highly advisable to go to the [[EasyCoding]] and [[NotSoEasyCoding]] pages and implement one of these ideas (or any idea of similar scope) so we have an idea how you work. Be sure to use your gna account when submitting these patches so we know who it is coming from. You can also implement some features from our feature request database at gna. When you implement something, also list it on your own page with a reference to the patch.

* For working on Wesnoth you have to be able to compile trunk. To do so you should have a look at the [[WesnothSVN|page about svn]] and afterwards [[CompilingWesnoth|compile Wesnoth svn]].

* Once you have everything done here and think your idea is okay, go to [http://groups.google.com/group/google-summer-of-code-announce/web/guide-to-the-gsoc-web-app-for-student-applicants to page at google] to submit your application. You have to submit it before '''Date to be supplied later''' or you have no chance to get in!

== List of Ideas for the Project (Suggestions from the wesnoth developers) ==

Here is only a short description of possible Ideas we have, each has a page of its own with a more detailed version on it.

=== Optimize implementation of WML for memory usage ===

Based on this idea: [http://dave.wesnoth.org/?p=9] optimize WML to minimize its memory usage. High memory usage has been a problem for Wesnoth, and this project will aim to reduce it.

=== Implement campaign statistics reports on stats.wesnoth.org ===

Wesnoth has an infrastructure which records details of campaigns that players play into a centralized MySQL database. However, we only have rudimentary reports based on this MySQL database available at this time, at [http://stats.wesnoth.org].

This project would involve writing a stats reporting web site which would take the data from the MySQL database and produce reports in chart and table form. Campaign designers would be able to use these reports to gather feedback on their campaigns and get ideas for improvements.

A student could largely make their choice of infrastructure for creating the Website -- whether they prefer Python, Perl, Ruby, PHP, etc. This is a great opportunity for someone who doesn't want to dive into hardcore C++ to make a valuable contribution to Wesnoth.

=== Extending the Multiplayer server ===

Our multiplayer community is generally strong and healthy, but we believe its growth is limited by some problems in the interface of the multiplayer lobby.

[[SoC Ideas Multiplayer server]] - Full version of the idea, with detailed information

=== Addon server ===
Wesnoth has an addon server which offers users to upload user
made content (UMC). This allows all other users of Wesnoth
to easily download and install this content. The server was
originally written for user-made campaigns but contains a lot
more types of addons nowadays. Both the server side and the
client side need to be improved.

[[SoC Ideas Addon Server]] - Full version of the idea, with detailed information

=== WML validation schemes ===
Wesnoth uses WML as basic data structure. Over the years
this language has evolved and got more complex. At the
moment the WML is validated at runtime and in case of a
problem the engine stops. With schemes these problems can
be validated when loading the WML, making it easier to find
problems before running into them.

[[SoC Ideas Schemes]] - Full version of the idea, with detailed information

=== Write a primitive library for Formula AI ===

Wesnoth has always had a simple C++ based AI. David (our lead developer) has been working on a simple language to write AI in Wesnoth: [[FormulaAI]]

The Wesnoth AI is used as an opponent in most campaigns, and as such is an important piece of code for the Wesnoth project. Unfortunately, because the skills required to understand and modify it are rather arcane, it is also one of the most neglected parts of the Wesnoth code. This is a place where a lot of research and useful work could be done. But keep in mind that [[WhyWritingAWesnothAIIsHard|writing an AI for Wesnoth is difficult]].

Writing a whole AI is so complicated that we believe it can't be done in a single Summer of code. All proposals should keep that in mind and try to identify an interesting subset that would be workable in the limited time of a summer of code

[[SoC Ideas FormulaAI]] - Full version of the idea, with detailed information

=== Savegame reorganization ===
The savegame formats of Wesnoth for single player campaigns
and multiplayer differ from each other. And they are processed
differently as well. Now there is an additional request coming
up: Multiplayer campaigns. The task will be to unify the savegames
for all types of scenarios in order to provide a maintainable code
again.

[[SoC Ideas Savegame]] - Full version of the idea, with detailed information

=== Other possible ideas to be fleshed out ===
A MapGenerator rewrite - better scalable for outdoor maps, plus the possibility to define areas (similar to the caverns in the cave generator) etc.

=== Make your own ideas ===
If you have your own idea the best thing is to join IRC wesnoth-dev at irc.freenode.net and discuss the idea with the developers there. If the developers think your idea is interesting and like the feature you can start to turn it into a full proposal. Once done discuss it again on IRC so the developers can accept your idea.

== Information about our Project ==
The information we provided google with about our project can be looked up at the site [[SoC Information for Google]].

Also see the [[DeveloperResources]] link (from the [[Project]] page).

== People to bug on IRC ==
We have prepared a list of people with their "area of competence". This is to give you an idea on which areas those people can be of help for you. Of course you should always just ask in the IRC chan, but those are the most likely ones to answer questions in the respective area. And here is the list:

[[SoC People to bug on IRC]]

== GSoC Student Applicant Ideas ==

Every student interested to work on Wesnoth as part of Summer of Code should create a page of his own where several things should be listed. Here is a short list of what should be mentioned on the list (the more info for us, the better...):

* Who are you? Please list your IRC and forum nickname in here and describe yourself so that we get you to know.
* What do you want to work on? Please flesh out your personal ideas, so that we get to know what you plan to work on.
* If you already submitted patches, please list those so that we have a reference.

[[Category:Summer of Code|*]]

EasyCoding

2009-03-09T22:30:01Z

Nital: removing implemented feature

== Foreword ==
This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature I'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

--[[User:Boucman|Boucman]] 20:48, 3 October 2006 (CEST)

Since bugs are sometimes a good opportunity to get a first idea of the code, i will add some here that are easy to fix as soon as i stumble upon them (the one i had in mind is fixed already ;-).

--Yogi Bear, 28 February 2008

== MP related features ==

=== Use different font for in-game chat ===
Since commas and dots are apparently hard to tell apart. As per FR #7470 [https://gna.org/bugs/?7470]

== WML related features ==

=== WML configurable village income / upkeep ===
Preferably as a [scenario], [side] or [campaign] keys. As per FR #6301 [https://gna.org/bugs/?6301]

=== Add support of [if] for [scenario] ===
As per FR #4539 [https://gna.org/bugs/?4539]

=== Make [have_unit] optionaly use full SUF ===
[have_unit] by default uses SUF but does not apply it to recall list. Introduce an optional key that will allow to lift that limitation.

=== Side-specific results ===
Giving result=defeat or result=victory for specific sides. ([http://gna.org/bugs/index.php?4960 FR #4960]) -- [[User:dlr365|dlr365]] -- patch submitted [https://gna.org/bugs/index.php?4960]

=== Support for leaderless multiplayergames ===
Add support for the WML key victory_when_enemies_defeated= in the scenario tag during multiplayergames. ([https://gna.org/bugs/index.php?8106 FR #8106])

=== Other Ideas ===
See [[FutureWML]]; some ideas there are easier than others.

== Improvements to FormulaAI ==

Add new formula functions, or minor improvements to the formula language. Make it easier to debug the formula language.

== GUI related features ==
-------------------

Note at the moment Mordante is working on a new GUI system, these
changes will probably affect the way these items need to be implemented.
Contact Mordante on IRC before starting to work on these.

--[[User:SkeletonCrew|SkeletonCrew]] 14:04, 9 March 2008 (EDT)

=== Theme Changes ===

* allow custom themes to display values of WML variables ([http://gna.org/bugs/index.php?6209 FR #6209])
* hide the hourglass item from the statusbar when there is no timer

=== Widget Changes ===
* show side number, name and team association information in the status table
* make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* input history (chat, commands, ..) - note: rujasu is working on this feature

== GUI2 related features ==
GUI2 is the new gui engine Mordante/SkeletonCrew is working on.
* Information on the wiki can be found here http://www.wesnoth.org/wiki/GUIToolkit
* The source code is under src/gui/
* The configuration config files are under data/gui/default

Some tasks need the --new-widgets since the code is only shown in the experimental mode. Tasks which need this switch have the * in the title.

=== Generic yes/no ok/cancel dialog ===
There's already a generic OK dialog
* src/gui/dialogs/message.[h|c]pp
* data/gui/default/window/message.cfg

This dialog should have the option to show a cancel button as well and also let the caller of the dialog determine the text of the button. Maybe more buttons (4 in total) can be added to make the dialog more flexible.

=== * Minimap ===
The minimap widget has already been made but is broken.
* src/gui/widgets/minimap.[c|h]pp

The drawing code has been rewritten, but this widget hasn't been updated it's used in the MP connection dialog (which needs more work).

=== * Savegame dialog ===
This is a new dialog to write and requires the minimap code to be fixed first. The dialog should mimic the current dialog. Sorting of a listbox and the proper alignment of the columns is not important (the engine doesn't support this yet). The code should only be used when --new-widgets is used as start switch since we're in a feature freeze at the moment.

=== * Title screen ===
A start has been made for the new titlescreen
* src/gui/dialogs/title_screen.[c|h]pp
* data/gui/default/window/title_screen.cfg
This should be improved to include the buttons and alignment of the current title screen. The 'roll-over' image is not part of this task.

=== Arrow keys for the slider ===
There's a new slider widget, but it doesn't support the keyboard yet.
gui/widgets/slider.[c|h]pp

Clicking on the widget should capture the keyboard and then arrow left/right should move one step even if not all steps are visible.

=== Slider sizing ===
There are some issues with the sizing of a slider.
gui/widgets/slider.[c|h]pp

In a layout step it needs to try to shrink itself, not entirely sure where or how yet, best ask mordante on irc.

== Miscellaneous ==

=== More powerful village naming ===
'''Adding mountain names and other features to village names, having a second random name in village names'''

Currently the village naming engine has a very good structure that could allow
more powerfull names to be generated.
Understanding how it works should be quite easy, and a few usefull improvements could be added.

* Currently villages can use lake names and river names, this should be extended to other features like bridges, swamps, mountains etc...
* It would be nice to have a separate list of "first sylabus" and "last sylabus" for naming. That's not really needed in english, but some translations could use it
* Again, it is common to have villages with more than one "random" word in them. having a $name2 variable would be nice

ACardboardRobot 2/2/07

=== Debug Mode ===
* New debug command functionality (setting additional status.variables, possibly terrain)

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]

AnimationWML

2009-03-01T17:21:39Z

Nital: /* Syntax summary */

{{WML Tags}}

== Introduction ==

This page covers unit animations. At any point in game, units are playing an animation. Even when the unit is standing, it is actually playing a single frame animation.

This page will deal with the two problems of animations
* How are animations Chosen
* What exactly is drawn

== How animations are drawn ==
=== Animations ===
Any unit has a huge set of animations to choose from. Animations are WML blocks in the unit type, enclosed in either the generic type '''[animation]''' or some more specific tags such as '''[attack_anim]''' '''[idle_anim]''' and the like. An animation is what a unit displays when a given event is triggered, and a certain set of conditions are met such as
* unit is attacking
* unit is idling
* unit is attacking (event) and uses a melee weapon (condition)
* unit is attacking (event) and uses a melee weapon (condition) and opponent can't retaliate (condition)

events and conditions are described entirely in the [animation] block, and will be discussed in the animation choice section.

=== Frames ===

An animation is cut in frames. Frames are WML blocks that are contained either in '''[frame]''' WML blocks or in generic '''[xxx_frame]''' block. (the xxx part can be any string not starting with an underscore) the xxx part in the frame name is called the frame prefix. frames of the type '''[frame]''' are said to have an empty prefix

A frame typically describes an image, where an how to render it. It can contain such things as
* the image to display
* how transparent should that image be
* where to draw that image.

At any given time, an animation will display one frame for each frame prefix it can find. I.e if your animation has both '''[frame]''' and '''[missile_frame]''' blocks, both will be displayed at the same time

The frame with the empty prefix is special in many way. It is assumed to contain the image representing the unit itself, and as such the engine will heavily temper with it in multiple ways, such as providing a default image if none is available, or forcing the image to be green when the unit is poisoned

=== Timing, Clock, Multiple animations ===
When an animation is played it has an internal clock that is run. The step of this clock is the milisecond, and each frame is played for a given duration. Each animation also has a starting time which tells the animation engine at what value the animation clock should start

This starting time is very important when multiple animations from different units are played synchronously Typically a fight involves a unit playing its defense animation while the opponent plays it's attack animation (and a third might play its leading animation, too). In that case all animations have a common clock, and are played concurrently.

The convention is that the "important time" (usually the time of the hit) is at time 0. everything before should be at negative time, everything after at positive time. This is a WML convention that is not enforced by the engine

In that case, it is very important that these animations (which can have different lengths) be synchronized. Fight animations are synchronized around the point of impact, so they all reach time 0 when the attack lands (or misses). This is accomplished through the use of the '''start_time''' key of the '''[animation]''' tag.

Just like the '''[frame]''' tag can have a prefix, so can the '''start_time''' key. A '''start_time''' key without prefix will affect a '''[frame]''' tag without prefix, while a '''start_time''' key with a prefix will affect a '''[frame]''' tag with the same prefix.

==== Example Syntax ====
[attack_anim]
[attack_filter]
name= _ "bow"
[/attack_filter]
'''start_time'''=-350
'''missile_start_time'''=-150
[missile_frame]
duration=150
image="projectiles/missile-n.png"
image_diagonal="projectiles/missile-ne.png"
[/missile_frame]
[if]
hits=yes
[frame]
duration=350
sound=bow.ogg
[/frame]
[/if]
[else]
hits=no
[frame]
duration=350
sound=bow-miss.ogg
[/frame]
[/else]
[/attack_anim]

=== The content of a frame ===
==== Syntax summary ====
[frame]
duration=<integer>
begin=<deprecated,integer>
end=<deprecated,integer>
image=<string>
image_diagonal=<string>
image_mod=<string>
sound=<string>
halo=<progressive string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
alpha=<progressive float>
offset=<progressive float>
blend_color=< red, green, blue >
blend_ratio=<progressive float>
text=<string>
text_color=< red, green, blue >
submerge=<dev:progressive float>
x=<dev:progressive int>
y=<dev:progressive int>
layer=<dev:progressive int>
[/frame]

dev denotes a {{DevFeature}}

==== Progressive parameters ====

Some parameters above are marked as ''progressive'' This means that you can specify that during the time the frame is displayed, the parameter should smoothly slide from one value to an other.

A typical example would be a unit progressively fading out, becoming transparent

To do that, you could use:

alpha=1~0

To make a frame, which is 900ms long, slide to transparent for 300ms, stay transparent for another 300ms and finally fade back to normal for 300ms, use:

alpha=1~0:300,0:300,0~1:300

you could also specify it like that

alpha=1~0,0,0~1

when a timing is missing, the engine will do its best to fill in in a fair way.

a progressive string has a similar syntax

halo=halo1.png:300,halo2.png:300,halo2.png:300

==== Field Description ====

** '''begin''': (deprecated) will be replaced by '''duration= <end - begin >'''
** '''end''': (deprecated) see '''begin''' and also [[AnimationWML#Timing.2C_Clock.2C_Multiple_animations|Timing, Clock, Multiple animations]] section for coverage of '''start_time''' which combines with '''duration''' to replace '''begin=''' '''end='''.
** '''duration''': how long the frame should be displayed. Use instead of '''begin=''' and '''end='''.
** '''image''': the image to display during the frame.
** '''image_diagonal''': the image to display when the attack occurs diagonally (directions ne,se,sw,nw).
** '''image_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all images
** '''sound''': the sound to play when the frame begins. Can be a comma-separated list of sounds, in which case one of them is chosen randomly every time.
** '''halo''': the halo to display at the time.
** '''halo_x''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_y''': the position the halo is displayed in pixel relative to the unit's center.
** '''halo_mod''': a string modifications (see [[ImagePathFunctionWML]] ) that will be applied to all haloes
** '''alpha''': transparency level to apply to the frame. This is a floating point progressive parameter ranging from 0.0 to 1.0.
** '''offset''': the position of the image relative to the hex the unit is facing, 0.0 will display the unit in the center of the hex, 1.0 in the center of the faced hex, -1.0 at the center of the hex behind you. This is a progressive parameter.
** '''blend_color''': a comma separated list of numbers representing a color in RGB (0-255) this color will be mixed to the frame to give it a tint.
** '''blend_ratio''': this is a progressive parameter ranging from 0 to 1: 0 means no tint, 1 means target color only.
** '''text''': if specified, floats a label with the given text above the unit (identical to the floating damage and healing numbers).
** '''text_color''': the color of the above floating label.
** '''submerge''': {{DevFeature}} the part of the unit that should drawn with 50% opacity (for units in water)
** '''x''': {{DevFeature}} x offset applied to the frame
** '''y''': {{DevFeature}} y offset applied to the frame
** '''layer''': {{DevFeature}} layer used to draw the frame, see discussion bellow

=== Drawing related animation content ===
==== Syntax summary ====
[animation]
<animation choice related content>
[frame]
<frame content>
[/frame]
[frame]
<frame content>
[/frame]
start_time=<integer>
offset=<progressive float>
image_mod=<string>
blend_with=<r,g,b>
blend_ratio=<progressive float>
halo=<progressive_string>
halo_x=<progressive int>
halo_y=<progressive int>
halo_mod=<string>
submerge=<dev:progressive float>
x=<dev:progressive int>
y=<dev:progressive int>
layer=<dev:progressive int>

[xxx_frame]
<frame content>
[/xxx_frame]
xxx_start_time=<integer>
xxx_image_mod=<string>
xxx_offset=<progressive float>
xxx_blend_with=<r,g,b>
xxx_blend_ratio=<progressive float>
xxx_halo=<progressive_string>
xxx_halo_x=<progressive int>
xxx_halo_y=<progressive int>
xxx_halo_mod=<string>
xxx_submerge=<dev:progressive float>
xxx_x=<dev:progressive int>
xxx_y=<dev:progressive int>
xxx_layer=<dev:progressive int>

[/animation]

dev denotes a {{DevFeature}}

==== Parameter handling ====
All drawing related parameters in '''[animation]''' can be matched with a corresponding parameter in a '''[frame]''' block (or a '''[xxx_frame]''' block) The value provided in the animation will be used if no value is provided in the frame.

The point of these two level of parameters is to easily be able to specify a parameter at the animation level and override it for a special case of frame.

== How animations are chosen ==
Within a unit decription block there are multiple animations. Each animation is meant to be played in a very special set of circumstances. We will discuss here how to tell the animation engine when a given animation should be played.

Let's take an example. Suppose we have a unit which has the skirmisher ability. We have the folowing movement animations :
* a normal walking animation
* a swimming animation when the unit is in water
* a tiptioeing animation when moving next to an ennemy unit

Ok. most of the time it's easy to guess what animation should be. However if you are both in water and next to an ennemy unit, the animation to play is not obvious.

To solve that question, each animation has a number of filtering criterias. The engine follow the following rules to select an animation
* Start with all animations
* Drop all animations with a criteria that fails on the current situation
* Take the animations that have the most maching criterias
* If there are more than one animation remaining, take an animation randomly
* If all animations have been droped, the engine will provide a smart default.

here is a pseudo-code explaination of this algorithm

foreach animation
animation_score = 0
foreach filter-criteria
if <criteria-fails>
animation_score = -1;
break;
elsif <criteria-matches>
animation_score++
endfor
if animation_score > max_score
<empty animation list>
max_score = animation_score;
push(animation,animation_list);
elsif animation_score = max_score
push(animation,animation_list);
endfor
<choose an animation randomly from animation_list>

Note that all animations don't have all the filters...

so, if we have a unit with
# an animation for water terrain
# an animation for SE on grassland
# an animation with no criteria
# an animation for N,NE,NW,S,SW,SE
# an animation for NW

* 3. will never be taken, because 4. will always trump it
* on water going NW, it can be 1. 4. 5.
* on water, any direction but NW, it will be 1. or 4.
* on SE grassland it will be 2.
* on other grasslands, it will be 4. (4. or 5. if NW)

=== Generic animation filters available for all animations ===
* '''apply_to''': a list of comma separated keywords describing what event should trigger the animation (movement, attack...) the complete list is given below
* '''value''': a list of comma separated integer, the meaning depends on the triggering event. the meaning is given with the list of event
* '''terrain''': a list of comma separated terrain letters, the animation will only be used on these terrains. See [[FilterWML]].
* '''[unit_filter]''': this will filter using a standard unit filter on the animated unit. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[unit_filter]''' blocks in an animation. ({{DevFeature}} renamed to [filter])
* '''[secondary_unit_filter]''': this will filter using a standard unit filter on the unit in the hex faced. Note that matching all criterias in the filter will only earn you one point for animation selection, but that you can have multiple '''[secondary_unit_filter]''' blocks in an animation. Also note that if the faced hex is empty, the whole filter will fail. ({{DevFeature}} renamed to [filter_second])
* '''direction''': a list of directions (n,ne,se,s,sw,nw), the animation will only be used when acting or moving in this direction (the attack direction for attack animations, moving direction for movement animations, direction of lead unit for leading animations, and so on).
* '''frequency''': this integer value allows to easily tweak the matching frequency of animations. The filter will fail n-1 times out of n, randomly. Note that unlike every other filter, matching this filter won't give an extra point.
* '''[attack_filter]''': a standard attack filter to match on the attacker's attack. See [[FilterWML]]. ({{DevFeature}} renamed to [filter_attack])
* '''[secondary_attack_filter]''': a standard attack filter to match on the defender's attack. See [[FilterWML]]. Also note that if the defender doesn't have any weapon to retaliate with, this filter will always fail. ({{DevFeature}} renamed to [filter_second_attack])
* '''hits''': filters attack animations based on whether the attack hits, misses or kills. Accepts a list of the following:
** '''hit''': the attack hits, defender survives.
** '''no''' or '''miss''': the attack misses.
** '''kill''': the attack hits, defender dies.
** '''yes''': is an alias of '''hit,kill'''.
* '''swing''': a list of numbers representing the swing numbers this animation should match (numbered from 1).

=== Events trigerring animations and default animations ===
==== standing ====
This animation is triggered whenever any other animation is finished, and is played in loop until another animation is triggered

this is the default "standing image" for the unit

''value='' is not used, and always contains 0

if no standing animation is set a single frame animation based on the enclosing unit's '''image=''' field is used
==== selected ====
This animation is triggered whenever the unit is selected

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0.0~0.3:100,0.3~0.0:200" blend_color=255,255,255''
==== recruited ====
This animation is triggered whenever the unit is recruited or recalled

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=0~1:600''
==== levelin ====
This animation is triggered whenever the unit levels, before the unit is replaced by the new unit

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:600" blend_color=255,255,255''
==== levelout ====
This animation is triggered whenever the unit levels, after the unit is replaced by the new unit

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:600" blend_color=255,255,255''
==== movement ====
This animation is used whenever a unit moves. There are multiple things to consider when dealing with movement animation
* unit stay ''exactly'' 150ms in each hex. so you typically want to have an offset of ''0~1:150,0~1:150,0~1:150,0~1:150,0~1:150'' or something similar
* when a unit enters a hex, the current anim is tested again.
** if the current animation is still valid (i.e it passes all its filter) it is kept, whatever the final score is
** if it fails, a new movement anim is searched

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"''
==== pre_teleport ====
This animation is triggered whenever the unit teleports, but before it has moved to the target hex

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="1~0:150" blend_color=255,255,255''
==== post_teleport ====
This animation is triggered whenever the unit teleports, but after it has moved to the target hex

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''blend_with="0~1:150" blend_color=255,255,255''
==== healing ====
This animation is triggered when the unit has healing powers and uses them

''value='' is the number of points healed

No default is provided by the engine
==== healed ====
This animation is triggered whenever the unit is healed for any reason

''value='' is the number of points healed

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=255,255,255''
and plays the sound ''heal.wav''
==== poisoned ====
This animation is triggered whenever the unit suffers poison dammage

''value='' is the number of points lost

if no animation is available, the default uses the standing animation(s) with ''blend_with="0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30,0.5:30,0:30" blend_color=0,255,0''
and plays the sound 'poison.ogg''
==== defend ====
This animation is triggered during a strike, of the unit receiving the blow

''value='' is the number of point lost, if any

No default is provided by the engine
==== attack ====
This animation is triggered during a strike, of the unit giving the blow

''value='' is the number of damage dealt, if any

if no animation is available, the default uses the standing animation(s) with ''offset="0~0.6:150,0.6~0:150"'' for melee attacks
No default is provided for range attacks
==== leading ====
This animation is triggered for units with the leading special ability, when the unit they are leading is attacking

''value='' is not used, and always contains 0

No default is provided by the engine

==== resistance ====
This animation is triggered for units with the resistance special ability affecting neighbouring fights, when the unit they are helping is defending

''value='' is not used, and always contains 0

No default is provided by the engine

==== death ====
This animation is triggered when a unit die.

''value='' is not used, and always contains 0

if no animation is available, the default uses the standing animation(s) with ''highlight=1~0:600'' and plays the sound in ''die_sound='' of the enclosing unit
==== victory ====
This animation is triggered when a unit finishes a fight by killing the other unit

''value='' is not used, and always contains 0

No default is provided by the engine
==== idling ====
This animation is called when the unit has been using its standing animation for a random duration.

''value='' is not used, and always contains 0

No default is provided by the engine

==== default {{DevFeature}} ====

This animation is never triggered, but is used as a base to create new animations

''value='' is used depending of the type of animation it replaces

A single animation made of the base frame is provided by the engine if no default animation is available

==== extra animations ====
Other values are never called by the engine. However they can be triggered by WML events allowing custom animations.

Note that WML events can also trigger standard animations.
''value='' is set from the WML event

== Shortcuts, tricks and quirks ==

=== ''[if]'' and ''[else]'' ===

Often, you need to do very slight variations in an animation (like a different sound depending on whether the unit hits or misses its attack), the '''[if]''' and '''[else]''' tags are meant to help you do that.

Using these in an animation is equivalent to having multiple animations, one with the '''[if]''' block and one with each of the ''[else]'' blocks. Any filtering flags in these blocks will replace the toplevel filters. You can have multiple '''[if]''' blocks in an animation, but you can't nest an '''[if]''' inside another. These should be written directly inside the '''[animation]''' block. The following example would make the '''[frame]''' inside the '''[if]''' be played when the attack misses, and the '''[frame]''' inside the '''[else]''' be played when the attack hits (producing a different sound):

[if]
hits=no
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound={SOUND_LIST:MISS}
[/frame]
[/if]
[else]
hits=yes
[frame]
begin=-100
end=100
image="units/dwarves/lord-attack.png"
sound=axe.ogg
[/frame]
[/else]

note that this is very close to preprocessing and should be considered as such, especially with regard to scoring and animation selection

=== Simplified animation blocks ===
To simplify the most common animation cases, you can use different blocks instead of the generic '''[animation]''' block. These are also here for backward compatibility, but are not deprecated and fully supported

some of these use extra tags which are translated in the normal ''value='' tag

some of these define '''[xxx_frame]''' blocks where the frame prefix starts with an underscore. This is not allowed in normal WML (prefix starting with underscore is reserved for the engine internal use). It is here for clarity purpose

* '''[leading_anim]''' is an animation with the following parameters automatically set
apply_to=leading
* '''[recruit_anim]''' is an animation with the following parameters automatically set
apply_to=recruited
* '''[standing_anim]''' is an animation with the following parameters automatically set
apply_to=standing,default
note for 1.4 :''default'' doesn't exist in 1.4, but the semantic is the same.

i.e: the animation will be used to build default animations
* '''[idle_anim]''' is an animation with the following parameters automatically set
apply_to=idling
* '''[levelin_anim]''' is an animation with the following parameters automatically set
apply_to=levelin
* '''[levelout_anim]''' is an animation with the following parameters automatically set
apply_to=levelout
* '''[healing_anim]''' is an animation with the following parameters automatically set
apply_to=healing
value=<damage= value>
* '''[healed_anim]''' is an animation with the following parameters automatically set
apply_to=healed
value=<healing= value>
[_healed_sound_frame]
sound=heal.wav
[/_healed_sound_frame]
* '''[poison_anim]''' is an animation with the following parameters automatically set
apply_to=poisoned
value=<damage= value>
[_poison_sound_frame]
sound=poison.ogg
[/_poison_sound_frame]
* '''[movement_anim]''' is an animation with the following parameters automatically set
apply_to=movement
offset="0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150,0~1:150"
* '''[defend]''' is an animation with the following parameters automatically set
apply_to=defend
value=<damage= value>
<WML content>
[frame]
blend_with=255,0,0
blend_ratio="0.5:50,0.0:50"
[/frame]

there are some subtil change compared to what is described above to avoid the red flash when value=0, but it should work as expected as far as WML author are concerned

* '''[attack_anim]''' is an animation with the following parameters automatically set
if the animation contains a missile frame

apply_to=attack
missile_offset="0~0.8"

else

apply_to=attack
offset="0~0.6,0.6~0"

* '''[death]''' is an animation with the following parameters automatically set
apply_to=death
[_death_sound_frame]
sound=<die_sound= of the enclosing [unit] tag>
[/_death_sound_frame]
* '''[victory_anim]''' is an animation with the following parameters automatically set
apply_to=victory
* '''[extra_anim]''' is an animation with the following parameters automatically set
apply_to=<flag= value of the anim>
* '''[teleport_anim]''' will be cut into two at the clock-time 0
everything before zero becomes an animation with the following parameters automatically set
apply_to=pre_teleport
everything after zero becomes an animation with the following parameters automatically set
apply_to=post_teleport

== Layering ==
The ''layer'' progressive parameter allows the animation writer to choose in what order the animation should be drawn.

this value must be between 0 and 100

* the back of haloes is drawn with a value of 10
* when unspecified, a animation is drawn with a value of 40
* terrain elements that are supposed to go in front of units (castles) are drawn with a value of 50
* orbs and status bars are drawn on layer 80
* when unspecified missile frames are drawn on layer 90

by changing these values, it is easy to have the unit display the way you want

== See Also ==

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

[[Category: WML Reference]]

InternalActionsWML

2009-02-22T20:53:13Z

Nital: /* [event] */

{{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
** [[StandardUnitFilter]] (almost... '''Note:''' does not check for matching units in the recall list)
** '''count''' {{DevFeature}}: if used, the given number of units must match the filter. Accepts a number, range, or comma separated range; default "1-99999"

* '''[have_location]''': a location passing this filter exists
** [[StandardLocationFilter]]
** '''count''' {{DevFeature}}: if used, the given number of location must match the filter. Accepts a number, range, or comma separated range; default "1-99999"

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

* '''[and],[or],[not]''': all top-level filters will support in-order conditional handling of and, or, and not. One important thing to remember is, if you have multiple [or]s, you should not wrap your first conditional statement into an [or] block.

* '''[variable]''': tests something about the value of a WML variable (see [[VariablesWML]])
** '''name''': the name of the variable to test the value of 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''': $name has the same boolean value (e.g. off, false, 0, no)
** '''contains''': $name contains this string
** {{DevFeature}} '''boolean_not_equals''': $name has not the same boolean value. Strictly a syntactic shortcut for the following syntax that served its absence in 1.4:
[not]
[variable]
name=...
boolean_equals=...
[/variable]
[/not]

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

== [switch] {{DevFeature}} ==

Executes different sets of action based on the value of a variable.
[switch]
variable=foo
[case]
value="A"
... WML if foo=A ...
[/case]
[case]
value="B"
... WML if foo=B ...
[/case]
[else]
... WML if not foo=A nor foo=B ...
[/else]
[/switch]

* '''variable''': name of the variable to check.
* '''[case]''': Case block. Contains:
** '''value''': value to test the variable against.
** the action WML to execute if the variable matches the value (rest of the block).
* '''[else]''': Block of action WML to execute if no '''[case]''' block matches.

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

=== {FOREACH} ===
If you wish to use a "for-each" iteration format (useful for example when you want to do an iteration for each row in a table) you can use the {{LinkMacro|FOREACH}} and {{LinkMacro|NEXT}} predefined macros.

=== {REPEAT} ===
You can use the {{LinkMacro|REPEAT}} macro to perform a quick iteration for a number of times you specify.

== [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. {{Note:Predefined Macro|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.
** '''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''': divide the variable by the given number. The result is an integer.
** '''modulo''': 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. You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'. You may provide a range of numbers (integers), e.g. 'random=3..5'. 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''.
** '''rand''': does the same as random, but has better MP support. See [[BuildingMultiplayerExamples]] for more info on the MP case. '''It is highly recommended that you use this feature for randomization.'''
** '''time=stamp''': 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.
** {{DevFeature}} '''string_length''': Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see [[VariablesWML]] for details).
** {{DevFeature}} '''[join]''' joins an array of strings to create a textual list
***variable: name of the array
***key: the key of each array element(array[$i].foo) in which the strings are stored
***separator: separator to connect the elements
***remove_empty: whether to ignore empty elements

* {{DevFeature}} '''[set_variables]''': manipulates a WML array
** '''name''': the name of the container to manipulate
** '''mode''': one of the following values:
***replace: will clean the array '''name''' and replace it with given data
***append: will append given data to the current array
***merge: will merge in the given data into '''name'''
***insert: will insert the given data at the index specified in the '''name''' attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. '''Note:''' if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index unless the variable already contains data at that index. This limitation may be removed in future versions.
** '''to_variable''': data will be set to the given array
** '''[value]''': the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags, example:
[set_variables]
name=arr
mode=replace
[value]
foo=bar
[/value]
[value]
foo=more
[/value]
[/set_variables]
{DEBUG_MSG $arr[0].foo}
{DEBUG_MSG $arr[1].foo}
=>bar; more
** '''[literal]''': same as '''[value]''', but variables will not be substituted, '''[literal]''' and '''[value]''' can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of '''[value]''' and '''[literal]''' tags
**'''[split]''' splits a textual list into an array which will then be set to data
***list: textual list to split
***key: the key of each array element(array[$i].foo) in which the strings are stored
***separator: separator to separate the elements
***remove_empty: wether to ignore empty elements

* {{DevFeature}} '''[fire_event]''': trigger a WML event
** '''name''': the name of event to trigger
** '''[primary_unit]''': primary unit for the event (usually the attacker) (optional)
** '''[secondary_unit]''': secondary unit for the event (usually the defender) (optional)
** both tags have some keys which are optional :
*** '''x,y''': location of this unit
*** In Wesnoth 1.5.9 and onwards, [primary_unit] and [secondary_unit] can take a [[FilterWML|Standard Unit Filter]], but it will never match on a recall list unit. If it matches multiple units, the first unit that would be obtained with [store_unit] will be used in the relevant event parameter ($unit or $secondary_unit) and event filter.
** '''[primary_attack]''': information passed to the primary attack filter and $weapon variable on the new event.
** '''[secondary_attack]''': information passed to the second attack filter and $second_weapon variable on the new event.

* '''[store_unit]''': stores details about units into game variables. 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. 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]''': [[StandardUnitFilter]] 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.
:* advances_to
:* 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
:* 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', 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed) and {{DevFeature}} 'owner_side' (villages only)
** '''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) and {{DevFeature}} 'owner_side' (villages only).
** [[StandardLocationFilter]]: 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 comma-sperated list of terrain codes. (See [[TerrainCodesWML]] for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.
** '''radius''': if present, any locations which are within '''radius''' hexes of the location filter will also be stored
** '''[filter]''': [[StandardUnitFilter]] 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]''': 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) and {{DevFeature}} 'owner_side'.
** '''owner_side''': a side number. If present, only villages owned by this side will be choosen. If owner_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 terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.
* '''[store_gold]''': Stores a side's gold into a variable.
** '''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', 'fog', 'shroud', 'hidden' {{DevFeature}}, 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.)
** '''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. 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, multiple comma-separated variable names can be given.
* '''[role]''': tries to find a unit to assign a role to. 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]]). 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 [[StandardUnitFilter]] 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 [[StandardUnitFilter]] 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.
* {{DevFeature}} '''[store_map_dimensions]''': Stores the map dimensions in a variable.
** '''variable''': the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members ''width'' and ''height''.
* {{DevFeature}} '''[insert_tag]''': inserts a variable as WML
**'''name''': the ["name"] to be given to the tag
**'''variable''': name of the variable to be inserted
* {{DevFeature}} '''[store_time_of_day]''': stores time of day information from the current scenario into a WML variable container.
** '''variable''': (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on [[TimeWML]].
** '''turn''': (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.

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

[[Category: WML Reference]]

SideWML

2009-02-22T19:50:30Z

Nital: /* the [side] tag */ added hidden attrib

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

The [side] tag is used to describe a side in a particular scenario.

The following keys are recognized:

* '''side''': a digit. The leader of this side is placed on the tile represented by this digit (see [[BuildingMaps]]). When defining sides, they must be defined in order since the side number is checked against the number of sides seen so far.

* '''controller''': how moves for this side should be inputted.
** '''ai''': the Wesnoth AI makes this side's moves. This is the default setting.
** '''human''': a player controls this side's moves.
** '''null''': the side doesn't get a turn to move and doesn't have a leader generated from the contents of the [side] tag. (It still can get units from [unit] tags in the [side] tag.)

* '''no_leader''': if "no" (default), then keys describing a unit which will begin on the side's keep will be the remainder of the '''[side]''' tag, See [[SingleUnitWML]]. Note that if the keys '''x''', '''y''' are included, the leader will begin there regardless of keep location. If this side has a recall list from a previous level, then the recall list will be searched for a leader (using '''canrecruit=yes''') and if one is found it will be used instead of the one described in the '''[side]''' tag. Typical keys used for defining the leader unit are '''type''' (mandatory), '''description''', '''id''' {{DevFeature}}, '''user_description''', '''name''' {{DevFeature}} and '''unrenamable=yes''', see [[UnitWML]].

* '''recruit''': a list of unit types. At the beginning of the scenario, the side gains recruitment of these units.

* '''gold''': the starting gold for this side. Default 100. (If gold is carried over from a previous scenario, this value is the minimum starting gold.)

* '''income''': the base income for this side, default 0. This is added to ''base_income'', '''[game_config]''' to determine the side's base income. (see [[GameConfigWML]]).

* {{DevFeature}} '''hidden''': if 'yes', side is not shown in status table.

* '''fog''': if 'yes', this side cannot see any tiles it is not within vision of, except at the start. Please note that the AI currently ignores the fog.

* '''shroud''': if 'yes', this side cannot see any tiles it has not moved within sight of. Please note that the AI currently ignores the shroud.

* '''shroud_data''': describes the area which this team has de-shrouded. An example:
|
|00011111000
This would leave the first column on the map unaltered and would change the second column for 11 tiles. A '0' means: shrouded, '1' means unshrouded. You can either call an external file using {@filename} (see [[PreprocessorRef]]) or place the data in quotes. For making an external file see [[BuildingScenariosShroudData]].

* '''persistent''': whether the side exists in any other scenarios. If '1'(yes), then ''save_id''(see below) becomes active for this side. Default '0'(no); when '''controller=human''', this is always '1'.

* '''save_id''': default ''description'' if available, 'Unknown' otherwise. The ID of the side with respect to the previous and next scenarios. Used to carry over the side's recall list (including the side's leader), recruitment list, and starting gold from scenario to scenario. Also used for the side's displayed name in the victory gold-calculation dialog. See [[SideSwitchingWML]].

* '''team_name''': a non translatable string representing the team's description. Sides with the same team_name are allied. Default ''side''.

* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Default ''team_name''.

* '''colour''': May be either a numeric color index or a color name (e.g. 'blue', 'purple', 'orange', etc.). The numeric form is deprecated. The default list of numbers and corresponding colours can be found in data/core/team_colors.cfg.

* '''flag''': a custom flag animation to use instead of the default one to mark captured villages. An automatic side-coloring is applied.
** Example animation that has three frames and loops every 750ms: ''flag=misc/myflag-1.png:250,misc/myflag-2.png:250,misc/myflag-3.png:250''

* '''flag_icon''': a custom flag icon to indicate the side playing in the statusbar (a size of 24x16 is recommended). An automatic side-coloring is applied.

* '''village_gold''': the amount of gold given to this side per village it controls per turn. Default specified in ''village_income'', '''[game_config]''' ([[GameConfigWML]]). '''Note:''' If you need village gold to be 0. Set the variable to -1.

* '''share_maps''': whether sides allied with this side see all terrains that this side sees, if they are on shroud.

* '''share_view''': whether sides allied with this side see the units that this side sees, if they are on FoW (fog).

* '''disallow_observers''': prevents observers from seeing this side turn. (default: no)

* '''[ai]''' if '''controller=ai''', gives parameters to the AI. See [[AiWML]].

* '''[village]''' describes a village the side begins in control of.
** ''x'', ''y'' the location of the village. If the pair of coordinates is not a village or is duplicated in another [village] tag, behaviour is undefined. Recent game engine or wmllint should warn about these.

* '''[unit]''' describes a unit which begins on the side. See [[SingleUnitWML]]. If the side has a recall list and the unit is not given a location, it will start on the recall list. Note that the ''side'' attribute under '''[unit]''' will be ignored, as the side will come from the ''side'' attribute of '''[side]'''.

The following keys are multiplayer only:

* '''allow_player''': if false then this side will not be allowed to be modified and will be hidden during game creation.

* '''team_lock''': if true then this side's team is not allowed to be modified.

* '''colour_lock''': if true then this side's color is not allowed to be modified.

* '''gold_lock''': if true then this side's gold is not allowed to be modified.

* '''income_lock''': if true then this side's income is not allowed to be modified.

* '''faction''': this lock this side to this faction.

* '''faction_from_recruit''' {{DevFeature}}: if true then this side will be locked to the faction that matches the recruits better. (this was enabled by default in 1.4)

== See Also ==
* [[EraWML]]
* [[ScenarioWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

DirectActionsWML

2009-02-22T19:48:33Z

Nital: /* Direct actions */ adding hidden attrib

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay.

The following tags are actions:
* '''[endlevel]''': ends the scenario.
** '''result''': before the scenario is over, all events with ''name=result'' are triggered. The message ''result_message'' with the heading ''result_heading'' (see [[LanguageWML]]) are displayed. If ''result=victory'', the player progresses to the next level; if ''result=defeat'', the game returns to the main menu. These last two are rarely used: ''result=continue'' behaves identically to ''result=victory'' except the player's gold is not reduced to 80%, and it does not bring up a "Victory" message or the gold changing message (since it doesn't change); ''result=continue_no_save'' works similarly, except the player is not asked whether to save the game, and is taken directly to the next scenario without any messages. Unless ''result=defeat'', the following keys can also be used:
** '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes.
** '''carryover_report''' {{DevFeature}}: whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.
** '''save''' {{DevFeature}}: whether a start-of-scenario save should be created for the next scenario, the default is save=yes.
** '''linger_mode''' {{DevFeature}}: whether the game should switch to linger_mode before advancing to the next scenario, the default is linger_mode=yes.
** '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
** When the result is "victory" the following keys can be used:
*** '''carryover_percentage''' {{DevFeature}}: by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
*** '''carryover_add''' {{DevFeature}}: if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.
** '''music''' {{DevFeature}}: (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.
** '''end_text''' {{DevFeature}}: Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
** '''end_text_duration''' {{DevFeature}}: Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].
* '''[unit]''': places a unit on the map. For syntax see [[SingleUnitWML]].
** {{Short Note:Predefined Macro|GENERIC_UNIT}}
** {{DevFeature}} '''to_variable''': spawn directly into a variable instead of on the map.
* '''[recall]''': recalls a unit. The unit is recalled free of charge, and is placed near the leader.
** [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored.
** '''x,y''': the unit is placed here instead of next to the leader.
** '''show''': if not "no", display the unit being recalled.
* '''[teleport]''': teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be teleported.
** '''x,y''': the position to teleport to.
** '''clear_shroud''': should shroud be cleared on arrival
** '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)
* '''[terrain_mask]''': changes the terrain on the map. See [[TerrainMaskWML]].
* '''[terrain]''': changes the terrain on the map.
** '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
** '''x,y''': the position (or range of positions) to change.
** {{DevFeature}} '''layer''': (overlay|base|both, default=both) only change the specified layer.
** {{DevFeature}} '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.
* '''[gold]''': give one side gold.
** '''amount''': the amount of gold to give.
** '''side''': (default=1) the number of the side to give the gold to.
* '''[unstore_unit]''': creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also '''[store_unit]''', '''[while]''' and [clear_variable] in [[InternalActionsWML]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
** '''variable''': the name of the variable.
** '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''text''': (translatable) floating text to display above the unit, such as a damage amount
** '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''advance''': if the XP has been modified then there will be tried to advance the unit, default true.
** {{DevFeature}} '''x''' ,'''y''': override unit location
* '''[allow_recruit]''': allows a side to recruit units it couldn't previously recruit.
** '''type''': the types of units that the side can now recruit.
** '''side''': (default=1) the number of the side that is being allowed to recruit the units.
* '''[disallow_recruit]''': prevents a side from recruiting units it could previously recruit.
** '''type''': the types of units that the side can no longer recruit.
** '''side''': (default=1) the number of the side that may no longer recruit the units.
* '''[set_recruit]''': sets the units a side can recruit.
** '''recruit''': the types of units that the side can now recruit.
** '''side''': (default=1) the number of the side that is having its recruitment set.
* '''[modify_side]''': modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'
** '''side''': (default=1) the number of the side that is to be changed.
** '''income''': the income given at the begining of each turn.
** '''team_name''': the team in which the side plays the scenario.
** '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
** '''gold''': the amount of gold the side owns.
** '''village_gold''': the income setting per village for the side.
** '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag.
** '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
** '''shroud''': a boolean string describing the status of Shroud for the side.
** {{DevFeature}} '''hidden''': a boolean string specifying whether side is shown in status table.
** {{DevFeature}} '''[ai]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''[modify_turns]''': modifies the turn limit in the middle of a scenario.
** '''value''': the new turn limit.
** '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
** {{DevFeature}} '''current''': changes the current turn number after applying turn limit modifications, if any. It is possible to change the current turn number to a greater one than the current only; also, it is not possible to change the turn number to exceed the turn limit.
* '''[capture_village]''': changes the ownership of a village.
** '''side''': the side that takes control of the village. If not given, the village will become neutral.
** '''x, y''': the location of the village.
* '''[kill]''': Removes all units (including units in a recall list) that match the filter from the game.
** [[StandardUnitFilter]]: selection criterion
** '''animate''': if 'yes', displays the unit dying (fading away).
** '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that any 'die' events triggered by this are executed immediately, interrupting the current event and thus causing the x1, y1, x2, and y2 variables to be reset for that 'die' event, which in turn causes those variables to be invalid for the remainder of this event. {{DevFeature}} 'last breath' events are also fired.
* '''[unstone]''': Unstones all units that match the filter.
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be unstoned. If no unit matches the filter, then nothing happens (probably). If absent, all units on the map are unstoned.
* '''[object]''': gives some unit an object and removes all items on the tile the unit is on.
** '''id''': when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per level. In a campaign objects with the same id can be assigned once per level.
** '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
** '''duration''': if 'level', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).
** '''[filter]''': [[StandardUnitFilter]] the first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
** '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
** '''silent''': whether or not messages should be suppressed. Default is "no".
** '''image''': the displayed image of the object.
** '''name''': (translatable) displayed as a caption of the image.

** '''user_description''': {{DevFeature}} (translatable) displayed as a message of the image. In 1.4 and older versions this is just '''description'''; that will still be expected for compatibility.
** '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.
** If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
** The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.
* '''[remove_shroud]''': removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
** '''side''': (default=1) the side for which to remove shroud.
** [[StandardLocationFilter]]: the range of tiles for which shroud should be removed.
** Note: '''[remove_shroud]''' doesnt't accept all of the standard location filters. In particular '''[filter]''' to remove shroud around units doesn't work, and radius may not either. To remove shroud around a group of units, you can temporarily switch the sides of the units using '''[store_unit]''', '''[set_variable]''', and then '''[unstore_unit]''' (do the '''[set_variable]''' and '''[unstore_unit]''' twice each, once to switch sides, and once to switch back). Just make sure you call '''[redraw]''' while the unit's side is switched to update shroud. Also make sure to use ''kill=no'' for the store and then ''find_vacant=no'' for the unstores.
** {{DevFeature}}: '''[remove_shroud]''' accepts a full standard location filter.
* '''[place_shroud]''': places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
** '''side''': (default=1) the side for which to place shroud.
** [[StandardLocationFilter]]: the range of tiles on which shroud should be placed.
* '''[allow_undo]''': allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move is undone. It is up to the scenario designer to avoid abusing this command.
** Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the move the first time.
* '''[heal_unit]''' {{DevFeature}}: heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser than the parameter '''amount''' if the unit is fully healed).
** '''[filter]''': [[StandardUnitFilter]] the first unit matching the filter will be healed.
** '''[secondary_unit_filter]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true).
** '''amount''': the maximum points the unit will be healed.
** '''animate''': a boolean which indicate if the healing animations must be played.
* '''[time_area]''' {{DevFeature}}: how a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] and [illuminated_time] tags in the [scenario] tag
** [[StandardLocationFilter]]: the locations to affect.
** [[TimeWML]]: the new schedule.
** '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later. See below.
** '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.
** {{DevFeature}}: in Wesnoth 1.5.9 and later, '''id''' may be a comma-separated list for removing time areas. It is not allowed, however, for inserting time areas; only the first id is taken into account in that case.

* '''[end_turn]''' {{DevFeature}}: end the current side's turn.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

Support

2009-02-22T09:23:22Z

Nital: /* IRC */

__NOTOC__
There are many ways to get help. From online documentation to support from the community on IRC or forums.

== Wiki Resources ==
* [[Play|Online Players Guide]] - Game manual, walkthroughs, strategy guides, and more.
* [[Create|Content-Creation Guide]] - Manual showing how to create new campaigns for Wesnoth.
* [[StartingPoints|Starting Points]] - List of pages to serve as starting point for diving deeply into the wiki...
* [[MP_CodeOfConduct | Multiplayer Information ]] - Info about server moderators, useful MP commands, and our online Code of Conduct.

== Reporting Bugs ==
If you are experiencing problems, you should consider [[ReportingBugs|reporting a bug]].

== Community ==

When asking for help with some technical problem in the game forums, please provide the following information:
* which operating system do you use (e.g. Windows, Linux, Mac OSX)
* which version of Wesnoth do you use (it is displayed in the bottom left corner of title screen)
* contents of file "stderr.txt"
** on MS Windows, it is here: "C:\Program Files\Wesnoth\stderr.txt"

=== Forums ===
* [http://www.wesnoth.org/forum/ Official Wesnoth forums]
* [[Wesnoth_Acronyms_and_Slang|Wesnoth Acronyms]] - forum lingo
* [http://www.wesnoth.cn Chinese wesnoth forums]
* [http://wif.altervista.org/index.php Wesnoth Italian Forums (W.I.F)]
* [http://www.wesnothlife.ru/forum/ Russian Wesnoth Forums]

=== IRC ===
If you don't know what IRC is, check out [http://www.irchelp.org/ irchelp].

* [irc://irc.freenode.net/wesnoth #wesnoth]: this channel is for general conversation amongst Wesnoth users and developers alike.
* [irc://irc.freenode.net/wesnoth-dev #wesnoth-dev]: the development discussion channel. Most contributors and developers (WML, C++ and art people alike) hang around here, exchanging ideas and code patches.
* [irc://irc.freenode.net/wesnoth-mp #wesnoth-mp]: the multiplayer servers' status and development discussion channel.
* [irc://irc.freenode.net/wesnoth-music #wesnoth-music]
* [irc://irc.freenode.net/wesnoth-umc-dev #wesnoth-umc-dev]: the look-alike of #wesnoth-dev for the [http://www.wesnoth.org/forum/viewtopic.php?f=8&t=21413 Wesnoth User-made Add-ons Development] repository.
* [irc://irc.tweakers.net/wesnoth #wesnoth (Dutch channel)]
* [irc://irc.freenode.net/wesnoth-de #wesnoth-de (German channel)]: the German look-alike of #wesnoth, mainly used by German-speaking users and translators.
* [irc://irc.freenode.net/wesnoth-pl #wesnoth-pl (Polish channel)]: as above, but Polish
* [irc://irc.syrolnet.org/WIF #WIF (Italian channel)]
You can also see the [http://irclog.wesnoth.org/ logs] of the #wesnoth, #wesnoth-de, #wesnoth-dev and #wesnoth-umc-dev channels.

=== Mailing Lists ===
* [https://mail.gna.org/listinfo/wesnoth-dev/ wesnoth-dev] ([https://mail.gna.org/public/wesnoth-dev/ archives]): the mailing list for discussing mainline development issues; it is not intended for bug reports or feature requests. See [[ReportingBugs]] for those.
* [https://mail.gna.org/listinfo/wesnoth-commits/ wesnoth-commits] ([https://mail.gna.org/public/wesnoth-commits/ archives]): all commits made to the mainline SVN repository are automatically echoed in this list for those who want or need to keep track of them. New developers and contributors are required to subscribe to this list.
* [https://mail.gna.org/listinfo/wesnoth-i18n/ wesnoth-i18n] ([https://mail.gna.org/public/wesnoth-i18n/ archives]): the internationalization (i18n) mailing list; all translation team maintainers and the i18n managers should subscribe and keep track of announcements and discussions taking place in this list.

=== Other Servers List ===
see [http://www.wesnoth.org/wiki/MultiplayerServers here]

[[Category:Troubleshooting and Bugs]]

EasyCoding

2009-02-21T00:40:18Z

Nital: /* GUI related features */

== Foreword ==
This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature I'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

--[[User:Boucman|Boucman]] 20:48, 3 October 2006 (CEST)

Since bugs are sometimes a good opportunity to get a first idea of the code, i will add some here that are easy to fix as soon as i stumble upon them (the one i had in mind is fixed already ;-).

--Yogi Bear, 28 February 2008

== MP related features ==

=== Use different font for in-game chat ===
Since commas and dots are apparently hard to tell apart. As per FR #7470 [https://gna.org/bugs/?7470]

== WML related features ==

=== Allow WML to open the in-game help ===
As per FR #11061 [http://gna.org/bugs/?11061] (see Patch #1123 [http://gna.org/patch/?1123])

=== WML configurable village income / upkeep ===
Preferably as a [scenario], [side] or [campaign] keys. As per FR #6301 [https://gna.org/bugs/?6301]

=== Add support of [if] for [scenario] ===
As per FR #4539 [https://gna.org/bugs/?4539]

=== Make [have_unit] optionaly use full SUF ===
[have_unit] by default uses SUF but does not apply it to recall list. Introduce an optional key that will allow to lift that limitation.

=== Side-specific results ===
Giving result=defeat or result=victory for specific sides. ([http://gna.org/bugs/index.php?4960 FR #4960]) -- [[User:dlr365|dlr365]] -- patch submitted [https://gna.org/bugs/index.php?4960]

=== Support for leaderless multiplayergames ===
Add support for the WML key victory_when_enemies_defeated= in the scenario tag during multiplayergames. ([https://gna.org/bugs/index.php?8106 FR #8106])

=== Other Ideas ===
See [[FutureWML]]; some ideas there are easier than others.

== Improvements to FormulaAI ==

Add new formula functions, or minor improvements to the formula language. Make it easier to debug the formula language.

== GUI related features ==
-------------------

Note at the moment Mordante is working on a new GUI system, these
changes will probably affect the way these items need to be implemented.
Contact Mordante on IRC before starting to work on these.

--[[User:SkeletonCrew|SkeletonCrew]] 14:04, 9 March 2008 (EDT)

=== Theme Changes ===

* allow custom themes to display values of WML variables ([http://gna.org/bugs/index.php?6209 FR #6209])
* hide the hourglass item from the statusbar when there is no timer

=== Widget Changes ===
* show side number, name and team association information in the status table
* make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* input history (chat, commands, ..) - note: rujasu is working on this feature

== GUI2 related features ==
GUI2 is the new gui engine Mordante/SkeletonCrew is working on.
* Information on the wiki can be found here http://www.wesnoth.org/wiki/GUIToolkit
* The source code is under src/gui/
* The configuration config files are under data/gui/default

Some tasks need the --new-widgets since the code is only shown in the experimental mode. Tasks which need this switch have the * in the title.

=== Generic yes/no ok/cancel dialog ===
There's already a generic OK dialog
* src/gui/dialogs/message.[h|c]pp
* data/gui/default/window/message.cfg

This dialog should have the option to show a cancel button as well and also let the caller of the dialog determine the text of the button. Maybe more buttons (4 in total) can be added to make the dialog more flexible.

=== * Minimap ===
The minimap widget has already been made but is broken.
* src/gui/widgets/minimap.[c|h]pp

The drawing code has been rewritten, but this widget hasn't been updated it's used in the MP connection dialog (which needs more work).

=== * Savegame dialog ===
This is a new dialog to write and requires the minimap code to be fixed first. The dialog should mimic the current dialog. Sorting of a listbox and the proper alignment of the columns is not important (the engine doesn't support this yet). The code should only be used when --new-widgets is used as start switch since we're in a feature freeze at the moment.

=== * Title screen ===
A start has been made for the new titlescreen
* src/gui/dialogs/title_screen.[c|h]pp
* data/gui/default/window/title_screen.cfg
This should be improved to include the buttons and alignment of the current title screen. The 'roll-over' image is not part of this task.

=== Arrow keys for the slider ===
There's a new slider widget, but it doesn't support the keyboard yet.
gui/widgets/slider.[c|h]pp

Clicking on the widget should capture the keyboard and then arrow left/right should move one step even if not all steps are visible.

=== Slider sizing ===
There are some issues with the sizing of a slider.
gui/widgets/slider.[c|h]pp

In a layout step it needs to try to shrink itself, not entirely sure where or how yet, best ask mordante on irc.

== Miscellaneous ==

=== More powerful village naming ===
'''Adding mountain names and other features to village names, having a second random name in village names'''

Currently the village naming engine has a very good structure that could allow
more powerfull names to be generated.
Understanding how it works should be quite easy, and a few usefull improvements could be added.

* Currently villages can use lake names and river names, this should be extended to other features like bridges, swamps, mountains etc...
* It would be nice to have a separate list of "first sylabus" and "last sylabus" for naming. That's not really needed in english, but some translations could use it
* Again, it is common to have villages with more than one "random" word in them. having a $name2 variable would be nice

ACardboardRobot 2/2/07

=== Debug Mode ===
* New debug command functionality (setting additional status.variables, possibly terrain)

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]

EasyCoding

2009-02-20T23:54:10Z

Nital: /* Use different font for in-game chat */ apparently author has dropped editing Wesnoth, so removing it to avoid confusion

== Foreword ==
This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature I'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

--[[User:Boucman|Boucman]] 20:48, 3 October 2006 (CEST)

Since bugs are sometimes a good opportunity to get a first idea of the code, i will add some here that are easy to fix as soon as i stumble upon them (the one i had in mind is fixed already ;-).

--Yogi Bear, 28 February 2008

== MP related features ==

=== Use different font for in-game chat ===
Since commas and dots are apparently hard to tell apart. As per FR #7470 [https://gna.org/bugs/?7470]

== WML related features ==

=== Allow WML to open the in-game help ===
As per FR #11061 [http://gna.org/bugs/?11061] (see Patch #1123 [http://gna.org/patch/?1123])

=== WML configurable village income / upkeep ===
Preferably as a [scenario], [side] or [campaign] keys. As per FR #6301 [https://gna.org/bugs/?6301]

=== Add support of [if] for [scenario] ===
As per FR #4539 [https://gna.org/bugs/?4539]

=== Make [have_unit] optionaly use full SUF ===
[have_unit] by default uses SUF but does not apply it to recall list. Introduce an optional key that will allow to lift that limitation.

=== Side-specific results ===
Giving result=defeat or result=victory for specific sides. ([http://gna.org/bugs/index.php?4960 FR #4960]) -- [[User:dlr365|dlr365]] -- patch submitted [https://gna.org/bugs/index.php?4960]

=== Support for leaderless multiplayergames ===
Add support for the WML key victory_when_enemies_defeated= in the scenario tag during multiplayergames. ([https://gna.org/bugs/index.php?8106 FR #8106])

=== Other Ideas ===
See [[FutureWML]]; some ideas there are easier than others.

== Improvements to FormulaAI ==

Add new formula functions, or minor improvements to the formula language. Make it easier to debug the formula language.

== GUI related features ==
=== Change map paths from dots to dashes ===
Or even better allow dashes and allow choice between the two. As per FR #5522 [https://gna.org/bugs/?5522]

-------------------

Note at the moment Mordante is working on a new GUI system, these
changes will probably affect the way these items need to be implemented.
Contact Mordante on IRC before starting to work on these.

--[[User:SkeletonCrew|SkeletonCrew]] 14:04, 9 March 2008 (EDT)

=== Theme Changes ===

* show number of owned villages/total villages (FR: #3135) (--[[User:Alink|alink]] done but must update help, doc, tooltip...)
* allow custom themes to display values of WML variables ([http://gna.org/bugs/index.php?6209 FR #6209])
* hide the hourglass item from the statusbar when there is no timer

=== Widget Changes ===
* show side number, name and team association information in the status table
* make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* input history (chat, commands, ..) - note: rujasu is working on this feature

== GUI2 related features ==
GUI2 is the new gui engine Mordante/SkeletonCrew is working on.
* Information on the wiki can be found here http://www.wesnoth.org/wiki/GUIToolkit
* The source code is under src/gui/
* The configuration config files are under data/gui/default

Some tasks need the --new-widgets since the code is only shown in the experimental mode. Tasks which need this switch have the * in the title.

=== Generic yes/no ok/cancel dialog ===
There's already a generic OK dialog
* src/gui/dialogs/message.[h|c]pp
* data/gui/default/window/message.cfg

This dialog should have the option to show a cancel button as well and also let the caller of the dialog determine the text of the button. Maybe more buttons (4 in total) can be added to make the dialog more flexible.

=== * Minimap ===
The minimap widget has already been made but is broken.
* src/gui/widgets/minimap.[c|h]pp

The drawing code has been rewritten, but this widget hasn't been updated it's used in the MP connection dialog (which needs more work).

=== * Savegame dialog ===
This is a new dialog to write and requires the minimap code to be fixed first. The dialog should mimic the current dialog. Sorting of a listbox and the proper alignment of the columns is not important (the engine doesn't support this yet). The code should only be used when --new-widgets is used as start switch since we're in a feature freeze at the moment.

=== * Title screen ===
A start has been made for the new titlescreen
* src/gui/dialogs/title_screen.[c|h]pp
* data/gui/default/window/title_screen.cfg
This should be improved to include the buttons and alignment of the current title screen. The 'roll-over' image is not part of this task.

=== Arrow keys for the slider ===
There's a new slider widget, but it doesn't support the keyboard yet.
gui/widgets/slider.[c|h]pp

Clicking on the widget should capture the keyboard and then arrow left/right should move one step even if not all steps are visible.

=== Slider sizing ===
There are some issues with the sizing of a slider.
gui/widgets/slider.[c|h]pp

In a layout step it needs to try to shrink itself, not entirely sure where or how yet, best ask mordante on irc.

== Miscellaneous ==

=== More powerful village naming ===
'''Adding mountain names and other features to village names, having a second random name in village names'''

Currently the village naming engine has a very good structure that could allow
more powerfull names to be generated.
Understanding how it works should be quite easy, and a few usefull improvements could be added.

* Currently villages can use lake names and river names, this should be extended to other features like bridges, swamps, mountains etc...
* It would be nice to have a separate list of "first sylabus" and "last sylabus" for naming. That's not really needed in english, but some translations could use it
* Again, it is common to have villages with more than one "random" word in them. having a $name2 variable would be nice

ACardboardRobot 2/2/07

=== Debug Mode ===
* New debug command functionality (setting additional status.variables, possibly terrain)

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]